mcplane 0.4.0 → 0.5.0

package/dist/checks/readiness.js

@@ -0,0 +1,230 @@
+/**
+ * Readiness for MCP 2026-07-28: warnings and notes, never blockers. The revision drops the
+ * initialize handshake for per-request _meta and server/discover, requires Mcp-Method and Mcp-Name
+ * headers on Streamable HTTP, deprecates Dynamic Client Registration for Client ID Metadata
+ * Documents, and has clients validate the issuer (RFC 8414 §3.3, RFC 9207). A warning means a
+ * 2026-07-28 client would fail today; a note means something deprecated or optional.
+ *
+ * Spec:         https://modelcontextprotocol.io/specification/2026-07-28
+ * Key changes:  https://modelcontextprotocol.io/specification/2026-07-28/changelog
+ * Release post: https://blog.modelcontextprotocol.io/posts/2026-07-28/
+ */
+import { McpClient } from '../mcp-client.js';
+import { VERSION } from '../version.js';
+import { metadata } from './oauth.js';
+export const MODERN = '2026-07-28';
+/** Handshake-era revisions, any of which is a fine answer to an initialize. */
+const LEGACY = ['2024-11-05', '2025-03-26', '2025-06-18', '2025-11-25'];
+/** Every modern request carries its version, client and capabilities in _meta (basic/versioning). */
+const META = {
+    'io.modelcontextprotocol/protocolVersion': MODERN,
+    'io.modelcontextprotocol/clientInfo': { name: 'mcplane', version: VERSION },
+    'io.modelcontextprotocol/clientCapabilities': {},
+};
+/** MCP-Protocol-Version and Mcp-Method go on every modern POST (basic/transports/streamable-http#request-metadata). */
+const modernHeaders = (method) => ({ 'mcp-protocol-version': MODERN, 'mcp-method': method });
+const check = (id, level, title, more = {}) => ({ id: `readiness.${id}`, level, title, ...more });
+const rpcError = (r) => (r?.body?.error ? `JSON-RPC ${r.body.error.code}${r.body.error.message ? ` ${String(r.body.error.message).slice(0, 80)}` : ''}` : '');
+const said = (r) => (r ? [`HTTP ${r.status}`, rpcError(r)].filter(Boolean).join(', ') : 'no answer');
+/**
+ * Reads the answer to a modern server/discover request the way a dual-era client does
+ * (basic/versioning#backward-compatibility): a DiscoverResult or a modern error means a modern
+ * server; a 4xx or a JSON-RPC error that isn't modern means a legacy one, and the client falls
+ * back to initialize. A 5xx, or no JSON-RPC answer at all, gives it nothing to go on.
+ */
+export function eraOf(r) {
+    if (!r)
+        return { era: 'broken', versions: [], detail: 'no answer' };
+    if (r.status === 401)
+        return { era: 'auth', versions: [], detail: 'HTTP 401' };
+    const versions = r.body?.result?.supportedVersions;
+    if (Array.isArray(versions))
+        return { era: 'modern', versions, detail: `supportedVersions ${versions.join(', ')}` };
+    // UnsupportedProtocolVersionError (-32022): modern, but not this version.
+    if (r.body?.error?.code === -32022)
+        return { era: 'modern', versions: r.body.error.data?.supported ?? [], detail: said(r) };
+    if (r.status >= 500)
+        return { era: 'broken', versions: [], detail: said(r) };
+    if (typeof r.body?.error?.code === 'number' || r.status >= 400)
+        return { era: 'legacy', versions: [], detail: said(r) };
+    return { era: 'broken', versions: [], detail: `HTTP ${r.status} without a JSON-RPC answer` };
+}
+export function eraCheck(e) {
+    const title = 'Speaks MCP 2026-07-28';
+    if (e.era === 'modern' && e.versions.includes(MODERN))
+        return check('era', 'pass', title, { detail: `server/discover: ${e.detail}` });
+    if (e.era === 'modern')
+        return check('era', 'info', title, { detail: `server/discover: ${e.detail}`, fix: 'Modern, but not 2026-07-28: clients retry with a version from your supported list.' });
+    if (e.era === 'auth')
+        return check('era', 'skip', title, { detail: 'the server answers 401 before sign-in', fix: 'Run again with --token <access token> to check how a 2026-07-28 client gets on after signing in.' });
+    if (e.era === 'legacy')
+        return check('era', 'info', title, {
+            detail: `legacy only: server/discover got ${e.detail}`,
+            fix: 'Nothing breaks yet: clients that speak both eras fall back to initialize. To serve 2026-07-28 clients directly, move to an SDK release that implements it (TypeScript, Python, Go and C# do) and answer server/discover.',
+        });
+    return check('era', 'warn', title, {
+        detail: `server/discover got ${e.detail}`,
+        fix: 'A 2026-07-28 client’s first request gets an error page. Clients that speak both eras fall back to initialize on a 4xx or a JSON-RPC error, so answer methods you don’t know with JSON-RPC -32601 instead of failing.',
+    });
+}
+/**
+ * An initialize that offers 2026-07-28. Under the 2025-11-25 lifecycle a server answers with the
+ * requested version only if it supports it, otherwise with one it does; 2026-07-28 has no initialize
+ * at all, so the right answer is a handshake-era version. A modern-only server rejects initialize
+ * and SHOULD name its versions in the error (basic/versioning).
+ * https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#version-negotiation
+ */
+export function initializeCheck(r, era) {
+    const title = 'An initialize that offers 2026-07-28 is negotiated down';
+    if (r?.status === 401)
+        return check('initialize', 'skip', title, { detail: 'HTTP 401', fix: 'Run again with --token <access token>.' });
+    const v = r?.body?.result?.protocolVersion;
+    if (v === MODERN)
+        return check('initialize', 'warn', title, {
+            detail: 'initialize answered with "2026-07-28"',
+            fix: '2026-07-28 has no initialize handshake, so answering one with it tells the client you speak something you don’t. Answer with the newest version you implement (e.g. 2025-11-25). A handler that copies params.protocolVersion back is the usual cause: check it against a supported list.',
+        });
+    if (typeof v === 'string' && LEGACY.includes(v))
+        return check('initialize', 'pass', title, { detail: `answered with ${v}` });
+    if (typeof v === 'string')
+        return check('initialize', 'warn', title, { detail: `answered with "${v}", which isn't a published version`, fix: 'Answer with a version you implement, such as 2025-11-25.' });
+    if (era === 'modern') {
+        const named = /\d{4}-\d{2}-\d{2}/.test(JSON.stringify(r?.body ?? ''));
+        return named
+            ? check('initialize', 'pass', title, { detail: `modern only: initialize got ${said(r)}, naming the versions it supports` })
+            : check('initialize', 'info', title, {
+                detail: `modern only: initialize got ${said(r)}`,
+                fix: 'Name the versions you support in that error. Clients from before 2026-07-28 have no way forward, and the error is the only thing they can show.',
+            });
+    }
+    return check('initialize', 'warn', title, {
+        detail: `initialize got ${said(r)}`,
+        fix: 'Answer with a version you support instead of an error. Under the 2025-11-25 lifecycle a server that doesn’t support the requested version replies with one it does, and clients that offer their newest version first fail against you otherwise.',
+    });
+}
+/** Modern servers: a tools/list carrying Mcp-Method is the ordinary case. A strict server rejects one without it (-32020). */
+export function modernHeaderCheck(r) {
+    const title = 'Accepts the Mcp-Method and Mcp-Name headers';
+    return r && r.status < 300 && r.body?.result
+        ? check('headers', 'pass', title, { detail: 'a 2026-07-28 tools/list with Mcp-Method works (Mcp-Name only goes on tools/call, resources/read and prompts/get, which mcplane doesn’t call)' })
+        : check('headers', 'warn', title, { detail: `a 2026-07-28 tools/list with Mcp-Method got ${said(r)}`, fix: 'Mcp-Method is required on every 2026-07-28 POST and must match the body’s method.' });
+}
+/** Legacy servers: the same tools/list with and without the new headers should get the same answer. */
+export function legacyHeaderCheck(plain, tagged) {
+    const title = 'Accepts the Mcp-Method and Mcp-Name headers';
+    const ok = (r) => !!r && r.status < 300 && !r.body?.error;
+    if (!ok(plain))
+        return check('headers', 'skip', title, { detail: `tools/list got ${said(plain)} without them, so there was nothing to compare` });
+    return ok(tagged)
+        ? check('headers', 'pass', title, { detail: 'tools/list answers the same with Mcp-Method and Mcp-Name set' })
+        : check('headers', 'warn', title, {
+            detail: `tools/list works, but with Mcp-Method and Mcp-Name set it got ${said(tagged)}`,
+            fix: '2026-07-28 clients send these on every request, and gateways route on them. A firewall rule, proxy or header allowlist is rejecting them: let Mcp-* headers through.',
+        });
+}
+/** Browser clients send both headers on every POST, so the CORS preflight must allow them. Null when the server doesn't answer CORS at all (server.cors covers that). */
+export function corsCheck(allowOrigin, allowHeaders) {
+    if (!allowOrigin)
+        return null;
+    const allowed = (allowHeaders ?? '').toLowerCase().split(',').map((h) => h.trim());
+    const missing = ['mcp-method', 'mcp-name'].filter((h) => !allowed.includes(h) && !allowed.includes('*'));
+    return missing.length
+        ? check('cors', 'info', 'CORS allows the Mcp-Method and Mcp-Name headers', {
+            detail: `Access-Control-Allow-Headers: ${allowHeaders ?? 'missing'}`,
+            fix: `Add ${missing.join(' and ')} to Access-Control-Allow-Headers. Browser-based 2026-07-28 clients send them on every request, and the preflight fails without them.`,
+        })
+        : check('cors', 'pass', 'CORS allows the Mcp-Method and Mcp-Name headers');
+}
+/**
+ * MCP Events is a draft, not part of 2026-07-28: events/list, events/poll, events/stream and
+ * events/subscribe, from the Triggers and Events Working Group. Reported, never a warning.
+ * https://github.com/modelcontextprotocol/experimental-ext-triggers-events/blob/main/docs/design-sketch-proposal.md
+ */
+export function eventsCheck(r) {
+    const title = 'Lists MCP Events (events/list, a draft)';
+    const events = r?.body?.result?.events;
+    if (Array.isArray(events))
+        return check('events', 'pass', title, { detail: events.length ? events.map((e) => e.name).join(', ') : 'no event types yet' });
+    if (r?.status === 401)
+        return check('events', 'skip', title, { detail: 'HTTP 401' });
+    return check('events', 'info', title, {
+        detail: `events/list got ${said(r)}`,
+        fix: 'Nothing to do yet. Events is a draft from the Triggers and Events Working Group, not part of 2026-07-28; if it lands, servers declare event types with events/list.',
+    });
+}
+/** 2026-07-28 clients MUST check the metadata's issuer against the issuer they built the URL from, and MUST NOT use it otherwise (authorization-server-discovery). */
+export function issuerCheck(d) {
+    const doc = d.oauth ?? d.oidc;
+    if (!doc?.forIssuer)
+        return null;
+    const title = 'The metadata’s issuer matches its URL';
+    const iss = doc.json?.issuer;
+    if (iss === doc.forIssuer)
+        return check('issuer', 'pass', title, { detail: iss });
+    return check('issuer', 'warn', title, {
+        detail: typeof iss === 'string' ? `${doc.url} says "${iss}", expected "${doc.forIssuer}"` : `${doc.url} has no issuer`,
+        fix: 'Make issuer exactly the identifier the well-known URL is built from, trailing slash included (RFC 8414 §3.3). 2026-07-28 clients must refuse metadata whose issuer differs.',
+    });
+}
+/** client_id_metadata_document_supported: DCR is deprecated in 2026-07-28 for CIMD, removable from the first revision on or after 2027-07-28. */
+export function cimdCheck(md) {
+    const title = 'Client ID Metadata Documents are advertised';
+    return md.client_id_metadata_document_supported === true
+        ? check('cimd', 'pass', title)
+        : check('cimd', 'info', title, {
+            detail: md.registration_endpoint ? 'Dynamic Client Registration only' : 'neither CIMD nor Dynamic Client Registration',
+            fix: '2026-07-28 deprecates Dynamic Client Registration in favour of Client ID Metadata Documents; DCR can go in the first revision on or after 2027-07-28. Accept URL client_ids, fetch and validate the document, and advertise client_id_metadata_document_supported: true.',
+        });
+}
+/** authorization_response_iss_parameter_supported (RFC 9207): a SHOULD in 2026-07-28, expected to become a MUST. */
+export function issCheck(md) {
+    const title = 'The authorization server returns iss (RFC 9207)';
+    return md.authorization_response_iss_parameter_supported === true
+        ? check('iss', 'pass', title)
+        : check('iss', 'info', title, {
+            detail: 'authorization_response_iss_parameter_supported not declared',
+            fix: 'Return iss in authorization responses, error responses included, and advertise authorization_response_iss_parameter_supported: true. It is a SHOULD in 2026-07-28 and expected to become a MUST; clients already compare any iss they get.',
+        });
+}
+export async function readinessChecks(url, auth, opts = {}) {
+    const bearer = opts.token ? { authorization: `Bearer ${opts.token}` } : {};
+    // Each modern request stands alone: a fresh client, so no session id goes with it.
+    const modern = (method) => new McpClient(url, bearer).request(method, { _meta: META }, { headers: modernHeaders(method) }).catch(() => null);
+    const e = eraOf(await modern('server/discover'));
+    const checks = [eraCheck(e)];
+    if (e.era !== 'auth') {
+        const init = await new McpClient(url, bearer).request('initialize', { protocolVersion: MODERN, capabilities: {}, clientInfo: { name: 'mcplane', version: VERSION } }).catch(() => null);
+        checks.push(initializeCheck(init, e.era));
+        if (e.era === 'modern') {
+            checks.push(modernHeaderCheck(await modern('tools/list')));
+            checks.push(eventsCheck(await modern('events/list')));
+        }
+        else {
+            const c = new McpClient(url, bearer);
+            const opened = await c.initialize().catch(() => null);
+            if (opened && opened.status < 300) {
+                const plain = await c.request('tools/list').catch(() => null);
+                const tagged = await c.request('tools/list', undefined, { headers: { 'mcp-method': 'tools/list', 'mcp-name': 'mcplane-probe' } }).catch(() => null);
+                checks.push(legacyHeaderCheck(plain, tagged));
+                checks.push(eventsCheck(await c.request('events/list').catch(() => null)));
+            }
+        }
+        const pre = await fetch(url, {
+            method: 'OPTIONS',
+            headers: { origin: 'https://chatgpt.com', 'access-control-request-method': 'POST', 'access-control-request-headers': 'content-type, mcp-protocol-version, mcp-method, mcp-name' },
+            signal: AbortSignal.timeout(10_000),
+        }).catch(() => null);
+        const cors = pre && pre.status < 300 ? corsCheck(pre.headers.get('access-control-allow-origin'), pre.headers.get('access-control-allow-headers')) : null;
+        if (cors)
+            checks.push(cors);
+    }
+    // From the discovery documents alone, so these run before sign-in too.
+    const md = metadata(opts.oauth);
+    if (auth === 'oauth' && opts.oauth && md) {
+        const iss = issuerCheck(opts.oauth);
+        if (iss)
+            checks.push(iss);
+        checks.push(cimdCheck(md), issCheck(md));
+    }
+    return checks;
+}

