mcplane 0.4.1 → 0.5.1

package/dist/cdp.js

@@ -0,0 +1,253 @@
+/**
+ * Just enough of the Chrome DevTools Protocol to drive an Electron app: one
+ * WebSocket, requests matched by id, events by name.
+ *
+ * The WebSocket is a few lines of RFC 6455 over node:http's upgrade rather than
+ * Node's built-in one: ChatGPT doesn't always answer a close frame, and the
+ * built-in client then holds the process open with no way to drop the socket.
+ * It also keeps mcplane on Node 20.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { get, request } from 'node:http';
+/** The debugging port's target list. Plain http with no keep-alive, so nothing holds the process open afterwards. */
+export function listTargets(port, timeoutMs = 2_000) {
+    return new Promise((resolve, reject) => {
+        const req = get({ host: '127.0.0.1', port, path: '/json/list', agent: false, timeout: timeoutMs }, (res) => {
+            let body = '';
+            res.setEncoding('utf8');
+            res.on('data', (d) => (body += d));
+            res.on('end', () => {
+                try {
+                    if (res.statusCode !== 200)
+                        throw new Error(`DevTools port ${port} answered HTTP ${res.statusCode}`);
+                    resolve(JSON.parse(body));
+                }
+                catch (e) {
+                    reject(e);
+                }
+            });
+        });
+        req.on('timeout', () => req.destroy(new Error(`DevTools port ${port} didn't answer`)));
+        req.on('error', reject);
+    });
+}
+/**
+ * The app's main window: the page target at exactly `url` (ChatGPT desktop: app://-/index.html).
+ * Its other windows (app://-/index.html?initialRoute=…), MCP App iframes, webviews and
+ * workers are separate targets and never match.
+ */
+export function pickMainWindow(targets, url) {
+    return targets.find((t) => t.type === 'page' && t.url === url && t.webSocketDebuggerUrl);
+}
+/* ---------------- WebSocket frames (RFC 6455) ---------------- */
+const GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+const OP = { continuation: 0x0, text: 0x1, binary: 0x2, close: 0x8, ping: 0x9, pong: 0xa };
+/** One client-to-server frame: final, masked as the RFC requires of clients. */
+export function encodeFrame(payload, opcode = OP.text, mask = randomBytes(4)) {
+    const len = payload.length;
+    const head = len < 126 ? 2 : len < 65_536 ? 4 : 10;
+    const out = Buffer.alloc(head + 4 + len);
+    out[0] = 0x80 | opcode;
+    if (len < 126)
+        out[1] = 0x80 | len;
+    else if (len < 65_536) {
+        out[1] = 0x80 | 126;
+        out.writeUInt16BE(len, 2);
+    }
+    else {
+        out[1] = 0x80 | 127;
+        out.writeBigUInt64BE(BigInt(len), 2);
+    }
+    mask.copy(out, head);
+    for (let i = 0; i < len; i++)
+        out[head + 4 + i] = payload[i] ^ mask[i & 3];
+    return out;
+}
+/** Takes every complete frame off the front of `buf`; `rest` is the partial frame still arriving. */
+export function decodeFrames(buf) {
+    const frames = [];
+    let off = 0;
+    for (;;) {
+        if (buf.length - off < 2)
+            break;
+        const b0 = buf[off];
+        const b1 = buf[off + 1];
+        let len = b1 & 0x7f;
+        let pos = off + 2;
+        if (len === 126) {
+            if (buf.length - pos < 2)
+                break;
+            len = buf.readUInt16BE(pos);
+            pos += 2;
+        }
+        else if (len === 127) {
+            if (buf.length - pos < 8)
+                break;
+            len = Number(buf.readBigUInt64BE(pos));
+            pos += 8;
+        }
+        let mask = null;
+        if (b1 & 0x80) {
+            if (buf.length - pos < 4)
+                break;
+            mask = buf.subarray(pos, pos + 4);
+            pos += 4;
+        }
+        if (buf.length - pos < len)
+            break;
+        let payload = buf.subarray(pos, pos + len);
+        if (mask) {
+            payload = Buffer.from(payload);
+            for (let i = 0; i < payload.length; i++)
+                payload[i] ^= mask[i & 3];
+        }
+        frames.push({ fin: (b0 & 0x80) !== 0, opcode: b0 & 0x0f, payload });
+        off = pos + len;
+    }
+    return { frames, rest: buf.subarray(off) };
+}
+export class Cdp {
+    socket;
+    next = 0;
+    pending = new Map();
+    listeners = new Map();
+    closed = false;
+    buf = Buffer.alloc(0);
+    parts = [];
+    constructor(socket, head) {
+        this.socket = socket;
+        socket.setNoDelay(true);
+        socket.on('data', (d) => this.data(d));
+        socket.on('error', () => null); // "close" follows
+        socket.on('close', () => this.ended('The DevTools connection closed (did ChatGPT quit?)'));
+        if (head.length)
+            this.data(head);
+    }
+    /** Opens a DevTools WebSocket URL (ws://127.0.0.1:<port>/devtools/page/<id>). */
+    static connect(url, timeoutMs = 10_000) {
+        const u = new URL(url);
+        const key = randomBytes(16).toString('base64');
+        return new Promise((resolve, reject) => {
+            const req = request({
+                host: u.hostname,
+                port: u.port,
+                path: u.pathname + u.search,
+                agent: false,
+                timeout: timeoutMs,
+                headers: { Connection: 'Upgrade', Upgrade: 'websocket', 'Sec-WebSocket-Version': '13', 'Sec-WebSocket-Key': key },
+            });
+            req.on('upgrade', (res, socket, head) => {
+                socket.setTimeout(0);
+                if (res.headers['sec-websocket-accept'] !== createHash('sha1').update(key + GUID).digest('base64')) {
+                    socket.destroy();
+                    reject(new Error(`${url} isn't a WebSocket endpoint`));
+                    return;
+                }
+                resolve(new Cdp(socket, head));
+            });
+            req.on('response', (res) => {
+                res.resume();
+                reject(new Error(`DevTools refused the connection (HTTP ${res.statusCode})`));
+            });
+            req.on('timeout', () => req.destroy(new Error(`Couldn't connect to ${url}`)));
+            req.on('error', reject);
+            req.end();
+        });
+    }
+    send(method, params = {}, timeoutMs = 30_000) {
+        if (this.closed)
+            return Promise.reject(new Error('The DevTools connection is closed'));
+        const id = ++this.next;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`${method} timed out`));
+            }, timeoutMs);
+            this.pending.set(id, {
+                method,
+                resolve: (v) => {
+                    clearTimeout(timer);
+                    resolve(v);
+                },
+                reject: (e) => {
+                    clearTimeout(timer);
+                    reject(e);
+                },
+            });
+            this.socket.write(encodeFrame(Buffer.from(JSON.stringify({ id, method, params }))));
+        });
+    }
+    /** Runs an expression in the page and returns its JSON value. */
+    async evaluate(expression) {
+        const r = await this.send('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: true });
+        if (r.exceptionDetails)
+            throw new Error(`Page script failed: ${r.exceptionDetails.exception?.description ?? r.exceptionDetails.text}`);
+        return r.result?.value;
+    }
+    /** Subscribes to an event; returns the unsubscribe function. */
+    on(event, fn) {
+        const set = this.listeners.get(event) ?? new Set();
+        set.add(fn);
+        this.listeners.set(event, set);
+        return () => set.delete(fn);
+    }
+    /** Sends a close frame and drops the socket without waiting for an answer. */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.socket.end(encodeFrame(Buffer.alloc(0), OP.close), () => this.socket.destroy());
+        this.ended('The DevTools connection is closed');
+    }
+    ended(why) {
+        this.closed = true;
+        for (const p of this.pending.values())
+            p.reject(new Error(why));
+        this.pending.clear();
+    }
+    data(chunk) {
+        this.buf = this.buf.length ? Buffer.concat([this.buf, chunk]) : chunk;
+        const { frames, rest } = decodeFrames(this.buf);
+        this.buf = rest;
+        for (const f of frames) {
+            if (f.opcode === OP.ping) {
+                if (!this.closed)
+                    this.socket.write(encodeFrame(f.payload, OP.pong));
+            }
+            else if (f.opcode === OP.close) {
+                this.close();
+            }
+            else if (f.opcode === OP.text || f.opcode === OP.binary || f.opcode === OP.continuation) {
+                this.parts.push(f.payload);
+                if (f.fin) {
+                    const message = Buffer.concat(this.parts).toString('utf8');
+                    this.parts = [];
+                    this.receive(message);
+                }
+            }
+        }
+    }
+    receive(raw) {
+        let m;
+        try {
+            m = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (typeof m.id === 'number') {
+            const p = this.pending.get(m.id);
+            if (!p)
+                return;
+            this.pending.delete(m.id);
+            if (m.error)
+                p.reject(new Error(`${p.method}: ${m.error.message}`));
+            else
+                p.resolve(m.result);
+            return;
+        }
+        if (m.method)
+            for (const fn of this.listeners.get(m.method) ?? [])
+                fn(m.params);
+    }
+}

