wiki-formant 0.10.0 → 0.12.0

package/dist/crawlers.js

@@ -68,11 +68,18 @@ export function aiCrawlerTokens() {
  * agent everything, because it stops matching `*` the moment it matches itself.
  */
 export function aiCrawlerRules(opts) {
+    const aiAllow = [opts.aiAllow].flat();
     return [
-        { userAgent: '*', allow: opts.allow, disallow: opts.disallow },
+        // `aiAllow` rides on the default group too, not only on the named roster.
+        // The agent surface an origin advertises has to be reachable by a caller it
+        // has never heard of: two origins here disallowed `/api/` under `*` while
+        // their own agent card named `/api/mcp`, so an MCP client that identified
+        // honestly as itself was told the endpoint was off limits. The roster is
+        // for indexing policy, not for hiding a documented endpoint.
+        { userAgent: '*', allow: [...new Set([...[opts.allow].flat(), ...aiAllow])], disallow: opts.disallow },
         ...aiCrawlerTokens().map(userAgent => ({
             userAgent,
-            allow: opts.aiAllow,
+            allow: aiAllow,
             disallow: opts.disallow,
         })),
     ];

package/dist/crawlers.js.map

@@ -1 +1 @@
-{"version":3,"file":"crawlers.js","sourceRoot":"","sources":["../src/crawlers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"crawlers.js","sourceRoot":"","sources":["../src/crawlers.ts"],"names":[],"mappings":"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"}

package/dist/http.d.ts

@@ -1,7 +1,15 @@
 /** A stable ETag from whatever the corpus revision is (count + newest stamp). */
 export declare function corpusEtag(parts: Array<string | number | Date | null | undefined>): string;
-/** 304 when the client already holds this revision, else `null` to render. */
-export declare function notModified(request: Request, etag: string, lastModified: string): Response | null;
+/**
+ * 304 when the client already holds this revision, else `null` to render.
+ *
+ * Both validators are matched the way RFC 9110 defines them rather than by
+ * string equality, because equality is wrong in the cases that actually occur:
+ * a client sends every tag it holds as a list, a proxy adds or strips the weak
+ * prefix, and a crawler reformats the date. Each of those took a full render
+ * from a response that was already fresh.
+ */
+export declare function notModified(request: Request, etag: string, lastModified?: string | null): Response | null;
 /**
  * Headers for a plain-text export. `maxAge` is the edge window — a curated
  * corpus can sit on hours, a projection of live data should pass a short one.
@@ -16,11 +24,42 @@ export declare function textHeaders(etag: string, lastModified: string, maxAge?:
  * offer, and a twin that stamps the epoch is worse than one that stamps
  * nothing. `extra` carries whatever the mount needs on top — an `X-Robots-Tag`
  * where the twin is a second public URL with no canonical of its own.
+ *
+ * Pass `etag`. The twin is the single most recrawled URL a page has, and a
+ * response with no validator is a full render on every pass forever — the same
+ * arithmetic that justifies the corpus ETag, applied per page. Three wikis
+ * shipped twins with neither validator and only 304'd where a proxy happened to
+ * synthesise one; that is why it is spelled out here rather than left optional
+ * in spirit.
  */
 export declare function markdownHeaders(lastModified?: string | null, opts?: {
+    maxAge?: number;
+    etag?: string;
+    extra?: Record<string, string>;
+}): Record<string, string>;
+/**
+ * Headers for a JSON descriptor — an agent card, an OpenAPI document, a
+ * registry manifest. These are the documents a client refetches most and the
+ * ones that had no validator at all: served as `Cache-Control: public` with no
+ * `max-age`, a caller falls back to heuristic freshness and can never
+ * revalidate, so a corrected card takes an unbounded time to reach anyone.
+ */
+export declare function descriptorHeaders(etag: string, opts?: {
     maxAge?: number;
     extra?: Record<string, string>;
 }): Record<string, string>;
+/**
+ * A JSON descriptor served with a validator, answering a conditional GET.
+ *
+ * The body is its own ETag source, so the tag moves exactly when the document
+ * does and never otherwise. Every descriptor route in this workspace was a
+ * hand-rolled `NextResponse.json` with a Cache-Control and no validator at all,
+ * which is why a corrected agent card took an unbounded time to reach anyone.
+ */
+export declare function descriptorResponse(request: Request, body: unknown, opts?: {
+    maxAge?: number;
+    extra?: Record<string, string>;
+}): Response;
 /** Strip URLs and collapse whitespace so an excerpt stays one readable line. */
 export declare function cleanSnippet(text: string, max?: number): string;
 /** One markdown bullet: linked title, excerpt, and the date an agent diffs on. */

package/dist/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAOA,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,CAY1F;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAMjG;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,MAAM,SAAO,GACZ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,EAC5B,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAO,GAC7D,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQxB;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAM,GAAG,MAAM,CAQ5D;AAED,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC;CAChC,GAAG,MAAM,CAMT"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAOA,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,CAY1F;AAKD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,MAAM,EACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAC3B,QAAQ,GAAG,IAAI,CAuBjB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,MAAM,SAAO,GACZ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,EAC5B,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAO,GAC5E,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASxB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAO,GAC7D,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQxB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,OAAO,EACb,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAO,GAC7D,QAAQ,CAIV;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAM,GAAG,MAAM,CAQ5D;AAED,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC;CAChC,GAAG,MAAM,CAMT"}

package/dist/http.js

@@ -18,14 +18,40 @@ export function corpusEtag(parts) {
     }
     return `W/"${hash.toString(36)}-${seed.length.toString(36)}"`;
 }
-/** 304 when the client already holds this revision, else `null` to render. */
+/** Weak comparison per RFC 9110 8.8.3.2: the `W/` prefix never affects a match. */
+const bareTag = (tag) => tag.trim().replace(/^W\//, '');
+/**
+ * 304 when the client already holds this revision, else `null` to render.
+ *
+ * Both validators are matched the way RFC 9110 defines them rather than by
+ * string equality, because equality is wrong in the cases that actually occur:
+ * a client sends every tag it holds as a list, a proxy adds or strips the weak
+ * prefix, and a crawler reformats the date. Each of those took a full render
+ * from a response that was already fresh.
+ */
 export function notModified(request, etag, lastModified) {
+    const headers = {
+        ETag: etag,
+        ...(lastModified ? { 'Last-Modified': lastModified } : {}),
+    };
     const inm = request.headers.get('if-none-match');
+    if (inm) {
+        const fresh = inm.trim() === '*' || inm.split(',').some(t => bareTag(t) === bareTag(etag));
+        // When If-None-Match is present If-Modified-Since must be ignored entirely.
+        return fresh ? new Response(null, { status: 304, headers }) : null;
+    }
     const ims = request.headers.get('if-modified-since');
-    const fresh = inm ? inm === etag : Boolean(ims && ims === lastModified);
-    if (!fresh)
+    if (!ims || !lastModified)
+        return null;
+    const held = Date.parse(ims);
+    const current = Date.parse(lastModified);
+    if (!Number.isFinite(held) || !Number.isFinite(current))
         return null;
-    return new Response(null, { status: 304, headers: { ETag: etag, 'Last-Modified': lastModified } });
+    // Second precision: the header carries no sub-second part, so a stamp that
+    // rounds down would otherwise read as newer than the copy it was sent for.
+    return Math.floor(current / 1000) <= Math.floor(held / 1000)
+        ? new Response(null, { status: 304, headers })
+        : null;
 }
 /**
  * Headers for a plain-text export. `maxAge` is the edge window — a curated
@@ -48,16 +74,53 @@ export function textHeaders(etag, lastModified, maxAge = 3600) {
  * offer, and a twin that stamps the epoch is worse than one that stamps
  * nothing. `extra` carries whatever the mount needs on top — an `X-Robots-Tag`
  * where the twin is a second public URL with no canonical of its own.
+ *
+ * Pass `etag`. The twin is the single most recrawled URL a page has, and a
+ * response with no validator is a full render on every pass forever — the same
+ * arithmetic that justifies the corpus ETag, applied per page. Three wikis
+ * shipped twins with neither validator and only 304'd where a proxy happened to
+ * synthesise one; that is why it is spelled out here rather than left optional
+ * in spirit.
  */
 export function markdownHeaders(lastModified, opts = {}) {
     const maxAge = opts.maxAge ?? 3600;
     return {
         'Content-Type': 'text/markdown; charset=utf-8',
         'Cache-Control': `public, s-maxage=${maxAge}, stale-while-revalidate=${maxAge * 24}`,
+        ...(opts.etag ? { ETag: opts.etag } : {}),
         ...(lastModified ? { 'Last-Modified': lastModified } : {}),
         ...opts.extra,
     };
 }
+/**
+ * Headers for a JSON descriptor — an agent card, an OpenAPI document, a
+ * registry manifest. These are the documents a client refetches most and the
+ * ones that had no validator at all: served as `Cache-Control: public` with no
+ * `max-age`, a caller falls back to heuristic freshness and can never
+ * revalidate, so a corrected card takes an unbounded time to reach anyone.
+ */
+export function descriptorHeaders(etag, opts = {}) {
+    const maxAge = opts.maxAge ?? 86400;
+    return {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Cache-Control': `public, max-age=300, s-maxage=${maxAge}, stale-while-revalidate=${maxAge * 7}`,
+        ETag: etag,
+        ...opts.extra,
+    };
+}
+/**
+ * A JSON descriptor served with a validator, answering a conditional GET.
+ *
+ * The body is its own ETag source, so the tag moves exactly when the document
+ * does and never otherwise. Every descriptor route in this workspace was a
+ * hand-rolled `NextResponse.json` with a Cache-Control and no validator at all,
+ * which is why a corrected agent card took an unbounded time to reach anyone.
+ */
+export function descriptorResponse(request, body, opts = {}) {
+    const text = JSON.stringify(body);
+    const etag = corpusEtag([text]);
+    return notModified(request, etag) ?? new Response(text, { headers: descriptorHeaders(etag, opts) });
+}
 /** Strip URLs and collapse whitespace so an excerpt stays one readable line. */
 export function cleanSnippet(text, max = 160) {
     return text

package/dist/http.js.map

@@ -1 +1 @@
-{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}

package/dist/mcp.d.ts

@@ -1,4 +1,20 @@
-export declare const MCP_PROTOCOL_VERSION = "2025-03-26";
+/**
+ * The versions this transport speaks, newest first.
+ *
+ * This was a constant answered unconditionally, which is legal and still wrong:
+ * a client asking for 2025-06-18 was told 2025-03-26 and silently gave up tool
+ * titles, structured output and `_meta`. The last one is where a payment
+ * receipt rides, so the one surface that needed it rebuilt this module's HTTP
+ * shell by hand to reach it.
+ */
+export declare const MCP_PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26", "2024-11-05"];
+export type McpProtocolVersion = (typeof MCP_PROTOCOL_VERSIONS)[number];
+/** The newest version spoken here, and what an unrecognised ask falls back to. */
+export declare const MCP_PROTOCOL_VERSION: McpProtocolVersion;
+/** Echo the client's version when it is one we speak, else offer the newest. */
+export declare function negotiateProtocol(requested: unknown): McpProtocolVersion;
+/** The version a post-initialize request is operating under. */
+export declare function requestProtocol(request: Request): McpProtocolVersion;
 export type ToolParam = {
     type: 'string' | 'number' | 'boolean' | 'array' | 'object';
     description: string;
@@ -29,10 +45,33 @@ export type ToolAnnotations = {
     /** Touches systems beyond this server. */
     openWorldHint?: boolean;
 };
+/**
+ * What a handler can see of the call beyond its arguments, and its one channel
+ * back out. `_meta` carries everything that is *about* a call rather than in it
+ * — a payment receipt, a progress token — and a handler returning a bare value
+ * could reach none of it.
+ */
+export interface ToolContext {
+    /** `params._meta` as it arrived. */
+    meta: Record<string, unknown>;
+    /** Set a key on this result's `_meta`. */
+    setMeta: (key: string, value: unknown) => void;
+    /** The version negotiated for this request. */
+    protocolVersion: McpProtocolVersion;
+    /** The HTTP request, where the mount had one to give. */
+    request?: Request;
+}
 export interface McpTool {
     name: string;
+    /** Human-facing label. 2025-06-18 promoted this out of `annotations`. */
+    title?: string;
     description: string;
     inputSchema: ToolSchema;
+    /**
+     * Declare it and the result carries `structuredContent` beside the text, so a
+     * client reads the answer instead of scraping prose for it.
+     */
+    outputSchema?: ToolSchema;
     annotations?: ToolAnnotations;
     /** Surfaced as an A2A skill on the agent card. Not sent over MCP. */
     skill?: {
@@ -40,7 +79,7 @@ export interface McpTool {
         tags: string[];
         examples?: string[];
     };
-    handler: (args: Record<string, unknown>) => Promise<unknown>;
+    handler: (args: Record<string, unknown>, ctx: ToolContext) => Promise<unknown>;
 }
 export interface McpResource {
     uri: string;
@@ -90,6 +129,21 @@ export interface McpServerConfig {
     maxBatch?: number;
     /** Per-request analytics hook. Runs before dispatch; never blocks the response. */
     onCall?: (request: Request, body: unknown) => void;
+    /**
+     * Envelope-level middleware: it may withhold entries before dispatch and
+     * merge its own responses back in afterwards. A payment gate has to sit here
+     * rather than in a handler, because the demand *replaces* the call and the
+     * receipt rides on the envelope. Without this hook one surface had rebuilt
+     * the whole of `mcpResponse` by hand to wrap it.
+     */
+    gate?: (body: unknown) => Promise<EnvelopeGate>;
+}
+/** What a `gate` hands back: the body to dispatch, and how to finish. */
+export interface EnvelopeGate {
+    body: RpcRequest | RpcRequest[];
+    /** Every entry withheld — dispatch nothing rather than an empty batch. */
+    empty: boolean;
+    finish(dispatched: object | object[] | null): Promise<object | object[] | null>;
 }
 /**
  * A caller-fixable failure inside a handler (page not found, empty input).
@@ -100,14 +154,21 @@ export declare class McpToolError extends Error {
     readonly details?: Record<string, unknown> | undefined;
     constructor(message: string, details?: Record<string, unknown> | undefined);
 }
-type RpcRequest = {
+/** One entry in a JSON-RPC envelope. Exported because `wiki-formant/x402`
+ *  gates the envelope before `handleMcp` ever sees it. */
+export type RpcRequest = {
     jsonrpc: '2.0';
     id: string | number | null;
     method: string;
     params?: unknown;
 };
+/** Everything the dispatcher needs that is not in the JSON-RPC entry itself. */
+interface Dispatch {
+    protocolVersion: McpProtocolVersion;
+    request?: Request;
+}
 /** Dispatch a parsed body. `null` means notification-only — answer 202, not 200. */
-export declare function handleMcp(body: RpcRequest | RpcRequest[], config: McpServerConfig): Promise<object | object[] | null>;
+export declare function handleMcp(body: RpcRequest | RpcRequest[], config: McpServerConfig, dispatch?: Dispatch): Promise<object | object[] | null>;
 export declare const MCP_CORS: Record<string, string>;
 export declare function withMcpCors<T extends Response>(res: T): T;
 export declare function mcpOptions(): Response;
@@ -117,7 +178,18 @@ export declare function mcpOptions(): Response;
  * could not even read the refusal — answer it here, and say what to do instead.
  */
 export declare function mcpGet(docsUrl?: string): Response;
-/** The whole POST leg: parse, track, dispatch, and answer with the right status. */
+/**
+ * The 429 an MCP endpoint owes a caller that is over budget.
+ *
+ * Every surface here answered with a bare `{error: "..."}` — a string where the
+ * client's parser expects `{code, message}` — on the one response an agent
+ * meets precisely when it is working hard, and the one it most needs to read to
+ * back off correctly. It needs the CORS headers for the same reason the GET
+ * refusal does. The id is null because the limiter runs before the body is
+ * parsed, which is deliberate: an unparsed body cannot cost a query.
+ */
+export declare function mcpRateLimited(retryAfterSec: number, message?: string): Response;
+/** The whole POST leg: parse, gate, track, dispatch, and answer with the right status. */
 export declare function mcpResponse(request: Request, config: McpServerConfig): Promise<Response>;
 export {};
 //# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"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"}

package/dist/mcp.js

@@ -1,5 +1,5 @@
 // mcp.ts — a minimal Model Context Protocol server over Streamable HTTP
-// (JSON-RPC). Spec: https://modelcontextprotocol.io/specification/2025-03-26
+// (JSON-RPC). Spec: https://modelcontextprotocol.io/specification/2025-06-18
 //
 // Web-standard `Request`/`Response` only, so this runs unchanged on Next route
 // handlers (NextResponse extends Response), Hono, Bun, Deno and workers.
@@ -12,7 +12,32 @@
 //
 // A caller-fixable mistake is a tool result with `isError`, never a -32603.
 // That split is the one most implementations get wrong.
-export const MCP_PROTOCOL_VERSION = '2025-03-26';
+/**
+ * The versions this transport speaks, newest first.
+ *
+ * This was a constant answered unconditionally, which is legal and still wrong:
+ * a client asking for 2025-06-18 was told 2025-03-26 and silently gave up tool
+ * titles, structured output and `_meta`. The last one is where a payment
+ * receipt rides, so the one surface that needed it rebuilt this module's HTTP
+ * shell by hand to reach it.
+ */
+export const MCP_PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+/** The newest version spoken here, and what an unrecognised ask falls back to. */
+export const MCP_PROTOCOL_VERSION = MCP_PROTOCOL_VERSIONS[0];
+/** What a request carrying no `MCP-Protocol-Version` header means, per the spec. */
+const ASSUMED_VERSION = '2025-03-26';
+const speaks = (v) => MCP_PROTOCOL_VERSIONS.includes(v);
+/** Echo the client's version when it is one we speak, else offer the newest. */
+export function negotiateProtocol(requested) {
+    return speaks(requested) ? requested : MCP_PROTOCOL_VERSION;
+}
+/** The version a post-initialize request is operating under. */
+export function requestProtocol(request) {
+    const header = request.headers.get('mcp-protocol-version');
+    return speaks(header) ? header : ASSUMED_VERSION;
+}
+/** JSON-RPC batching was removed in 2025-06-18; it stays legal below that. */
+const allowsBatch = (v) => v !== '2025-06-18';
 /**
  * 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
@@ -40,10 +65,10 @@ const rpcError = (id, code, message, data) => ({
     id,
     error: { code, message, ...(data ? { data } : {}) },
 });
-const toolText = (id, text, isError = false) => ({
+const toolText = (id, text, isError = false, extra = {}) => ({
     jsonrpc: '2.0',
     id,
-    result: { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) },
+    result: { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}), ...extra },
 });
 /**
  * Every problem with the call at once, each naming the field and its legal
@@ -107,11 +132,19 @@ const BASE_METHODS = ['initialize', 'ping', 'tools/list', 'tools/call'];
 function methodsFor(config) {
     return [
         ...BASE_METHODS,
-        ...(config.resources?.length ? ['resources/list', 'resources/read'] : []),
-        ...(config.prompts?.length ? ['prompts/list', 'prompts/get'] : []),
+        // The list methods answer whether or not anything is registered: an empty
+        // list is a better answer to a client that asked than a -32601 it has to
+        // interpret. This enumeration used to omit them while the dispatch below
+        // answered them, so the error message contradicted the server describing
+        // itself.
+        'resources/list',
+        'resources/templates/list',
+        'prompts/list',
+        ...(config.resources?.length ? ['resources/read'] : []),
+        ...(config.prompts?.length ? ['prompts/get'] : []),
     ];
 }
-async function handleRpc(req, config) {
+async function handleRpc(req, config, dispatch) {
     const { id, method, params } = req;
     const p = (params ?? {});
     const resources = config.resources ?? [];
@@ -123,7 +156,9 @@ async function handleRpc(req, config) {
                     jsonrpc: '2.0',
                     id,
                     result: {
-                        protocolVersion: MCP_PROTOCOL_VERSION,
+                        // Echo what the client asked for when we speak it. Answering a
+                        // constant is what silently held every caller at 2025-03-26.
+                        protocolVersion: negotiateProtocol(p.protocolVersion),
                         // Only advertise capabilities the config actually populates — an
                         // advertised `resources` whose list comes back empty reads as a bug
                         // to a client, not as honesty.
@@ -147,10 +182,12 @@ async function handleRpc(req, config) {
                     jsonrpc: '2.0',
                     id,
                     result: {
-                        tools: config.tools.map(({ name, description, inputSchema, annotations }) => ({
+                        tools: config.tools.map(({ name, title, description, inputSchema, outputSchema, annotations }) => ({
                             name,
+                            ...(title ? { title } : {}),
                             description,
                             inputSchema,
+                            ...(outputSchema ? { outputSchema } : {}),
                             ...(annotations ? { annotations } : {}),
                         })),
                     },
@@ -168,6 +205,11 @@ async function handleRpc(req, config) {
                         })),
                     },
                 };
+            // Declared `resources` makes a client ask for templates too. There are
+            // none to give — every resource here is a fixed URI — but an empty list
+            // is the answer to that question, where -32601 reads as a broken server.
+            case 'resources/templates/list':
+                return { jsonrpc: '2.0', id, result: { resourceTemplates: [] } };
             case 'resources/read': {
                 const { uri } = p;
                 const resource = uri ? resources.find(r => r.uri === uri) : undefined;
@@ -223,9 +265,28 @@ async function handleRpc(req, config) {
                 const invalid = validateArgs(tool, args);
                 if (invalid)
                     return toolText(id, invalid, true);
+                const out = {};
+                const ctx = {
+                    meta: (p._meta ?? {}),
+                    setMeta: (key, value) => {
+                        out[key] = value;
+                    },
+                    protocolVersion: dispatch.protocolVersion,
+                    request: dispatch.request,
+                };
                 try {
-                    const data = await tool.handler(args);
-                    return toolText(id, typeof data === 'string' ? data : JSON.stringify(data, null, 2));
+                    const data = await tool.handler(args, ctx);
+                    const text = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+                    // `structuredContent` only where a schema says what its shape is; the
+                    // text block stays either way, because a client that never looked at
+                    // outputSchema still has to be able to read the answer.
+                    const structured = tool.outputSchema && data !== null && typeof data === 'object' && !Array.isArray(data)
+                        ? { structuredContent: data }
+                        : {};
+                    return toolText(id, text, false, {
+                        ...structured,
+                        ...(Object.keys(out).length ? { _meta: out } : {}),
+                    });
                 }
                 catch (err) {
                     if (!(err instanceof McpToolError))
@@ -245,7 +306,7 @@ async function handleRpc(req, config) {
     }
 }
 /** Dispatch a parsed body. `null` means notification-only — answer 202, not 200. */
-export async function handleMcp(body, config) {
+export async function handleMcp(body, config, dispatch = { protocolVersion: ASSUMED_VERSION }) {
     const maxBatch = config.maxBatch ?? DEFAULT_MAX_BATCH;
     const isBatch = Array.isArray(body);
     if (isBatch && body.length > maxBatch) {
@@ -254,7 +315,7 @@ export async function handleMcp(body, config) {
     if (isBatch && body.length === 0) {
         return rpcError(null, -32600, 'Batch is empty. Send at least one JSON-RPC request.');
     }
-    const responses = (await Promise.all((isBatch ? body : [body]).map(r => handleRpc(r, config)))).filter(Boolean);
+    const responses = (await Promise.all((isBatch ? body : [body]).map(r => handleRpc(r, config, dispatch)))).filter(Boolean);
     return isBatch ? responses : (responses[0] ?? null);
 }
 // ---------------------------------------------------------------------------
@@ -270,6 +331,11 @@ 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, Last-Event-ID',
+    // 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
+    // how long to wait — which reads as a hang, not as a limit.
+    'Access-Control-Expose-Headers': 'Mcp-Session-Id, Mcp-Protocol-Version, Retry-After',
     'Access-Control-Max-Age': '86400',
 };
 export function withMcpCors(res) {
@@ -293,8 +359,26 @@ export function mcpGet(docsUrl) {
         headers: { ...MCP_CORS, Allow: 'POST, OPTIONS' },
     });
 }
-/** The whole POST leg: parse, track, dispatch, and answer with the right status. */
+/**
+ * The 429 an MCP endpoint owes a caller that is over budget.
+ *
+ * Every surface here answered with a bare `{error: "..."}` — a string where the
+ * client's parser expects `{code, message}` — on the one response an agent
+ * meets precisely when it is working hard, and the one it most needs to read to
+ * back off correctly. It needs the CORS headers for the same reason the GET
+ * refusal does. The id is null because the limiter runs before the body is
+ * parsed, which is deliberate: an unparsed body cannot cost a query.
+ */
+export function mcpRateLimited(retryAfterSec, message) {
+    return Response.json(rpcError(null, -32000, message ?? `Rate limit exceeded. Retry in ${retryAfterSec} seconds.`, { retryAfterSec }), { status: 429, headers: { ...MCP_CORS, 'Retry-After': String(retryAfterSec) } });
+}
+/** The whole POST leg: parse, gate, track, dispatch, and answer with the right status. */
 export async function mcpResponse(request, config) {
+    const protocolVersion = requestProtocol(request);
+    // Echoed on every response so a client can see which version it is actually
+    // being answered under, rather than inferring it from the initialize it sent
+    // some requests ago.
+    const headers = { ...MCP_CORS, 'MCP-Protocol-Version': protocolVersion };
     let body;
     try {
         body = await request.json();
@@ -302,16 +386,25 @@ export async function mcpResponse(request, config) {
     catch {
         return Response.json(rpcError(null, -32700, 'Parse error: request body is not valid JSON.'), {
             status: 400,
-            headers: MCP_CORS,
+            headers,
         });
     }
+    if (Array.isArray(body) && !allowsBatch(protocolVersion)) {
+        return Response.json(rpcError(null, -32600, `JSON-RPC batching was removed in MCP ${protocolVersion}. Send one request per POST, or negotiate ${ASSUMED_VERSION} to keep batching.`), { status: 400, headers });
+    }
+    // Tracked on the original body, before a gate withholds anything: a call an
+    // agent walked away from is exactly the one worth counting.
     config.onCall?.(request, body);
-    const result = await handleMcp(body, config);
+    const gate = await config.gate?.(body);
+    const dispatched = gate?.empty
+        ? null
+        : await handleMcp(gate ? gate.body : body, config, { protocolVersion, request });
+    const result = gate ? await gate.finish(dispatched) : dispatched;
     // Notification-only input produces no response bodies; the spec requires a
     // bare 202 there, not a 200 carrying a JSON `null`.
     if (result == null || (Array.isArray(result) && !result.length)) {
-        return new Response(null, { status: 202, headers: MCP_CORS });
+        return new Response(null, { status: 202, headers });
     }
-    return Response.json(result, { headers: MCP_CORS });
+    return Response.json(result, { headers });
 }
 //# sourceMappingURL=mcp.js.map