package/dist/checks/tools.js

@@ -16,6 +16,19 @@ const INSTRUCTION = [
 const UPSELL = /\b(upgrade (to|your|now)|pro plan|premium (plan|tier|account|subscription|version)|paid (plan|tier|account)|free trial|subscribe (to|now)|unlock (more|premium|pro|unlimited|all))\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;
+/** OpenAI's destructive effects ("deletion, overwriting, cancellation, access revocation") in the words a tool uses about itself. */
+const DESTRUCTIVE = /\b(overwrit\w*|replac\w*|revo[kc]\w*|delet\w*|cancel\w*|archiv\w*|expir\w*|passwords?|gat(?:e|es|ed|ing))\b/gi;
+const NEGATED = /\b(never|not|no|without|nothing|refuses?|cannot|can['’]t|doesn['’]t|don['’]t|won['’]t)\b(\s+\w+){0,2}\s*$/i;
+/** The destructive words in a tool's name, title and description, skipping negated ones ("never overwrites"). */
+function destructiveWords(text) {
+    const found = new Set();
+    for (const m of text.matchAll(DESTRUCTIVE)) {
+        if (NEGATED.test(text.slice(Math.max(0, m.index - 40), m.index)))
+            continue;
+        found.add(m[1].toLowerCase());
+    }
+    return [...found];
+}
 export function toolChecks(tools) {
     if (!tools.length)
         return [];
@@ -31,7 +44,7 @@ export function toolChecks(tools) {
             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.',
+            fix: 'Set readOnlyHint, destructiveHint and openWorldHint to true or false on every tool. ChatGPT requires explicit values and its automated review checks them against what each tool does (justifications are no longer required; appeal if it flags one you believe is right). 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' });
@@ -70,8 +83,8 @@ export function toolChecks(tools) {
             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.
+    // OpenAI: openWorldHint is true for public or open-ended entities, read-only web search and arbitrary destinations
+    // included; a tool confined to a bounded private account, workspace or catalog may be false. Connectivity alone doesn't decide it.
     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
@@ -79,12 +92,12 @@ export function toolChecks(tools) {
             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.',
+            detail: `${openWorld.map((t) => t.name).join(', ')}: openWorldHint is false, but the tool seems to reach public or open-ended destinations (sending, posting, publishing or searching the web)`,
+            fix: 'OpenAI: use true "for public or open-ended entities, including read-only web search and arbitrary destinations". A tool "confined to a bounded private account, workspace, or catalog may use false, even when externally hosted", and "connectivity alone does not determine this value". If it only reaches the user’s own account, false is right.',
             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.
+    // OpenAI: for writes, destructiveHint is true for destructive or irreversible effects, "irreversible sends or transactions" 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({
@@ -92,7 +105,25 @@ export function toolChecks(tools) {
             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).',
+            fix: 'OpenAI: for writes, use true "for potentially destructive or irreversible effects, such as deletion, overwriting, cancellation, access revocation, or irreversible sends or transactions", and false "only for additive writes without destructive or irreversible effects". A message can’t be unsent, so set it to true, and ask for confirmation before it goes.',
+            stores: ['chatgpt'],
+        });
+    }
+    // The same definition covers overwriting, revoking access and deleting; an undo doesn't change that.
+    // Conservative: explicit write tools whose own words say so, negated mentions ("never overwrites") excluded.
+    const destroys = tools.flatMap((t) => {
+        if (t.annotations?.readOnlyHint !== false || t.annotations?.destructiveHint !== false)
+            return [];
+        const words = destructiveWords(`${t.name.replace(/[_-]+/g, ' ').replace(/([a-z])([A-Z])/g, '$1 $2')} ${t.title ?? ''} ${t.description ?? ''}`);
+        return words.length ? [`${t.name} (${words.join(', ')})`] : [];
+    });
+    if (destroys.length) {
+        checks.push({
+            id: 'tools.destructive-overwrite',
+            level: 'warn',
+            title: 'destructiveHint covers overwriting, revoking and deleting',
+            detail: `${destroys.join('; ')}: destructiveHint is false, but the tool seems to overwrite, revoke access or delete`,
+            fix: 'OpenAI: for writes, use true "for potentially destructive or irreversible effects, such as deletion, overwriting, cancellation, access revocation, or irreversible sends or transactions". "Being able to undo an action does not, by itself, justify setting destructiveHint to false." If the tool only adds, keep false, and appeal if review flags it.',
             stores: ['chatgpt'],
         });
     }

