wiki-formant 0.18.0 → 0.20.0

package/README.md

@@ -120,8 +120,9 @@ What it gets right:
 - **Malformed JSON is `-32700` with a `400`**, never a 500.
 - **`GET` is an explicit 405 with CORS headers.** A framework's automatic 405 carries none, so a browser client cannot even read the refusal.
 - **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. Under 2025-06-18 they are refused outright, because the revision removed them.
-- **The protocol version is negotiated, not asserted.** `initialize` echoes what the client asked for when it is one of `2025-06-18`, `2025-03-26` or `2024-11-05`, and offers the newest otherwise; every response carries the negotiated version 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.
+- **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 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.
@@ -369,6 +370,7 @@ const block = licenseBlock({ license, scope: 'The protocol compilation and prose
 
 ```ts
 addCopyButtons(el);            // every <pre> gets one, once
+sortTables(el);                // every column-headed table sorts by its headers
 hydrateTweetEmbeds(el);        // placeholders get a live src
 const off = onTweetResize(h => sizeTweetEmbeds(el, h));
 ```
@@ -377,6 +379,8 @@ const off = onTweetResize(h => sizeTweetEmbeds(el, h));
 
 `activateTabGroups` turns stored `[data-tabs]` markup into a working tab group. The editor persists tabs as nested divs, which is the right thing to store — it survives a markdown twin, a plain HTML render and a reader with JavaScript off, all of which show every tab in order. Making one of them pressable is a reader-side job, and it sits beside the other passes rather than inside a component.
 
+`sortTables` makes the tables stored in article HTML sortable by their headers. They arrive as a string a `dangerouslySetInnerHTML` wrote, so React never sees their rows and cannot sort them. A column is dates if every filled cell starts with one, numbers if every one does, and text otherwise — one stray value makes the whole column text, which beats sorting half of it by one rule and half by another. A third press restores the author's order, which is often chronological or ranked and otherwise needs a reload. Label/value tables and tables with merged cells are left alone. The markup it writes — `aria-sort` on the cell, a `.sort-header` button inside it — is the markup a React sortable header should write too, so both kinds of table draw their arrows from one stylesheet rule.
+
 `TWITTER_ORIGIN` is written down once. It is both the embed host and the allow-list `onTweetResize` checks before believing a posted height, and it had been spelled out at four call sites across two repos. Any page can `postMessage`; only the embed host may size the embed.
 
 ## Editor nodes

package/dist/conformance.d.ts

@@ -34,12 +34,19 @@ export interface Rpc {
         protocolVersion?: string;
         capabilities?: Record<string, unknown>;
         instructions?: string;
+        resultType?: string;
+        supportedVersions?: string[];
+        ttlMs?: number;
+        cacheScope?: string;
+        _meta?: Record<string, unknown>;
     };
     error?: {
         code: number;
         message: string;
         data?: {
             availableTools?: string[];
+            supported?: string[];
+            requested?: string;
         };
     };
 }

package/dist/conformance.js

@@ -15,7 +15,7 @@
 // Every value the transport assertions compare against is imported from `mcp.ts`,
 // not restated here. A suite that carries its own copy of the contract stops
 // testing the boundary the moment the contract moves and says nothing about it.
-import { DEFAULT_MAX_BATCH, MCP_CORS, MCP_PROTOCOL_VERSION } from './mcp.js';
+import { DEFAULT_MAX_BATCH, MCP_CORS, MCP_LEGACY_PROTOCOL_VERSION, MCP_META, MCP_MODERN_VERSIONS, MCP_PROTOCOL_VERSIONS, } from './mcp.js';
 /**
  * Does the live preflight carry every token `MCP_CORS` declares for this header?
  *
@@ -111,11 +111,11 @@ expectedCapabilities = ['tools']) {
     // 2025-03-26 — forfeiting structured output, tool titles and `_meta` — while
     // every suite reported green.
     const echoed = await t.rpc('initialize', {
-        protocolVersion: MCP_PROTOCOL_VERSION,
+        protocolVersion: MCP_LEGACY_PROTOCOL_VERSION,
         capabilities: {},
         clientInfo: { name: clientName, version: '1' },
     });
-    t.check('protocol negotiated', echoed.result?.protocolVersion === MCP_PROTOCOL_VERSION, `asked ${MCP_PROTOCOL_VERSION}, got ${echoed.result?.protocolVersion}`);
+    t.check('protocol negotiated', echoed.result?.protocolVersion === MCP_LEGACY_PROTOCOL_VERSION, `asked ${MCP_LEGACY_PROTOCOL_VERSION}, got ${echoed.result?.protocolVersion}`);
     t.check('downgrades gracefully', (init.result?.protocolVersion ?? '').length > 0, `asked 2024-11-05, got ${init.result?.protocolVersion}`);
     console.log(`\n=== transport ===`);
     const opt = await fetch(t.endpoint, { method: 'OPTIONS' });
@@ -156,19 +156,67 @@ expectedCapabilities = ['tools']) {
         t.check('resources/templates/list', Array.isArray(templates.result?.resourceTemplates), templates.error ? `-${templates.error.code}` : `${templates.result?.resourceTemplates?.length} templates`);
     }
     const versioned = await rawPost(t.endpoint, { jsonrpc: '2.0', id: 1, method: 'ping' }, {
-        'MCP-Protocol-Version': MCP_PROTOCOL_VERSION,
+        'MCP-Protocol-Version': MCP_LEGACY_PROTOCOL_VERSION,
     });
     t.recordCall();
-    t.check('MCP-Protocol-Version echoed', versioned.headers.get('mcp-protocol-version') === MCP_PROTOCOL_VERSION, `sent ${MCP_PROTOCOL_VERSION}, got ${versioned.headers.get('mcp-protocol-version')}`);
+    t.check('MCP-Protocol-Version echoed', versioned.headers.get('mcp-protocol-version') === MCP_LEGACY_PROTOCOL_VERSION, `sent ${MCP_LEGACY_PROTOCOL_VERSION}, got ${versioned.headers.get('mcp-protocol-version')}`);
     // Batching was removed in 2025-06-18. A server that keeps honouring it under
     // a version that forbids it is telling the client something untrue.
     const batched = await rawPost(t.endpoint, [{ jsonrpc: '2.0', id: 1, method: 'ping' }], {
-        'MCP-Protocol-Version': MCP_PROTOCOL_VERSION,
+        'MCP-Protocol-Version': MCP_LEGACY_PROTOCOL_VERSION,
     });
     t.recordCall();
-    t.check('batch refused at 2025-06-18', batched.status === 400, `${batched.status}`);
+    t.check(`batch refused at ${MCP_LEGACY_PROTOCOL_VERSION}`, batched.status === 400, `${batched.status}`);
+    await modernChecks(t, caps);
     return init;
 }
+/**
+ * A modern request exactly as a `2026-07-28` client sends it: version and
+ * capabilities in `_meta`, echoed by the headers a gateway routes on.
+ */
+const modernPost = async (t, method, opts = {}) => {
+    const version = opts.version ?? MCP_MODERN_VERSIONS[0];
+    const res = await rawPost(t.endpoint, {
+        jsonrpc: '2.0',
+        id: method,
+        method,
+        params: { _meta: { [MCP_META.protocolVersion]: version, [MCP_META.clientCapabilities]: {} } },
+    }, { 'MCP-Protocol-Version': version, 'Mcp-Method': method, ...opts.headers });
+    t.recordCall();
+    return { status: res.status, json: (await res.json()) };
+};
+/**
+ * The modern era, served beside the legacy one. Every probe that graded these
+ * servers on `server/discover` saw a -32601 for a month while every legacy check
+ * here stayed green, because nothing asked the modern question.
+ */
+async function modernChecks(t, legacyCapabilities) {
+    console.log(`\n=== modern era (${MCP_MODERN_VERSIONS[0]}) ===`);
+    const discover = await modernPost(t, 'server/discover');
+    const d = discover.json.result;
+    t.check('server/discover', discover.status === 200 &&
+        d?.resultType === 'complete' &&
+        MCP_PROTOCOL_VERSIONS.every(v => d.supportedVersions?.includes(v)) &&
+        !!d.instructions &&
+        typeof d.ttlMs === 'number' &&
+        !!d.cacheScope &&
+        !!d._meta?.[MCP_META.serverInfo], `${discover.status} ${JSON.stringify(d?.supportedVersions ?? discover.json.error)}`);
+    // One server, two ways to ask what it can do. They must give one answer.
+    t.check('discover agrees with initialize', JSON.stringify(d?.capabilities) === JSON.stringify(legacyCapabilities), `discover=${JSON.stringify(d?.capabilities)} initialize=${JSON.stringify(legacyCapabilities)}`);
+    const list = await modernPost(t, 'tools/list');
+    t.check('modern tools/list', list.status === 200 &&
+        list.json.result?.resultType === 'complete' &&
+        (list.json.result?.tools?.length ?? 0) > 0 &&
+        typeof list.json.result?.ttlMs === 'number', `${list.status} tools=${list.json.result?.tools?.length ?? JSON.stringify(list.json.error)} ttlMs=${list.json.result?.ttlMs}`);
+    const unsupported = await modernPost(t, 'tools/list', { version: '1999-01-01' });
+    t.check('unsupported version→-32022', unsupported.status === 400 &&
+        unsupported.json.error?.code === -32022 &&
+        JSON.stringify(unsupported.json.error?.data?.supported) === JSON.stringify(MCP_PROTOCOL_VERSIONS), `${unsupported.status} code=${unsupported.json.error?.code} supported=${JSON.stringify(unsupported.json.error?.data?.supported)}`);
+    const ping = await modernPost(t, 'ping');
+    t.check('removed method→404', ping.status === 404 && ping.json.error?.code === -32601, `ping: ${ping.status} code=${ping.json.error?.code}`);
+    const mismatch = await modernPost(t, 'tools/list', { headers: { 'Mcp-Method': 'prompts/list' } });
+    t.check('header mismatch→-32020', mismatch.status === 400 && mismatch.json.error?.code === -32020, `${mismatch.status} code=${mismatch.json.error?.code}`);
+}
 /**
  * One service, many descriptors — server.json, the two agent-card paths, the
  * OpenAPI document, the MCP server card, and `initialize` — should never

package/dist/dom.d.ts

@@ -65,3 +65,27 @@ export interface TabGroupClassNames {
  * silently reset it to the first tab.
  */
 export declare function activateTabGroups(root: ParentNode, classNames?: TabGroupClassNames): void;
+export interface SortTablesOptions {
+    /** Class on the injected header button. Style it in your own stylesheet. */
+    className?: string;
+}
+/**
+ * Make every column-headed table under `root` sortable by its headers, once.
+ *
+ * Pressing a header sorts by that column. Text sorts A–Z first and numbers and
+ * dates largest first, the same as a React table sorted by `useTableSort`. A
+ * second press reverses the order and a third restores the author's order,
+ * which is often meaningful (chronological, or ranked) and otherwise could only
+ * be recovered by a reload.
+ *
+ * Tables stored in article HTML arrive as a string a `dangerouslySetInnerHTML`
+ * wrote, so React never sees their rows and cannot sort them — which is why
+ * this is a DOM pass beside `addCopyButtons` rather than a component. The
+ * markup it writes, `aria-sort` on the cell and a button inside it, is the
+ * markup a React sortable header should write too, so both kinds of table draw
+ * their arrows from one stylesheet rule.
+ *
+ * Skipped: tables with merged cells, where moving a row would break the grid;
+ * tables with fewer than two rows to sort; and rows that span several `<tbody>`s.
+ */
+export declare function sortTables(root: ParentNode, options?: SortTablesOptions): void;

package/dist/dom.js

@@ -163,3 +163,138 @@ export function activateTabGroups(root, classNames = {}) {
         group.appendChild(tabPanels);
     }
 }
