wiki-formant 0.71.0 → 0.73.0

package/README.md

@@ -213,6 +213,12 @@ What it gets right:
 - **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.
@@ -260,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/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

@@ -600,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

@@ -240,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

@@ -86,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

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

@@ -178,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.71.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",