wiki-formant 0.70.0 → 0.73.0

package/README.md

@@ -207,11 +207,18 @@ What it gets right:
 - **The preflight allow-list includes `Accept` and `Mcp-Protocol-Version`.** One missing entry fails the preflight rather than the POST, which presents as "the server is down".
 - **Batches are capped** (default 20) with a teaching error, because the rate limiter charges one token per HTTP request before the body is parsed. From 2025-06-18 on they are refused outright, because that revision removed them.
 - **Both protocol eras, one endpoint.** A request carrying `io.modelcontextprotocol/protocolVersion` in `params._meta` is served as `2026-07-28`: `server/discover`, per-request version and header validation (`-32022` naming every version spoken, `-32020` on a routing header that disagrees with the body), `resultType` and cache hints on results, and 404 for the methods that revision removed. Everything else is the legacy era, where `initialize` echoes the client's version when it is one of `2025-11-25`, `2025-06-18`, `2025-03-26` or `2024-11-05` and offers the newest otherwise. The spec permits a dual-era server, and it is the only way to adopt the new revision without failing the handshake of every client already in the field.
+- **The A2A call an agent card invites is answered.** Every card names this endpoint as its JSON-RPC `url`, so `message/send` (v0.3) and `SendMessage` (v1.0) get a message back: the result of the tool `answer` names (`{ tool: 'search_wiki', argument: 'query' }`), or `instructions` and the tool names without one. The task methods are `-32001`, since no task is ever created; streaming and push are `-32004`.
 - **The version is negotiated, not asserted.** Every response carries it back in `MCP-Protocol-Version`. Answering a constant is legal and still costs the caller structured output, tool titles and `_meta` without ever saying so.
 - **`Access-Control-Expose-Headers` is set.** Allow-Headers governs what a browser may send, Expose-Headers what it may read — without the second a browser client cannot see `Retry-After` on a 429, and a rate limit presents as a hang.
 - **The rate limit is declared, not wired.** Put `rateLimit: {capacity, refillPerSec}` on the config and `mcpResponse` enforces it before parsing the body, refuses with a JSON-RPC envelope, and states `RateLimit-Limit`/`-Remaining`/`-Reset` on every answer. Four routes had each transcribed that by hand through three differently-named local helpers, which is how a headroom header gets added to one surface and forgotten on the next.
 - **`mcpRateLimited(retryAfterSec)` is a JSON-RPC envelope.** A 429 whose body is `{"error": "..."}` is a string where the client's parser expects `{code, message}`, on the one response an agent meets exactly when it is working hard.
 
+### A read-only surface
+
+`readOnly(config, hide?)` is the same server with its writes taken off: the tools marked `readOnlyHint: true` and not named in `hide`, with every instruction line and prompt that names a dropped tool dropped too, and `destructiveHint` and `openWorldHint` stated on each tool that is kept. It exists for ChatGPT plugins, whose review refuses crypto transfers and checkout links and whose reviewers cannot sign a ROLA challenge. Mount it at its own route (`mcpResponse(req, readOnly(config))`), so the main endpoint keeps its writes, and hold the plugin package to it with `pluginParity` (Conformance). Keep each instruction a line of its own, so a line that names a write takes nothing else with it.
+
+`openaiChallengeHandler()` from `wiki-formant/well-known` serves `/.well-known/openai-apps-challenge`: the portal's domain token from `OPENAI_APPS_CHALLENGE`, as bare text, or a 404 while it is unset.
+
 ### Structured output, `_meta`, and the envelope gate
 
 **Every object a handler returns comes back as `structuredContent` beside the text block**, so a client reads the answer rather than scraping prose for it. This used to be gated on declaring an `outputSchema`, and the result was that across four live servers and thirty-two tools — every one of them answering in JSON — not a single response ever carried it. `outputSchema` remains the stronger contract, because a client validates against it; it is no longer the price of admission. A handler returning a string is left alone.