package/dist/checks/ard.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Agentic Resource Discovery (ARD v0.91, a proposal dated 26 Aug 2026): a manifest of entries at
+ * /.well-known/ard.json that tells agents and registries what a domain offers, MCP servers included.
+ * The predecessor path was /.well-known/ai-catalog.json, and that is what Lighthouse 13.5's
+ * ard-schema audit still reads (after a robots.txt Agentmap line or a rel="ai-catalog" link), with
+ * a port of the ARD conformance tester and the older ai-catalog schema: specVersion "1.0" required,
+ * nothing but specVersion, host and entries at the top level.
+ *
+ * Spec:       https://agenticresourcediscovery.org/spec/ (https://github.com/ards-project/ard-spec, spec/ard.md)
+ * Lighthouse: https://github.com/GoogleChrome/lighthouse/blob/v13.5.0/core/audits/agentic/ard-schema.js
+ */
+import type { Check, Manifest } from '../types.js';
+export declare const ARD_PATH = "/.well-known/ard.json";
+export declare const LEGACY_PATH = "/.well-known/ai-catalog.json";
+export declare const MCP_CARD_TYPE = "application/mcp-server-card+json";
+export interface ArdIssues {
+    /** Against ARD v0.91: the entry schema and its required terms. */
+    errors: string[];
+    /** Soft: representativeQueries outside 2 to 5, types Lighthouse doesn't know. */
+    warnings: string[];
+    /** What only Lighthouse 13.5 rejects, from its stricter ai-catalog schema. */
+    lighthouse: string[];
+}
+export declare function validateArd(doc: unknown): ArdIssues;
+/** An entry that points at this MCP server: its URL, a server card on the same site (often the apex, beside api.), or inline data naming the URL. */
+export declare function describesServer(e: any, serverUrl: string): boolean;
+export interface ArdFetched {
+    origin: string;
+    ard: unknown;
+    legacy: unknown;
+    /** The robots.txt Agentmap URL, if any, and what it served. */
+    agentmap?: {
+        url: string;
+        doc: unknown;
+    };
+}
+/** The checks, from what was fetched. undefined means nothing usable was there. */
+export declare function ardFindings(serverUrl: string, f: ArdFetched): Check[];
+/** Looks on the website's origin, then the MCP server's. */
+export declare function ardChecks(m: Manifest): Promise<Check[]>;
+/**
+ * A manifest for /.well-known/ard.json that Lighthouse 13.5 also accepts: one entry for the MCP
+ * server, pointing at its server card when there is one. representativeQueries come from your
+ * prompts and test cases, capabilities from your tool names.
+ */
+export declare function ardManifest(m: Manifest, o?: {
+    tools?: string[];
+    serverCard?: string;
+}): {
+    specVersion: string;
+    host: {
+        logoUrl?: string | undefined;
+        documentationUrl?: string | undefined;
+        displayName: string;
+    };
+    entries: {
+        version?: string | undefined;
+        tags?: string[] | undefined;
+        capabilities?: string[] | undefined;
+        representativeQueries?: string[] | undefined;
+        description?: string | undefined;
+        identifier: string;
+        displayName: string;
+        type: string;
+        url: string;
+    }[];
+};

