wiki-formant 0.11.0 → 0.13.0

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;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACnC,YAAY,SAAuB,GAClC,QAAQ,CAKV;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,57 @@ 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;
+}
+/**
+ * A 404 that teaches, for the plain-GET half of an agent surface.
+ *
+ * The MCP half of every server here answers a wrong identifier by naming the
+ * tools that find a right one. The GET half, reached by exactly the agents that
+ * guessed a URL, answered the same mistake with `Page not found`, `Not found`,
+ * and in one case a 26 KB HTML error page — nothing to retry from. `hints` are
+ * merged into the body, so an index URL or a nearest match rides along. A
+ * missing page is a hot crawler path, so it is cacheable by default; pass
+ * `cacheControl` where the surface has its own edge posture.
+ */
+export function teachingNotFound(message, hints = {}, cacheControl = 'public, max-age=60') {
+    return Response.json({ error: message, ...hints }, {
+        status: 404,
+        headers: { 'Cache-Control': cacheControl },
+    });
 }
 /**
  * Headers for a plain-text export. `maxAge` is the edge window — a curated
@@ -48,16 +91,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,21 @@
-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;
+import { type RateLimitOptions } from './rate-limit.js';
 export type ToolParam = {
     type: 'string' | 'number' | 'boolean' | 'array' | 'object';
     description: string;
@@ -11,6 +28,13 @@ export type ToolSchema = {
     type: 'object';
     properties: Record<string, ToolParam>;
     required?: string[];
+    /**
+     * At least one of these must be present. `required` cannot say "query or
+     * popular", so a tool needing that checked it in its handler and the caller
+     * only learned at execution time — the one class of argument mistake this
+     * module was otherwise catching before dispatch.
+     */
+    requireOneOf?: string[];
 };
 /**
  * Behavioural hints a client uses to decide what needs a human in the loop.
@@ -18,7 +42,11 @@ export type ToolSchema = {
  * calls has no way to tell a lookup from one that reaches a payment processor.
  */
 export type ToolAnnotations = {
-    /** Human-facing label for the tool. */
+    /**
+     * Human-facing label — the pre-2025-06-18 slot. `tools/list` hoists it to
+     * the top-level `title` when that is absent, so a manifest written against
+     * either revision renders the same in a client. Prefer `McpTool.title`.
+     */
     title?: string;
     /** Does not modify anything. */
     readOnlyHint?: boolean;
@@ -29,10 +57,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 +91,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;
@@ -88,8 +139,41 @@ export interface McpServerConfig {
      * query. Keep this aligned with whatever ceiling the batching tools advertise.
      */
     maxBatch?: number;
+    /**
+     * Per-IP budget for this endpoint.
+     *
+     * Declared rather than wired: the four routes in this workspace each spelled
+     * out the same verdict → refuse → answer → attach-headroom dance through
+     * three differently-named local helpers, two of them taking an async detour
+     * through the framework's `headers()` to reach a `Request` that was already
+     * in hand. A surface that states a budget owes the same four things every
+     * time, so stating the budget is now the whole of it — and the headroom
+     * header cannot be the part a new surface forgets.
+     *
+     * Enforced before the body is parsed, deliberately: an unparsed body must not
+     * cost a query.
+     */
+    rateLimit?: RateLimitOptions & {
+        /** Bucket namespace. Defaults to `mcp`; endpoints sharing it share a bucket. */
+        prefix?: string;
+    };
     /** 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).
@@ -108,8 +192,13 @@ export type RpcRequest = {
     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;
@@ -119,6 +208,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,33 @@
 //
 // 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';
+import { clientKey, rateLimit, rateLimitHeaders, withRateLimit } from './rate-limit.js';
 /**
  * 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,17 +66,17 @@ 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
  * values, plus the schema — one retry should be able to fix all of them.
  */
 function validateArgs(tool, args) {
-    const { properties, required = [] } = tool.inputSchema;
+    const { properties, required = [], requireOneOf } = tool.inputSchema;
     const allowed = Object.keys(properties);
     const problems = [];
     for (const key of Object.keys(args)) {
@@ -65,6 +91,9 @@ function validateArgs(tool, args) {
             problems.push(`Missing required parameter "${key}". Required: ${quote(required)}.`);
         }
     }
+    if (requireOneOf?.length && !requireOneOf.some(k => args[k] !== undefined && args[k] !== null)) {
+        problems.push(`Provide at least one of ${quote(requireOneOf)}.`);
+    }
     for (const [key, spec] of Object.entries(properties)) {
         const value = args[key];
         if (value === undefined || value === null)
@@ -107,11 +136,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 +160,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 +186,16 @@ 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,
+                            // 2025-06-18 promoted `title` out of `annotations`. Hoisting
+                            // rather than requiring every manifest to be rewritten: a
+                            // client reading only the new slot showed a raw tool name for
+                            // every surface that had not moved its label yet.
+                            ...(title ?? annotations?.title ? { title: title ?? annotations.title } : {}),
                             description,
                             inputSchema,
+                            ...(outputSchema ? { outputSchema } : {}),
                             ...(annotations ? { annotations } : {}),
                         })),
                     },
@@ -168,6 +213,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 +273,34 @@ 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);
+                    // Every object answer, not only the schema-bearing ones. Gating this
+                    // on `outputSchema` meant that across four live servers and thirty-two
+                    // tools — every one of them returning JSON — not a single result ever
+                    // carried `structuredContent`, and every agent parsed prose to reach
+                    // data the server already had in hand. A declared `outputSchema` is
+                    // still the stronger contract (a client validates against it); it is
+                    // no longer the price of admission. The text block stays regardless:
+                    // the spec asks for the serialised twin, and a client that reads only
+                    // content still has to be able to read the answer.
+                    const structured = 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 +320,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 +329,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 +345,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, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset',
     'Access-Control-Max-Age': '86400',
 };
 export function withMcpCors(res) {
@@ -293,8 +373,38 @@ 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);
+    // Before `request.json()`: an unparsed body must not cost a query, which is
+    // also why the refusal carries a null id.
+    let headroom = {};
+    if (config.rateLimit) {
+        const verdict = rateLimit(clientKey(config.rateLimit.prefix ?? 'mcp', request.headers), config.rateLimit);
+        if (!verdict.ok) {
+            return withRateLimit(mcpRateLimited(verdict.retryAfterSec), verdict, config.rateLimit);
+        }
+        headroom = rateLimitHeaders(verdict, config.rateLimit);
+    }
+    // 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. The headroom rides alongside on every answer, not only
+    // on the 429 — a budget discoverable only by exceeding it is one an agent
+    // meets when it is least able to act on it.
+    const headers = { ...MCP_CORS, 'MCP-Protocol-Version': protocolVersion, ...headroom };
     let body;
     try {
         body = await request.json();
@@ -302,16 +412,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