@@ -259,6 +266,7 @@ The drift checks hold an MCP server to what its own site does, so a tool cannot
 - `roundTrip(t, label, { read, write })`: what a read tool hands out, the write tool takes back unchanged, and the next read matches.
 - `openapiWriteParity(t, [[path, method, tool], …])`: every field an OpenAPI write documents, the matching tool takes.
 - `rolaOriginCheck(t)`: a challenge tool's ROLA recipe names the origin under test.
+- `pluginParity(t, { plugin, mcp })`: a ChatGPT plugin package (`chatgpt/plugin.json` and `chatgpt/mcp.json`) agrees with the endpoint it names, rebased onto the origin under test: one streamable-HTTP server that answers; every tool a review case triggers is listed there; every tool states `readOnlyHint`, `destructiveHint` and `openWorldHint` as booleans; `capabilities` claims `Write` exactly when a write tool is listed; no instruction, description or prompt names a tool the main endpoint has and the plugin's lacks; the listing is within the portal's limits with five positive and three negative cases; and each listing page on the site's own origin answers, with its `#anchor` where it names one. The demo recording is the one review field it cannot check.
 
 `standardVersionSources(t, openapiPaths)` is the `versionCoherence` map every S10 surface serves — both agent-card paths, `mcp.json`, the server card and each path the OpenAPI document answers at — so a suite names only the paths it adds. `t.rpcAt(endpoint, …)` and `t.callAt` drive a second MCP endpoint on the same surface with the same backoff, User-Agent and tally.
 

package/dist/a2a.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/a2a.js