package/dist/checks/ard.js

@@ -0,0 +1,215 @@
+export const ARD_PATH = '/.well-known/ard.json';
+export const LEGACY_PATH = '/.well-known/ai-catalog.json';
+export const MCP_CARD_TYPE = 'application/mcp-server-card+json';
+/** spec/schemas/ard-entry.schema.json: urn:air:<publisher>:<namespace>:<name>. */
+const URN = /^urn:air:[a-zA-Z0-9.-]+(:[a-zA-Z0-9._-]+)+$/;
+/** The types Lighthouse 13.5 calls standard; others get a low-severity warning there. */
+const STANDARD_TYPES = [
+    'application/ai-catalog+json',
+    'application/agent-card+json',
+    'application/a2a-agent-card+json',
+    MCP_CARD_TYPE,
+    'application/agent-skills+zip',
+    'application/agent-skills+gzip',
+    'text/markdown; profile="urn:air:agent-skills"',
+    'application/ai-registry',
+    'application/ai-registry+json',
+];
+/** The ai-catalog schema allows only these in host. */
+const HOST_KEYS = ['displayName', 'identifier', 'documentationUrl', 'logoUrl', 'trustManifest'];
+export function validateArd(doc) {
+    const out = { errors: [], warnings: [], lighthouse: [] };
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc))
+        return { ...out, errors: ['not a JSON object'] };
+    const d = doc;
+    if (!Array.isArray(d.entries))
+        out.errors.push(d.entries === undefined ? 'no "entries" array' : '"entries" is not an array');
+    if (d.specVersion !== '1.0')
+        out.lighthouse.push(d.specVersion === undefined ? 'no specVersion' : `specVersion "${d.specVersion}"`);
+    const extra = Object.keys(d).filter((k) => !['specVersion', 'host', 'entries'].includes(k));
+    if (extra.length)
+        out.lighthouse.push(`top-level ${extra.join(', ')}`);
+    if (d.host !== undefined) {
+        if (!d.host || typeof d.host !== 'object' || !d.host.displayName)
+            out.lighthouse.push('host has no displayName');
+        const hostExtra = Object.keys(d.host ?? {}).filter((k) => !HOST_KEYS.includes(k));
+        if (hostExtra.length)
+            out.lighthouse.push(`host.${hostExtra.join(', host.')}`);
+    }
+    (Array.isArray(d.entries) ? d.entries : []).forEach((e, i) => {
+        const label = e?.displayName || e?.identifier || `entry ${i + 1}`;
+        if (!e || typeof e !== 'object') {
+            out.errors.push(`${label}: not an object`);
+            return;
+        }
+        if (!e.identifier)
+            out.errors.push(`${label}: no identifier`);
+        else if (!URN.test(e.identifier))
+            out.errors.push(`${label}: identifier "${e.identifier}" isn't urn:air:<publisher>:<namespace>:<name>`);
+        if (!e.displayName)
+            out.errors.push(`${label}: no displayName`);
+        if (!e.type)
+            out.errors.push(`${label}: no type`);
+        else if (!STANDARD_TYPES.includes(e.type))
+            out.warnings.push(`${label}: Lighthouse doesn't know type "${e.type}"`);
+        if ((e.url !== undefined) === (e.data !== undefined))
+            out.errors.push(`${label}: needs exactly one of url and data`);
+        const q = e.representativeQueries;
+        if (q === undefined)
+            out.warnings.push(`${label}: no representativeQueries`);
+        else if (!Array.isArray(q) || q.some((x) => typeof x !== 'string'))
+            out.errors.push(`${label}: representativeQueries must be strings`);
+        else if (q.length < 2 || q.length > 5)
+            out.warnings.push(`${label}: ${q.length} representativeQueries`);
+        if (e.trustManifest !== undefined && !e.trustManifest?.identity)
+            out.errors.push(`${label}: trustManifest has no identity`);
+    });
+    return out;
+}
+const bare = (u) => (u ?? '').replace(/\/+$/, '').toLowerCase();
+/** The last two labels of a hostname: enough to tell api.example.com and example.com are one site. */
+const site = (u) => {
+    try {
+        return new URL(u).hostname.split('.').slice(-2).join('.');
+    }
+    catch {
+        return '';
+    }
+};
+/** An entry that points at this MCP server: its URL, a server card on the same site (often the apex, beside api.), or inline data naming the URL. */
+export function describesServer(e, serverUrl) {
+    if (!e || typeof e !== 'object')
+        return false;
+    if (bare(e.url) === bare(serverUrl))
+        return true;
+    if (typeof e.url === 'string' && e.type === MCP_CARD_TYPE)
+        return site(e.url) === site(serverUrl);
+    return e.data !== undefined && JSON.stringify(e.data).includes(serverUrl);
+}
+/** The checks, from what was fetched. undefined means nothing usable was there. */
+export function ardFindings(serverUrl, f) {
+    const checks = [];
+    const found = f.ard ?? f.legacy;
+    const where = `${f.origin}${f.ard !== undefined ? ARD_PATH : LEGACY_PATH}`;
+    checks.push(f.ard !== undefined
+        ? { id: 'ard.path', level: 'pass', title: 'The ARD manifest is at /.well-known/ard.json', detail: where }
+        : {
+            id: 'ard.path',
+            level: 'warn',
+            title: 'The ARD manifest is at /.well-known/ard.json',
+            detail: `only at ${where}, the predecessor path`,
+            fix: `ARD v0.91 consumers must read ${ARD_PATH} and needn't read ai-catalog.json. Serve the same file at both while Lighthouse 13.5 still reads ai-catalog.json.`,
+        });
+    const v = validateArd(found);
+    const entries = Array.isArray(found?.entries) ? found.entries : [];
+    checks.push(v.errors.length
+        ? {
+            id: 'ard.manifest',
+            level: 'warn',
+            title: 'The ARD manifest is valid',
+            detail: v.errors.slice(0, 4).join('; ') + (v.errors.length > 4 ? `; ${v.errors.length - 4} more` : ''),
+            fix: 'Each entry needs identifier (urn:air:<publisher>:<namespace>:<name>), displayName, type and exactly one of url or data (ARD v0.91 §4.2). "mcplane pack ard" writes a valid one.',
+        }
+        : { id: 'ard.manifest', level: 'pass', title: 'The ARD manifest is valid', detail: `${entries.length} ${entries.length === 1 ? 'entry' : 'entries'}${v.warnings.length ? `; ${v.warnings.join('; ')}` : ''}` });
+    // Lighthouse reads the Agentmap target, else ai-catalog.json (a rel="ai-catalog" link in the page also counts; not read here).
+    const lhUrl = f.agentmap?.url ?? (f.legacy !== undefined ? `${f.origin}${LEGACY_PATH}` : null);
+    const lhDoc = f.agentmap ? f.agentmap.doc : f.legacy;
+    if (!lhUrl) {
+        checks.push({
+            id: 'ard.lighthouse',
+            level: 'info',
+            title: 'Lighthouse 13.5 can find the ARD manifest',
+            detail: `no robots.txt Agentmap line and nothing at ${LEGACY_PATH}`,
+            fix: `Add "Agentmap: ${where}" to robots.txt. Lighthouse 13.5 reads an Agentmap line, a rel="ai-catalog" link or ${LEGACY_PATH}, and otherwise marks its ARD audit not applicable.`,
+        });
+    }
+    else {
+        const lh = validateArd(lhDoc);
+        const bad = lhDoc === undefined ? [`nothing usable at ${lhUrl}`] : [...lh.errors, ...lh.lighthouse];
+        checks.push(bad.length
+            ? {
+                id: 'ard.lighthouse',
+                level: 'warn',
+                title: 'Lighthouse 13.5 accepts the ARD manifest',
+                detail: `${lhUrl}: ${bad.slice(0, 4).join('; ')}`,
+                fix: 'Lighthouse validates against the older ai-catalog schema: specVersion "1.0", nothing but specVersion, host and entries at the top level, and host limited to displayName, identifier, documentationUrl, logoUrl and trustManifest. ARD v0.91 ignores extra top-level members, so meeting both costs nothing.',
+            }
+            : { id: 'ard.lighthouse', level: 'pass', title: 'Lighthouse 13.5 accepts the ARD manifest', detail: lhUrl });
+    }
+    const mine = entries.find((e) => describesServer(e, serverUrl));
+    checks.push(mine
+        ? { id: 'ard.entry', level: 'pass', title: 'The ARD manifest lists this MCP server', detail: mine.identifier }
+        : { id: 'ard.entry', level: 'info', title: 'The ARD manifest lists this MCP server', detail: `no entry points at ${serverUrl} or its server card`, fix: `Add an entry with type ${MCP_CARD_TYPE}. "mcplane pack ard" writes one.` });
+    return checks;
+}
+const getJson = async (url) => {
+    const r = await fetch(url, { headers: { accept: 'application/json', 'user-agent': 'mcplane' }, redirect: 'follow', signal: AbortSignal.timeout(10_000) }).catch(() => null);
+    if (!r?.ok)
+        return undefined;
+    try {
+        return JSON.parse(await r.text()) ?? undefined;
+    }
+    catch {
+        // A catch-all page that answers every path with HTML isn't a manifest.
+        return undefined;
+    }
+};
+/** Looks on the website's origin, then the MCP server's. */
+export async function ardChecks(m) {
+    const origins = [...new Set([m.links?.website, m.server.url].filter((u) => !!u).map((u) => new URL(u).origin))];
+    for (const origin of origins) {
+        const [ard, legacy, robots] = await Promise.all([
+            getJson(`${origin}${ARD_PATH}`),
+            getJson(`${origin}${LEGACY_PATH}`),
+            fetch(`${origin}/robots.txt`, { headers: { 'user-agent': 'mcplane' }, signal: AbortSignal.timeout(10_000) })
+                .then((r) => (r.ok ? r.text() : ''))
+                .catch(() => ''),
+        ]);
+        if (ard === undefined && legacy === undefined)
+            continue;
+        const line = robots.match(/^\s*Agentmap:\s*(\S+)/im)?.[1];
+        let agentmap;
+        if (line) {
+            const url = new URL(line, origin).href;
+            agentmap = { url, doc: url === `${origin}${ARD_PATH}` ? ard : url === `${origin}${LEGACY_PATH}` ? legacy : await getJson(url) };
+        }
+        return ardFindings(m.server.url, { origin, ard, legacy, agentmap });
+    }
+    return [
+        {
+            id: 'ard.path',
+            level: 'info',
+            title: 'The ARD manifest is at /.well-known/ard.json',
+            detail: `nothing at ${origins.map((o) => `${o}${ARD_PATH}`).join(' or ')}`,
+            fix: '"mcplane pack ard" writes one. ARD (Agentic Resource Discovery, v0.91, a proposal) is how agents and registries find what a domain offers, and Lighthouse 13.5 audits it.',
+        },
+    ];
+}
+/**
+ * A manifest for /.well-known/ard.json that Lighthouse 13.5 also accepts: one entry for the MCP
+ * server, pointing at its server card when there is one. representativeQueries come from your
+ * prompts and test cases, capabilities from your tool names.
+ */
+export function ardManifest(m, o = {}) {
+    const publisher = new URL(m.links?.website ?? m.server.url).hostname.replace(/^www\./, '');
+    const queries = [...new Set([...(m.prompts ?? []), ...(m.tests?.positive ?? []).map((t) => t.prompt)].map((q) => q.trim()).filter((q) => q && q.length <= 160))].slice(0, 5);
+    const tools = o.tools?.length ? o.tools : [...new Set((m.tests?.positive ?? []).flatMap((t) => t.tools))];
+    const description = m.oneLiner || m.description?.split(/\n\s*\n/)[0];
+    return {
+        specVersion: '1.0',
+        host: { displayName: m.author?.name || m.title, ...(m.links?.docs ? { documentationUrl: m.links.docs } : {}), ...(m.icon ? { logoUrl: m.icon } : {}) },
+        entries: [
+            {
+                identifier: `urn:air:${publisher}:server:${m.name}`,
+                displayName: m.title,
+                type: MCP_CARD_TYPE,
+                url: o.serverCard ?? m.server.url,
+                ...(description ? { description } : {}),
+                ...(queries.length ? { representativeQueries: queries } : {}),
+                ...(tools.length ? { capabilities: tools } : {}),
+                ...(m.category ? { tags: [m.category] } : {}),
+                ...(m.version ? { version: m.version } : {}),
+            },
+        ],
+    };
+}