package/dist/checks/vercel.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Vercel Connect, the connector catalog for apps and agents, takes service submissions since
+ * 29 Sep 2026. These checks follow its "For Service Providers" page, from your discovery documents
+ * alone (nothing is registered). Its tiers set the level: Required blocks, Recommended warns,
+ * Optional is a note. What needs a real token (expires_in, refresh rotation, the redirect URL) is
+ * left to the reminders.
+ *
+ * https://vercel.com/docs/connect/providers
+ * https://vercel.com/changelog/vercel-connect-service-submissions
+ */
+import type { Check, Manifest } from '../types.js';
+import { type Discovery } from './oauth.js';
+export declare const CONNECT_CALLBACK = "https://connect.vercel.com/callback";
+/** The client authentication methods Vercel Connect registers clients with. */
+export declare const CONNECT_AUTH_METHODS: string[];
+/** Each grant, and the token subject type Connect offers for it. */
+export declare const SUBJECTS: Record<string, string>;
+/** What Connect can do about client creation, from the metadata: DCR, CIMD, both or neither. */
+export declare function clientCreation(md: Record<string, any>): {
+    dcr: boolean;
+    cimd: boolean;
+    methods: string[] | undefined;
+    usable: string[];
+};
+export declare function vercelChecks(m: Manifest, d: Discovery | null): Check[];
+/** What only a token or the form can show. */
+export declare const VERCEL_REMINDERS: string[];

