@@ -47,7 +47,7 @@ files:
 
   - path: README.md
     role: protocol
-    hash: sha256:c2e411e2234d7cdec0b89f42af402919f62633e7fd600399abf47e27307362e9
+    hash: sha256:dfebb03cd3f65629151a36d66eb7ed84a1918b5208e2ea6f6b2c41a4870b2141
     note: Template overview
 
   - path: favicon.svg
@@ -122,12 +122,12 @@ files:
 
   - path: scripts/eval.js
     role: tooling
-    hash: sha256:1f441afee32a8f0ad72986cba5acd227a67400c0bbff53655ce3c0a5fa8db4a7
+    hash: sha256:c2d73494bb777a6a23a78893ac38162d99bf252620d748ca27e5a9b504062ea9
     note: Behavioral and security regression suite
 
   - path: mcp-server.js
     role: tooling
-    hash: sha256:7a6e590449baa4eaff376e8a23d5bedbcf8a546d1a75d149287bc0c13517840f
+    hash: sha256:47dbdf6fd84013df6407ed538c72816d758c4531b65be11b1d95861e1d7467da
     note: Read-only MCP interface over canonical project data
 
   - path: scripts/check-links.js
 
@@ -14,7 +14,8 @@ This guide captures the exact prep work, in the order it has to happen.
   using only `a-z`, `0-9`, and single hyphens. Run `node scripts/validate.js`
   before publishing so unsafe IDs are rejected before they become MCP-visible
   data.
