mcplane 0.1.0

package/dist/checks/tools.js

@@ -0,0 +1,122 @@
+const HINTS = ['readOnlyHint', 'destructiveHint', 'openWorldHint'];
+/** Phrases that read as instructions to the model rather than a description of the tool. */
+const INSTRUCTION = [
+    /\byou (must|should|always|never)\b/i,
+    /\balways (call|use|run)\b/i,
+    /\bnever (call|use|tell|mention)\b/i,
+    /\bignore (previous|prior|other|all)\b/i,
+    /\b(before|after) (calling|using) (this|any|another) tool\b/i,
+    /\buse this tool (whenever|for every|for all)\b/i,
+    /\bdo not (tell|inform|mention)\b/i,
+    /\bonly (call|use) (this|it|with|when)\b/i,
+    /\b(call|use) (this|it) only\b/i,
+];
+/** Plan and pricing copy. OpenAI prohibits in-app upsells, "including freemium upsells". */
+const UPSELL = /\b(upgrade|pro plan|premium|paid plan|pricing|subscribe|subscription|free trial|unlock)\b/i;
+/** Inputs that suggest a write authorised only by a secret passed through the chat. */
+const BEARER_INPUT = /^(token|edit_token|update_token|secret|access_key|api_key|password)$/i;
+export function toolChecks(tools) {
+    if (!tools.length)
+        return [];
+    const checks = [];
+    const names = new Set(tools.map((t) => t.name));
+    const noTitle = tools.filter((t) => !t.title && !t.annotations?.title);
+    checks.push(noTitle.length
+        ? { id: 'tools.title', level: 'fail', title: 'Every tool has a human-readable title', detail: noTitle.map((t) => t.name).join(', '), fix: 'Add "title" (or annotations.title) to each tool. Anthropic rejects connectors without them.', stores: ['claude-connectors', 'claude-plugins'] }
+        : { id: 'tools.title', level: 'pass', title: 'Every tool has a human-readable title' });
+    const missing = tools.flatMap((t) => HINTS.filter((h) => typeof t.annotations?.[h] !== 'boolean').map((h) => `${t.name}.${h}`));
+    checks.push(missing.length
+        ? {
+            id: 'tools.hints',
+            level: 'fail',
+            title: 'Safety annotations are explicit on every tool',
+            detail: missing.join(', '),
+            fix: 'Set readOnlyHint, destructiveHint and openWorldHint to true or false on every tool. ChatGPT asks you to justify each explicit value and flags missing ones; Claude checks them against your read/write answer.',
+            stores: ['chatgpt', 'claude-connectors'],
+        }
+        : { id: 'tools.hints', level: 'pass', title: 'Safety annotations are explicit on every tool' });
+    const contradictory = tools.filter((t) => t.annotations?.readOnlyHint === true && t.annotations?.destructiveHint === true);
+    if (contradictory.length) {
+        checks.push({ id: 'tools.hints-consistent', level: 'fail', title: 'Annotations are consistent', detail: `read-only yet destructive: ${contradictory.map((t) => t.name).join(', ')}`, fix: 'A read-only tool cannot be destructive.' });
+    }
+    const noOutput = tools.filter((t) => !t.outputSchema);
+    checks.push(noOutput.length
+        ? { id: 'tools.output-schema', level: 'warn', title: 'Tools declare an outputSchema', detail: noOutput.map((t) => t.name).join(', '), fix: 'Declare outputSchema and return structuredContent that matches it. ChatGPT recommends it on every tool during review.', stores: ['chatgpt'] }
+        : { id: 'tools.output-schema', level: 'pass', title: 'Tools declare an outputSchema' });
+    const instructing = tools.flatMap((t) => {
+        const text = `${t.description ?? ''}`;
+        const hits = INSTRUCTION.filter((re) => re.test(text)).map((re) => text.match(re)[0]);
+        const others = [...names].filter((n) => n !== t.name && text.includes(n));
+        return hits.length || others.length ? [`${t.name}: ${[...hits.map((h) => `"${h}"`), ...others.map((n) => `mentions ${n}`)].join(', ')}`] : [];
+    });
+    checks.push(instructing.length
+        ? {
+            id: 'tools.no-instructions',
+            level: 'warn',
+            title: 'Descriptions describe the tool, not the model’s behaviour',
+            detail: instructing.join('; '),
+            fix: "Anthropic's submission asks you to confirm tool descriptions contain no instructions about model behaviour or other tools. Rephrase as facts about what the tool does, or explain the line in the form's Additional notes.",
+            stores: ['claude-connectors', 'claude-plugins'],
+        }
+        : { id: 'tools.no-instructions', level: 'pass', title: 'Descriptions describe the tool, not the model’s behaviour' });
+    const bearer = tools.filter((t) => t.annotations?.readOnlyHint !== true && Object.keys(t.inputSchema?.properties ?? {}).some((k) => BEARER_INPUT.test(k)));
+    checks.push(bearer.length
+        ? {
+            id: 'tools.bearer-writes',
+            level: 'fail',
+            title: 'Writes are bound to an owner, not a token in the chat',
+            detail: bearer.map((t) => t.name).join(', '),
+            fix: 'Anthropic rejected a write tool authorised only by a token passed through the conversation ("anyone who obtains or guesses a token can rewrite"). Put writes behind OAuth, or move them to your site and email the owner a private link.',
+            stores: ['claude-connectors'],
+        }
+        : { id: 'tools.bearer-writes', level: 'pass', title: 'Writes are bound to an owner, not a token in the chat' });
+    // OpenAI: openWorldHint is true for tools that reach the public internet or open-ended external entities,
+    // read-only ones like web search included, and for writes that post, send, publish, push or submit.
+    const openWorld = tools.filter((t) => t.annotations?.openWorldHint === false &&
+        /\b(send|sends|sent|e-?mail(s|ed)?|post|posts|publish|publishes|public|tweet|message|notify|notifies|web search|search the web|internet|any url|fetch(es)? (a |the |any )?url|scrape|scrapes|crawl|crawls)\b/i.test(`${t.description ?? ''} ${Object.keys(t.inputSchema?.properties ?? {}).join(' ')}`));
+    checks.push(openWorld.length
+        ? {
+            id: 'tools.open-world',
+            level: 'warn',
+            title: 'openWorldHint matches what the tool does',
+            detail: `${openWorld.map((t) => t.name).join(', ')}: openWorldHint is false, but the tool seems to send, post or publish`,
+            fix: 'OpenAI: set openWorldHint to true "if the tool accesses the public internet or open-ended external entities", including read-only tools such as web search and tools that post, send messages to external recipients, publish, push code or submit forms. False only when it is limited to a bounded private account or workspace.',
+            stores: ['chatgpt'],
+        }
+        : { id: 'tools.open-world', level: 'pass', title: 'openWorldHint matches what the tool does' });
+    // OpenAI: destructiveHint is true for irreversible outcomes, "sending messages or transactions you can't undo" included.
+    const sends = tools.filter((t) => t.annotations?.destructiveHint === false && t.annotations?.readOnlyHint !== true && /\b(sends?|sent|e-?mail(s|ed)?|sms|texts?|messag(es?|ed)|notif(y|ies|ied)|transfers?|pays?|payments?)\b/i.test(t.description ?? ''));
+    if (sends.length) {
+        checks.push({
+            id: 'tools.destructive-send',
+            level: 'warn',
+            title: 'destructiveHint covers messages that can’t be unsent',
+            detail: `${sends.map((t) => t.name).join(', ')}: destructiveHint is false, but the tool seems to send something`,
+            fix: 'OpenAI sets destructiveHint to true for tools that can cause irreversible outcomes, "sending messages or transactions you can\'t undo" included, even through default parameters. If a user can\'t take it back, set it to true and say in the justification what safeguards exist (confirmation, scoping).',
+            stores: ['chatgpt'],
+        });
+    }
+    const long = tools.filter((t) => t.name.length > 64);
+    if (long.length)
+        checks.push({ id: 'tools.name-length', level: 'fail', title: 'Tool names are 64 characters or fewer', detail: long.map((t) => t.name).join(', '), fix: 'Anthropic’s review criteria cap tool names at 64 characters.', stores: ['claude-connectors', 'claude-plugins'] });
+    // A tool that takes an HTTP method and a path is one tool doing both reads and writes.
+    const catchAll = tools.filter((t) => {
+        const keys = Object.keys(t.inputSchema?.properties ?? {}).map((k) => k.toLowerCase());
+        return keys.some((k) => k === 'method' || k === 'http_method' || k === 'verb') && keys.some((k) => /^(path|endpoint|url|route)$/.test(k));
+    });
+    if (catchAll.length) {
+        checks.push({ id: 'tools.catch-all', level: 'warn', title: 'No catch-all request tool', detail: catchAll.map((t) => t.name).join(', '), fix: 'Anthropic rejects a single tool that makes any API call (e.g. api_request with a method parameter). Split it into read tools and write tools with honest hints.', stores: ['claude-connectors'] });
+    }
+    // Inputs that ask for data OpenAI treats as sensitive.
+    const sensitive = tools.flatMap((t) => Object.keys(t.inputSchema?.properties ?? {})
+        .filter((k) => /(ssn|social_security|passport|national_id|tax_id|credit_card|card_number|cvv|iban|password|mfa|otp|2fa|diagnos|medical|health_record|biometric|fingerprint)/i.test(k))
+        .map((k) => `${t.name}.${k}`));
+    if (sensitive.length) {
+        checks.push({ id: 'tools.sensitive-inputs', level: 'fail', title: 'Tools don’t ask for sensitive data', detail: sensitive.join(', '), fix: 'OpenAI flags inputs that request PHI, card data, SSNs, credentials, MFA codes, government IDs or biometrics unless strictly necessary. Remove them or justify them in the submission.', stores: ['chatgpt'] });
+    }
+    const upsell = tools.filter((t) => UPSELL.test(`${t.title ?? ''} ${t.annotations?.title ?? ''} ${t.description ?? ''}`));
+    checks.push(upsell.length
+        ? { id: 'tools.no-upsell', level: 'fail', title: 'No upgrade or pricing copy in tools', detail: upsell.map((t) => t.name).join(', '), fix: 'OpenAI prohibits in-app commerce for digital subscriptions, including freemium upsells. Keep plans and pricing on your site; tool text and errors should not steer users to upgrade.', stores: ['chatgpt'] }
+        : { id: 'tools.no-upsell', level: 'pass', title: 'No upgrade or pricing copy in tools' });
+    return checks;
+}