package/dist/checks/vercel.js

@@ -0,0 +1,153 @@
+import { isJsonType, metadata, wellKnown } from './oauth.js';
+const S = ['vercel-connect'];
+export const CONNECT_CALLBACK = 'https://connect.vercel.com/callback';
+/** The client authentication methods Vercel Connect registers clients with. */
+export const CONNECT_AUTH_METHODS = ['client_secret_basic', 'client_secret_post', 'none', 'private_key_jwt'];
+/** Each grant, and the token subject type Connect offers for it. */
+export const SUBJECTS = {
+    authorization_code: 'user',
+    client_credentials: 'app',
+    'urn:ietf:params:oauth:grant-type:jwt-bearer': 'jwt-bearer',
+};
+const check = (id, level, title, more = {}) => ({ id: `vercel.${id}`, level, title, ...more, stores: S });
+/** What Connect can do about client creation, from the metadata: DCR, CIMD, both or neither. */
+export function clientCreation(md) {
+    const methods = Array.isArray(md.token_endpoint_auth_methods_supported) ? md.token_endpoint_auth_methods_supported : undefined;
+    // RFC 8414 §2: when the list is left out, the default is client_secret_basic.
+    const usable = (methods ?? ['client_secret_basic']).filter((x) => CONNECT_AUTH_METHODS.includes(x));
+    const s256 = (md.code_challenge_methods_supported ?? []).includes('S256');
+    return {
+        dcr: typeof md.registration_endpoint === 'string' && usable.length > 0,
+        cimd: md.client_id_metadata_document_supported === true && (!!methods?.includes('private_key_jwt') || (!!methods?.includes('none') && s256)),
+        methods,
+        usable,
+    };
+}
+export function vercelChecks(m, d) {
+    if ((m.server.auth ?? 'none') !== 'oauth') {
+        return [
+            m.vercelConnect?.apiKey
+                ? check('method', 'pass', 'Vercel Connect has a connection method', { detail: 'API key: Vercel validates its configuration only, with no token test' })
+                : check('method', 'warn', 'Vercel Connect has a connection method', {
+                    detail: 'server.auth is "none" and mcplane.json has no vercelConnect.apiKey',
+                    fix: 'Vercel Connect brokers OAuth tokens and API keys, and a submission needs at least one connection method. An authless server has nothing to connect; if users need a key, describe it under vercelConnect.apiKey.',
+                }),
+        ];
+    }
+    if (!d)
+        return [];
+    const md = metadata(d);
+    const found = [d.oauth, d.oidc].filter((x) => x !== null);
+    const tried = [...d.oauthTried, ...d.oidcTried];
+    const out = [];
+    // Required: discovery documents, served as JSON, at the path-suffixed form when the issuer has a path.
+    if (!md) {
+        const notJson = tried.find((t) => t.status === 200 && t.json && !isJsonType(t.contentType));
+        out.push(check('metadata', 'fail', 'Authorization-server metadata is published as JSON', {
+            detail: notJson ? `${notJson.url} is served as ${notJson.contentType || 'no content type'}` : tried.map((t) => `${t.url} (${t.status || 'no answer'})`).join(', '),
+            fix: notJson
+                ? 'Serve it as application/json. Vercel Connect skips a document that exists but isn’t served as JSON.'
+                : `Publish RFC 8414 metadata (or OpenID Connect discovery) for ${d.issuer}. Vercel Connect reads your endpoints and capabilities from it; without it your users enter every endpoint by hand.`,
+        }));
+        return out;
+    }
+    const oauthForms = wellKnown(d.issuer, 'oauth-authorization-server');
+    const oidcForms = wellKnown(d.issuer, 'openid-configuration');
+    const originOnly = !!oauthForms.inserted && found.every((x) => x.url === oauthForms.origin || x.url === oidcForms.origin);
+    const title = 'Authorization-server metadata is published as JSON';
+    const pathFix = `For a URL with a path, Vercel Connect looks for the path-suffixed form and can't find metadata that is only at the origin. Serve it at ${oauthForms.inserted} too (RFC 8414 §3.1)`;
+    out.push(!originOnly
+        ? check('metadata', 'pass', title, { detail: found.map((x) => x.url).join(', ') })
+        : d.prm
+            ? // Your PRM names an issuer with a path, so every client builds the path-suffixed URL.
+                check('metadata', 'fail', title, { detail: `only at ${found.map((x) => x.url).join(', ')}, but the issuer ${d.issuer} has a path`, fix: `${pathFix}.` })
+            : // No PRM: Connect treats the MCP URL as the issuer. Entering the bare host still works.
+                check('metadata', 'warn', title, {
+                    detail: `only at ${found.map((x) => x.url).join(', ')}, and with no protected-resource metadata Connect takes ${d.issuer} as the issuer`,
+                    fix: `${pathFix}, or publish protected-resource metadata (RFC 9728) naming your issuer. Until then your users must enter ${new URL(d.issuer).host} rather than the MCP URL.`,
+                }));
+    // Required: with both documents, Connect fills gaps in the OAuth one from OpenID Connect, so they must agree.
+    if (d.oauth && d.oidc) {
+        const differ = ['issuer', 'token_endpoint'].filter((k) => d.oauth.json[k] !== d.oidc.json[k]);
+        out.push(differ.length
+            ? check('oidc-agrees', 'fail', 'OAuth and OpenID Connect metadata agree', {
+                detail: differ.map((k) => `${k}: "${d.oauth.json[k] ?? ''}" vs "${d.oidc.json[k] ?? ''}"`).join('; '),
+                fix: 'Vercel Connect fills gaps in your OAuth metadata from your OpenID Connect document, and both must declare the same issuer and token_endpoint.',
+            })
+            : check('oidc-agrees', 'pass', 'OAuth and OpenID Connect metadata agree'));
+    }
+    out.push(typeof md.token_endpoint === 'string'
+        ? check('token-endpoint', 'pass', 'token_endpoint is declared')
+        : check('token-endpoint', 'fail', 'token_endpoint is declared', { fix: 'Every Vercel Connect flow uses token_endpoint. Declare it in your metadata.' }));
+    // Required: grant types decide which token subject types a connector offers.
+    const grants = Array.isArray(md.grant_types_supported) ? md.grant_types_supported : [];
+    const subjects = grants.filter((g) => SUBJECTS[g]).map((g) => `${SUBJECTS[g]} (${g.replace('urn:ietf:params:oauth:grant-type:', '')})`);
+    out.push(!grants.length
+        ? check('grant-types', 'fail', 'grant_types_supported says what a connector can do', {
+            detail: 'grant_types_supported is missing',
+            fix: 'Declare it, e.g. ["authorization_code", "refresh_token"], plus client_credentials if you issue app tokens. Vercel Connect reads it to decide which token types a connector offers, and a grant you leave out never shows up.',
+        })
+        : !subjects.length
+            ? check('grant-types', 'fail', 'grant_types_supported says what a connector can do', {
+                detail: `declares ${grants.join(', ')}`,
+                fix: 'Include authorization_code (user tokens) or client_credentials (app tokens). None of the declared grants gives Vercel Connect a token to hand out.',
+            })
+            : check('grant-types', 'pass', 'grant_types_supported says what a connector can do', { detail: `subject types: ${subjects.join(', ')}` }));
+    if (grants.includes('authorization_code') && typeof md.authorization_endpoint !== 'string') {
+        out.push(check('authorization-endpoint', 'fail', 'authorization_endpoint is declared for user tokens', { fix: 'User tokens need authorization_endpoint alongside token_endpoint.' }));
+    }
+    // Recommended: Connect creates the OAuth client itself, through DCR or CIMD.
+    const cc = clientCreation(md);
+    out.push(cc.dcr || cc.cimd
+        ? check('registration', 'pass', 'Vercel Connect can create the OAuth client', { detail: [cc.dcr && 'Dynamic Client Registration', cc.cimd && 'Client ID Metadata Documents'].filter(Boolean).join(' and ') })
+        : check('registration', 'warn', 'Vercel Connect can create the OAuth client', {
+            detail: [
+                !md.registration_endpoint ? 'no registration_endpoint' : 'registration_endpoint, but no client authentication method Connect uses',
+                md.client_id_metadata_document_supported !== true ? 'client_id_metadata_document_supported not declared' : 'CIMD declared, but neither private_key_jwt nor public clients (none) with S256',
+            ].join('; '),
+            fix: `Declare a registration_endpoint (RFC 7591), or client_id_metadata_document_supported: true with private_key_jwt or public clients and S256. Otherwise each user registers an application with you, allows ${CONNECT_CALLBACK} and pastes in its client ID and secret.`,
+        }));
+    if (typeof md.registration_endpoint === 'string') {
+        out.push(!cc.methods
+            ? check('auth-methods', 'warn', 'token_endpoint_auth_methods_supported names a method Connect can use', {
+                detail: 'not declared (RFC 8414 defaults it to client_secret_basic)',
+                fix: `Declare the methods you accept. Vercel Connect registers clients with ${CONNECT_AUTH_METHODS.join(', ')}, and skips DCR when the list names none of them.`,
+            })
+            : cc.usable.length
+                ? check('auth-methods', 'pass', 'token_endpoint_auth_methods_supported names a method Connect can use', { detail: cc.usable.join(', ') })
+                : check('auth-methods', 'warn', 'token_endpoint_auth_methods_supported names a method Connect can use', {
+                    detail: cc.methods.join(', '),
+                    fix: `Add one of ${CONNECT_AUTH_METHODS.join(', ')}. Without one, Vercel Connect won't register a client and your users paste in a client ID and secret even though you support DCR.`,
+                }));
+    }
+    out.push((md.code_challenge_methods_supported ?? []).includes('S256')
+        ? check('pkce', 'pass', 'PKCE with S256 is declared')
+        : check('pkce', 'warn', 'PKCE with S256 is declared', { fix: 'Declare code_challenge_methods_supported: ["S256"]. Vercel Connect then uses PKCE (RFC 9700), and it is one of the two routes to CIMD for public clients.' }));
+    out.push(grants.includes('refresh_token')
+        ? check('refresh', 'pass', 'Refresh tokens are declared')
+        : check('refresh', 'warn', 'Refresh tokens are declared', { fix: 'Declare refresh_token in grant_types_supported and issue refresh tokens with the authorization code flow. Without them every expiry sends your user back through the consent prompt.' }));
+    // Optional: notes, never warnings.
+    const prmServers = d.prm?.json?.authorization_servers;
+    out.push(Array.isArray(prmServers) && prmServers.length
+        ? check('prm', 'pass', 'Protected-resource metadata names the authorization server', { detail: d.prm.url })
+        : check('prm', 'info', 'Protected-resource metadata names the authorization server', {
+            fix: 'Publish RFC 9728 metadata with a non-empty authorization_servers array, so users can give Vercel Connect the MCP URL they already know instead of looking up your authorization server.',
+        }));
+    out.push(typeof md.revocation_endpoint === 'string'
+        ? check('revocation', 'pass', 'revocation_endpoint is declared')
+        : check('revocation', 'info', 'revocation_endpoint is declared', {
+            fix: 'Declare one (RFC 7009). Vercel Connect then offers revocation and calls it; without it, revoking only removes Vercel’s copy and your side treats the token as live until it expires.',
+        }));
+    const scopes = Array.isArray(md.scopes_supported) ? md.scopes_supported : [];
+    out.push(!scopes.length
+        ? check('scopes', 'info', 'scopes_supported lists your scopes', { fix: 'List every scope a client can request. Vercel Connect offers this set when users configure your OAuth client.' })
+        : d.oidc && !scopes.includes('openid')
+            ? check('scopes', 'info', 'scopes_supported lists your scopes', { detail: scopes.join(' '), fix: 'You serve OpenID Connect, so include openid, plus profile and email where you support them. Vercel Connect shows those apart from your API scopes.' })
+            : check('scopes', 'pass', 'scopes_supported lists your scopes', { detail: scopes.join(' ') }));
+    return out;
+}
+/** What only a token or the form can show. */
+export const VERCEL_REMINDERS = [
+    `Vercel Connect: allow the redirect URL ${CONNECT_CALLBACK} (exact match), return expires_in in token responses, and if you rotate refresh tokens return the new one in every refresh response. None of these can be checked without a token.`,
+    'Vercel Connect: test each OAuth method in Submit a Service (Set Up Test Connector, then Test User Token, with the default scopes selected) and keep that connector and its token in your team until review ends. Vercel re-checks it when you submit, and any change to the method or your discovery documents needs a new test.',
+];