@@ -0,0 +1,95 @@
+// a2a.ts — the A2A calls an agent card invites, answered on the MCP endpoint.
+//
+// Every card here names the MCP endpoint as its `url` with `preferredTransport:
+// JSONRPC`, which to an A2A client means "send `message/send` here". The
+// endpoint answered -32601, so the card promised an interface the server then
+// refused: A2A clients and the registries that probe for them sent about 140
+// such calls per origin in a fortnight (October 2026) and got nothing back.
+// Now a message is answered with the site's own search, and the task methods
+// say plainly that no task exists, since every answer is a direct message.
+//
+// Both revisions in the field are spoken: v0.3 (`message/send`, a Message with
+// `kind`) and v1.0 (`SendMessage`, a `{ message }` with proto-JSON enums).
+import { McpToolError } from './mcp.js';
+const SEND = { 'message/send': '0.3', SendMessage: '1.0' };
+/** Task methods: none can succeed, because no task is ever created. */
+const TASK = new Set(['tasks/get', 'tasks/cancel', 'tasks/resubscribe', 'GetTask', 'CancelTask', 'SubscribeToTask']);
+/** Everything else either revision defines, which this server declines. */
+const UNSUPPORTED = new Set([
+    'message/stream',
+    'tasks/pushNotificationConfig/set',
+    'tasks/pushNotificationConfig/get',
+    'tasks/pushNotificationConfig/list',
+    'tasks/pushNotificationConfig/delete',
+    'agent/getAuthenticatedExtendedCard',
+    'SendStreamingMessage',
+    'ListTasks',
+    'CreateTaskPushNotificationConfig',
+    'GetTaskPushNotificationConfig',
+    'ListTaskPushNotificationConfigs',
+    'DeleteTaskPushNotificationConfig',
+    'GetExtendedAgentCard',
+]);
+/** @internal */
+export const isA2aMethod = (method) => method in SEND || TASK.has(method) || UNSUPPORTED.has(method);
+const error = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+/** The text of a message's text parts, whichever revision shaped them. */
+function textOf(message) {
+    const parts = message?.parts;
+    if (!Array.isArray(parts))
+        return '';
+    return parts
+        .map(p => (p && typeof p.text === 'string' ? p.text : ''))
+        .join(' ')
+        .trim();
+}
+/** What a message gets when there is no search to run: what this server is and how to use it. */
+const orientation = (config) => `${config.instructions}\n\nThis endpoint also speaks MCP (JSON-RPC over POST): send "initialize", then "tools/list". Tools: ${config.tools.map(t => t.name).join(', ')}.`;
+async function reply(text, config) {
+    const tool = config.answer && config.tools.find(t => t.name === config.answer.tool);
+    if (!text || !tool)
+        return { text: orientation(config) };
+    try {
+        const out = await tool.handler({ [config.answer.argument]: text }, {
+            meta: {},
+            setMeta: () => { },
+            protocolVersion: '2025-11-25',
+        });
+        const lead = `${config.serverInfo.name} ${tool.name} for ${JSON.stringify(text)}. For more, call this endpoint over MCP: "initialize", then "tools/list".`;
+        if (typeof out === 'string')
+            return { text: `${lead}\n\n${out}` };
+        // The text twin stays beside the data, as it does on an MCP tool result:
+        // a client that reads only text parts still has to be able to read the answer.
+        return { text: `${lead}\n\n${JSON.stringify(out, null, 2)}`, ...(out && typeof out === 'object' && !Array.isArray(out) ? { data: out } : {}) };
+    }
+    catch (err) {
+        if (err instanceof McpToolError)
+            return { text: `${err.message}\n\n${orientation(config)}` };
+        throw err;
+    }
+}
+/** Answer one A2A call. Only reached for a method `isA2aMethod` accepts. @internal */
+export async function handleA2a(req, config) {
+    const { id, method } = req;
+    if (TASK.has(method)) {
+        return error(id, -32001, 'Task not found: this agent keeps no tasks. Every message it is sent is answered directly with a message.');
+    }
+    const revision = SEND[method];
+    if (!revision) {
+        const send = method.includes('/') ? 'message/send' : 'SendMessage';
+        return error(id, -32004, `Unsupported operation: "${method}". This agent answers ${send} only, without streaming or push notifications.`);
+    }
+    const message = req.params?.message;
+    if (!message || typeof message !== 'object') {
+        return error(id, -32602, 'Missing params.message: send a message with at least one text part.');
+    }
+    const { text, data } = await reply(textOf(message), config);
+    const contextId = typeof message.contextId === 'string' ? message.contextId : crypto.randomUUID();
+    const messageId = crypto.randomUUID();
+    if (revision === '1.0') {
+        const parts = [{ text }, ...(data ? [{ data }] : [])];
+        return { jsonrpc: '2.0', id, result: { message: { messageId, contextId, role: 'ROLE_AGENT', parts } } };
+    }
+    const parts = [{ kind: 'text', text }, ...(data ? [{ kind: 'data', data }] : [])];
+    return { jsonrpc: '2.0', id, result: { kind: 'message', messageId, contextId, role: 'agent', parts } };
+}

package/dist/conformance.d.ts

@@ -260,3 +260,18 @@ export declare function rolaOriginCheck(t: Tester, opts?: {
     endpoint?: string;
     tool?: string;
 }): Promise<void>;
+/**
+ * A ChatGPT plugin package agrees with the server it names. The ZIP is uploaded
+ * once and OpenAI rescans the server every day, so a renamed tool, a write that
+ * reaches the plugin's endpoint, a description naming a tool the endpoint lacks,
+ * or a moved legal page fails review with nothing in the repo noticing. Pass the
+ * parsed `chatgpt/plugin.json` and `chatgpt/mcp.json`.
+ *
+ * URLs on the plugin's own origin are rebased onto the origin under test, so a
+ * run against a dev server checks the dev server. The demo recording is the
+ * one review field no code can hold, so it is not checked.
+ */
+export declare function pluginParity(t: Tester, pkg: {
+    plugin: unknown;
+    mcp: unknown;
+}): Promise<void>;

package/dist/conformance.js