package/dist/checks/auth.js

@@ -1,3 +1,4 @@
+import { VERSION } from '../version.js';
 const REDIRECTS = {
     chatgpt: ['https://chatgpt.com/connector_platform_oauth_redirect', 'https://platform.openai.com/apps-manage/oauth'],
     claude: ['https://claude.ai/api/mcp/auth_callback'],
@@ -14,7 +15,7 @@ export async function authChecks(url, opts = {}) {
     const bare = await fetch(url, {
         method: 'POST',
         headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream', 'user-agent': 'mcplane' },
-        body: '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"mcplane","version":"0.1.0"}}}',
+        body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'mcplane', version: VERSION } } }),
     }).catch(() => null);
     const www = bare?.headers.get('www-authenticate') ?? '';
     if (bare?.status === 401 && /resource_metadata=/i.test(www)) {

package/dist/checks/chain.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The sign-in chain a reviewer walks: the authorization endpoint, the page it sends them to, and the
+ * identity-provider hosts that page loads. Plain GETs, as a browser would send them: nothing signs in
+ * and no client is registered, so an authorization server that checks client_id first stops the walk
+ * at its own error, and server.signIn (or --sign-in) names the pages to check from there.
+ *
+ * A bot challenge (Cloudflare's cf-mitigated: challenge) or a 403 anywhere on the chain leaves the
+ * OAuth window blank or erroring, often only from the data-centre networks reviewers use, while every
+ * check on the MCP server itself passes.
+ */
+import type { Check, Manifest } from '../types.js';
+import { type Discovery } from './oauth.js';
+export interface Hop {
+    url: string;
+    status: number;
+    /** What walled it off, if anything. */
+    wall: string | null;
+    location?: string;
+    contentType?: string;
+    /** A short reason from the body of an error answer (invalid_client, …). */
+    said?: string;
+    error?: string;
+}
+/** A bot challenge or a refusal, read from the response the way a browser would get it. */
+export declare function wallOf(status: number, headers: Headers): string | null;
+/** Sign-in pages and identity-provider URLs a page links to or loads. */
+export declare function authLinks(html: string, base: string): string[];
+/** Requests left for one chain, so a long redirect loop or a page full of links can't run away (Workers cap subrequests). */
+export interface Budget {
+    left: number;
+}
+/** GETs a URL and follows its redirects by hand, recording every hop. Never follows into the client's redirect URI. */
+export declare function walk(start: string, budget?: Budget): Promise<{
+    hops: Hop[];
+    html?: string;
+    last: string;
+}>;
+/** The authorization request a client would open, for a client that isn't registered. */
+export declare function authorizeUrl(endpoint: string, md: Record<string, any>, resource: string): string;
+/** The chain's hops as one check. Exported for tests. */
+export declare function chainCheck(start: Hop[], pages: Hop[][], opts: {
+    stoppedEarly: boolean;
+    seeded: boolean;
+}): Check;
+export declare function chainChecks(m: Manifest, d: Discovery | null): Promise<Check[]>;