package/dist/cli.js

@@ -7,7 +7,7 @@ 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 { PACKS, packFor, writePack } from './packs.js';
 import { drift, printDrift, takeSnapshot } from './drift.js';
 import { publish } from './publish.js';
 import { lanes, runLane, tryLinks } from './extras.js';
@@ -23,18 +23,30 @@ Usage
       --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)
+      --sign-in <url>                 A sign-in page your consent screen uses, checked for bot walls (repeatable)
   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 pack <store>                Write a submission pack to .mcplane/packs (chatgpt, claude-connectors, vercel-connect, cursor, muse, directories)
+      pack ard                        An ARD manifest for /.well-known/ard.json
+      pack claude-eval                A "claude plugin eval" suite from your review tests
+      --tools <file>                  A saved tools/list result, for servers behind sign-in (or pass --token)
   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 demo                        Record the review demo video in ChatGPT desktop from your positive tests (macOS)
+      --only 1,3                      Which tests to record (default: all)
+      --out <file>                    Where to write it (default: .mcplane/packs/chatgpt/demo.mp4)
+      --approve                       Click "Allow once" when ChatGPT asks to run a tool
+      --plugin <name>                 The plugin to @mention, as ChatGPT names it (default: title)
+      --work                          Record in Work mode instead of Chat
+      --keep-open                     Leave ChatGPT running afterwards
+      --yes                           Don't ask before driving ChatGPT
   mcplane listings [--store <id>]...  Where you're listed, and whether what went live matches your server (--ci)
   mcplane lanes                       List lanes; run one with "mcplane <lane>" (built in: check, watch, release)
   mcplane fleet [--root <dir>]        Every project under a folder: blockers, store updates needed, reviews waiting