package/dist/cli.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+import { writeFile, access } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+import { MANIFEST_FILE, draftManifest, loadManifest } from './manifest.js';
+import { VERSION } from './version.js';
+import { preflight } from './preflight.js';
+import { printPreflight } from './report.js';
+import { STORE_NAMES } from './types.js';
+import { recordDecision, recordSubmitted, status } from './submissions.js';
+import { chatgptPack, claudePack, directoriesPack, simplePack, writePack } from './packs.js';
+import { drift, printDrift, takeSnapshot } from './drift.js';
+import { publish } from './publish.js';
+import { lanes, pull, runLane, tryLinks } from './extras.js';
+import { fleet, fleetRun, printFleet } from './fleet.js';
+const HELP = `mcplane: fastlane for MCP servers
+
+Usage
+  mcplane init --url <mcp url>        Create mcplane.json from your live server
+  mcplane preflight [--store <id>]... Check against every store's rejection causes
+      --url <mcp url>                 Check a server without a manifest
+      --json                          Machine-readable output (exit 1 on blockers)
+      --verbose                       List passing checks too
+      --register                      Also test OAuth client registration (writes test clients)
+      --token <token>                 Access token for servers behind sign-in (or MCPLANE_TOKEN)
+  mcplane submitted <store>           Record a submission and log it to Review Times
+      --date YYYY-MM-DD --kind new|update|resubmission --version x.y.z
+      --app-id asdk_app_...           ChatGPT: your app id, so its draft date is checked
+      --private                       Keep it local; don't log to Review Times
+  mcplane decided <store> approved|rejected|withdrawn [--date YYYY-MM-DD]
+  mcplane status                      Every submission, how long it's waited, and the store's typical wait
+  mcplane pack <store>                Write a submission pack to .mcplane/packs (chatgpt, claude-connectors, cursor, muse, directories)
+  mcplane drift [--store <id>]...     What changed since each store saw your server, and what each needs
+      --ci                            Exit 1 when a store needs a new version or an edit
+  mcplane baseline <store> [--version x.y.z]   Record a listing that's already live as the drift baseline
+  mcplane publish <store> [--yes]     Publish where the store allows it (mcp-registry, grok); dry run without --yes
+  mcplane try                         Install links for every client, for you and your testers
+  mcplane pull                        Compare your live public listings with mcplane.json
+  mcplane lanes                       List lanes; run one with "mcplane <lane>" (built in: check, release)
+  mcplane fleet [--root <dir>]        Every project under a folder: blockers, store updates needed, reviews waiting
+      --quick                         Skip the live checks; just submissions
+  mcplane fleet run <command...>      Run any mcplane command in every project (e.g. fleet run publish mcp-registry --yes)
+  mcplane mcp                         Run as an MCP server over stdio (claude mcp add mcplane -- npx -y mcplane mcp)
+
+Stores: ${Object.keys(STORE_NAMES).join(', ')}
+`;
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    // Everything after "fleet run" belongs to the command being run, so it's passed through untouched.
+    if (cmd === 'fleet' && rest[0] === 'run') {
+        const i = rest.indexOf('--root');
+        const root = i > 0 ? rest[i + 1] : process.cwd();
+        const args = i > 0 ? [...rest.slice(1, i), ...rest.slice(i + 2)] : rest.slice(1);
+        if (!args.length)
+            throw new Error('Which command? e.g. mcplane fleet run preflight');
+        process.exitCode = await fleetRun(root, args);
+        return;
+    }
+    const { values, positionals } = parseArgs({
+        args: rest,
+        options: {
+            url: { type: 'string' },
+            store: { type: 'string', multiple: true },
+            json: { type: 'boolean' },
+            verbose: { type: 'boolean' },
+            register: { type: 'boolean' },
+            token: { type: 'string' },
+            date: { type: 'string' },
+            kind: { type: 'string' },
+            version: { type: 'string' },
+            'app-id': { type: 'string' },
+            private: { type: 'boolean' },
+            ci: { type: 'boolean' },
+            root: { type: 'string' },
+            quick: { type: 'boolean' },
+            yes: { type: 'boolean' },
+        },
+        allowPositionals: true,
+    });
+    const asStore = (v) => {
+        if (!v || !(v in STORE_NAMES))
+            throw new Error(`Which store? One of: ${Object.keys(STORE_NAMES).join(', ')}`);
+        return v;
+    };
+    if (cmd === 'mcp') {
+        const { serve } = await import('./mcp-server.js');
+        await serve();
+        return;
+    }
+    if (cmd === '--version' || cmd === '-v') {
+        console.log(VERSION);
+        return;
+    }
+    if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+        console.log(HELP);
+        return;
+    }
+    if (cmd === 'init') {
+        if (!values.url)
+            throw new Error('mcplane init needs --url <your MCP server URL>');
+        const exists = await access(MANIFEST_FILE).then(() => true, () => false);
+        if (exists)
+            throw new Error(`${MANIFEST_FILE} already exists.`);
+        const m = await draftManifest(values.url);
+        await writeFile(MANIFEST_FILE, JSON.stringify(m, null, 2) + '\n');
+        console.log(`Wrote ${MANIFEST_FILE}. Fill in the blanks, then run "mcplane preflight".`);
+        return;
+    }
+    if (cmd === 'preflight') {
+        const m = values.url ? await draftManifest(values.url) : await loadManifest();
+        const stores = (values.store ?? []);
+        for (const s of stores)
+            if (!(s in STORE_NAMES))
+                throw new Error(`Unknown store "${s}". Stores: ${Object.keys(STORE_NAMES).join(', ')}`);
+        const r = await preflight(m, { stores, register: values.register, token: values.token ?? process.env.MCPLANE_TOKEN });
+        if (values.json)
+            console.log(JSON.stringify(r, null, 2));
+        else
+            printPreflight(r, { verbose: values.verbose });
+        process.exitCode = r.checks.some((c) => c.level === 'fail') ? 1 : 0;
+        return;
+    }
+    if (cmd === 'submitted') {
+        const m = await loadManifest();
+        const store = asStore(positionals[0]);
+        const kind = (values.kind ?? 'new');
+        const { submission, note } = await recordSubmitted(m, store, { date: values.date, kind, version: values.version, appId: values['app-id'], share: !values.private, token: values.token ?? process.env.MCPLANE_TOKEN });
+        console.log(`Recorded: ${STORE_NAMES[store]}, submitted ${submission.submittedOn}${submission.version ? ` (v${submission.version})` : ''}.`);
+        console.log(note);
+        return;
+    }
+    if (cmd === 'decided') {
+        const store = asStore(positionals[0]);
+        const outcome = positionals[1];
+        if (!['approved', 'rejected', 'withdrawn'].includes(outcome))
+            throw new Error('Say how it went: approved, rejected or withdrawn.');
+        const s = await recordDecision(store, outcome, values.date);
+        console.log(`${STORE_NAMES[store]}: ${outcome} on ${s.decidedOn}, ${Math.round((Date.parse(s.decidedOn) - Date.parse(s.submittedOn)) / 86_400_000)} days after submitting.`);
+        return;
+    }
+    if (cmd === 'pack') {
+        const m = await loadManifest();
+        const store = positionals[0] === 'directories' ? null : asStore(positionals[0]);
+        const token = values.token ?? process.env.MCPLANE_TOKEN;
+        const pack = !store ? directoriesPack(m) : store === 'chatgpt' ? await chatgptPack(m, token) : store === 'claude-connectors' ? await claudePack(m, token) : await simplePack(m, store);
+        const written = await writePack(pack);
+        console.log(`Wrote ${written.join(', ')}`);
+        if (pack.problems.length) {
+            console.log('\nFix before submitting:');
+            for (const p of pack.problems)
+                console.log(`  ✗ ${p}`);
+        }
+        if (pack.todo.length) {
+            console.log('\nThen:');
+            for (const t of pack.todo)
+                console.log(`  • ${t}`);
+        }
+        process.exitCode = pack.problems.length ? 1 : 0;
+        return;
+    }
+    if (cmd === 'baseline') {
+        const m = await loadManifest();
+        const store = asStore(positionals[0]);
+        const snap = await takeSnapshot(m, store, { version: values.version, state: 'live', token: values.token ?? process.env.MCPLANE_TOKEN });
+        console.log(`Baseline for ${STORE_NAMES[store]}: ${snap.tools.length} tools${snap.repoSha ? `, repo at ${snap.repoSha.slice(0, 7)}` : ''}. "mcplane drift" now compares against this.`);
+        return;
+    }
+    if (cmd === 'drift') {
+        const m = await loadManifest();
+        const stores = (values.store?.length ? values.store : m.stores ?? Object.keys(STORE_NAMES));
+        const r = await drift(m, stores, { token: values.token ?? process.env.MCPLANE_TOKEN });
+        if (values.json)
+            console.log(JSON.stringify(r, null, 2));
+        else
+            printDrift(r);
+        if (values.ci && r.items.some((i) => i.level === 'action'))
+            process.exitCode = 1;
+        return;
+    }
+    if (cmd === 'status') {
+        const rows = await status();
+        if (!rows.length) {
+            console.log('No submissions recorded yet. After you submit, run "mcplane submitted <store>".');
+            return;
+        }
+        if (values.json) {
+            console.log(JSON.stringify(rows, null, 2));
+            return;
+        }
+        for (const r of rows) {
+            const s = r.submission;
+            const state = s.status === 'waiting' ? `waiting ${r.days} day${r.days === 1 ? '' : 's'}` : `${s.status} after ${r.days} day${r.days === 1 ? '' : 's'}`;
+            console.log(`${STORE_NAMES[s.store].padEnd(22)} ${s.submittedOn}  ${state}${s.version ? `  v${s.version}` : ''}`);
+            if (r.typical && s.status === 'waiting')
+                console.log(`${''.padEnd(22)} Store right now: ${r.typical}`);
+        }
+        return;
+    }
+    if (cmd === 'publish') {
+        const m = await loadManifest();
+        const store = asStore(positionals[0]);
+        const r = await publish(m, store, { yes: values.yes });
+        for (const l of r.lines)
+            if (l)
+                console.log(l);
+        if (r.done && values.yes && (store === 'mcp-registry' || store === 'grok')) {
+            const { note } = await recordSubmitted(m, store, { version: m.version, share: true }).catch(() => ({ note: '' }));
+            if (note)
+                console.log(note);
+        }
+        return;
+    }
+    if (cmd === 'fleet') {
+        const rows = await fleet(values.root ?? process.cwd(), { checks: !values.quick, token: values.token ?? process.env.MCPLANE_TOKEN });
+        if (values.json)
+            console.log(JSON.stringify(rows, null, 2));
+        else
+            printFleet(rows);
+        if (values.ci && rows.some((r) => r.error || r.blocking || r.driftActions?.length))
+            process.exitCode = 1;
+        return;
+    }
+    if (cmd === 'try') {
+        const m = await loadManifest();
+        for (const t of tryLinks(m))
+            console.log(`${t.client.padEnd(22)} ${t.how}`);
+        return;
+    }
+    if (cmd === 'pull') {
+        const m = await loadManifest();
+        const diffs = await pull(m);
+        if (values.json) {
+            console.log(JSON.stringify(diffs, null, 2));
+            return;
+        }
+        for (const d of diffs) {
+            if (!d.found)
+                console.log(`${d.store}: not listed yet.`);
+            else if (!d.fields.length)
+                console.log(`${d.store}: matches mcplane.json.`);
+            else {
+                console.log(`${d.store}: live listing differs${d.url ? ` (${d.url})` : ''}`);
+                for (const f of d.fields)
+                    console.log(`  ${f.field}\n    live:  ${f.live.slice(0, 160)}\n    yours: ${f.yours.slice(0, 160)}`);
+            }
+        }
+        return;
+    }
+    const m = await loadManifest().catch(() => null);
+    const all = m ? lanes(m) : lanes({ name: '', title: '', server: { url: '' } });
+    if (cmd === 'lanes') {
+        for (const [name, steps] of Object.entries(all))
+            console.log(`${name}: ${steps.map((s) => (s.startsWith('handoff:') ? '(you)' : s)).join(' → ')}`);
+        return;
+    }
+    if (all[cmd]) {
+        process.exitCode = runLane(cmd, all[cmd], values.token ? ['--token', values.token] : []);
+        return;
+    }
+    throw new Error(`Unknown command "${cmd}". Run "mcplane help".`);
+}
+main().catch((e) => {
+    console.error(`mcplane: ${e.message}`);
+    process.exitCode = 2;
+});

