From e5129aedeb9833963c4115f4fd19bb9f1216d468 Mon Sep 17 00:00:00 2001 From: Joost de Valk Date: Thu, 16 Jul 2026 09:37:09 +0200 Subject: [PATCH] change(mcp): advertise protocol revision 2025-11-25, negotiate older versions The Worker pinned 2025-06-18 while 2025-11-25 has been stable since November. Nothing in the new revision changes this server's feature surface (no auth, elicitation, sampling, tasks, or SSE here), so the upgrade is advertisement plus three real fixes: - initialize now does spec-correct version negotiation: echo the client's requested version when supported (2025-11-25, 2025-06-18, 2025-03-26), answer with our latest otherwise. - Tool execution errors return isError tool results instead of -32603 protocol errors (SEP-1303), so calling models can self-correct. - serverInfo gains the 2025-11-25 description, websiteUrl, and icons fields. Drift fixed along the way: the static server card claimed "96 spec pages" (there are 163) and both it and the Worker landing page were missing the get_changes tool. The mcp-and-tool-discovery page no longer describes HTTP+SSE as the remote transport (deprecated; Streamable HTTP replaced it), and both citing pages now reference the 2025-11-25 spec URL. SKILL.md revision + digest resynced via sign:skill. The next revision (draft, expected 2026-07-28) is a breaking rework (removes initialize, adds server/discover, required resultType) and is deliberately not adopted while still in draft. Co-Authored-By: Claude Fable 5 --- mcp/src/index.ts | 41 +++++++++++++++---- public/.well-known/agent-skills/index.json | 2 +- .../specification-website/SKILL.md | 2 +- public/.well-known/mcp/server-card.json | 9 ++-- .../agent-readiness/mcp-and-tool-discovery.md | 6 +-- src/content/spec/agent-readiness/webmcp.md | 4 +- 6 files changed, 46 insertions(+), 18 deletions(-) diff --git a/mcp/src/index.ts b/mcp/src/index.ts index a81bc0a6..fb83c377 100644 --- a/mcp/src/index.ts +++ b/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).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 {
  • get_topic({ slug }) — full Markdown for one page
  • get_checklist({ category?, status? }) — flat checklist
  • get_categories() — taxonomy with counts
    • +
  • get_changes({ since?, type?, limit? }) — spec changelog, resolved to current topics

    • Prompts

    diff --git a/public/.well-known/agent-skills/index.json b/public/.well-known/agent-skills/index.json index e35a2ff9..8df87c1e 100644 --- a/public/.well-known/agent-skills/index.json +++ b/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" } ] } diff --git a/public/.well-known/agent-skills/specification-website/SKILL.md b/public/.well-known/agent-skills/specification-website/SKILL.md index e44df446..615a3632 100644 --- a/public/.well-known/agent-skills/specification-website/SKILL.md +++ b/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: diff --git a/public/.well-known/mcp/server-card.json b/public/.well-known/mcp/server-card.json index 06ec1dd7..e127a888 100644 --- a/public/.well-known/mcp/server-card.json +++ b/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." } diff --git a/src/content/spec/agent-readiness/mcp-and-tool-discovery.md b/src/content/spec/agent-readiness/mcp-and-tool-discovery.md index ff726d81..9ff85623 100644 --- a/src/content/spec/agent-readiness/mcp-and-tool-discovery.md +++ b/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. diff --git a/src/content/spec/agent-readiness/webmcp.md b/src/content/spec/agent-readiness/webmcp.md index 59fe56ad..9efbe150 100644 --- a/src/content/spec/agent-readiness/webmcp.md +++ b/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" ---