From 95c6ffbedd9fc5de612faab69d916ae45a0a9891 Mon Sep 17 00:00:00 2001 From: Wayner Barrios Date: Tue, 28 Jul 2026 15:30:21 -0400 Subject: [PATCH] Clarify MCP negotiation tests --- skills/mcp-builder/SKILL.md | 12 +++++++----- tests/mcp-builder.test.mjs | 24 ++++++++++++++++++------ 2 files changed, 25 insertions(+), 11 deletions(-) diff --git a/skills/mcp-builder/SKILL.md b/skills/mcp-builder/SKILL.md index 8ef5d77..bb56435 100644 --- a/skills/mcp-builder/SKILL.md +++ b/skills/mcp-builder/SKILL.md @@ -57,7 +57,7 @@ Build the smallest correct TypeScript or Python MCP server in three phases: sele #### 2.2 Enforce lifecycle and capability negotiation - `initialize` must be the first protocol operation. It exchanges protocol version and capabilities; after success, the client sends `notifications/initialized`. -- Reject unsupported required protocol versions. Invoke optional operations only when negotiated, and do not send optional notifications unless the peer advertised the corresponding capability. +- When the client proposes an unsupported protocol version, the server responds during `initialize` with a supported version. The client continues only if it supports that counteroffered version; otherwise it disconnects. Genuinely incompatible version negotiation must fail cleanly without entering operation. Invoke optional operations only when negotiated, and do not send optional notifications unless the peer advertised the corresponding capability. - Advertise only implemented capabilities. Report `listChanged` accurately and claim resource subscription support only when subscriptions and their lifecycle are implemented. #### 2.3 Design the exposed surface @@ -87,10 +87,12 @@ Build the smallest correct TypeScript or Python MCP server in three phases: sele Test the generated MCP project without external network or LLM calls. Cover: -- Initialization order, version negotiation, incompatible versions, and exact advertised capabilities. -- Capability-gated operations and notifications, including `listChanged` and resource subscriptions when exposed. -- Lists, reads and calls, resource templates, prompts, pagination cursors, schemas, and structured-output conformance for every exposed surface. -- JSON-RPC protocol failures and `isError`: true execution failures, including malformed requests, timeout, cancellation, cleanup, teardown, and shutdown. +- Test initialization order and version negotiation, including compatible fallback through the server's supported-version counteroffer and genuinely incompatible versions. +- Test exact advertised capabilities and capability-gated operations and notifications, including `listChanged` and resource subscriptions when exposed. +- Test lists, reads and calls, resource templates, prompts, pagination cursors, schemas, and structured-output conformance for every exposed surface. +- Test JSON-RPC protocol failures and `isError`: true execution failures, including malformed requests and timeout behavior. +- Test cancellation handling and cleanup. +- Test transport teardown and orderly shutdown. - stdio stdout purity and stderr diagnostics. - Streamable HTTP `Origin`, authentication, protocol-version, session, and content-type behavior when HTTP is selected. - Fixed fixtures plus deterministic IDs and clocks. diff --git a/tests/mcp-builder.test.mjs b/tests/mcp-builder.test.mjs index 5dc7882..dcd487e 100644 --- a/tests/mcp-builder.test.mjs +++ b/tests/mcp-builder.test.mjs @@ -21,9 +21,12 @@ test("mcp-builder defines modern transport and security contracts", () => { assert.match(skill, /stdout.*protocol.*stderr.*log/is); assert.match(skill, /Streamable HTTP.*remote/is); assert.match(skill, /HTTP\+SSE.*compatibility-only|legacy HTTP\+SSE.*compatibility/is); - for (const concept of ["Origin", "loopback", "authentication", "session", "protocol-version", "cancellation", "shutdown"]) { - assert.match(skill, new RegExp(concept, "i"), concept); - } + assert.match(skill, /validate `?Origin`?/i); + assert.match(skill, /bind local[^.\n]*loopback/i); + assert.match(skill, /require[^.\n]*authentication[^.\n]*remote/i); + assert.match(skill, /cryptographically secure[^.\n]*non-authorizing session IDs/i); + assert.match(skill, /validate protocol-version and session headers/i); + assert.doesNotMatch(skill, /(?:do not|don't|never)[^.\n]*(?:validate[^.\n]*Origin|bind[^.\n]*loopback|authentication|session IDs?|headers?)/i); }); test("mcp-builder negotiates lifecycle and capabilities", () => { @@ -31,6 +34,9 @@ test("mcp-builder negotiates lifecycle and capabilities", () => { assert.match(skill, /protocol version.*capabilit/is); assert.match(skill, /notifications\/initialized/); assert.match(skill, /only.*negotiated|advertised.*capabilit/is); + assert.match(skill, /client proposes an unsupported protocol version[^.]*server responds[^.]*supported version/i); + assert.match(skill, /client continues only if it supports that counteroffered version[^.]*otherwise (?:it )?disconnects/i); + assert.match(skill, /genuinely incompatible version negotiation[^.]*fail cleanly/i); assert.match(skill, /listChanged/); assert.match(skill, /resource subscriptions?/i); }); @@ -53,9 +59,15 @@ test("mcp-builder uses both MCP error channels", () => { test("mcp-builder requires deterministic protocol tests before evaluations", () => { assert.match(skill, /deterministic protocol tests/i); assert.match(skill, /in-memory.*transport|paired transport/is); - for (const concept of ["initialization", "capability", "pagination", "schema", "timeout", "cancellation", "teardown"]) { - assert.match(skill, new RegExp(concept, "i"), concept); - } + assert.match(skill, /test[^.\n]*initialization[^.\n]*version negotiation/i); + assert.match(skill, /test[^.\n]*compatible fallback[^.\n]*counteroffer/i); + assert.match(skill, /test[^.\n]*genuinely incompatible versions/i); + assert.match(skill, /test[^.\n]*capabilit/i); + assert.match(skill, /test[^.\n]*pagination[^.\n]*schemas/i); + assert.match(skill, /test[^.\n]*timeout/i); + assert.match(skill, /test[^.\n]*cancellation/i); + assert.match(skill, /test[^.\n]*(?:teardown[^.\n]*shutdown|shutdown[^.\n]*teardown)/i); + assert.doesNotMatch(skill, /(?:do not|don't|never)[^.\n]*(?:test|verify)[^.\n]*(?:timeout|cancellation|teardown|shutdown)/i); assert.match(skill, /Inspector.*supplemental|supplemental.*Inspector/is); assert.doesNotMatch(skill, /Create 10 evaluation questions||XML file/i); });