+const MONTHS = ['january', 'february', 'march', 'april', 'may', 'june', 'july', 'august', 'september', 'october', 'november', 'december'];
+const monthIndex = (name) => MONTHS.findIndex(m => m.startsWith(name.toLowerCase()));
+// A dash, a question mark or "n/a" means the cell has no value. It sorts last
+// in both directions, so it never lands above real values.
+const BLANK = /^(?:[-–—?]|n\/?a|tb[ad])?$/i;
+const DAY_FIRST = /^(\d{1,2})(?:st|nd|rd|th)?\s+([a-z]{3,9})\.?,?\s+(\d{4})(?:,?\s+(\d{1,2}):(\d{2})(?::(\d{2}))?)?/i;
+const MONTH_FIRST = /^([a-z]{3,9})\.?\s+(?:(\d{1,2})(?:st|nd|rd|th)?,?\s+)?(\d{4})/i;
+/** The time a cell starts with, as ms. Accepts ISO dates, "4 Jun 2026", "June 4, 2026", "June 2026" and a bare year. */
+function parseDate(s) {
+    const iso = /^(\d{4})(?:-(\d{2})(?:-(\d{2}))?(?:[ T](\d{2}):(\d{2}))?)?(?![\d,.])/.exec(s);
+    if (iso)
+        return Date.UTC(+iso[1], +(iso[2] ?? 1) - 1, +(iso[3] ?? 1), +(iso[4] ?? 0), +(iso[5] ?? 0));
+    const d = DAY_FIRST.exec(s);
+    if (d && monthIndex(d[2]) >= 0)
+        return Date.UTC(+d[3], monthIndex(d[2]), +d[1], +(d[4] ?? 0), +(d[5] ?? 0), +(d[6] ?? 0));
+    const m = MONTH_FIRST.exec(s);
+    if (m && monthIndex(m[1]) >= 0)
+        return Date.UTC(+m[3], monthIndex(m[1]), +(m[2] ?? 1));
+    return null;
+}
+const MULTIPLIER = {
+    k: 1e3, thousand: 1e3, m: 1e6, million: 1e6, b: 1e9, bn: 1e9, billion: 1e9, t: 1e12, trillion: 1e12,
+    kb: 1e3, mb: 1e6, gb: 1e9, tb: 1e12, kib: 2 ** 10, mib: 2 ** 20, gib: 2 ** 30, tib: 2 ** 40,
+};
+// The number a cell starts with: "~$3,500", "+137%", "−0.4", "142M XRD",
+// "14.00 million", "3.4 MB". A version string like "1.18.4" is not a number, so a column
+// of versions falls through to the natural text order, where 1.9 comes before 1.10.
+const NUMBER = /^[~≈<>≤≥]?\s*([+\-−]?)\s*[#$€£¥]?\s*(\d[\d,]*(?:\.\d+)?|\.\d+)(?![.\d])(?:\s*(%|(?:thousand|million|billion|trillion|[kmgt]i?b|bn|[kmbt])(?![a-z])))?/i;
+function parseNumber(s) {
+    const n = NUMBER.exec(s);
+    if (!n)
+        return null;
+    const value = parseFloat(n[2].replace(/,/g, '')) * (MULTIPLIER[n[3]?.toLowerCase() ?? ''] ?? 1);
+    return n[1] && n[1] !== '+' ? -value : value;
+}
+/**
+ * The column's sort keys. A column is dates if every filled cell starts with a
+ * date, numbers if every one starts with a number, and text otherwise. One
+ * stray value makes the whole column text, which is better than sorting it half
+ * by one rule and half by another.
+ */
+function columnKeys(cells) {
+    const blank = cells.map(c => BLANK.test(c));
+    for (const parse of [parseDate, parseNumber]) {
+        const keys = cells.map((c, i) => (blank[i] ? null : parse(c)));
+        if (keys.every((k, i) => k !== null || blank[i]))
+            return keys;
+    }
+    return cells.map((c, i) => (blank[i] ? null : c));
+}
+const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: 'base' });
+function compare(a, b, direction) {
+    if (a === null || b === null)
+        return a === b ? 0 : a === null ? 1 : -1;
+    const order = typeof a === 'number' && typeof b === 'number' ? a - b : collator.compare(String(a), String(b));
+    return direction === 'ascending' ? order : -order;
+}
+/**
+ * The row whose cells label the columns: the last row of a `<thead>`, or the
+ * first row when every cell in it is a `<th>`. The editor writes the second
+ * form. An infobox's label/value table has neither form, so it is left alone.
+ */
+function headerRow(table) {
+    const head = table.tHead?.rows;
+    if (head?.length)
+        return head[head.length - 1];
+    const first = table.rows[0];
+    return first && Array.from(first.cells).every(c => c.tagName === 'TH') ? first : undefined;
+}
+/**
+ * Make every column-headed table under `root` sortable by its headers, once.
+ *
+ * Pressing a header sorts by that column. Text sorts A–Z first and numbers and
+ * dates largest first, the same as a React table sorted by `useTableSort`. A
+ * second press reverses the order and a third restores the author's order,
+ * which is often meaningful (chronological, or ranked) and otherwise could only
+ * be recovered by a reload.
+ *
+ * Tables stored in article HTML arrive as a string a `dangerouslySetInnerHTML`
+ * wrote, so React never sees their rows and cannot sort them — which is why
+ * this is a DOM pass beside `addCopyButtons` rather than a component. The
+ * markup it writes, `aria-sort` on the cell and a button inside it, is the
+ * markup a React sortable header should write too, so both kinds of table draw
+ * their arrows from one stylesheet rule.
+ *
+ * Skipped: tables with merged cells, where moving a row would break the grid;
+ * tables with fewer than two rows to sort; and rows that span several `<tbody>`s.
+ */
+export function sortTables(root, options = {}) {
+    const { className = 'sort-header' } = options;
+    for (const table of Array.from(root.querySelectorAll('table:not([data-sort-init])'))) {
+        table.setAttribute('data-sort-init', '');
+        const head = headerRow(table);
+        if (!head)
+            continue;
+        const rows = Array.from(table.tBodies).flatMap(b => Array.from(b.rows)).filter(r => r !== head);
+        const body = rows[0]?.parentElement;
+        if (!body || rows.length < 2 || rows.some(r => r.parentElement !== body))
+            continue;
+        if (Array.from(table.querySelectorAll('th, td')).some(c => c.colSpan > 1 || c.rowSpan > 1))
+            continue;
+        const headers = Array.from(head.cells);
+        const sortBy = (col, th) => {
+            const keys = columnKeys(rows.map(r => r.cells[col]?.textContent?.trim() ?? ''));
+            const first = typeof keys.find(k => k !== null) === 'string' ? 'ascending' : 'descending';
+            const current = th.getAttribute('aria-sort');
+            const next = current === first ? (first === 'ascending' ? 'descending' : 'ascending') : current === 'none' ? first : null;
+            for (const h of headers)
+                if (h.hasAttribute('aria-sort'))
+                    h.setAttribute('aria-sort', 'none');
+            if (next)
+                th.setAttribute('aria-sort', next);
+            const order = next
+                ? rows.map((row, i) => ({ row, key: keys[i] ?? null })).sort((a, b) => compare(a.key, b.key, next)).map(x => x.row)
+                : rows;
+            body.append(...order);
+        };
+        headers.forEach((th, col) => {
+            // A header with no label has nothing to press, and a link inside a
+            // button would fire both.
+            if (!th.textContent?.trim() || th.querySelector('a, button'))
+                return;
+            const button = document.createElement('button');
+            button.type = 'button';
+            button.className = className;
+            // The editor wraps every cell's text in a <p>, which a button cannot hold.
+            const label = th.children.length === 1 && th.firstElementChild?.tagName === 'P' ? th.firstElementChild : th;
+            button.append(...Array.from(label.childNodes));
+            button.onclick = () => sortBy(col, th);
+            th.replaceChildren(button);
+            th.scope ||= 'col';
+            th.setAttribute('aria-sort', 'none');
+        });
+    }
+}