@@ -65,6 +77,8 @@ async function main() {
             verbose: { type: 'boolean' },
             register: { type: 'boolean' },
             token: { type: 'string' },
+            tools: { type: 'string' },
+            'sign-in': { type: 'string', multiple: true },
             date: { type: 'string' },
             kind: { type: 'string' },
             version: { type: 'string' },
@@ -74,6 +88,13 @@ async function main() {
             root: { type: 'string' },
             quick: { type: 'boolean' },
             yes: { type: 'boolean' },
+            only: { type: 'string' },
+            out: { type: 'string' },
+            approve: { type: 'boolean' },
+            plugin: { type: 'string' },
+            work: { type: 'boolean' },
+            'keep-open': { type: 'boolean' },
+            port: { type: 'string' },
         },
         allowPositionals: true,
     });
@@ -108,6 +129,8 @@ async function main() {
     }
     if (cmd === 'preflight') {
         const m = values.url ? await draftManifest(values.url) : await loadManifest();
+        if (values['sign-in']?.length)
+            m.server.signIn = [...(m.server.signIn ?? []), ...values['sign-in']];
         const stores = (values.store ?? []);
         for (const s of stores)
             if (!(s in STORE_NAMES))
@@ -140,11 +163,13 @@ async function main() {
     }
     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 name = positionals[0];
+        if (!PACKS.includes(name))
+            asStore(name);
+        const pack = await packFor(m, name, { token: values.token ?? process.env.MCPLANE_TOKEN, tools: values.tools });
         const written = await writePack(pack);
-        console.log(`Wrote ${written.join(', ')}`);
+        const dirs = [...new Set(written.map((w) => w.split('/').slice(0, 3).join('/')))];
+        console.log(written.length > 6 ? `Wrote ${written.length} files under ${dirs.join(', ')}/` : `Wrote ${written.join(', ')}`);
         if (pack.problems.length) {
             console.log('\nFix before submitting:');
             for (const p of pack.problems)
@@ -226,6 +251,29 @@ async function main() {
             console.log(`${t.client.padEnd(22)} ${t.how}`);
         return;
     }
+    if (cmd === 'demo') {
+        const m = await loadManifest();
+        if (values.port && !/^\d+$/.test(values.port))
+            throw new Error('--port takes a port number, e.g. 9333.');
+        const { demo } = await import('./demo.js');
+        const r = await demo(m, {
+            only: values.only,
+            out: values.out,
+            approve: values.approve,
+            plugin: values.plugin,
+            work: values.work,
+            keepOpen: values['keep-open'],
+            yes: values.yes,
+            port: values.port ? Number(values.port) : undefined,
+            token: values.token ?? process.env.MCPLANE_TOKEN,
+        });
+        const mins = Math.floor(r.seconds / 60);
+        console.log(`\nWrote ${r.out} (${r.scenes} scene${r.scenes === 1 ? '' : 's'}, ${mins ? `${mins}m ` : ''}${Math.round(r.seconds % 60)}s).`);
+        for (const n of r.notes)
+            console.log(`  ! ${n}`);
+        console.log('Watch it, upload it where a reviewer can open it without signing in, set chatgpt.demoVideo to that URL, then run "mcplane pack chatgpt".');
+        return;
+    }
     if (cmd === 'listings' || cmd === 'pull') {
         const m = await loadManifest();
         const stores = (values.store?.length ? values.store : storesOf(m));

package/dist/core.d.ts

@@ -14,5 +14,6 @@ export declare function preflight(m: Manifest, opts?: {
 }): Promise<PreflightResult>;
 export { draftManifest, forStore, storesOf, SCHEMA_URL } from './draft.js';
 export { toolChecks } from './checks/tools.js';
+export { validateArd, ardManifest } from './checks/ard.js';
 export { STORE_NAMES } from './types.js';
 export type { Check, Level, Manifest, StoreId, Tool } from './types.js';