package/dist/drift.js

@@ -0,0 +1,207 @@
+/**
+ * Drift: what changed since each store last saw your server, and what each
+ * store needs because of it. A snapshot of tools and listing text is saved
+ * whenever you record a submission (or `mcplane baseline`); drift compares
+ * the live server and mcplane.json against it.
+ *
+ * Every store calls your live server, so behaviour fixes reach users on their
+ * own. What doesn't: listing text, tool names in Claude's listing, hint
+ * justifications, registry versions and plugins pinned to a commit.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { ensureLocalDir } from './manifest.js';
+import { McpClient } from './mcp-client.js';
+import { STORE_NAMES } from './types.js';
+const DIR = '.mcplane/snapshots';
+/** JSON with sorted keys, so reordering isn't a change. */
+function canon(v) {
+    if (v === undefined || v === null)
+        return '';
+    const sort = (x) => (Array.isArray(x) ? x.map(sort) : x && typeof x === 'object' ? Object.fromEntries(Object.keys(x).sort().map((k) => [k, sort(x[k])])) : x);
+    return JSON.stringify(sort(v));
+}
+function shape(t) {
+    return {
+        name: t.name,
+        title: t.title ?? t.annotations?.title,
+        description: t.description,
+        hints: { readOnly: t.annotations?.readOnlyHint, destructive: t.annotations?.destructiveHint, openWorld: t.annotations?.openWorldHint },
+        input: canon(t.inputSchema),
+        output: canon(t.outputSchema),
+    };
+}
+function listingOf(m) {
+    return {
+        title: m.title,
+        subtitle: m.subtitle,
+        oneLiner: m.oneLiner,
+        description: m.description,
+        icon: m.icon,
+        privacy: m.links?.privacy,
+        support: m.links?.support,
+        website: m.links?.website,
+    };
+}
+export async function liveTools(m, token) {
+    const c = new McpClient(m.server.url, token ? { authorization: `Bearer ${token}` } : {});
+    const init = await c.initialize();
+    if (init.status >= 400)
+        throw new Error(`Couldn't read tools from ${m.server.url} (HTTP ${init.status})${m.server.auth === 'oauth' ? '; pass --token' : ''}.`);
+    return ((await c.request('tools/list')).body?.result?.tools ?? []);
+}
+/** HEAD of the plugin repository on GitHub, when there is one. */
+export async function repoHead(repository) {
+    const gh = repository?.match(/github\.com\/([^/]+)\/([^/#?]+?)(?:\.git)?$/);
+    if (!gh)
+        return undefined;
+    const headers = { 'user-agent': 'mcplane', accept: 'application/vnd.github+json' };
+    if (process.env.GITHUB_TOKEN)
+        headers.authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+    const r = await fetch(`https://api.github.com/repos/${gh[1]}/${gh[2]}/commits/HEAD`, { headers }).catch(() => null);
+    return r?.ok ? (await r.json()).sha : undefined;
+}
+export async function takeSnapshot(m, store, opts, dir = process.cwd()) {
+    const [tools, repoSha] = await Promise.all([liveTools(m, opts.token), repoHead(m.repository)]);
+    const snap = {
+        store,
+        takenOn: new Date().toISOString().slice(0, 10),
+        version: opts.version,
+        state: opts.state,
+        tools: tools.map(shape),
+        listing: listingOf(m),
+        repoSha,
+    };
+    await ensureLocalDir(dir);
+    await mkdir(resolve(dir, DIR), { recursive: true });
+    await writeFile(resolve(dir, DIR, `${store}.json`), JSON.stringify(snap, null, 2) + '\n');
+    return snap;
+}
+export async function markLive(store, dir = process.cwd()) {
+    const snap = await readSnapshot(store, dir);
+    if (!snap)
+        return;
+    snap.state = 'live';
+    await writeFile(resolve(dir, DIR, `${store}.json`), JSON.stringify(snap, null, 2) + '\n');
+}
+async function readSnapshot(store, dir = process.cwd()) {
+    try {
+        return JSON.parse(await readFile(resolve(dir, DIR, `${store}.json`), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** What changed between a snapshot and now, as plain descriptions. */
+export function diffTools(before, now) {
+    const b = new Map(before.map((t) => [t.name, t]));
+    const n = new Map(now.map((t) => [t.name, t]));
+    const added = [...n.keys()].filter((k) => !b.has(k));
+    const removed = [...b.keys()].filter((k) => !n.has(k));
+    const changed = [];
+    for (const [name, t] of n) {
+        const o = b.get(name);
+        if (!o)
+            continue;
+        const fields = [];
+        for (const h of ['readOnly', 'destructive', 'openWorld'])
+            if (o.hints[h] !== t.hints[h])
+                fields.push(`${h}Hint ${o.hints[h]} → ${t.hints[h]}`);
+        if (o.input !== t.input)
+            fields.push('inputs');
+        if (o.output !== t.output)
+            fields.push('outputSchema');
+        if ((o.title ?? '') !== (t.title ?? ''))
+            fields.push('title');
+        if ((o.description ?? '') !== (t.description ?? ''))
+            fields.push('description');
+        if (fields.length)
+            changed.push({ tool: name, fields });
+    }
+    return { added, removed, changed };
+}
+/** Grok bumps pins daily; this reads the pin it currently serves. */
+async function grokPin(name) {
+    const r = await fetch('https://raw.githubusercontent.com/xai-org/plugin-marketplace/main/.grok-plugin/marketplace.json', { headers: { 'user-agent': 'mcplane' } }).catch(() => null);
+    const data = r?.ok ? (await r.json().catch(() => null)) : null;
+    return data?.plugins?.find((p) => p.name === name)?.source?.sha;
+}
+export async function drift(m, stores, opts = {}, dir = process.cwd()) {
+    const items = [];
+    const missing = [];
+    const [live, head] = await Promise.all([liveTools(m, opts.token), repoHead(m.repository)]);
+    const now = live.map(shape);
+    const listing = listingOf(m);
+    for (const store of stores) {
+        const snap = await readSnapshot(store, dir);
+        if (!snap) {
+            missing.push(store);
+            continue;
+        }
+        const d = diffTools(snap.tools, now);
+        const toolChange = d.added.length + d.removed.length + d.changed.length > 0;
+        const listingChange = Object.keys(listing).filter((k) => (listing[k] ?? '') !== (snap.listing[k] ?? ''));
+        const summary = [
+            d.added.length && `added ${d.added.join(', ')}`,
+            d.removed.length && `removed ${d.removed.join(', ')}`,
+            ...d.changed.map((c) => `${c.tool}: ${c.fields.join(', ')}`),
+        ]
+            .filter(Boolean)
+            .join('; ');
+        const since = `since ${snap.state === 'live' ? 'the live version' : 'your submission'}${snap.version ? ` (v${snap.version})` : ''} on ${snap.takenOn}`;
+        if (store === 'chatgpt') {
+            // OpenAI rescans published servers: removals apply at once, new and changed tools after automated checks.
+            // Listing text is part of the version and needs a new one.
+            const hintChanges = d.changed.filter((c) => c.fields.some((f) => f.includes('Hint')));
+            if (toolChange)
+                items.push({
+                    store,
+                    level: 'info',
+                    what: `Tools changed ${since}: ${summary}`,
+                    todo: `No resubmission needed for tools: OpenAI rescans your server, drops removed tools at once and switches new or changed ones over after they pass automated checks (the old definition stays live until then).${d.added.length || d.removed.length ? ' Update the test cases and demo video in your next version.' : ''}`,
+                });
+            if (hintChanges.length)
+                items.push({ store, level: 'action', what: `Hints changed: ${hintChanges.map((c) => c.tool).join(', ')}`, todo: 'Your published version’s justifications explain the old values. Put new ones in the next version ("mcplane pack chatgpt").' });
+            if (listingChange.length)
+                items.push({ store, level: 'action', what: `Listing text changed (${listingChange.join(', ')})`, todo: 'Listing changes need a new version, review and publication: "mcplane pack chatgpt", import it into a new version, submit.' });
+        }
+        if (store === 'claude-connectors') {
+            if (d.added.length || d.removed.length)
+                items.push({ store, level: 'action', what: `Tool list changed ${since}: ${summary}`, todo: 'Edit the listing’s tool names in claude.ai/directory/manage (changes are reviewed before going live).' });
+            const hintChanges = d.changed.filter((c) => c.fields.some((f) => f.includes('Hint')));
+            if (hintChanges.length)
+                items.push({ store, level: 'action', what: `Safety hints changed: ${hintChanges.map((c) => `${c.tool} (${c.fields.filter((f) => f.includes('Hint')).join(', ')})`).join('; ')}`, todo: 'Reviewers check hints against your read/write answer. Update it if needed and add a line to the listing’s Additional notes.' });
+            const other = d.changed.filter((c) => !c.fields.every((f) => f.includes('Hint')));
+            if (other.length && !d.added.length && !d.removed.length)
+                items.push({ store, level: 'info', what: `Tool details changed: ${other.map((c) => c.tool).join(', ')}`, todo: 'Claude reads descriptions and schemas live; nothing to resubmit.' });
+            if (listingChange.length)
+                items.push({ store, level: 'action', what: `Listing text changed (${listingChange.join(', ')})`, todo: 'Edit the listing in claude.ai/directory/manage.' });
+        }
+        if (store === 'claude-plugins' || store === 'cursor') {
+            if (head && snap.repoSha && head !== snap.repoSha)
+                items.push({ store, level: store === 'cursor' ? 'action' : 'info', what: `Plugin repo moved on ${since} (${snap.repoSha.slice(0, 7)} → ${head.slice(0, 7)})`, todo: store === 'cursor' ? 'Cursor pins marketplace plugins to the commit that was current when they were added and doesn’t document updates. Resubmit at cursor.com/marketplace/publish, or ask Cursor to re-pin.' : 'The portal picks up commits on the branch it tracks (push webhook or scheduled check) and validates them; a reviewer publishes each version unless you have auto-publish. Check claude.ai/directory/manage.' });
+        }
+        if (store === 'grok' && head) {
+            const pinned = await grokPin(m.name);
+            if (pinned && pinned !== head)
+                items.push({ store, level: 'info', what: `Grok serves ${pinned.slice(0, 7)}; your repo is at ${head.slice(0, 7)}`, todo: 'xAI bumps pins daily. If it’s still behind tomorrow, "mcplane publish grok" opens a pin-bump pull request.' });
+        }
+        if (store === 'muse' && (toolChange || listingChange.length)) {
+            items.push({ store, level: 'info', what: `Changed ${since}: ${[summary, listingChange.length && `listing ${listingChange.join(', ')}`].filter(Boolean).join('; ')}`, todo: 'Meta hasn’t published an update process yet. Update the listing in muse.ai/platform if it shows old details.' });
+        }
+        if (store === 'mcp-registry' && (toolChange || listingChange.length)) {
+            items.push({ store, level: 'action', what: `Changed ${since}`, todo: 'Bump the version and run "mcplane publish mcp-registry".' });
+        }
+    }
+    return { items, missing };
+}
+export function printDrift(r) {
+    if (!r.items.length)
+        console.log('No drift: every store with a snapshot matches your live server and mcplane.json.');
+    for (const i of r.items) {
+        console.log(`${i.level === 'action' ? '✗' : '•'} ${STORE_NAMES[i.store]}: ${i.what}`);
+        console.log(`    ${i.todo}`);
+    }
+    if (r.missing.length)
+        console.log(`\nNo snapshot yet for ${r.missing.map((s) => STORE_NAMES[s]).join(', ')}. Run "mcplane baseline <store>" for listings that are already live.`);
+}