Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

7.6 KB
Raw Blame
#!/usr/bin/env node
// The MCP tool release history: which tools each release added and removed, on
// which server. /mcp-tools renders it as the "Releases" list and the changelog
// links to it, so "what can an agent do now that it could not last week" has a
// real, per-tool answer.
//
// Source of truth is public/mcp-catalog.json (scripts/build-mcp-catalog.mjs).
// The history file is append-only: each run replays every release from empty,
// compares the result with the catalog, and if they differ records the
// difference as today's release (merged into today's entry if one already
// exists). Replaying the file therefore always reproduces the current tool set,
// and `--check` fails the build when it does not.
//
//   node scripts/build-mcp-tool-history.mjs          append today's diff, if any
//   node scripts/build-mcp-tool-history.mjs --check  exit 1 when the history is stale
//   node scripts/build-mcp-tool-history.mjs --seed   rebuild from the git history
//                                                    of public/mcp-catalog.json
//
// --seed reads every committed version of the catalog, keeps the last snapshot
// of each day, and maps the server ids the catalog used before the live census
// to today's ids. Only servers three.ws ships today are tracked.

import { execFileSync } from 'node:child_process';
import { existsSync, readFileSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { ROOT } from './lib/mcp-tool-sources.mjs';

const CATALOG = join(ROOT, 'public', 'mcp-catalog.json');
const OUT = join(ROOT, 'public', 'mcp-tool-history.json');
const CATALOG_REL = 'public/mcp-catalog.json';

// Server ids the static catalog used before it was built from tools/list.
const LEGACY_IDS = {
	'three.ws': 'mcp',
	'threews-agent': 'mcp-agent',
	'threews-3d-studio': 'mcp-3d',
	'threews-3d-studio-free': 'mcp-studio',
	'threews-x402-bazaar': 'mcp-bazaar',
	'ibm-x402-mcp-remote': 'ibm-mcp',
	'threews-pumpfun': 'pump-fun-mcp',
	'mcp-server': 'three-ws-mcp-server',
};

const today = () => new Date().toISOString().slice(0, 10);
const keyOf = (server, name) => `${server}/${name}`;

/** The tool keys a catalog document describes, restricted to `servers`. */
function keysOf(doc, servers) {
	const keys = new Set();
	for (const t of doc.tools || []) {
		const raw = t.server?.id;
		const id = LEGACY_IDS[raw] || raw;
		if (servers.has(id)) keys.add(keyOf(id, t.name));
	}
	return keys;
}

/** Group a list of keys as { server: [names] }, both sorted. */
function grouped(keys) {
	const out = {};
	for (const k of [...keys].sort()) {
		const i = k.indexOf('/');
		(out[k.slice(0, i)] ||= []).push(k.slice(i + 1));
	}
	return out;
}

const flatten = (groups) => Object.entries(groups || {}).flatMap(([s, names]) => names.map((n) => keyOf(s, n)));

/** Replay releases from empty: the tool set the history says exists now. */
function replay(releases) {
	const state = new Set();
	for (const r of releases) {
		for (const k of flatten(r.removed)) state.delete(k);
		for (const k of flatten(r.added)) state.add(k);
	}
	return state;
}

function release(date, before, after, extra = {}) {
	const added = [...after].filter((k) => !before.has(k));
	const removed = [...before].filter((k) => !after.has(k));
	if (!added.length && !removed.length) return null;
	return {
		date,
		...extra,
		added: grouped(added),
		removed: grouped(removed),
		counts: { added: added.length, removed: removed.length, total: after.size },
	};
}

function document(releases) {
	return {
		$comment:
			'Generated by scripts/build-mcp-tool-history.mjs from public/mcp-catalog.json. Append-only: replaying every release from empty reproduces the current tool set, and npm run audit:mcp-catalog fails the build when it does not.',
		method:
			'Each release is the difference between the tool set of the previous release and the catalog built that day, keyed by server id and tool name. A tool that moves between servers shows as removed from one and added to the other.',
		releases,
	};
}

/** Every committed version of the catalog, oldest first, one per day (the last). */
function committedSnapshots() {
	const log = execFileSync('git', ['log', '--reverse', '--format=%H %cs', '--', CATALOG_REL], { cwd: ROOT, encoding: 'utf8' })
		.trim()
		.split('\n')
		.filter(Boolean)
		.map((line) => line.split(' '));
	const lastOfDay = new Map();
	for (const [sha, date] of log) lastOfDay.set(date, sha);
	return [...lastOfDay].map(([date, sha]) => {
		const body = execFileSync('git', ['show', `${sha}:${CATALOG_REL}`], { cwd: ROOT, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
		return { date, sha: sha.slice(0, 9), doc: JSON.parse(body) };
	});
}

const catalog = JSON.parse(readFileSync(CATALOG, 'utf8'));
const servers = new Set(catalog.servers.map((s) => s.id));
const current = keysOf(catalog, servers);
const existing = existsSync(OUT) ? JSON.parse(readFileSync(OUT, 'utf8')) : null;

if (process.argv.includes('--seed')) {
	const releases = [];
	let before = new Set();
	for (const snap of committedSnapshots()) {
		const after = keysOf(snap.doc, servers);
		const r = release(snap.date, before, after, { commit: snap.sha });
		if (r) releases.push(r);
		before = after;
	}
	const live = release(today(), before, current, {
		note: 'First release counted from the live tools/list of every server. The earlier static catalog read tool files and missed tools registered at runtime, so some tools listed as added here already existed.',
	});
	if (live) releases.push(live);
	writeFileSync(OUT, `${JSON.stringify(document(releases), null, '\t')}\n`);
	console.log(`[build:mcp-tool-history] seeded ${releases.length} releases from the git history of ${CATALOG_REL}`);
	process.exit(0);
}

const releases = existing?.releases || [];
const replayed = replay(releases);
const inSync = replayed.size === current.size && [...current].every((k) => replayed.has(k));

if (process.argv.includes('--check')) {
	if (!existing) {
		console.error('[audit:mcp-tool-history] public/mcp-tool-history.json is missing. Fix: npm run build:mcp-catalog');
		process.exit(1);
	}
	if (!inSync) {
		const added = [...current].filter((k) => !replayed.has(k));
		const removed = [...replayed].filter((k) => !current.has(k));
		console.error('[audit:mcp-tool-history] the release history does not reproduce the catalog.');
		if (added.length) console.error(`  not recorded as added: ${added.slice(0, 12).join(', ')}${added.length > 12 ? ` and ${added.length - 12} more` : ''}`);
		if (removed.length) console.error(`  not recorded as removed: ${removed.slice(0, 12).join(', ')}${removed.length > 12 ? ` and ${removed.length - 12} more` : ''}`);
		console.error('  Fix: npm run build:mcp-catalog');
		process.exit(1);
	}
	console.log(`[audit:mcp-tool-history] ${releases.length} releases replay to the ${current.size} tools in the catalog`);
	process.exit(0);
}

if (inSync) {
	console.log(`[build:mcp-tool-history] no tool changes since the last release (${releases.length} releases)`);
	process.exit(0);
}

// Merge into today's entry when one exists, so a day of rebuilds is one release.
const date = today();
const last = releases.at(-1);
const mergeToday = last?.date === date;
const base = mergeToday ? replay(releases.slice(0, -1)) : replayed;
const keep = mergeToday ? { ...(last.commit ? { commit: last.commit } : {}), ...(last.note ? { note: last.note } : {}) } : {};
const next = release(date, base, current, keep);
const out = mergeToday ? [...releases.slice(0, -1), ...(next ? [next] : [])] : [...releases, next];
writeFileSync(OUT, `${JSON.stringify(document(out), null, '\t')}\n`);
console.log(`[build:mcp-tool-history] recorded ${date}: +${next?.counts.added ?? 0} -${next?.counts.removed ?? 0} (${current.size} tools)`);