change(mcp): advertise protocol revision 2025-11-25, negotiate older versions

mcp/src/index.ts

@@ -3,8 +3,10 @@
 // Streamable HTTP transport (the modern MCP transport): the client POSTs
 // JSON-RPC 2.0 messages to /mcp and gets back JSON-RPC responses. No
 // sessions, no server-initiated messages, no SSE — this server is stateless
-// and read-only. Advertises the 2025-06-18 protocol revision (tool
-// annotations + structured output / outputSchema).
+// and read-only. Advertises the 2025-11-25 protocol revision and negotiates
+// down to 2025-06-18 / 2025-03-26 when a client requests one of those —
+// the feature surface (tool annotations, structured output / outputSchema)
+// is identical across them for this server.
 //
 // All spec content is bundled at build time via scripts/build-data.mjs.
 // The Worker holds the manifest in module scope, so it is parsed once per
@@ -31,11 +33,25 @@ interface Env {
 
 const manifest = data as unknown as Manifest;
 
-const PROTOCOL_VERSION = '2025-06-18';
+const PROTOCOL_VERSION = '2025-11-25';
+// Older revisions this server is also fully compatible with. Version
+// negotiation (spec: basic/lifecycle) echoes the client's requested version
+// when it is in this set, and answers with PROTOCOL_VERSION otherwise.
+const SUPPORTED_PROTOCOL_VERSIONS = [PROTOCOL_VERSION, '2025-06-18', '2025-03-26'];
 const SERVER_INFO = {
   name: 'specification-website',
-  version: '0.1.0',
+  version: '0.2.0',
   title: 'The Website Specification',
+  description:
+    'Read-only MCP server exposing The Website Specification — search, list, fetch, and checklist tools over every spec page, plus an audit_url prompt.',
+  websiteUrl: 'https://specification.website',
+  icons: [
+    {
+      src: 'https://specification.website/icon-512.png',
+      mimeType: 'image/png',
+      sizes: ['512x512'],
+    },
+  ],
 };
 
 const CORS_HEADERS = {
@@ -77,9 +93,12 @@ function handleRpc(req: RpcRequest): RpcResponse | null {
   const { id, method, params = {} } = req;
 
   switch (method) {
-    case 'initialize':
+    case 'initialize': {
+      const requested = String((params as Record<string, unknown>).protocolVersion || '');
       return ok(id, {
-        protocolVersion: PROTOCOL_VERSION,
+        protocolVersion: SUPPORTED_PROTOCOL_VERSIONS.includes(requested)
+          ? requested
+          : PROTOCOL_VERSION,
         serverInfo: SERVER_INFO,
         capabilities: {
           tools: { listChanged: false },
@@ -95,6 +114,7 @@ function handleRpc(req: RpcRequest): RpcResponse | null {
           'The `list_topics` and `get_checklist` tools return ALL statuses by default — pass `status` to filter. ' +
           'The `audit_url` prompt is the exception: with no `focus`, it defaults to `required`-only.',
       });
+    }
 
     case 'notifications/initialized':
     case 'notifications/cancelled':
@@ -127,7 +147,13 @@ function handleRpc(req: RpcRequest): RpcResponse | null {
             return err(id, -32602, `Unknown tool: ${name}`);
         }
       } catch (e) {
-        return err(id, -32603, `Tool error: ${(e as Error).message}`);
+        // Per SEP-1303 (2025-11-25): execution/validation failures inside a
+        // known tool are tool results with isError, not protocol errors, so
+        // the calling model can read the message and self-correct.
+        return ok(id, {
+          content: [{ type: 'text', text: `Tool error: ${(e as Error).message}` }],
+          isError: true,
+        });
       }
     }
 
@@ -192,6 +218,7 @@ function htmlLanding(): Response {
   <li><code>get_topic({ slug })</code> — full Markdown for one page</li>
   <li><code>get_checklist({ category?, status? })</code> — flat checklist</li>
   <li><code>get_categories()</code> — taxonomy with counts</li>
+  <li><code>get_changes({ since?, type?, limit? })</code> — spec changelog, resolved to current topics</li>
 </ul>
 
 <h2>Prompts</h2>

public/.well-known/agent-skills/index.json

@@ -6,7 +6,7 @@
       "type": "skill-md",
       "description": "Query and apply The Website Specification — a platform-agnostic specification of what a good website does. Use when the user asks what their site should have, whether something is required, how to audit a URL, what's missing for agent readiness, or anything else where you'd otherwise be guessing at web best practice. Backs answers with primary sources and ships an MCP server with search, list, fetch, checklist, and audit tools.",
       "url": "/.well-known/agent-skills/specification-website/SKILL.md",
-      "digest": "sha256:e18d06425be153932e9338d068b4e27432bc991e7f12ca0a5794592fb8628fab"
+      "digest": "sha256:117eab2f07512f3520dd90acb13f733abf94e45489ce6feb75bc05a841360cc8"
     }
   ]
 }

public/.well-known/agent-skills/specification-website/SKILL.md

@@ -19,7 +19,7 @@ If you can speak MCP, use it. The server is stateless Streamable HTTP, no auth,
 
 - Endpoint: `https://mcp.specification.website/mcp`
 - Server card: `https://specification.website/.well-known/mcp/server-card.json`
-- Protocol revision: 2025-06-18
+- Protocol revision: 2025-11-25
 
 Tools:
 

public/.well-known/mcp/server-card.json

@@ -1,8 +1,8 @@
 {
   "name": "specification-website",
   "title": "The Website Specification",
-  "version": "0.1.0",
-  "description": "Read-only MCP server exposing the 96 spec pages of specification.website as queryable tools — search, list_topics, get_topic, get_checklist, get_categories — plus an `audit_url` prompt for URL audits.",
+  "version": "0.2.0",
+  "description": "Read-only MCP server exposing every spec page of specification.website as queryable tools — search, list_topics, get_topic, get_checklist, get_categories, get_changes — plus an `audit_url` prompt for URL audits.",
   "vendor": {
     "name": "Joost de Valk",
     "url": "https://joost.blog"
@@ -14,7 +14,7 @@
   },
   "endpoint": "https://mcp.specification.website/mcp",
   "transport": "http",
-  "protocolVersion": "2025-06-18",
+  "protocolVersion": "2025-11-25",
   "authentication": "none",
   "capabilities": {
     "tools": true,
@@ -27,7 +27,8 @@
     { "name": "list_topics", "description": "List spec topics, optionally filtered by category and/or status." },
     { "name": "get_topic", "description": "Fetch full canonical Markdown for a single spec page by slug." },
     { "name": "get_checklist", "description": "Return a Markdown checklist of spec items, grouped by category." },
-    { "name": "get_categories", "description": "List the ten top-level categories with summaries and topic counts." }
+    { "name": "get_categories", "description": "List the ten top-level categories with summaries and topic counts." },
+    { "name": "get_changes", "description": "List spec changes since a date — new pages, status changes, rewrites, removals — resolved to current topics." }
   ],
   "prompts": [
     { "name": "audit_url", "description": "Generate an audit plan for a target URL against this spec." }

src/content/spec/agent-readiness/mcp-and-tool-discovery.md

@@ -7,7 +7,7 @@ status: optional
 order: 80
 appliesTo: [all]
 relatedSlugs: [agent-readiness-overview, machine-readable-formats, llms-txt, link-headers, api-catalog, agent-skills-discovery, a2a-agent-cards, webmcp, nlweb, agentic-resource-discovery, oauth-protected-resource]
-updated: "2026-06-17T00:00:00.000Z"
+updated: "2026-07-16T00:00:00.000Z"
 sources:
   - title: "Model Context Protocol"
     url: "https://modelcontextprotocol.io/"
@@ -16,7 +16,7 @@ sources:
     url: "https://modelcontextprotocol.io/specification"
     publisher: "MCP project"
   - title: "MCP server tools: annotations & structured content"
-    url: "https://modelcontextprotocol.io/specification/2025-06-18/server/tools"
+    url: "https://modelcontextprotocol.io/specification/2025-11-25/server/tools"
     publisher: "MCP project"
   - title: "Is It Agent Ready?"
     url: "https://isitagentready.com/"
@@ -27,7 +27,7 @@ sources:
 
 The Model Context Protocol (MCP) is an open protocol, originally proposed by Anthropic in late 2024, that defines how language-model clients talk to external tools and data sources. Instead of an agent scraping your UI, you expose an MCP server that declares a set of tools, resources, and prompts; the agent calls them directly.
 
-MCP is built on JSON-RPC over a few transports — stdio for local servers, HTTP plus Server-Sent Events for remote ones. A tool definition includes a name, a description, and a JSON Schema for inputs.
+MCP is built on JSON-RPC over two transports — stdio for local servers, Streamable HTTP for remote ones (the older HTTP-plus-Server-Sent-Events transport is deprecated). A tool definition includes a name, a description, and a JSON Schema for inputs.
 
 This is relevant when your site exposes actions a user might want an agent to take: search a catalogue, create a ticket, book an appointment, query an account. For static content sites and blogs, MCP often adds little — well-cached HTML and a feed are enough. The exception is structured content sites where the data is filterable: a documentation set, a spec, a knowledge base. There an MCP server lets an agent ask "list all required SEO topics" or "give me the canonical CSP page" in a single typed call, instead of crawling and parsing.
 

src/content/spec/agent-readiness/webmcp.md

@@ -7,7 +7,7 @@ status: optional
 order: 88
 appliesTo: [all]
 relatedSlugs: [mcp-and-tool-discovery, agent-skills-discovery, agent-readiness-overview, structured-data-for-agents]
-updated: "2026-05-29T12:14:17.000Z"
+updated: "2026-07-16T00:00:00.000Z"
 sources:
   - title: "WebMCP — W3C Web Machine Learning Community Group"
     url: "https://webmachinelearning.github.io/webmcp/"
@@ -16,7 +16,7 @@ sources:
     url: "https://github.com/webmachinelearning/webmcp"
     publisher: "W3C WebML CG"
   - title: "Model Context Protocol — Tools"
-    url: "https://modelcontextprotocol.io/specification/2025-06-18/server/tools"
+    url: "https://modelcontextprotocol.io/specification/2025-11-25/server/tools"
     publisher: "MCP"
 ---