@@ -294,6 +294,13 @@ export async function agentCardParity(t) {
     const probe = await rawPost(endpoint, { jsonrpc: '2.0', id: 1, method: 'ping' });
     t.recordCall();
     t.check('agent card url is callable', (probe.headers.get('content-type') ?? '').includes('json'), `POST ${endpoint} -> ${probe.status} ${probe.headers.get('content-type')}`);
+    // Callable is not the same as answering. A `JSONRPC` url invites A2A's own
+    // first call, and a -32601 to it refuses the interface the card names.
+    const send = await t.rpcAt(endpoint, 'message/send', {
+        message: { kind: 'message', role: 'user', messageId: 'conformance', parts: [{ kind: 'text', text: String(a.name ?? 'help') }] },
+    });
+    const reply = send.result;
+    t.check('agent card url answers A2A', reply?.kind === 'message' && typeof reply.parts?.[0]?.text === 'string', reply ? `message/send -> ${reply.parts?.length} part(s)` : `message/send -> ${JSON.stringify(send.error)}`);
 }
 /**
  * Any surface an agent recrawls should answer a conditional GET with a 304.
@@ -593,3 +600,91 @@ export async function rolaOriginCheck(t, opts = {}) {
     const message = answer?.sign?.message ?? '';
     t.check('ROLA recipe names this origin', message.includes(`"${origin}"`), `expects "${origin}" in: …${message.slice(-90)}`);
 }
+const LISTING_LIMITS = { displayName: 30, shortDescription: 30, longDescription: 4000, developerName: 80, category: 80 };
+const LISTING_URLS = ['websiteURL', 'supportURL', 'privacyPolicyURL', 'termsOfServiceURL'];
+const HINTS = ['readOnlyHint', 'destructiveHint', 'openWorldHint'];
+/**
+ * A ChatGPT plugin package agrees with the server it names. The ZIP is uploaded
+ * once and OpenAI rescans the server every day, so a renamed tool, a write that
+ * reaches the plugin's endpoint, a description naming a tool the endpoint lacks,
+ * or a moved legal page fails review with nothing in the repo noticing. Pass the
+ * parsed `chatgpt/plugin.json` and `chatgpt/mcp.json`.
+ *
+ * URLs on the plugin's own origin are rebased onto the origin under test, so a
+ * run against a dev server checks the dev server. The demo recording is the
+ * one review field no code can hold, so it is not checked.
+ */
+export async function pluginParity(t, pkg) {
+    const openai = pkg.plugin.extensions?.['com.openai'] ?? {};
+    const listing = openai.interface ?? {};
+    const cases = openai.review?.test_cases ?? {};
+    const servers = Object.values(pkg.mcp.mcpServers ?? {});
+    const named = servers[0]?.url ?? '';
+    t.check('plugin names one server', servers.length === 1 && servers[0]?.type === 'streamable-http' && named.startsWith('https://'), `${servers.length} server(s): ${named || 'no url'}`);
+    if (!named.startsWith('https://'))
+        return;
+    const canonical = new URL(named).origin;
+    const here = (url) => {
+        const u = new URL(url);
+        return u.origin === canonical ? new URL(`${u.pathname}${u.search}`, t.base).href : url;
+    };
+    const endpoint = here(named);
+    const tools = (await t.rpcAt(endpoint, 'tools/list')).result?.tools ?? [];
+    const names = new Set(tools.map(x => x.name));
+    t.check('plugin endpoint answers', tools.length > 0, `${endpoint}: ${tools.length} tools`);
+    const triggered = [...new Set((cases.positive ?? []).flatMap(c => (c.tools_triggered ?? '').split(/[\s,]+/).filter(Boolean)))];
+    const absent = triggered.filter(n => !names.has(n));
+    t.check('review cases name live tools', triggered.length > 0 && absent.length === 0, absent.length ? `not on the endpoint: ${absent.join(', ')}` : `${triggered.join(', ')}`);
+    const vague = tools.filter(x => HINTS.some(k => typeof x.annotations?.[k] !== 'boolean'));
+    t.check('plugin hints are booleans', vague.length === 0, vague.length ? vague.map(x => x.name).join(', ') : `${HINTS.join(', ')} on ${tools.length} tools`);
+    const writes = tools.filter(x => x.annotations?.readOnlyHint === false).map(x => x.name);
+    const claimsWrite = Array.isArray(listing.capabilities) && listing.capabilities.includes('Write');
+    t.check('plugin capabilities', claimsWrite === writes.length > 0, `capabilities ${claimsWrite ? 'claim' : 'omit'} Write; ${writes.length ? `writes: ${writes.join(', ')}` : 'no write tools'}`);
+    // A tool the main endpoint has and the plugin's lacks, named anywhere the
+    // model reads on the plugin's endpoint, sends it to a call that cannot work.
+    const lost = ((await t.rpc('tools/list')).result?.tools ?? []).map(x => x.name).filter(n => !names.has(n));
+    const init = await t.rpcAt(endpoint, 'initialize', {
+        protocolVersion: MCP_LEGACY_PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: 'plugin-parity', version: '1' },
+    });
+    const prompts = (await t.rpcAt(endpoint, 'prompts/list')).result?.prompts ?? [];
+    const texts = [
+        ['instructions', init.result?.instructions ?? ''],
+        ...tools.map((x) => [`${x.name} description`, x.description ?? '']),
+    ];
+    for (const p of prompts) {
+        const got = (await t.rpcAt(endpoint, 'prompts/get', { name: p.name })).result;
+        texts.push([`prompt ${p.name}`, (got?.messages ?? []).map(m => m.content?.text ?? '').join('\n')]);
+    }
+    const strays = texts.flatMap(([where, text]) => lost.filter(n => new RegExp(`\\b${n}\\b`).test(text)).map(n => `${where} names ${n}`));
+    t.check('plugin text names only its tools', strays.length === 0, strays.length ? strays.join('; ') : `${texts.length} texts, ${lost.length} tools withheld`);
+    const str = (k) => (typeof listing[k] === 'string' ? listing[k] : '');
+    const starters = Array.isArray(listing.defaultPrompt) ? listing.defaultPrompt : [];
+    const positive = cases.positive ?? [];
+    const faults = [
+        ...Object.entries(LISTING_LIMITS).filter(([k, n]) => !str(k) || str(k).length > n).map(([k, n]) => `${k} ${str(k).length}/${n}`),
+        ...(starters.length > 3 || starters.some(p => typeof p !== 'string' || p.length > 128) ? ['defaultPrompt: at most 3, 128 each'] : []),
+        ...(typeof listing.logo === 'string' ? [] : ['no logo']),
+        ...(positive.length === 5 && positive.every(c => c.description && c.prompt && c.tools_triggered && c.expected_behavior)
+            ? []
+            : ['5 positive cases, each with description, prompt, tools_triggered and expected_behavior']),
+        ...((cases.negative ?? []).length === 3 && (cases.negative ?? []).every(c => c.description && c.prompt) ? [] : ['3 negative cases']),
+    ];
+    t.check('plugin listing', faults.length === 0, faults.length ? faults.join('; ') : `${str('displayName')}: ${str('shortDescription')}`);
+    for (const k of LISTING_URLS) {
+        const url = str(k);
+        if (!url.startsWith('https://')) {
+            t.check(`listing ${k}`, false, url ? `not https: ${url}` : 'missing');
+            continue;
+        }
+        if (new URL(url).origin !== canonical) {
+            t.check(`listing ${k}`, true, `${url} (another origin, not fetched)`);
+            continue;
+        }
+        const res = await fetch(here(url));
+        const anchor = decodeURIComponent(new URL(url).hash.slice(1));
+        const found = !anchor || (await res.text()).includes(`id="${anchor}"`);
+        t.check(`listing ${k}`, res.ok && found, `${res.status} ${url}${found ? '' : ` (no id="${anchor}")`}`);
+    }
+}

