diff --git a/.changeset/stdio-pinned-unsupported-protocol-version.md b/.changeset/stdio-pinned-unsupported-protocol-version.md new file mode 100644 index 0000000000..68cb0811d7 --- /dev/null +++ b/.changeset/stdio-pinned-unsupported-protocol-version.md @@ -0,0 +1,5 @@ +--- +'@modelcontextprotocol/server': patch +--- + +Reject a request on a `serveStdio` connection pinned to the 2026-07-28 revision when that request's `_meta` envelope names a protocol version the server does not implement. The response is `-32022` with the supported list, and the method does not run. An unknown method is still `-32601`, and a missing or malformed envelope is still `-32602`. diff --git a/packages/server/src/server/serveStdio.ts b/packages/server/src/server/serveStdio.ts index 39e5fd6ce6..8d935dcf3c 100644 --- a/packages/server/src/server/serveStdio.ts +++ b/packages/server/src/server/serveStdio.ts @@ -6,11 +6,13 @@ * The entry owns the stdio transport and the era decision for the connection. * It classifies the connection's opening exchange exactly once (using the * same body-primary rules as the HTTP entry), constructs ONE server instance - * from the consumer's factory for the era the client opened with, pins that - * instance for the lifetime of the connection, and passes every later message - * straight through to it. No per-message era classification ever runs after - * the connection is pinned — exactly mirroring how `createMcpHandler` - * classifies an HTTP request before any instance exists. + * from the consumer's factory for the era the client opened with, and pins + * that instance for the lifetime of the connection. Later messages pass + * through to that instance. A modern request whose envelope names a revision + * this entry does not serve is answered with `-32022` before the instance + * runs it. No per-message era classification ever runs after the connection + * is pinned — exactly mirroring how `createMcpHandler` classifies an HTTP + * request before any instance exists. * * The opening exchange: * @@ -59,6 +61,7 @@ import type { } from '@modelcontextprotocol/core-internal'; import { carriesValidModernEnvelopeClaim, + codecForVersion, envelopeClaimVersion, extensionsSettled, hasEnvelopeClaim, @@ -66,6 +69,7 @@ import { isJSONRPCNotification, isJSONRPCRequest, isJSONRPCResultResponse, + MODERN_WIRE_REVISION, modernOnlyStrictRejection, ProtocolErrorCode, requestMetaOf, @@ -339,6 +343,32 @@ function classifyOpeningMessage(message: JSONRPCRequest | JSONRPCNotification): return { kind: 'modern', revision: claimedVersion, classification: { era: 'modern', revision: claimedVersion } }; } +/** + * Revision a modern-pinned request must be rejected for before dispatch. + * `undefined` leaves the answer to the instance: an unknown method is + * `-32601` and a missing or malformed envelope is `-32602`, and both outrank + * an unsupported revision. + */ +function unsupportedPinnedRevision(message: JSONRPCRequest): string | undefined { + // Method existence is the instance's -32601. Only a method the modern + // registry actually serves can reach the revision check. + if (!codecForVersion(MODERN_WIRE_REVISION).hasRequestMethod(message.method)) { + return undefined; + } + if (!hasEnvelopeClaim(message.params)) { + return undefined; + } + const meta = requestMetaOf(message.params); + if (meta === undefined || validateEnvelopeMeta(meta).length > 0) { + return undefined; + } + const claimedVersion = envelopeClaimVersion(message.params); + if (claimedVersion !== undefined && SUPPORTED_MODERN_PROTOCOL_VERSIONS.includes(claimedVersion)) { + return undefined; + } + return claimedVersion ?? 'unknown'; +} + /* ------------------------------------------------------------------------ * * The entry * ------------------------------------------------------------------------ */ @@ -606,6 +636,20 @@ export function serveStdio(factory: McpServerFactory, options: ServeStdioOptions // buffered final message can race stdin EOF): stay closed. return; } + if (state.era === 'modern' && isJSONRPCRequest(message)) { + const requested = unsupportedPinnedRevision(message); + if (requested !== undefined) { + // Same -32022 the opening classifier and the HTTP entry + // answer, before the pinned instance can run the method. + const error = new UnsupportedProtocolVersionError({ + supported: [...SUPPORTED_MODERN_PROTOCOL_VERSIONS], + requested + }); + reportError(error); + await writeErrorResponse(message.id, error.code, error.message, error.data); + return; + } + } state.instance.channel.deliver(message); return; } diff --git a/packages/server/test/server/serveStdio.test.ts b/packages/server/test/server/serveStdio.test.ts index eea38beb08..967ef08740 100644 --- a/packages/server/test/server/serveStdio.test.ts +++ b/packages/server/test/server/serveStdio.test.ts @@ -18,7 +18,10 @@ * - `legacy: 'reject'` answers legacy openings with the same error and never * pins a legacy instance; * - malformed and unsupported envelope claims are answered by the entry, - * consistent with the HTTP entry's treatment, without pinning. + * consistent with the HTTP entry's treatment, without pinning; + * - once the modern era is pinned, a later request naming a revision the + * entry does not serve is answered `-32022` before the method runs. + * An unknown method stays `-32601` and a malformed envelope stays `-32602`. */ import { Readable, Writable } from 'node:stream'; @@ -579,6 +582,97 @@ describe('malformed and unsupported envelope claims (entry-answered, never pinne }); }); +describe('unsupported revision on a modern-pinned connection', () => { + it('answers -32022 and does not run the method when a later request names a revision the entry does not serve', async () => { + let calls = 0; + const eras: Array<'legacy' | 'modern'> = []; + const factory: McpServerFactory = ctx => { + eras.push(ctx.era); + const server = new McpServer({ name: 'serve-stdio-test-server', version: '1.0.0' }, { capabilities: { tools: {} } }); + server.registerTool('echo', { inputSchema: z.object({ text: z.string() }) }, ({ text }) => { + calls += 1; + return { content: [{ type: 'text', text }] }; + }); + return server; + }; + const { handle, request } = await startEntryWith(factory); + + const pin = await request({ jsonrpc: '2.0', id: 1, method: 'tools/list', params: { _meta: envelope() } }); + expect(isJSONRPCResultResponse(pin)).toBe(true); + + const expectUnsupported = async (id: number, method: string, protocolVersion: string, params: Record = {}) => { + const response = await request({ + jsonrpc: '2.0', + id, + method, + params: { ...params, _meta: envelope({ [PROTOCOL_VERSION_META_KEY]: protocolVersion }) } + }); + expect(isJSONRPCErrorResponse(response)).toBe(true); + if (isJSONRPCErrorResponse(response)) { + expect(response.error.code).toBe(-32_022); + expect(response.error.message).toBe(`Unsupported protocol version: ${protocolVersion}`); + const data = response.error.data as { supported?: string[]; requested?: string }; + expect(data.supported).toEqual([MODERN]); + expect(data.requested).toBe(protocolVersion); + } + }; + + // The same requests the opening window rejects, after the pin. + await expectUnsupported(2, 'server/discover', '2099-01-01'); + await expectUnsupported(3, 'tools/list', '2099-01-01'); + await expectUnsupported(4, 'tools/call', '2099-01-01', { name: 'echo', arguments: { text: 'should not run' } }); + await expectUnsupported(5, 'tools/list', '2025-11-25'); + expect(calls).toBe(0); + + const again = await request({ jsonrpc: '2.0', id: 6, method: 'tools/list', params: { _meta: envelope() } }); + expect(isJSONRPCResultResponse(again)).toBe(true); + const ran = await request({ + jsonrpc: '2.0', + id: 7, + method: 'tools/call', + params: { name: 'echo', arguments: { text: 'after' }, _meta: envelope() } + }); + expect(isJSONRPCResultResponse(ran)).toBe(true); + expect(calls).toBe(1); + // The rejection did not rebuild the instance or unpin the connection. + expect(eras).toEqual(['modern']); + + await handle.close(); + }); + + it('keeps -32601 for an unknown method and -32602 for a malformed envelope ahead of the revision check', async () => { + const { handle, request } = await startEntry(); + const pin = await request({ jsonrpc: '2.0', id: 1, method: 'tools/list', params: { _meta: envelope() } }); + expect(isJSONRPCResultResponse(pin)).toBe(true); + + const unknown = await request({ + jsonrpc: '2.0', + id: 2, + method: 'nope', + params: { _meta: envelope({ [PROTOCOL_VERSION_META_KEY]: '2099-01-01' }) } + }); + expect(isJSONRPCErrorResponse(unknown)).toBe(true); + if (isJSONRPCErrorResponse(unknown)) { + expect(unknown.error.code).toBe(-32_601); + expect(unknown.error.message).toBe('Method not found'); + } + + const malformed = await request({ + jsonrpc: '2.0', + id: 3, + method: 'tools/list', + params: { _meta: { [PROTOCOL_VERSION_META_KEY]: '2099-01-01' } } + }); + expect(isJSONRPCErrorResponse(malformed)).toBe(true); + if (isJSONRPCErrorResponse(malformed)) { + expect(malformed.error.code).toBe(-32_602); + expect(malformed.error.message).toContain('Invalid _meta envelope'); + } + + await handle.close(); + }); +}); + describe('factory or connect failure during the opening exchange (entry-answered, never pinned)', () => { it('answers a legacy opening with -32603 when the factory throws, reports the error, and leaves the connection unpinned', async () => { const { factory: workingFactory, eras } = trackingFactory();