-- `node mcp-server.js` works locally — pipe `{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}`
+- `node mcp-server.js` works locally — pipe
+  `{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"smoke-test","version":"0.0.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}`
   into it and you should get back your tools.
 - An npm account ([npmjs.com](https://npmjs.com/signup)) with 2FA enabled.
 - A GitHub account that matches the org/user owning the repo.
@@ -99,11 +100,20 @@ add it to `files` and re-run. If anything is included that shouldn't be (a
 Then test that the MCP server still runs after the package.json changes:
 
 ```bash
-echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node mcp-server.js
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"smoke-test","version":"0.0.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}' | node mcp-server.js
 ```
 
 You should get back your tools.
 
+That smoke test is the *stateless* form from the 2026-07-28 spec revision: no
+`initialize` handshake, the protocol version rides in each request's `_meta`,
+and `server/discover` is the new MUST-implement discovery method. The server
+in this template is dual-era — a legacy client that opens with `initialize`
+still gets the 2024-11-05 handshake it expects, for as long as the deprecation
+window runs, while modern clients are served statelessly in the same process.
+A `_meta` protocol version the server doesn't support gets error `-32022`
+back, not a guess; a request with no `_meta` at all is served as legacy.
+
 The server follows JSON-RPC notification semantics. Messages without an `id`
 are notifications and do not receive responses, including unknown-method
 notifications.
@@ -129,7 +139,7 @@ Verify:
 
 ```bash
 npm view your-package-name version
-npx -y your-package-name <<< '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
+npx -y your-package-name <<< '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"smoke-test","version":"0.0.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}'
 ```
 
 A cold install + tools list confirms the package is real.
 
@@ -63,7 +63,7 @@ This canonical repository tracks only the generated `demo/` published at `https:
 - **Dark/light theme** — with persistence
 - **Client-side search** — lazy-loaded, keyboard-navigable
 - **Sortable tables** — click any column header to sort
-- **Local MCP server** — optional read-only agent access through `mcp-server.js`; it runs separately from the static build
+- **Local MCP server** — optional read-only agent access through `mcp-server.js`; it runs separately from the static build. Dual-era: speaks MCP spec 2026-07-28 (stateless, `server/discover`, cacheable tool lists) and legacy 2024-11-05, so generated projects work with both current and older MCP clients
 - **Discovery files** — llms.txt, agents.json, RSS for machine consumption
 - **Safe generated output** — generated links, CSS tokens, and client-side comparison labels are normalized or escaped
 - **Subpath-safe deployment** — canonical, discovery, 404, and asset URLs preserve a configured path such as `/demo/`
 
@@ -307,22 +307,46 @@ function handleToolCall(name, args) {
 // JSON-RPC / MCP protocol
 // ---------------------------------------------------------------------------
 
+// Dual-era server (MCP spec revision 2026-07-28): a legacy client selects the
+// 2024-11-05 semantics via `initialize`; a modern client carries per-request
+// `_meta` and is served statelessly. Both eras run concurrently in-process.
+const SUPPORTED_PROTOCOL_VERSIONS = ['2026-07-28', '2024-11-05'];
+// Static data regenerated on a known cadence — safe to cache for an hour.
+const CACHE_TTL_MS = 3600000;
+const CACHE_SCOPE = 'public';
+
 function makeResponse(id, result) {
     return JSON.stringify({ jsonrpc: '2.0', id, result });
 }
 
-function makeError(id, code, message) {
-    return JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } });
+function makeError(id, code, message, data) {
+    const error = { code, message };
+    if (data !== undefined) error.data = data;
+    return JSON.stringify({ jsonrpc: '2.0', id, error });
 }
 
 function handleMessage(msg) {
     const { id, method, params } = msg;
     const hasId = Object.prototype.hasOwnProperty.call(msg, 'id');
 
+    // Modern requests declare their protocol version per request. Unknown
+    // versions are rejected; requests without `_meta` (legacy handshake or
+    // bare requests) are served exactly as before.
+    const requestedVersion = params?._meta?.['io.modelcontextprotocol/protocolVersion'];
+    if (requestedVersion !== undefined && !SUPPORTED_PROTOCOL_VERSIONS.includes(requestedVersion)) {
+        if (!hasId) return null;
+        return makeError(id, -32022, 'Unsupported protocol version', {
+            supported: SUPPORTED_PROTOCOL_VERSIONS,
+            requested: requestedVersion
+        });
+    }
+
     if (method === 'initialize') {
         if (!hasId) return null;
+        const clientVersion = params?.protocolVersion;
         return makeResponse(id, {
-            protocolVersion: '2024-11-05',
+            resultType: 'complete',
+            protocolVersion: SUPPORTED_PROTOCOL_VERSIONS.includes(clientVersion) ? clientVersion : '2024-11-05',
             capabilities: { tools: {} },
             serverInfo: {
                 name: config.name || 'Knowledge Base MCP',
@@ -335,17 +359,41 @@ function handleMessage(msg) {
         return null; // notification, no response
     }
 
+    if (method === 'server/discover') {
+        if (!hasId) return null;
+        const result = {
+            resultType: 'complete',
+            supportedVersions: SUPPORTED_PROTOCOL_VERSIONS,
+            capabilities: { tools: {} },
+            _meta: {
+                'io.modelcontextprotocol/serverInfo': {
+                    name: config.name || 'Knowledge Base MCP',
+                    version: packageMetadata.version
+                }
+            },
+            ttlMs: CACHE_TTL_MS,
+            cacheScope: CACHE_SCOPE
+        };
+        if (config.description) result.instructions = config.description;
+        return makeResponse(id, result);
+    }
+
     if (method === 'tools/list') {
         if (!hasId) return null;
-        return makeResponse(id, { tools: getToolDefinitions() });
+        return makeResponse(id, {
+            resultType: 'complete',
+            tools: getToolDefinitions(),
+            ttlMs: CACHE_TTL_MS,
+            cacheScope: CACHE_SCOPE
+        });
     }
 
     if (method === 'tools/call') {
         if (!hasId) return null;
         const toolName = params?.name;
         const toolArgs = params?.arguments || {};
         const result = handleToolCall(toolName, toolArgs);
-        return makeResponse(id, result);
+        return makeResponse(id, { resultType: 'complete', ...result });
     }
 
     if (!hasId) return null;
 
@@ -854,6 +854,7 @@ function evalMcpSmoke() {
     assertIncludes(interactive.stdout, 'iso-27001');
     assertIncludes(interactive.stdout, 'talking_point');
     assertIncludes(interactive.stdout, 'sources');
+    assertIncludes(interactive.stdout, 'supportedVersions');
 }
 
 function evalMcpResponseShape() {
@@ -879,6 +880,31 @@ function evalMcpResponseShape() {
     assertIncludes(missing.error, 'not found: missing-id');
 }
 
+function evalMcpDualEraContract() {
+    const meta = {
+        'io.modelcontextprotocol/protocolVersion': '2026-07-28',
+        'io.modelcontextprotocol/clientInfo': { name: 'eval', version: '1.0.0' },
+        'io.modelcontextprotocol/clientCapabilities': {}
+    };
+    const input = [
+        { jsonrpc: '2.0', id: 1, method: 'server/discover', params: { _meta: meta } },
+        { jsonrpc: '2.0', id: 2, method: 'tools/list', params: { _meta: meta } },
+        { jsonrpc: '2.0', id: 3, method: 'tools/list', params: { _meta: { 'io.modelcontextprotocol/protocolVersion': '1900-01-01' } } }
+    ].map(message => JSON.stringify(message)).join('\n') + '\n';
+    const result = spawnSync(process.execPath, ['mcp-server.js'], { cwd: ROOT, encoding: 'utf8', input });
+    assert.strictEqual(result.status, 0, `MCP dual-era check failed:\n${result.stdout}\n${result.stderr}`);
+    const responses = result.stdout.trim().split('\n').map(line => JSON.parse(line));
+    const discover = responses[0].result;
+    assert.strictEqual(discover.resultType, 'complete');
+    assert.ok(discover.supportedVersions.includes('2026-07-28'), 'server/discover must advertise 2026-07-28.');
+    assert.ok(discover.capabilities.tools, 'server/discover must advertise the tools capability.');
+    const list = responses[1].result;
+    assert.strictEqual(typeof list.ttlMs, 'number', 'tools/list must carry a numeric ttlMs.');
+    assert.strictEqual(list.cacheScope, 'public');
+    assert.strictEqual(responses[2].error.code, -32022);
+    assert.ok(Array.isArray(responses[2].error.data.supported), 'UnsupportedProtocolVersionError must list supported versions.');
+}
+
 function evalGeneratedArtifactCleanliness() {
     const forbiddenNames = new Set(['.DS_Store', 'Thumbs.db', 'CNAME']);
     const tracked = runCommand('git', ['ls-files', '-z', 'demo']);
@@ -1005,6 +1031,7 @@ const evals = [
     ['HTML snapshots', evalHtmlSnapshots],
     ['MCP smoke', evalMcpSmoke],
     ['MCP response shape', evalMcpResponseShape],
+    ['MCP dual-era contract', evalMcpDualEraContract],
     ['MCP notification silence', evalMcpNotificationSilence],
     ['generated artifact cleanliness', evalGeneratedArtifactCleanliness],
     ['workflow contract', evalWorkflowContract],
 
@@ -1,3 +1,4 @@
 {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"eval","version":"1.0.0"}}}
 {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
 {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_framework","arguments":{"id":"iso-27001"}}}
+{"jsonrpc":"2.0","id":4,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"eval","version":"1.0.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}