package/dist/mcp.d.ts

@@ -179,6 +179,16 @@ export interface McpServerConfig {
      * clicks when they do not have one yet.
      */
     prompts?: McpPrompt[];
+    /**
+     * The tool an A2A `message/send` is answered with, and the argument its text
+     * fills: usually the search tool and its query. Without it a message is
+     * answered with `instructions` and the tool names, which is still an answer
+     * where -32601 was a refusal of the interface the agent card names.
+     */
+    answer?: {
+        tool: string;
+        argument: string;
+    };
     /** Appended to the GET refusal so a browser that lands here learns where to go. */
     docsUrl?: string;
     /**
@@ -230,6 +240,18 @@ export interface EnvelopeGate {
     empty: boolean;
     finish(dispatched: object | object[] | null): Promise<object | object[] | null>;
 }
+/**
+ * The same server with its writes taken off, for a client that may not carry
+ * them: ChatGPT's plugin review refuses crypto transfers and checkout links, and
+ * a reviewer cannot sign a ROLA challenge. It keeps the tools marked
+ * `readOnlyHint: true` and not in `hide`, then drops every instruction line and
+ * prompt that names a tool it lost, so nothing sends an agent to a tool that is
+ * not there.
+ *
+ * The kept tools state all three hints that review reads. A read-only tool
+ * destroys nothing, and an unstated `openWorldHint` is the spec's default, true.
+ */
+export declare function readOnly(config: McpServerConfig, hide?: readonly string[]): McpServerConfig;
 /**
  * A caller-fixable failure inside a handler (page not found, empty input).
  * Reported as a tool result with `isError` so the model sees the text and can

package/dist/mcp.js

@@ -66,6 +66,7 @@ function requestProtocol(request) {
 }
 /** JSON-RPC batching was removed in 2025-06-18 and stays removed; it is legal only below that. */
 const allowsBatch = (v) => v === '2025-03-26' || v === '2024-11-05';
+import { handleA2a, isA2aMethod } from './a2a.js';
 import { clientKey, rateLimit, rateLimitHeaders, withRateLimit } from './rate-limit.js';
 /**
  * A tool as every surface advertises it — `tools/list`, the agent card and
@@ -85,6 +86,28 @@ export function toolCard(tool) {
         ...(tool.annotations ? { annotations: tool.annotations } : {}),
     };
 }
+/**
+ * The same server with its writes taken off, for a client that may not carry
+ * them: ChatGPT's plugin review refuses crypto transfers and checkout links, and
+ * a reviewer cannot sign a ROLA challenge. It keeps the tools marked
+ * `readOnlyHint: true` and not in `hide`, then drops every instruction line and
+ * prompt that names a tool it lost, so nothing sends an agent to a tool that is
+ * not there.
+ *
+ * The kept tools state all three hints that review reads. A read-only tool
+ * destroys nothing, and an unstated `openWorldHint` is the spec's default, true.
+ */
+export function readOnly(config, hide = []) {
+    const kept = config.tools.filter(t => t.annotations?.readOnlyHint === true && !hide.includes(t.name));
+    const lost = config.tools.filter(t => !kept.includes(t)).map(t => t.name);
+    const names = (text) => lost.some(name => new RegExp(`\\b${name}\\b`).test(text));
+    return {
+        ...config,
+        instructions: config.instructions.split('\n').filter(line => !names(line)).join('\n'),
+        tools: kept.map(t => ({ ...t, annotations: { destructiveHint: false, openWorldHint: true, ...t.annotations } })),
+        prompts: config.prompts?.filter(p => !names(p.text)),
+    };
+}
 /**
  * A caller-fixable failure inside a handler (page not found, empty input).
  * Reported as a tool result with `isError` so the model sees the text and can
@@ -418,6 +441,8 @@ async function handleRpc(req, config, dispatch) {
                 }
             }
             default:
+                if (isA2aMethod(method))
+                    return await handleA2a(req, config);
                 return methodNotFound(id, method, config, dispatch.era);
         }
     }
@@ -452,7 +477,7 @@ export async function handleMcp(body, config, dispatch = { protocolVersion: ASSU
 export const MCP_CORS = {
     'Access-Control-Allow-Origin': '*',
     'Access-Control-Allow-Methods': 'POST, OPTIONS',
-    'Access-Control-Allow-Headers': 'Content-Type, Accept, Authorization, Mcp-Session-Id, Mcp-Protocol-Version, Mcp-Method, Mcp-Name, Last-Event-ID',
+    'Access-Control-Allow-Headers': 'Content-Type, Accept, Authorization, Mcp-Session-Id, Mcp-Protocol-Version, Mcp-Method, Mcp-Name, Last-Event-ID, A2A-Version',
     // Allow-Headers governs what a browser may send; without Expose-Headers it
     // may read none of what comes back. A browser client could not see the
     // negotiated version, and could not see `Retry-After` on the 429 telling it

package/dist/store.d.ts

@@ -147,8 +147,8 @@ export declare function wikiStore<B extends DiffBlock = DiffBlock>(o: WikiStoreO
         items: {
             content: B[];
             title: string;
-            metadata: PageMetadata;
             id: string;
+            metadata: PageMetadata;
             tagPath: string;
             slug: string;
             siteId: string;

package/dist/well-known.d.ts

@@ -104,6 +104,13 @@ protocolVersions: readonly string[]): Record<string, unknown>;
  * configured" instead of failing verification for a reason nobody sees.
  */
 export declare function registryAuthHandler(publicKey?: string | undefined, keyType?: string | undefined): () => Response;
+/**
+ * `/.well-known/openai-apps-challenge`: the token OpenAI's plugin portal issues
+ * to prove the MCP origin is the publisher's, served as the bare text it checks
+ * for. An env var for the same reason as the registry key: the portal issues it
+ * per plugin, after the code has shipped. Unset → 404.
+ */
+export declare function openaiChallengeHandler(token?: string | undefined): () => Response;
 /** A tool as `/.well-known/mcp.json` lists it: what tools/list says, no handler. */
 export interface ManifestTool {
     name: string;

package/dist/well-known.js

@@ -84,10 +84,20 @@ export function agentCard(config) {
         // The endpoint, not the homepage. A card's `url` is where a client sends
         // its first call, and every card here pointed at an HTML page — so a client
         // that believed the card got markup back, or a 405. MCP is JSON-RPC over
-        // HTTP POST, so an A2A caller arriving at it is answered in a shape it can
-        // parse: a -32601 naming every method the server does implement.
+        // HTTP POST, and the endpoint answers A2A's `message/send` (v0.3) and
+        // `SendMessage` (v1.0) from the site's own search (`McpServerConfig.answer`).
         url: endpoint,
         preferredTransport: 'JSONRPC',
+        // v1.0 reads the interfaces from here and ignores `url`; v0.3 the reverse.
+        ...(mcpEndpoint === null
+            ? {}
+            : {
+                supportedInterfaces: ['1.0', '0.3'].map(protocolVersion => ({
+                    url: endpoint,
+                    protocolBinding: 'JSONRPC',
+                    protocolVersion,
+                })),
+            }),
         version,
         capabilities: { streaming: false, pushNotifications: false },
         skills,
@@ -168,6 +178,17 @@ export function registryAuthHandler(publicKey = process.env.MCP_REGISTRY_PUBLIC_
         });
     };
 }
+/**
+ * `/.well-known/openai-apps-challenge`: the token OpenAI's plugin portal issues
+ * to prove the MCP origin is the publisher's, served as the bare text it checks
+ * for. An env var for the same reason as the registry key: the portal issues it
+ * per plugin, after the code has shipped. Unset → 404.
+ */
+export function openaiChallengeHandler(token = process.env.OPENAI_APPS_CHALLENGE) {
+    return () => token
+        ? new Response(token.trim(), { headers: { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'no-store' } })
+        : new Response('Not found', { status: 404 });
+}
 /**
  * `/.well-known/mcp.json`: the third path an arriving agent probes, after the
  * agent card and the OpenAPI spec. All three origins wrote the same envelope,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.70.0",
+  "version": "0.73.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, conditional-GET plumbing, and the headers and CSP every origin sends.",
   "type": "module",
   "license": "MIT",