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.

feat(mcp): add daily MCP registry sentinel cron and trust helpers

nirholas218f00660734
diff --git a/CLAUDE.md b/CLAUDE.md
index a7707d27e..b5a33200b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -205,7 +205,7 @@ Production deploys need owner approval (gate 2) unless the current instruction i
- Frontend: vanilla JS modules + Vite (`npm run dev`, port 3000).
- 3D: Three.js with glTF/GLB.
- Backend touchpoints: serverless-style handlers in `api/`, workers in `workers/`.
-- **Production runs on Google Cloud Run, NOT Vercel** (migrated 2026-07-07 after Vercel disabled the deployment). One container ([server/index.mjs](server/index.mjs)) serves the static frontend, the vercel.json route table, and all `api/**` handlers; the crons (133 as of 2026-10-10, see vercel.json) run on Cloud Scheduler. `vercel.json` is a LIVE config file: `server/index.mjs` reads its `routes` array on boot (split at the `{handle:"filesystem"}` marker into pre- and post-filesystem phases), and `scripts/create-gcp-scheduler.mjs` reads its `crons` array to sync Cloud Scheduler jobs. The server itself never reads `crons`. Never delete `vercel.json` as a leftover. GCP builds/deploys must pin the `three-ws-build@` (build) and `three-ws@` (runtime) service accounts; the project's default compute SA was deleted. Deploys: see the "Deploy runbook" section above.
+- **Production runs on Google Cloud Run, NOT Vercel** (migrated 2026-07-07 after Vercel disabled the deployment). One container ([server/index.mjs](server/index.mjs)) serves the static frontend, the vercel.json route table, and all `api/**` handlers; the crons (140 as of 2026-10-23, see vercel.json) run on Cloud Scheduler. `vercel.json` is a LIVE config file: `server/index.mjs` reads its `routes` array on boot (split at the `{handle:"filesystem"}` marker into pre- and post-filesystem phases), and `scripts/create-gcp-scheduler.mjs` reads its `crons` array to sync Cloud Scheduler jobs. The server itself never reads `crons`. Never delete `vercel.json` as a leftover. GCP builds/deploys must pin the `three-ws-build@` (build) and `three-ws@` (runtime) service accounts; the project's default compute SA was deleted. Deploys: see the "Deploy runbook" section above.
- **Env-var trap:** `vercel env pull` returns EMPTY for secret-type vars. Never trust a Vercel env export as complete. Production env lives on the Cloud Run service (`gcloud run services describe/update three-ws-api --region us-central1`).
- Solana/agent SDKs in `sdk/`, `solana-agent-sdk/`, `agent-payments-sdk/`.
- Real APIs in use: Pump.fun feed, Solana RPC, OpenAI/Anthropic via worker proxies. Never mock these.
diff --git a/api/_lib/mcp-registry-sentinel.js b/api/_lib/mcp-registry-sentinel.js
new file mode 100644
index 000000000..1e5d5aac4
--- /dev/null
+++ b/api/_lib/mcp-registry-sentinel.js
@@ -0,0 +1,129 @@
+// Pure diff logic for the MCP registry sentinel (api/cron/mcp-registry-sentinel.js).
+//
+// Inputs are plain data (local server.json manifests, the registry's latest
+// entries for our namespace, npm latest versions), so every finding type is
+// testable against fixtures without a network or a clock.
+
+export const NAMESPACE = 'io.github.nirholas/';
+
+function semverParts(v) {
+ const m = /^(\d+)\.(\d+)\.(\d+)/.exec(String(v || ''));
+ return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+/** @returns {number} 1 when a > b, -1 when a < b, 0 when equal or not comparable. */
+export function compareSemver(a, b) {
+ const pa = semverParts(a);
+ const pb = semverParts(b);
+ if (!pa || !pb) return 0;
+ for (let i = 0; i < 3; i++) {
+ if (pa[i] !== pb[i]) return pa[i] > pb[i] ? 1 : -1;
+ }
+ return 0;
+}
+
+function normRepo(url) {
+ return String(url || '')
+ .trim()
+ .toLowerCase()
+ .replace(/\.git$/, '')
+ .replace(/\/+$/, '');
+}
+
+/**
+ * @param {object} input
+ * @param {Array<{ name: string, version: string, repoUrl?: string, dir: string, npm?: { identifier: string, version: string } }>} input.local
+ * @param {Array<{ name: string, version: string, repoUrl?: string }>} input.registry latest entries under our namespace
+ * @param {Record<string, string|null>} input.npmLatest npm package -> latest version (null = not on npm)
+ * @param {Array<{ name: string, url: string, ok: boolean, status?: number }>} [input.remotes]
+ * @returns {{ unpublished: object[], behind: object[], repoMismatch: object[], registryOnly: object[], npmBehind: object[], remoteDown: object[] }}
+ */
+export function diffRegistry({ local, registry, npmLatest = {}, remotes = [] }) {
+ const reg = new Map(registry.map((r) => [r.name, r]));
+ const localNames = new Set(local.map((l) => l.name));
+ const out = {
+ unpublished: [],
+ behind: [],
+ repoMismatch: [],
+ registryOnly: [],
+ npmBehind: [],
+ remoteDown: [],
+ };
+
+ for (const l of local) {
+ const r = reg.get(l.name);
+ if (!r) {
+ out.unpublished.push({ name: l.name, version: l.version, dir: l.dir });
+ } else {
+ if (compareSemver(l.version, r.version) > 0) {
+ out.behind.push({ name: l.name, local: l.version, registry: r.version });
+ }
+ if (l.repoUrl && r.repoUrl && normRepo(l.repoUrl) !== normRepo(r.repoUrl)) {
+ out.repoMismatch.push({ name: l.name, local: l.repoUrl, registry: r.repoUrl });
+ }
+ }
+ if (l.npm) {
+ const published = npmLatest[l.npm.identifier];
+ if (published === null || published === undefined || compareSemver(l.npm.version, published) > 0) {
+ out.npmBehind.push({
+ name: l.name,
+ package: l.npm.identifier,
+ local: l.npm.version,
+ npm: published ?? null,
+ });
+ }
+ }
+ }
+
+ for (const r of registry) {
+ if (!localNames.has(r.name)) out.registryOnly.push({ name: r.name, version: r.version });
+ }
+ for (const m of remotes) {
+ if (!m.ok) out.remoteDown.push({ name: m.name, url: m.url, status: m.status ?? null });
+ }
+
+ for (const list of Object.values(out)) list.sort((a, b) => a.name.localeCompare(b.name));
+ return out;
+}
+
+/** Flat, stable `kind:name` keys, so "changed since last run" is a set comparison. */
+export function findingKeys(diff) {
+ const kinds = {
+ unpublished: 'unpublished',
+ behind: 'behind',
+ repoMismatch: 'repo_mismatch',
+ registryOnly: 'registry_only',
+ npmBehind: 'npm_behind',
+ remoteDown: 'remote_down',
+ };
+ const keys = [];
+ for (const [field, kind] of Object.entries(kinds)) {
+ for (const f of diff[field]) keys.push(`${kind}:${f.name}`);
+ }
+ return keys.sort();
+}
+
+/** @returns {{ added: string[], resolved: string[] }} */
+export function changedSince(previousKeys, currentKeys) {
+ const prev = new Set(previousKeys || []);
+ const cur = new Set(currentKeys);
+ return {
+ added: currentKeys.filter((k) => !prev.has(k)),
+ resolved: [...prev].filter((k) => !cur.has(k)).sort(),
+ };
+}
+
+export function alertDetail(diff, added) {
+ const lines = [];
+ const addedSet = new Set(added);
+ const line = (kind, f, text) => {
+ if (addedSet.has(`${kind}:${f.name}`)) lines.push(`${kind}: ${f.name} ${text}`);
+ };
+ for (const f of diff.unpublished) line('unpublished', f, `(local ${f.version}, ${f.dir})`);
+ for (const f of diff.behind) line('behind', f, `(local ${f.local}, registry ${f.registry})`);
+ for (const f of diff.repoMismatch) line('repo_mismatch', f, `(local ${f.local}, registry ${f.registry})`);
+ for (const f of diff.npmBehind) line('npm_behind', f, `(${f.package} local ${f.local}, npm ${f.npm ?? 'missing'})`);
+ for (const f of diff.registryOnly) line('registry_only', f, `(registry ${f.version}, no local server.json)`);
+ for (const f of diff.remoteDown) line('remote_down', f, `(${f.url}, status ${f.status ?? 'unreachable'})`);
+ return lines.join('\n');
+}
diff --git a/api/cron/mcp-registry-sentinel.js b/api/cron/mcp-registry-sentinel.js
new file mode 100644
index 000000000..610d66f23
--- /dev/null
+++ b/api/cron/mcp-registry-sentinel.js
@@ -0,0 +1,207 @@
+// GET /api/cron/mcp-registry-sentinel: daily diff of our MCP servers against
+// the official MCP registry and npm.
+//
+// Reads every local server.json at runtime (repo root, mcp-bridge, mcp-server,
+// packages/*, robinhood/*, services/*), pages the registry's latest entries for
+// our namespace (following metadata.nextCursor), looks up npm latest versions,
+// probes each hosted remote, and reports: unpublished, behind, repository URL
+// mismatch, registry-only names we do not track, npm behind/missing, remote down.
+//
+// An ops alert fires only when the finding set changed since the last run (the
+// previous keys live in app_settings), so a standing gap alerts once, not daily.
+// Diff logic: api/_lib/mcp-registry-sentinel.js. Ops doc: docs/mcp-registry-sentinel.md.
+
+import { readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { json, wrapCron, method, error } from '../_lib/http.js';
+import { requireCron } from '../_lib/cron-auth.js';
+import { sql } from '../_lib/db.js';
+import { sendOpsAlert } from '../_lib/alerts.js';
+import {
+ NAMESPACE,
+ diffRegistry,
+ findingKeys,
+ changedSince,
+ alertDetail,
+} from '../_lib/mcp-registry-sentinel.js';
+
+const REGISTRY = 'https://registry.modelcontextprotocol.io/v0/servers';
+const NPM = 'https://registry.npmjs.org';
+const STATE_KEY = 'mcp_registry_sentinel';
+const MAX_PAGES = 20;
+const CONCURRENCY = 8;
+const ROOT = process.cwd();
+const SUBDIR_PARENTS = ['packages', 'robinhood', 'services'];
+
+async function readManifest(dir) {
+ try {
+ const raw = JSON.parse(await readFile(path.join(ROOT, dir, 'server.json'), 'utf8'));
+ if (typeof raw.name !== 'string' || !raw.name.startsWith(NAMESPACE)) return null;
+ const npmPkg = (raw.packages || []).find((p) => p.registryType === 'npm');
+ return {
+ name: raw.name,
+ version: String(raw.version || ''),
+ repoUrl: raw.repository?.url,
+ dir: dir || '.',
+ npm: npmPkg ? { identifier: npmPkg.identifier, version: String(npmPkg.version || raw.version || '') } : undefined,
+ remotes: (raw.remotes || []).filter((r) => r.url),
+ };
+ } catch {
+ return null;
+ }
+}
+
+export async function readLocalManifests() {
+ const dirs = ['', 'mcp-bridge', 'mcp-server'];
+ for (const parent of SUBDIR_PARENTS) {
+ try {
+ const entries = await readdir(path.join(ROOT, parent), { withFileTypes: true });
+ for (const e of entries) if (e.isDirectory()) dirs.push(`${parent}/${e.name}`);
+ } catch {
+ /* parent absent in this build */
+ }
+ }
+ const found = await Promise.all(dirs.map(readManifest));
+ return found.filter(Boolean);
+}
+
+export async function fetchRegistryLatest(fetchImpl = fetch) {
+ const out = [];
+ let cursor = '';
+ for (let page = 0; page < MAX_PAGES; page++) {
+ const url = `${REGISTRY}?search=${encodeURIComponent(NAMESPACE.slice(0, -1))}&version=latest&limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ''}`;
+ const r = await fetchImpl(url, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(20_000) });
+ if (!r.ok) throw new Error(`registry ${r.status}`);
+ const body = await r.json();
+ for (const item of body.servers || []) {
+ const s = item.server;
+ if (!s?.name?.startsWith(NAMESPACE)) continue;
+ const meta = item._meta?.['io.modelcontextprotocol.registry/official'];
+ if (meta && meta.isLatest === false) continue;
+ out.push({ name: s.name, version: String(s.version || ''), repoUrl: s.repository?.url });
+ }
+ cursor = body.metadata?.nextCursor || '';
+ if (!cursor) return out;
+ }
+ throw new Error(`registry pagination exceeded ${MAX_PAGES} pages`);
+}
+
+async function npmLatestVersion(pkg, fetchImpl = fetch) {
+ const r = await fetchImpl(`${NPM}/${pkg.replace('/', '%2f')}/latest`, {
+ headers: { accept: 'application/json' },
+ signal: AbortSignal.timeout(15_000),
+ });
+ if (r.status === 404) return null;
+ if (!r.ok) throw new Error(`npm ${r.status} for ${pkg}`);
+ return String((await r.json()).version || '') || null;
+}
+
+async function probeRemote(name, url) {
+ try {
+ const r = await fetch(url, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream' },
+ body: JSON.stringify({
+ jsonrpc: '2.0',
+ id: 1,
+ method: 'initialize',
+ params: { protocolVersion: '2025-03-26', capabilities: {}, clientInfo: { name: 'three-ws-registry-sentinel', version: '1.0.0' } },
+ }),
+ signal: AbortSignal.timeout(10_000),
+ });
+ return { name, url, ok: r.status < 500 && r.status !== 404, status: r.status };
+ } catch {
+ return { name, url, ok: false };
+ }
+}
+
+async function pool(items, fn) {
+ const results = new Array(items.length);
+ let next = 0;
+ await Promise.all(
+ Array.from({ length: Math.min(CONCURRENCY, items.length) }, async () => {
+ while (next < items.length) {
+ const i = next++;
+ results[i] = await fn(items[i]);
+ }
+ }),
+ );
+ return results;
+}
+
+async function loadPrevious() {
+ try {
+ const [row] = await sql`SELECT value FROM app_settings WHERE key = ${STATE_KEY}`;
+ return row?.value?.keys ?? null;
+ } catch {
+ return null;
+ }
+}
+
+async function saveState(keys) {
+ await sql`
+ INSERT INTO app_settings (key, value) VALUES (${STATE_KEY}, ${JSON.stringify({ keys, at: new Date().toISOString() })}::jsonb)
+ ON CONFLICT (key) DO UPDATE SET value = excluded.value, updated_at = now()
+ `;
+}
+
+export default wrapCron(async (req, res) => {
+ if (!method(req, res, ['GET', 'POST'])) return;
+ if (!requireCron(req, res)) return;
+
+ const local = await readLocalManifests();
+ if (!local.length) {
+ return error(res, 500, 'no_local_manifests', 'no server.json found under the working directory; refusing to run');
+ }
+
+ let registry;
+ try {
+ registry = await fetchRegistryLatest();
+ } catch (err) {
+ return error(res, 502, 'registry_unreachable', err.message);
+ }
+
+ const packages = [...new Set(local.filter((l) => l.npm).map((l) => l.npm.identifier))];
+ const npmLatest = {};
+ const npmErrors = [];
+ await pool(packages, async (pkg) => {
+ try {
+ npmLatest[pkg] = await npmLatestVersion(pkg);
+ } catch (err) {
+ npmErrors.push(err.message);
+ }
+ });
+ // A failed npm lookup must not read as "missing on npm": drop the npm leg for that entry only.
+ const lookedUp = local.map((l) => (l.npm && !npmLookedUp(npmLatest, l.npm.identifier) ? { ...l, npm: undefined } : l));
+
+ const remoteTargets = local.flatMap((l) => l.remotes.map((r) => ({ name: l.name, url: r.url })));
+ const remotes = await pool(remoteTargets, (t) => probeRemote(t.name, t.url));
+
+ const diff = diffRegistry({ local: lookedUp, registry, npmLatest, remotes });
+ const keys = findingKeys(diff);
+ const previous = await loadPrevious();
+ const { added, resolved } = changedSince(previous, keys);
+
+ if (added.length) {
+ await sendOpsAlert(
+ `MCP registry sentinel: ${added.length} new finding${added.length === 1 ? '' : 's'}`,
+ alertDetail(diff, added),
+ { severity: 'warn', signature: `mcp-registry-sentinel:${added.join(',')}` },
+ );
+ }
+ if (added.length || resolved.length || previous === null) await saveState(keys);
+
+ return json(res, 200, {
+ ok: true,
+ local: local.length,
+ registry: registry.length,
+ findings: diff,
+ alerted: added,
+ resolved,
+ npm_errors: npmErrors,
+ });
+});
+
+function npmLookedUp(npmLatest, id) {
+ return Object.prototype.hasOwnProperty.call(npmLatest, id);
+}
diff --git a/scripts/lib/mcp-trust.mjs b/scripts/lib/mcp-trust.mjs
new file mode 100644
index 000000000..f9b252192
--- /dev/null
+++ b/scripts/lib/mcp-trust.mjs
@@ -0,0 +1,196 @@
+// Trust grade for every server in the MCP catalog.
+//
+// A visitor to /mcp-tools cannot tell a polished, published, tested server from
+// a stub, so each server gets a 0-100 score built from facts this repo can check
+// mechanically, and a letter grade from that score. Every fact carries a fixed
+// weight (FACTS below, documented in docs/mcp.md), and the catalog stores the
+// whole breakdown so the page can show exactly why a server earned its grade.
+//
+// Everything here reads the working tree and the catalog payload only, so the
+// build stays offline-safe and byte-reproducible. Facts that need the network
+// (is the npm version live, does the registry list it, does the hosted endpoint
+// answer) belong to the registry sentinel, which stores its own results; this
+// rubric scores the local evidence that a server is ready to be published.
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { ROOT } from './mcp-tool-sources.mjs';
+
+/** Fact id, weight, and the one-line reading shown in the tooltip. Weights sum to 100. */
+export const FACTS = [
+ { id: 'tools', weight: 15, label: 'Declares at least one tool' },
+ { id: 'toolDocs', weight: 5, label: 'Every tool has a description' },
+ { id: 'safety', weight: 15, label: 'Every tool carries read-only and destructive safety annotations' },
+ { id: 'distribution', weight: 15, label: 'Installable: npm package ready to publish, or hosted endpoint mounted' },
+ { id: 'registry', weight: 10, label: 'Has a server.json for the official MCP registry' },
+ { id: 'readme', weight: 10, label: 'Documented: README or a guide in docs/' },
+ { id: 'license', weight: 10, label: 'License file present' },
+ { id: 'tests', weight: 5, label: 'Has tests' },
+ { id: 'prompts', weight: 5, label: 'Declares prompts' },
+ { id: 'resources', weight: 5, label: 'Declares resources or resource templates' },
+ { id: 'glama', weight: 5, label: 'Glama maintainer claim present' },
+];
+
+/** Lowest score for each grade, best first. */
+export const GRADES = [
+ ['A', 85],
+ ['B', 70],
+ ['C', 50],
+ ['D', 30],
+ ['F', 0],
+];
+
+export const gradeFor = (score) => GRADES.find(([, min]) => score >= min)[0];
+
+/** Hosted servers have no package directory, so their guides are named here. */
+const REMOTE_DOCS = {
+ mcp: 'docs/mcp.md',
+ 'mcp-agent': 'docs/mcp-agent.md',
+ 'mcp-3d': 'docs/mcp-3d-studio.md',
+ 'mcp-bazaar': 'docs/mcp-x402-bazaar.md',
+ 'ibm-mcp': 'docs/ibm-x402-mcp.md',
+ 'mcp-studio': 'docs/mcp-studio.md',
+ 'mcp-grok': 'docs/grok-bot.md',
+ 'pump-fun-mcp': 'docs/pump-fun-mcp-edge.md',
+};
+
+const has = (rel) => existsSync(join(ROOT, rel));
+const readJson = (rel) => {
+ try {
+ return JSON.parse(readFileSync(join(ROOT, rel), 'utf8'));
+ } catch {
+ return null;
+ }
+};
+
+/** Every server.json the repo publishes, outside agent worktrees and dependencies. */
+function registryManifests() {
+ const found = [];
+ const walk = (dir, depth) => {
+ if (depth > 3) return;
+ for (const entry of readdirSync(join(ROOT, dir), { withFileTypes: true })) {
+ if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+ const rel = dir ? `${dir}/${entry.name}` : entry.name;
+ if (entry.isDirectory()) walk(rel, depth + 1);
+ else if (entry.name === 'server.json') {
+ const doc = readJson(rel);
+ if (doc) found.push(doc);
+ }
+ }
+ };
+ walk('', 0);
+ return found;
+}
+
+function testSources() {
+ const dir = join(ROOT, 'tests');
+ if (!existsSync(dir)) return [];
+ return readdirSync(dir)
+ .filter((f) => /\.test\.[cm]?js$/.test(f))
+ .map((f) => readFileSync(join(dir, f), 'utf8'));
+}
+
+function handlerFile(endpoint) {
+ for (const rel of [`${endpoint.slice(1)}.js`, `${endpoint.slice(1)}/index.js`]) if (has(rel)) return rel;
+ return null;
+}
+
+const dirHasTests = (dir) => {
+ for (const sub of ['test', 'tests']) {
+ if (has(`${dir}/${sub}`) && readdirSync(join(ROOT, dir, sub)).some((f) => /\.test\.[cm]?[jt]s$/.test(f))) return true;
+ }
+ return false;
+};
+
+/**
+ * Grade every server.
+ * @param {Array} servers allServers() output: id, transport, dir, endpoint, url, tools, resources, templates, prompts.
+ * @returns {Map<string, {score:number, grade:string, facts:Array}>}
+ */
+export function gradeServers(servers) {
+ const manifests = registryManifests();
+ const tests = testSources();
+ const glama = readJson('glama.json');
+ const glamaClaimed = Array.isArray(glama?.maintainers) && glama.maintainers.length > 0;
+ const rootPkg = readJson('package.json');
+ const out = new Map();
+
+ for (const s of servers) {
+ const remote = s.transport === 'remote';
+ const dir = remote ? null : s.dir;
+ const pkg = dir ? readJson(`${dir}/package.json`) : null;
+ const tools = s.tools || [];
+ const detail = {};
+ const pass = {};
+
+ pass.tools = tools.length > 0;
+ detail.tools = `${tools.length} tools`;
+
+ const undocumented = tools.filter((t) => !String(t.description || '').trim()).length;
+ pass.toolDocs = tools.length > 0 && undocumented === 0;
+ detail.toolDocs = undocumented ? `${undocumented} without a description` : 'all described';
+
+ const unannotated = tools.filter((t) => {
+ const a = t.annotations || {};
+ return typeof a.readOnlyHint !== 'boolean' || (a.readOnlyHint === false && typeof a.destructiveHint !== 'boolean');
+ }).length;
+ pass.safety = tools.length > 0 && unannotated === 0;
+ detail.safety = unannotated ? `${unannotated} tools missing hints` : 'all annotated';
+
+ if (remote) {
+ const file = handlerFile(s.endpoint);
+ pass.distribution = Boolean(file);
+ detail.distribution = file ? `handler ${file}` : 'no handler file found';
+ } else {
+ const ready = Boolean(pkg && pkg.name && pkg.version && !pkg.private && pkg.publishConfig?.access === 'public');
+ pass.distribution = ready;
+ detail.distribution = ready ? `${pkg.name}@${pkg.version}` : 'package.json is private or lacks publishConfig.access=public';
+ }
+
+ if (remote) {
+ pass.registry = manifests.some((m) => (m.remotes || []).some((r) => r.url === s.url));
+ detail.registry = pass.registry ? 'listed as a remote in a server.json' : 'no server.json lists this URL';
+ } else {
+ const manifest = readJson(`${dir}/server.json`);
+ const pkgEntry = (manifest?.packages || []).find((p) => p.identifier === pkg?.name);
+ pass.registry = Boolean(manifest?.name && pkgEntry && pkgEntry.version === pkg?.version);
+ detail.registry = pass.registry ? manifest.name : manifest ? 'server.json does not match package.json' : 'no server.json';
+ }
+
+ const doc = remote ? REMOTE_DOCS[s.id] : `${dir}/README.md`;
+ pass.readme = Boolean(doc && has(doc));
+ detail.readme = pass.readme ? doc : 'no README or guide';
+
+ const license = remote ? 'LICENSE' : `${dir}/LICENSE`;
+ pass.license = has(license) || Boolean(pkg?.license && has('LICENSE')) || (remote && Boolean(rootPkg?.license) && has('LICENSE'));
+ detail.license = pass.license ? 'present' : 'missing';
+
+ if (remote) {
+ const base = s.endpoint.slice(1);
+ const ref = new RegExp(`${base.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')}(?![-\\w/])`);
+ pass.tests = tests.some((t) => ref.test(t));
+ } else {
+ pass.tests = dirHasTests(dir);
+ }
+ detail.tests = pass.tests ? 'covered' : 'none found';
+
+ pass.prompts = (s.prompts || []).length > 0;
+ detail.prompts = `${(s.prompts || []).length} prompts`;
+ pass.resources = (s.resources || []).length + (s.templates || []).length > 0;
+ detail.resources = `${(s.resources || []).length} resources, ${(s.templates || []).length} templates`;
+ pass.glama = glamaClaimed;
+ detail.glama = glamaClaimed ? 'repository claimed' : 'no glama.json maintainers';
+
+ const facts = FACTS.map((f) => ({
+ id: f.id,
+ label: f.label,
+ weight: f.weight,
+ earned: pass[f.id] ? f.weight : 0,
+ detail: detail[f.id],
+ }));
+ const score = facts.reduce((sum, f) => sum + f.earned, 0);
+ out.set(s.id, { score, grade: gradeFor(score), facts });
+ }
+ return out;
+}
diff --git a/tests/mcp-registry-sentinel.test.js b/tests/mcp-registry-sentinel.test.js
new file mode 100644
index 000000000..5d000f982
--- /dev/null
+++ b/tests/mcp-registry-sentinel.test.js
@@ -0,0 +1,99 @@
+// Unit tests for the MCP registry sentinel: one case per finding type, the
+// change-detection that gates alerts, and registry cursor pagination.
+
+import { describe, it, expect, vi } from 'vitest';
+import {
+ diffRegistry,
+ findingKeys,
+ changedSince,
+ compareSemver,
+ alertDetail,
+} from '../api/_lib/mcp-registry-sentinel.js';
+import { fetchRegistryLatest } from '../api/cron/mcp-registry-sentinel.js';
+
+const REPO = 'https://github.com/nirholas/three.ws';
+const local = [
+ { name: 'io.github.nirholas/solana-memo-media-mcp', version: '0.1.0', repoUrl: REPO, dir: 'packages/solana-memo-media-mcp', npm: { identifier: '@three-ws/solana-memo-media-mcp', version: '0.1.0' } },
+ { name: 'io.github.nirholas/kol-mcp', version: '0.1.3', repoUrl: REPO, dir: 'packages/kol-mcp', npm: { identifier: '@three-ws/kol-mcp', version: '0.1.3' } },
+ { name: 'io.github.nirholas/moved-mcp', version: '1.0.0', repoUrl: REPO, dir: 'packages/moved-mcp' },
+ { name: 'io.github.nirholas/three.ws', version: '1.0.1', repoUrl: REPO, dir: '.' },
+];
+const registry = [
+ { name: 'io.github.nirholas/kol-mcp', version: '0.1.2', repoUrl: REPO },
+ { name: 'io.github.nirholas/moved-mcp', version: '1.0.0', repoUrl: 'https://github.com/nirholas/gone.git' },
+ { name: 'io.github.nirholas/three.ws', version: '1.0.1', repoUrl: `${REPO}.git` },
+ { name: 'io.github.nirholas/orphan-mcp', version: '2.0.0', repoUrl: REPO },
+];
+const npmLatest = { '@three-ws/solana-memo-media-mcp': null, '@three-ws/kol-mcp': '0.1.2' };
+const remotes = [
+ { name: 'io.github.nirholas/three.ws', url: 'https://three.ws/api/mcp', ok: true, status: 200 },
+ { name: 'io.github.nirholas/kol-mcp', url: 'https://example.invalid/mcp', ok: false },
+];
+
+describe('diffRegistry', () => {
+ const diff = diffRegistry({ local, registry, npmLatest, remotes });
+
+ it('lists a local server missing from the registry as unpublished', () => {
+ expect(diff.unpublished.map((f) => f.name)).toEqual(['io.github.nirholas/solana-memo-media-mcp']);
+ });
+ it('flags a local version newer than the registry as behind', () => {
+ expect(diff.behind).toEqual([{ name: 'io.github.nirholas/kol-mcp', local: '0.1.3', registry: '0.1.2' }]);
+ });
+ it('flags a repository URL mismatch and ignores a trailing .git', () => {
+ expect(diff.repoMismatch.map((f) => f.name)).toEqual(['io.github.nirholas/moved-mcp']);
+ });
+ it('lists registry names with no local manifest', () => {
+ expect(diff.registryOnly.map((f) => f.name)).toEqual(['io.github.nirholas/orphan-mcp']);
+ });
+ it('flags npm missing or older than the local package version', () => {
+ expect(diff.npmBehind.map((f) => [f.package, f.npm])).toEqual([
+ ['@three-ws/kol-mcp', '0.1.2'],
+ ['@three-ws/solana-memo-media-mcp', null],
+ ]);
+ });
+ it('flags an unreachable hosted remote', () => {
+ expect(diff.remoteDown).toEqual([{ name: 'io.github.nirholas/kol-mcp', url: 'https://example.invalid/mcp', status: null }]);
+ });
+ it('reports nothing for a fully published, in-sync server', () => {
+ const clean = diffRegistry({ local: [local[3]], registry: [registry[2]], npmLatest: {}, remotes: [remotes[0]] });
+ expect(findingKeys(clean)).toEqual([]);
+ });
+});
+
+describe('changedSince', () => {
+ it('alerts only on new keys and reports resolved ones', () => {
+ expect(changedSince(['a', 'b'], ['b', 'c'])).toEqual({ added: ['c'], resolved: ['a'] });
+ expect(changedSince(['a'], ['a'])).toEqual({ added: [], resolved: [] });
+ });
+ it('treats a first run as all-new', () => {
+ expect(changedSince(null, ['a']).added).toEqual(['a']);
+ });
+ it('limits alert text to added findings', () => {
+ const diff = diffRegistry({ local, registry, npmLatest, remotes });
+ const text = alertDetail(diff, ['unpublished:io.github.nirholas/solana-memo-media-mcp']);
+ expect(text).toContain('solana-memo-media-mcp');
+ expect(text).not.toContain('orphan');
+ });
+});
+
+describe('compareSemver', () => {
+ it('orders numerically, not lexically', () => {
+ expect(compareSemver('0.10.0', '0.9.0')).toBe(1);
+ expect(compareSemver('1.0.0', '1.0.0')).toBe(0);
+ expect(compareSemver('x', '1.0.0')).toBe(0);
+ });
+});
+
+describe('fetchRegistryLatest', () => {
+ const entry = (name, extra = {}) => ({ server: { name, version: '1.0.0', repository: { url: REPO } }, _meta: { 'io.modelcontextprotocol.registry/official': { isLatest: true, ...extra } } });
+ it('follows nextCursor until empty and skips foreign namespaces and non-latest rows', async () => {
+ const pages = [
+ { servers: [entry('io.github.nirholas/a'), entry('io.github.other/x')], metadata: { nextCursor: 'c1' } },
+ { servers: [entry('io.github.nirholas/b'), entry('io.github.nirholas/old', { isLatest: false })], metadata: {} },
+ ];
+ const fetchImpl = vi.fn(async () => ({ ok: true, json: async () => pages.shift() }));
+ const out = await fetchRegistryLatest(fetchImpl);
+ expect(out.map((e) => e.name)).toEqual(['io.github.nirholas/a', 'io.github.nirholas/b']);
+ expect(fetchImpl.mock.calls[1][0]).toContain('cursor=c1');
+ });
+});
diff --git a/vercel.json b/vercel.json
index 38fe24574..c564bc58e 100644
--- a/vercel.json
+++ b/vercel.json
@@ -7143,6 +7143,10 @@
"path": "/api/cron/x402-directory-registrar",
"schedule": "23 * * * *"
},
+ {
+ "path": "/api/cron/mcp-registry-sentinel",
+ "schedule": "41 6 * * *"
+ },
{
"path": "/api/cron/relayer-balance-check",
"schedule": "0 */6 * * *"