package/dist/mcp.d.ts

@@ -1,16 +1,38 @@
 /**
- * The versions this transport speaks, newest first.
+ * The modern era: every request carries its own version and client
+ * capabilities in `params._meta`. No handshake, no session, no `ping`, no batch.
+ */
+export declare const MCP_MODERN_VERSIONS: readonly ["2026-07-28"];
+/**
+ * The legacy era, negotiated by an `initialize` handshake.
  *
- * 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.
+ * Served beside the modern era rather than replaced by it. The spec lets one
+ * endpoint speak both, and a legacy client meeting a dual-era server works;
+ * going modern-only would fail the handshake of every client in the field.
  */
-export declare const MCP_PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26", "2024-11-05"];
+export declare const MCP_LEGACY_VERSIONS: readonly ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+/**
+ * Every version this transport speaks, newest first. It is the `supported` list
+ * a `-32022` names and the `supportedVersions` of `server/discover`, so a modern
+ * client that cannot use the newest still learns a legacy fallback exists.
+ */
+export declare const MCP_PROTOCOL_VERSIONS: readonly ["2026-07-28", "2025-11-25", "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. */
+type LegacyVersion = (typeof MCP_LEGACY_VERSIONS)[number];
+/** The newest version spoken here. */
 export declare const MCP_PROTOCOL_VERSION: McpProtocolVersion;
+/**
+ * The newest version `initialize` can negotiate, and what an unrecognised ask is
+ * offered. A handshake cannot land on a modern version — the modern era has no
+ * handshake — so this, not `MCP_PROTOCOL_VERSION`, is what a legacy client gets.
+ */
+export declare const MCP_LEGACY_PROTOCOL_VERSION: LegacyVersion;
+/** The reserved `_meta` keys the modern era is spelled in. */
+export declare const MCP_META: {
+    readonly protocolVersion: "io.modelcontextprotocol/protocolVersion";
+    readonly clientCapabilities: "io.modelcontextprotocol/clientCapabilities";
+    readonly serverInfo: "io.modelcontextprotocol/serverInfo";
+};
 import { type RateLimitOptions } from './rate-limit.js';
 export type ToolParam = {
     type: 'string' | 'number' | 'boolean' | 'array' | 'object';
@@ -122,6 +144,12 @@ export interface McpServerConfig {
     prompts?: McpPrompt[];
     /** Appended to the GET refusal so a browser that lands here learns where to go. */
     docsUrl?: string;
+    /**
+     * How long, in ms, a modern client may reuse `server/discover`, a list or a
+     * read. The modern era requires the hint on each of those. Defaults to five
+     * minutes: tool and prompt lists only change on deploy.
+     */
+    cacheTtlMs?: number;
     /**
      * Cap on JSON-RPC batch size. The rate limiter charges one token per HTTP
      * request, before the body is parsed — an unbounded batch would let a single
@@ -199,9 +227,16 @@ export declare const toolText: (id: RpcRequest["id"], text: string, isError?: bo
         }[];
     };
 };
+/** The methods one era has and the other does not. Everything else is shared. */
+declare const ERA_METHODS: {
+    readonly legacy: readonly ["initialize", "ping"];
+    readonly modern: readonly ["server/discover"];
+};
+type Era = keyof typeof ERA_METHODS;
 /** Everything the dispatcher needs that is not in the JSON-RPC entry itself. */
 interface Dispatch {
     protocolVersion: McpProtocolVersion;
+    era: Era;
     request?: Request;
 }
 /** Dispatch a parsed body. `null` means notification-only — answer 202, not 200. */

package/dist/mcp.js

@@ -1,5 +1,6 @@
 // mcp.ts — a minimal Model Context Protocol server over Streamable HTTP
-// (JSON-RPC). Spec: https://modelcontextprotocol.io/specification/2025-06-18
+// (JSON-RPC), serving both protocol eras from one endpoint.
+// Spec: https://modelcontextprotocol.io/specification/2026-07-28
 //
 // Web-standard `Request`/`Response` only, so this runs unchanged on Next route
 // handlers (NextResponse extends Response), Hono, Bun, Deno and workers.
@@ -13,31 +14,58 @@
 // A caller-fixable mistake is a tool result with `isError`, never a -32603.
 // That split is the one most implementations get wrong.
 /**
- * The versions this transport speaks, newest first.
+ * The modern era: every request carries its own version and client
+ * capabilities in `params._meta`. No handshake, no session, no `ping`, no batch.
+ */
+export const MCP_MODERN_VERSIONS = ['2026-07-28'];
+/**
+ * The legacy era, negotiated by an `initialize` handshake.
  *
- * 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.
+ * Served beside the modern era rather than replaced by it. The spec lets one
+ * endpoint speak both, and a legacy client meeting a dual-era server works;
+ * going modern-only would fail the handshake of every client in the field.
+ */
+export const MCP_LEGACY_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+/**
+ * Every version this transport speaks, newest first. It is the `supported` list
+ * a `-32022` names and the `supportedVersions` of `server/discover`, so a modern
+ * client that cannot use the newest still learns a legacy fallback exists.
  */
-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_VERSIONS = [...MCP_MODERN_VERSIONS, ...MCP_LEGACY_VERSIONS];
+/** The newest version spoken here. */
 export const MCP_PROTOCOL_VERSION = MCP_PROTOCOL_VERSIONS[0];
-/** What a request carrying no `MCP-Protocol-Version` header means, per the spec. */
+/**
+ * The newest version `initialize` can negotiate, and what an unrecognised ask is
+ * offered. A handshake cannot land on a modern version — the modern era has no
+ * handshake — so this, not `MCP_PROTOCOL_VERSION`, is what a legacy client gets.
+ */
+export const MCP_LEGACY_PROTOCOL_VERSION = MCP_LEGACY_VERSIONS[0];
+/** The reserved `_meta` keys the modern era is spelled in. */
+export const MCP_META = {
+    protocolVersion: 'io.modelcontextprotocol/protocolVersion',
+    clientCapabilities: 'io.modelcontextprotocol/clientCapabilities',
+    serverInfo: 'io.modelcontextprotocol/serverInfo',
+};
+/** What a legacy 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. */
+const member = (list) => (v) => list.includes(v);
+const speaksLegacy = member(MCP_LEGACY_VERSIONS);
+const speaksModern = member(MCP_MODERN_VERSIONS);
+/**
+ * Echo the client's version when it is one we speak, else offer the newest.
+ * Answering a constant instead is legal and still wrong: it silently held every
+ * caller below the version that carries structured output and `_meta`.
+ */
 function negotiateProtocol(requested) {
-    return speaks(requested) ? requested : MCP_PROTOCOL_VERSION;
+    return speaksLegacy(requested) ? requested : MCP_LEGACY_PROTOCOL_VERSION;
 }
 /** The version a post-initialize request is operating under. */
 function requestProtocol(request) {
     const header = request.headers.get('mcp-protocol-version');
-    return speaks(header) ? header : ASSUMED_VERSION;
+    return speaksLegacy(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';
+/** 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 { clientKey, rateLimit, rateLimitHeaders, withRateLimit } from './rate-limit.js';
 /**
  * A caller-fixable failure inside a handler (page not found, empty input).
@@ -137,10 +165,16 @@ function validateArgs(tool, args) {
         `Expected schema: ${JSON.stringify(tool.inputSchema)}`,
     ].join('\n');
 }
-const BASE_METHODS = ['initialize', 'ping', 'tools/list', 'tools/call'];
-function methodsFor(config) {
+/** The methods one era has and the other does not. Everything else is shared. */
+const ERA_METHODS = {
+    legacy: ['initialize', 'ping'],
+    modern: ['server/discover'],
+};
+function methodsFor(config, era) {
     return [
-        ...BASE_METHODS,
+        ...ERA_METHODS[era],
+        'tools/list',
+        'tools/call',
         // 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.
@@ -151,11 +185,30 @@ function methodsFor(config) {
         ...(config.prompts?.length ? ['prompts/get'] : []),
     ];
 }
+const methodNotFound = (id, method, config, era) => {
+    const methods = methodsFor(config, era);
+    return rpcError(id, -32601, `Method not found: "${method}". This server implements: ${quote(methods)}.`, { supportedMethods: methods });
+};
+/**
+ * Only the capabilities the config actually populates — an advertised
+ * `resources` whose list comes back empty reads as a bug to a client, not as
+ * honesty. One function, so `initialize` and `server/discover` cannot disagree.
+ */
+const capabilitiesOf = (config) => ({
+    tools: {},
+    ...(config.resources?.length ? { resources: {} } : {}),
+    ...(config.prompts?.length ? { prompts: {} } : {}),
+});
 async function handleRpc(req, config, dispatch) {
     const { id, method, params } = req;
     const p = (params ?? {});
     const resources = config.resources ?? [];
     const prompts = config.prompts ?? [];
+    // A method the other era owns is not found in this one, however well the
+    // server knows it: a modern `ping` is a removed method, not a pong.
+    const foreign = ERA_METHODS[dispatch.era === 'modern' ? 'legacy' : 'modern'];
+    if (foreign.includes(method))
+        return methodNotFound(id, method, config, dispatch.era);
     try {
         switch (method) {
             case 'initialize':
@@ -163,21 +216,24 @@ async function handleRpc(req, config, dispatch) {
                     jsonrpc: '2.0',
                     id,
                     result: {
-                        // 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.
-                        capabilities: {
-                            tools: {},
-                            ...(resources.length ? { resources: {} } : {}),
-                            ...(prompts.length ? { prompts: {} } : {}),
-                        },
+                        capabilities: capabilitiesOf(config),
                         serverInfo: config.serverInfo,
                         instructions: config.instructions,
                     },
                 };
+            // What `initialize` tells a legacy client, asked the modern way. The
+            // transport adds `resultType`, the cache hints and `_meta` serverInfo.
+            case 'server/discover':
+                return {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        supportedVersions: [...MCP_PROTOCOL_VERSIONS],
+                        capabilities: capabilitiesOf(config),
+                        instructions: config.instructions,
+                    },
+                };
             // Notifications have no response at all.
             case 'notifications/initialized':
             case 'notifications/cancelled':
@@ -306,10 +362,8 @@ async function handleRpc(req, config, dispatch) {
                     return toolText(id, JSON.stringify({ error: err.message, ...err.details }, null, 2), true);
                 }
             }
-            default: {
-                const methods = methodsFor(config);
-                return rpcError(id, -32601, `Method not found: "${method}". This server implements: ${quote(methods)}.`, { supportedMethods: methods });
-            }
+            default:
+                return methodNotFound(id, method, config, dispatch.era);
         }
     }
     catch (err) {
@@ -318,7 +372,7 @@ async function handleRpc(req, config, dispatch) {
     }
 }
 /** Dispatch a parsed body. `null` means notification-only — answer 202, not 200. */
-export async function handleMcp(body, config, dispatch = { protocolVersion: ASSUMED_VERSION }) {
+export async function handleMcp(body, config, dispatch = { protocolVersion: ASSUMED_VERSION, era: 'legacy' }) {
     const maxBatch = config.maxBatch ?? DEFAULT_MAX_BATCH;
     const isBatch = Array.isArray(body);
     if (isBatch && body.length > maxBatch) {
@@ -337,12 +391,13 @@ export async function handleMcp(body, config, dispatch = { protocolVersion: ASSU
 // the spec's Origin-validation MUST exists to protect localhost servers from
 // DNS rebinding, which is the opposite situation. The allow-headers list
 // matters more than it looks — MCP clients preflight with `Accept` and
-// `Mcp-Protocol-Version`, and one missing entry fails the preflight, not the
-// POST, which reads as "the server is down".
+// `Mcp-Protocol-Version` — and a modern client adds `Mcp-Method` and `Mcp-Name`
+// on every call — and one missing entry fails the preflight, not the POST,
+// which reads as "the server is down".
 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',
+    'Access-Control-Allow-Headers': 'Content-Type, Accept, Authorization, Mcp-Session-Id, Mcp-Protocol-Version, Mcp-Method, Mcp-Name, 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
@@ -386,7 +441,6 @@ export function mcpRateLimited(retryAfterSec, message) {
 }
 /** 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 = {};
@@ -397,12 +451,10 @@ export async function mcpResponse(request, config) {
         }
         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 };
+    // The headroom rides 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 base = { ...MCP_CORS, ...headroom };
     let body;
     try {
         body = await request.json();
@@ -410,20 +462,49 @@ export async function mcpResponse(request, config) {
     catch {
         return Response.json(rpcError(null, -32700, 'Parse error: request body is not valid JSON.'), {
             status: 400,
-            headers,
+            headers: { ...base, 'MCP-Protocol-Version': requestProtocol(request) },
         });
     }
+    // Tracked before either era refuses anything: a probe the server turns away,
+    // and a call an agent walked away from behind a gate, are exactly the ones
+    // worth counting.
+    config.onCall?.(request, body);
+    return isModern(request, body)
+        ? modernResponse(request, body, config, base)
+        : legacyResponse(request, body, config, base);
+}
+/**
+ * Which era a POST belongs to. The spec's rule: modern `_meta` selects the modern
+ * era and `initialize` selects the legacy one. A modern version header and
+ * `server/discover` can only mean one thing too. Anything else is legacy,
+ * because a body without `_meta` is exactly what every client in the field sends.
+ */
+function isModern(request, body) {
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        return false;
+    const { method, params } = body;
+    if (method === 'initialize')
+        return false;
+    const meta = params?._meta;
+    return ((!!meta && typeof meta === 'object' && MCP_META.protocolVersion in meta) ||
+        method === 'server/discover' ||
+        speaksModern(request.headers.get('mcp-protocol-version')));
+}
+async function dispatchThroughGate(body, config, dispatch) {
+    const gate = await config.gate?.(body);
+    const dispatched = gate?.empty ? null : await handleMcp(gate ? gate.body : body, config, dispatch);
+    return gate ? gate.finish(dispatched) : dispatched;
+}
+async function legacyResponse(request, body, config, base) {
+    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 = { ...base, 'MCP-Protocol-Version': protocolVersion };
     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 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;
+    const result = await dispatchThroughGate(body, config, { protocolVersion, era: 'legacy', request });
     // 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)) {
@@ -431,3 +512,125 @@ export async function mcpResponse(request, config) {
     }
     return Response.json(result, { headers });
 }
+/** The modern era maps a protocol error to an HTTP status; the legacy era answered 200. */
+const MODERN_STATUS = {
+    [-32601]: 404,
+    [-32602]: 400,
+    [-32020]: 400,
+    [-32021]: 400,
+    [-32022]: 400,
+};
+/** The results a modern client may cache. A call or a prompt is never among them. */
+const CACHEABLE = new Set([
+    'server/discover',
+    'tools/list',
+    'prompts/list',
+    'resources/list',
+    'resources/templates/list',
+    'resources/read',
+]);
+const DEFAULT_CACHE_TTL_MS = 300_000;
+/** `Mcp-Name` carries the target of the three calls that have one, for a gateway to route on. */
+const NAME_PARAM = {
+    'tools/call': 'name',
+    'prompts/get': 'name',
+    'resources/read': 'uri',
+};
+/** A header value, decoded from the `=?base64?…?=` form a client uses for non-ASCII. */
+function headerValue(raw) {
+    const encoded = raw?.match(/^=\?base64\?(.*)\?=$/i)?.[1];
+    if (encoded === undefined)
+        return raw;
+    try {
+        return new TextDecoder().decode(Uint8Array.from(atob(encoded), c => c.charCodeAt(0)));
+    }
+    catch {
+        return null;
+    }
+}
+/** The first routing header that disagrees with the body, described. */
+function headerMismatch(request, method, params, version) {
+    const expected = [
+        ['MCP-Protocol-Version', version],
+        ['Mcp-Method', method],
+    ];
+    const nameKey = NAME_PARAM[method];
+    // A call missing its name is reported by the dispatcher, which can list the names.
+    if (nameKey && typeof params[nameKey] === 'string')
+        expected.push(['Mcp-Name', params[nameKey]]);
+    for (const [name, want] of expected) {
+        const got = headerValue(request.headers.get(name));
+        if (got !== want) {
+            return `Header ${name} must equal ${JSON.stringify(want)}; received ${got === null ? 'none' : JSON.stringify(got)}.`;
+        }
+    }
+    return null;
+}
+/**
+ * A modern result: `resultType` on every one, cache hints on the cacheable ones,
+ * and serverInfo in `_meta` now that no handshake carries it. Applied after the
+ * gate, so an answer a gate builds in place of a call is shaped the same way.
+ */
+function modernResult(response, method, config) {
+    if (!('result' in response))
+        return response;
+    const result = response.result;
+    return {
+        ...response,
+        result: {
+            resultType: 'complete',
+            ...result,
+            ...(CACHEABLE.has(method)
+                ? {
+                    ttlMs: config.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS,
+                    // Nothing here varies by caller, except a read a gate may have
+                    // charged for, which a shared cache must not hand to the next one.
+                    cacheScope: method === 'resources/read' ? 'private' : 'public',
+                }
+                : {}),
+            _meta: { ...result._meta, [MCP_META.serverInfo]: config.serverInfo },
+        },
+    };
+}
+async function modernResponse(request, body, config, base) {
+    const params = (body.params ?? {});
+    const meta = (params._meta ?? {});
+    const requested = meta[MCP_META.protocolVersion];
+    const headers = {
+        ...base,
+        'MCP-Protocol-Version': speaksModern(requested) ? requested : MCP_MODERN_VERSIONS[0],
+    };
+    const refuse = (code, message, data) => Response.json(rpcError(body.id ?? null, code, message, data), {
+        status: MODERN_STATUS[code] ?? 400,
+        headers,
+    });
+    if (typeof requested !== 'string') {
+        return refuse(-32602, `Missing params._meta["${MCP_META.protocolVersion}"]. A ${MCP_MODERN_VERSIONS[0]} request carries its version and client capabilities on every call; to use ${MCP_LEGACY_PROTOCOL_VERSION} instead, send "initialize".`);
+    }
+    if (!speaksModern(requested)) {
+        return refuse(-32022, 'Unsupported protocol version', {
+            supported: [...MCP_PROTOCOL_VERSIONS],
+            requested,
+        });
+    }
+    const capabilities = meta[MCP_META.clientCapabilities];
+    if (!capabilities || typeof capabilities !== 'object' || Array.isArray(capabilities)) {
+        return refuse(-32602, `Missing params._meta["${MCP_META.clientCapabilities}"]. Send {} when the client declares none.`);
+    }
+    const mismatch = headerMismatch(request, body.method, params, requested);
+    if (mismatch)
+        return refuse(-32020, mismatch);
+    const result = await dispatchThroughGate(body, config, {
+        protocolVersion: requested,
+        era: 'modern',
+        request,
+    });
+    if (result == null)
+        return new Response(null, { status: 202, headers });
+    const response = modernResult(result, body.method, config);
+    const code = response.error?.code;
+    return Response.json(response, {
+        status: (code !== undefined && MODERN_STATUS[code]) || 200,
+        headers,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.18.0",
+  "version": "0.20.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, and conditional-GET plumbing.",
   "type": "module",
   "license": "MIT",
@@ -193,6 +193,7 @@
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "jose": "^6.2.10",
+    "jsdom": "^30.1.0",
     "react": "^19.2.4",
     "typescript": "^5.9.0"
   },
@@ -200,18 +201,18 @@
     "@radixdlt/rola": ">=2",
     "@tiptap/core": ">=2.10",
     "@tiptap/extension-code-block": ">=2.10",
-    "@tiptap/extension-youtube": ">=2.10",
-    "@tiptap/react": ">=2.10",
-    "jose": ">=5",
-    "react": ">=18",
-    "@tiptap/starter-kit": ">=2.10",
-    "@tiptap/extension-link": ">=2.10",
     "@tiptap/extension-image": ">=2.10",
+    "@tiptap/extension-link": ">=2.10",
+    "@tiptap/extension-placeholder": ">=2.10",
     "@tiptap/extension-table": ">=2.10",
-    "@tiptap/extension-table-row": ">=2.10",
     "@tiptap/extension-table-cell": ">=2.10",
     "@tiptap/extension-table-header": ">=2.10",
-    "@tiptap/extension-placeholder": ">=2.10"
+    "@tiptap/extension-table-row": ">=2.10",
+    "@tiptap/extension-youtube": ">=2.10",
+    "@tiptap/react": ">=2.10",
+    "@tiptap/starter-kit": ">=2.10",
+    "jose": ">=5",
+    "react": ">=18"
   },
   "peerDependenciesMeta": {
     "react": {