Validate all wire messages against the per-version spec JSON schema (#399)

* Vendor schema/{version}/schema.json alongside schema.ts

sync-schema now copies the spec repo's JSON Schema for each version into
src/spec-types/{version}.schema.json (same pinned SHA recorded in SOURCE:
modelcontextprotocol@f817239f4d6b1efff2c4dfc2f7af85c985d73076). These are
the inputs for runtime wire-message validation. Vendored verbatim, so they
join schema.ts in .prettierignore.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JHNrpU3Vr6Q1rPZiji7zLY

* Validate all wire messages against the per-version spec JSON schema

Every JSON-RPC message the harness sends or receives is now validated
(ajv) against the vendored schema.json for the run's spec version, at the
wire choke points: sendStatelessRequest (outbound request, JSON response,
SSE events), connectStateful (request/result/notifications), and both mock
servers (inbound client requests, outbound responses/handler results).

Beyond the JSONRPCMessage envelope, messages are validated against the
most specific definition the schema has: typed requests/notifications by
method const, typed error responses by error.code const (e.g. -32021 ->
MissingRequiredClientCapabilityError, the #376 hallucination), and typed
results via the XxxRequest -> XxxResult pair, with SEP-2322
InputRequiredResult discriminated on resultType.

Violations are recorded per scenario and surfaced by the runners as a
synthetic wire-schema-valid check (FAILURE when the implementation under
test sent an invalid message) plus a wire-schema-harness-error check when
the invalid message was harness-authored. A vitest-wide afterEach guard
fails any self-test that recorded violations, so hallucinated fixtures
can't ship (#376, #271). Opt-outs are explicit and greppable: per-call
skipValidation for deliberately malformed traffic, takeWireViolations()
drains in tests that exercise deliberately broken fixtures.

Offenders the new validation caught, now fixed:
- everything-server stateless path omitted resultType (and the caching
  hints on server/discover) required by the draft schema
- sep-2164-empty-contents fixture omitted resultType/ttlMs/cacheScope
  (its intended violation, empty contents, is schema-valid prose-only)
- connection/mock-server unit-test fixtures used schema-invalid stubs
  (tools/call without name, ListToolsResult without required members,
  Tool without inputSchema, ProgressNotification without progressToken,
  ElicitRequest without message/requestedSchema)
- http-standard-headers test mocks returned bare { tools: [] } results
- input-required-result-validate-input deliberately sends malformed
  inputResponses; now marked skipValidation

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JHNrpU3Vr6Q1rPZiji7zLY

* Validate the stateful wire at the SDK transport, close review-panel gaps

Address the review-panel findings on the wire-schema validation PR:

- Stateful wire: hook the SDK transport inside connectToServer, wrapping
  send/onmessage so every raw wire message in both directions is
  validated for the scenario's spec version -- including the initialize
  handshake, server->client requests (elicitation/sampling), and the
  harness's responses to them. Request ids are correlated per direction
  so responses validate against their typed result definition (e.g. an
  outbound ElicitResult). The reconstructed stand-ins in
  connectStateful (fake id: 0 envelopes, Zod-reparsed results) are
  removed; the hook sees the real bytes. The four scenarios that call
  connectToServer directly (elicitation-defaults, elicitation-enums,
  tools, lifecycle) now pass ctx.specVersion and get validation for
  free; the runner surfaces their violations through the existing
  recorder. Known remaining gap (documented in the module doc): the
  client-auth scenarios' bespoke express mock is not instrumented.

- skipValidation now skips only the request direction; the
  implementation's response to a deliberately malformed request is
  still validated, with a narrow carve-out tolerating the JSON-RPC 2.0
  id: null an error response must carry when the request could not be
  processed (the MCP schema's RequestId forbids null). Covered by new
  unit tests pinning both the still-validated response and the
  narrowness of the carve-out.

- negative-mrtr.test.ts: the file-wide drain now asserts every recorded
  violation is implementation-origin (the deliberately broken fixture)
  and throws on any harness-origin violation.

- everything-server: hoist the cacheable-methods set to module scope
  and replace the per-request res.json monkey-patch with an explicit
  sendStatelessJson(res, method, payload) helper applied at each
  dispatch site.

- Pin the extracted dispatch maps (methodDefs/errorDefs, e.g.
  -32021 -> MissingRequiredClientCapabilityError under the draft) per
  spec version in wire-schema.test.ts, so a schema sync that breaks the
  const extraction fails loudly instead of degrading to envelope-only
  validation. Also note the batch branch's requestMethod forwarding
  limitation.

Offender the transport hook flushed out: the everything-server's
test_elicitation_sep1034_defaults tool sent a number-typed elicitation
field with default: 95.5, which the 2025-11-25 schema forbids
(NumberSchema.default is typed integer there; widened to number only in
the draft). The fixture and the scenario's expected default are now the
integer-valued 95, with comments explaining why.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JHNrpU3Vr6Q1rPZiji7zLY

* Condense comments to three lines max

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JHNrpU3Vr6Q1rPZiji7zLY

* Re-vendor spec schemas at pinned SHA 71e30695

Regenerate src/spec-types/*.schema.json via npm run sync-schema at the
SHA already recorded in SOURCE. The previously vendored draft schema
predated spec PR #3002, so it still required DiscoverResult.serverInfo
at the top level; the mock server now correctly reports serverInfo via
result _meta, which the stale schema rejected.

* Scope the wire-violation recorder per scenario for parallel suite runs

Client --suite runs execute scenarios concurrently over what was a
module-global violation recorder, so scenarios could steal or wipe each
other's recorded violations. Give each suite scenario its own recorder
via AsyncLocalStorage; code outside a scope (single-scenario runs, the
sequential server suite, vitest hooks) falls back to the global
recorder. Also condense a four-line comment in connection/stateful.ts
to three lines.

* Patch the 2025-11-25 NumberSchema generator bug as a load-time erratum

The released 2025-11-25 schema.json types NumberSchema
minimum/maximum/default as integer, contradicting its own schema.ts
(default?: number) — a typescript-json-schema artifact, fixed for draft
in modelcontextprotocol#2710 and proposed for 2025-11-25 in
modelcontextprotocol#3139. Patch the schema at load time so SDK
fixtures with fractional number defaults (all tier-1 SDKs send 95.5)
are not flagged; restore the sep-1034 scenario and example-server
fixture to 95.5. Delete the erratum when #3139 lands and the schemas
are re-vendored.

Also scope the sequential server-suite loop with withWireRecorder so a
connection leaked by a failed scenario cannot attribute late traffic to
the next scenario.

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Paul Carleton <paulc@anthropic.com>
This commit is contained in:
claude[bot] 2026-07-27 15:58:43 +01:00 • committed by GitHub
commit 89c2c0452e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
31 changed files with 14136 additions and 129 deletions

View file

@ -3,6 +3,7 @@ import { isStatefulVersion, STATELESS_SPEC_VERSIONS } from './select';
import { connectStateless } from './stateless';
import { JsonRpcError } from './index';
import { DRAFT_PROTOCOL_VERSION } from '../types';
import { takeWireViolations } from '../validation/wire-schema';
describe('STATELESS_SPEC_VERSIONS', () => {
it('contains exactly the versions isStatefulVersion rejects', () => {
@ -37,7 +38,16 @@ describe('connectStateless', () => {
it('injects required _meta keys and MCP-Protocol-Version header', async () => {
mockFetch.mockResolvedValue(
jsonResponse({ jsonrpc: '2.0', id: 1, result: { ok: true } })
jsonResponse({
jsonrpc: '2.0',
id: 1,
result: {
tools: [],
resultType: 'complete',
ttlMs: 0,
cacheScope: 'private'
}
})
);
const conn = await connectStateless('http://test/mcp');
await conn.request('tools/list');
@ -76,6 +86,8 @@ describe('connectStateless', () => {
);
const conn = await connectStateless('http://test/mcp');
await expect(conn.request('tools/list')).rejects.toThrow(/HTTP 502/);
// The gateway body is deliberately not a JSON-RPC message.
expect(takeWireViolations().violations).toHaveLength(1);
});
it('throws a useful error for non-JSON non-SSE responses', async () => {
@ -92,12 +104,15 @@ describe('connectStateless', () => {
it('parses SSE: collects notifications and returns final result (LF)', async () => {
mockFetch.mockResolvedValue(
sseResponse([
'event: message\ndata: {"jsonrpc":"2.0","method":"notifications/progress","params":{"progress":1}}\n\n',
'event: message\ndata: {"jsonrpc":"2.0","id":1,"result":{"done":true}}\n\n'
'event: message\ndata: {"jsonrpc":"2.0","method":"notifications/progress","params":{"progressToken":"t1","progress":1}}\n\n',
'event: message\ndata: {"jsonrpc":"2.0","id":1,"result":{"content":[],"resultType":"complete","done":true}}\n\n'
])
);
const conn = await connectStateless('http://test/mcp');
const result = await conn.request<{ done: boolean }>('tools/call', {});
const result = await conn.request<{ done: boolean }>('tools/call', {
name: 'echo',
arguments: {}
});
expect(result.done).toBe(true);
expect(conn.notifications).toHaveLength(1);
expect(conn.notifications[0].method).toBe('notifications/progress');
@ -106,21 +121,26 @@ describe('connectStateless', () => {
it('parses SSE with CRLF line endings', async () => {
mockFetch.mockResolvedValue(
sseResponse([
'event: message\r\ndata: {"jsonrpc":"2.0","id":1,"result":{"ok":true}}\r\n\r\n'
'event: message\r\ndata: {"jsonrpc":"2.0","id":1,"result":{"content":[],"resultType":"complete","ok":true}}\r\n\r\n'
])
);
const conn = await connectStateless('http://test/mcp');
const result = await conn.request<{ ok: boolean }>('tools/call', {});
const result = await conn.request<{ ok: boolean }>('tools/call', {
name: 'echo',
arguments: {}
});
expect(result.ok).toBe(true);
});
it('rejects server-to-client requests on the SSE stream', async () => {
mockFetch.mockResolvedValue(
sseResponse([
'event: message\ndata: {"jsonrpc":"2.0","id":99,"method":"elicitation/create","params":{}}\n\n'
'event: message\ndata: {"jsonrpc":"2.0","id":99,"method":"elicitation/create","params":{"message":"Name?","requestedSchema":{"type":"object","properties":{}}}}\n\n'
])
);
const conn = await connectStateless('http://test/mcp');
await expect(conn.request('tools/call', {})).rejects.toThrow(/MRTR/);
await expect(
conn.request('tools/call', { name: 'echo', arguments: {} })
).rejects.toThrow(/MRTR/);
});
});

View file

@ -6,9 +6,17 @@ import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import {
LoggingMessageNotificationSchema,
ProgressNotificationSchema
ProgressNotificationSchema,
type JSONRPCMessage,
type MessageExtraInfo
} from '@modelcontextprotocol/sdk/types.js';
import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
import { LATEST_SPEC_VERSION, type SpecVersion } from '../types';
import {
validateWireMessage,
type WireOrigin
} from '../validation/wire-schema';
import type { ConnectOptions } from './index';
const DEFAULT_CLIENT_INFO = {
@ -26,21 +34,100 @@ export interface MCPClientConnection {
close: () => Promise<void>;
}
/** Hook an SDK transport so every raw wire message, both directions (handshake included,
* no bypass), is schema-validated. Outbound = harness origin, inbound = implementation;
* request ids are tracked per direction to validate responses against typed results. */
function instrumentTransport(
transport: Transport,
specVersion: SpecVersion
): void {
// Request id → method, per direction. An entry is consumed by the response
// travelling the opposite way, so the maps stay bounded.
const harnessRequests = new Map<string | number, string>();
const implementationRequests = new Map<string | number, string>();
const validate = (message: unknown, origin: WireOrigin): void => {
const ownRequests =
origin === 'harness' ? harnessRequests : implementationRequests;
const peerRequests =
origin === 'harness' ? implementationRequests : harnessRequests;
// `send` accepts arrays (2025-03-26 batches); validate each element with
// its own classification, then the batch envelope itself.
for (const m of Array.isArray(message) ? message : [message]) {
const msg = (typeof m === 'object' && m !== null ? m : {}) as Record<
string,
unknown
>;
const id = msg.id as string | number | undefined;
let context: string;
let requestMethod: string | undefined;
if (typeof msg.method === 'string') {
if (id !== undefined) {
ownRequests.set(id, msg.method);
context = `stateful request '${msg.method}'`;
} else {
context = `stateful notification '${msg.method}'`;
}
} else {
requestMethod = id !== undefined ? peerRequests.get(id) : undefined;
if (id !== undefined) peerRequests.delete(id);
context = `stateful response to '${requestMethod ?? `id ${String(id)}`}'`;
}
validateWireMessage(specVersion, m, { origin, context, requestMethod });
}
if (Array.isArray(message)) {
validateWireMessage(specVersion, message, {
origin,
context: 'stateful batch'
});
}
};
const originalSend = transport.send.bind(transport);
transport.send = (message, options) => {
validate(message, 'harness');
return originalSend(message, options);
};
// The SDK's protocol layer assigns `onmessage` during `client.connect()`;
// intercept the assignment so the validator sees every inbound message
// before the handler does.
let inner:
| ((message: JSONRPCMessage, extra?: MessageExtraInfo) => void)
| undefined;
const wrapped = (message: JSONRPCMessage, extra?: MessageExtraInfo): void => {
validate(message, 'implementation');
inner?.(message, extra);
};
Object.defineProperty(transport, 'onmessage', {
configurable: true,
enumerable: true,
get: () => (inner === undefined ? undefined : wrapped),
set: (handler: typeof inner) => {
inner = handler;
}
});
}
/**
* Create and connect an MCP client to a server. `opts.capabilities` and
* `opts.clientInfo` override the harness defaults — scenarios that
* negotiate extensions (tasks, EMA, ...) pass them through to drive a
* conformant `initialize`.
* conformant `initialize`. The transport is instrumented so every wire
* message in both directions is validated against `specVersion`'s spec
* JSON schema; scenarios that call this directly pass `ctx.specVersion`.
*/
export async function connectToServer(
serverUrl: string,
opts: ConnectOptions = {}
opts: ConnectOptions = {},
specVersion: SpecVersion = LATEST_SPEC_VERSION
): Promise<MCPClientConnection> {
const client = new Client(opts.clientInfo ?? DEFAULT_CLIENT_INFO, {
capabilities: opts.capabilities ?? DEFAULT_CAPABILITIES
});
const transport = new StreamableHTTPClientTransport(new URL(serverUrl));
instrumentTransport(transport, specVersion);
await client.connect(transport);

View file

@ -43,11 +43,11 @@ export const STATELESS_SPEC_VERSIONS: readonly SpecVersion[] =
export function connectFor(
specVersion: SpecVersion
): (serverUrl: string, opts?: ConnectOptions) => Promise<Connection> {
// Pass the version through so requests declare (and are wire-schema
// validated against) the spec version the run was invoked with.
return isStatefulVersion(specVersion)
? connectStateful
: // Pass the version through so stateless requests declare the spec
// version the run was invoked with (matters under --force).
(serverUrl, opts) => connectStateless(serverUrl, specVersion, opts);
? (serverUrl, opts) => connectStateful(serverUrl, opts, specVersion)
: (serverUrl, opts) => connectStateless(serverUrl, specVersion, opts);
}
/**

View file

@ -15,23 +15,29 @@ import {
} from '@modelcontextprotocol/sdk/types.js';
import { connectToServer } from './sdk-client';
import type { JSONRPCNotification } from '../spec-types/2025-11-25';
import { LATEST_SPEC_VERSION, type SpecVersion } from '../types';
import { JsonRpcError, type Connection, type ConnectOptions } from './index';
export async function connectStateful(
serverUrl: string,
opts: ConnectOptions = {}
opts: ConnectOptions = {},
specVersion: SpecVersion = LATEST_SPEC_VERSION
): Promise<Connection> {
const { client, close } = await connectToServer(serverUrl, opts);
// Wire-schema validation happens inside connectToServer, which hooks the
// SDK transport's send/onmessage so the real bytes of every message in
// both directions are validated — no per-call choke points needed here.
const { client, close } = await connectToServer(serverUrl, opts, specVersion);
const notifications: JSONRPCNotification[] = [];
const collect = (n: unknown) => {
// The SDK's Zod parsing strips the jsonrpc field; restore it so collected
// notifications match the JSONRPCNotification wire shape, as
// connectStateless provides.
notifications.push({
// notifications match the wire shape connectStateless provides (the raw
// notification was already validated by the transport hook).
const notification = {
jsonrpc: '2.0',
...(n as object)
} as JSONRPCNotification);
} as JSONRPCNotification;
notifications.push(notification);
};
// The SDK pre-registers a handler for notifications/progress (to drive the
// onprogress callback feature), so it never reaches the fallback. Register
@ -73,7 +79,8 @@ export async function connectStateful(
);
}
try {
return (await client.request({ method, params }, ResultSchema)) as R;
const result = await client.request({ method, params }, ResultSchema);
return result as R;
} catch (e) {
// Normalize so scenarios always see JsonRpcError regardless of impl.
// The SDK prefixes messages with "MCP error <code>: "; strip it so

View file

@ -13,6 +13,7 @@ import {
DEFAULT_CLIENT_CAPABILITIES
} from './stateless';
import { DRAFT_PROTOCOL_VERSION } from '../types';
import { takeWireViolations } from '../validation/wire-schema';
describe('buildStandardHeaders', () => {
test('sets the standard headers pinned to the draft protocol version', () => {
@ -87,7 +88,12 @@ describe('sendStatelessRequest', () => {
JSON.stringify({
jsonrpc: '2.0',
id: request.id,
result: { tools: [] }
result: {
tools: [],
resultType: 'complete',
ttlMs: 0,
cacheScope: 'private'
}
})
);
});
@ -100,7 +106,12 @@ describe('sendStatelessRequest', () => {
'tools/list'
);
expect(response.status).toBe(200);
expect(response.body?.result).toEqual({ tools: [] });
expect(response.body?.result).toEqual({
tools: [],
resultType: 'complete',
ttlMs: 0,
cacheScope: 'private'
});
} finally {
await new Promise<void>((resolve) => server.close(() => resolve()));
}
@ -151,6 +162,8 @@ describe('connectStateless', () => {
await expect(conn.request('tools/list')).rejects.toThrow(
/HTTP 502.*upstream timeout/
);
// The proxy body is deliberately not a JSON-RPC message.
expect(takeWireViolations().violations).toHaveLength(1);
} finally {
await new Promise<void>((resolve) => server.close(() => resolve()));
}

View file

@ -22,6 +22,7 @@
import { DRAFT_PROTOCOL_VERSION, type SpecVersion } from '../types';
import type { JSONRPCNotification } from '../spec-types/2025-11-25';
import { validateWireMessage } from '../validation/wire-schema';
import { JsonRpcError, type Connection, type ConnectOptions } from './index';
export interface JsonRpcResponse {
@ -242,19 +243,47 @@ export async function sendStatelessRequest(
headers?: Record<string, string>;
timeoutMs?: number;
specVersion?: SpecVersion;
/** Skip wire-schema validation of the *outgoing request* only (for intentionally
* malformed traffic). Responses stay validated, with one carve-out: JSON-RPC 2.0
* requires `id: null` on errors for unprocessable requests, which RequestId forbids. */
skipValidation?: boolean;
} = {}
): Promise<StatelessResponse> {
const id = nextRequestId++;
const specVersion = options.specVersion ?? DRAFT_PROTOCOL_VERSION;
const headers = buildStandardHeaders(method, params, {
headers: options.headers,
specVersion: options.specVersion
});
const body = JSON.stringify({
const request = {
jsonrpc: '2.0',
id,
method,
params: withRequestMeta(params, options.specVersion)
});
};
if (!options.skipValidation) {
validateWireMessage(specVersion, request, {
origin: 'harness',
context: `stateless request '${method}'`
});
}
const body = JSON.stringify(request);
// See the `skipValidation` doc above: on a skip-validated request, tolerate the
// JSON-RPC 2.0 `id: null` an error response must carry when the request could not be
// processed, by validating the rest of the shape with the request's real id substituted.
const withNullIdCarveOut = (event: unknown): unknown => {
if (
options.skipValidation &&
typeof event === 'object' &&
event !== null &&
(event as Record<string, unknown>).error !== undefined &&
(event as Record<string, unknown>).id === null
) {
return { ...(event as Record<string, unknown>), id };
}
return event;
};
const controller = new AbortController();
const timeout = setTimeout(
@ -275,6 +304,13 @@ export async function sendStatelessRequest(
// Read the stream incrementally and resolve on the matching response —
// a server that keeps the stream open must not stall the harness.
const { events, body: matched } = await readSseJsonRpcResponse(res, id);
for (const event of events) {
validateWireMessage(specVersion, withNullIdCarveOut(event), {
origin: 'implementation',
context: `SSE event during '${method}'`,
requestMethod: event === matched ? method : undefined
});
}
return {
status: res.status,
headers: res.headers,
@ -286,11 +322,19 @@ export async function sendStatelessRequest(
const text = await res.text();
try {
const parsed = text ? (JSON.parse(text) as JsonRpcResponse) : undefined;
if (parsed !== undefined) {
validateWireMessage(specVersion, withNullIdCarveOut(parsed), {
origin: 'implementation',
context: `response to '${method}'`,
requestMethod: method
});
}
return {
status: res.status,
headers: res.headers,
contentType,
body: text ? (JSON.parse(text) as JsonRpcResponse) : undefined
body: parsed
};
} catch {
return { status: res.status, headers: res.headers, contentType, text };

View file

@ -43,6 +43,7 @@ import {
ServerOptionsSchema
} from './schemas';
import type { AuthorizationServerOptions } from './schemas';
import { withWireRecorder } from './validation/wire-schema';
import {
loadExpectedFailures,
evaluateBaseline,
@ -159,13 +160,17 @@ program
const results = await Promise.all(
scenarios.map(async (scenarioName) => {
try {
const result = await runConformanceTest(
options.command,
scenarioName,
timeout,
outputDir,
specVersionFilter,
options.force ?? false
// Each concurrent scenario records wire violations into its own
// AsyncLocalStorage-scoped recorder (see withWireRecorder).
const result = await withWireRecorder(() =>
runConformanceTest(
options.command,
scenarioName,
timeout,
outputDir,
specVersionFilter,
options.force ?? false
)
);
return {
scenario: scenarioName,
@ -452,11 +457,15 @@ program
for (const scenarioName of scenarios) {
console.log(`\n=== Running scenario: ${scenarioName} ===`);
try {
const result = await runServerConformanceTest(
validated.url,
scenarioName,
outputDir,
specVersionFilter
// Sequential, but a failed scenario can leak a connection that
// emits late traffic; scoping keeps it out of the next scenario.
const result = await withWireRecorder(() =>
runServerConformanceTest(
validated.url,
scenarioName,
outputDir,
specVersionFilter
)
);
allResults.push({ scenario: scenarioName, checks: result.checks });
} catch (error) {

View file

@ -9,6 +9,7 @@ import {
} from './stateless';
import { STATELESS_SPEC_VERSIONS } from '../connection/select';
import { DRAFT_PROTOCOL_VERSION } from '../types';
import { takeWireViolations } from '../validation/wire-schema';
const meta = {
'io.modelcontextprotocol/protocolVersion': DRAFT_PROTOCOL_VERSION,
@ -180,9 +181,33 @@ describe('withRequiredDraftResultFields', () => {
});
describe('createServerFor', () => {
it('returns stateful for dated 2025-x versions', () => {
expect(createServerFor('2025-06-18')).toBe(createServerStateful);
expect(createServerFor('2025-11-25')).toBe(createServerStateful);
it('returns a stateful factory for dated 2025-x versions', async () => {
const srv = await createServerFor('2025-11-25')({
'tools/list': () => ({ tools: [] })
});
try {
// Only the stateful (initialize handshake) impl answers initialize.
const r = await fetch(srv.url, {
method: 'POST',
headers: {
'content-type': 'application/json',
accept: 'application/json, text/event-stream'
},
body: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'initialize',
params: {
protocolVersion: '2025-11-25',
capabilities: {},
clientInfo: { name: 't', version: '1' }
}
})
});
expect(r.status).toBe(200);
} finally {
await srv.close();
}
});
it('returns a stateless factory bound to the requested version', async () => {
const srv = await createServerFor(DRAFT_PROTOCOL_VERSION)({});
@ -232,6 +257,8 @@ describe('createServerStateless', () => {
);
expect(status).toBe(400);
expect(body.error.code).toBe(-32602);
// The request is deliberately schema-invalid (missing params._meta).
expect(takeWireViolations().violations).toHaveLength(1);
} finally {
await srv.close();
}
@ -307,7 +334,9 @@ describe('createServerStateless', () => {
it('routes to handlers and records requests', async () => {
const srv = await createServerStateless({
'tools/list': () => ({ tools: [{ name: 'x' }] })
'tools/list': () => ({
tools: [{ name: 'x', inputSchema: { type: 'object' } }]
})
});
try {
const { body } = await post(
@ -338,6 +367,8 @@ describe('createServerStateless', () => {
);
expect(status).toBe(400);
expect(srv.recorded.map((r) => r.method)).toEqual(['tools/list']);
// The request is deliberately schema-invalid (missing params._meta).
expect(takeWireViolations().violations).toHaveLength(1);
} finally {
await srv.close();
}
@ -365,7 +396,9 @@ describe('createServerStateless', () => {
it('stamps the draft-required result members onto handler results', async () => {
const srv = await createServerStateless({
'tools/list': () => ({ tools: [{ name: 'x' }] }),
'tools/list': () => ({
tools: [{ name: 'x', inputSchema: { type: 'object' } }]
}),
'tools/call': () => ({ content: [{ type: 'text', text: 'ok' }] })
});
try {
@ -415,7 +448,7 @@ describe('createServerStateless', () => {
jsonrpc: '2.0',
id: 1,
method: 'tools/call',
params: { _meta: meta }
params: { _meta: meta, name: 'x' }
},
headers
);

View file

@ -8,6 +8,6 @@ export function createServerFor(
specVersion: SpecVersion
): (handlers: RequestHandlers) => Promise<MockServer> {
return isStatefulVersion(specVersion)
? createServerStateful
? (handlers) => createServerStateful(handlers, specVersion)
: (handlers) => createServerStateless(handlers, specVersion);
}

View file

@ -13,6 +13,8 @@ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/
import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
import { z } from 'zod';
import type { JSONRPCRequest } from '../spec-types/2025-11-25';
import { LATEST_SPEC_VERSION, type SpecVersion } from '../types';
import { validateWireMessage } from '../validation/wire-schema';
import type { MockServer, RequestHandlers } from './index';
const CAPABILITY_BY_PREFIX: Record<string, string> = {
@ -40,7 +42,8 @@ export function capabilitiesFromHandlers(
}
export async function createServerStateful(
handlers: RequestHandlers
handlers: RequestHandlers,
specVersion: SpecVersion = LATEST_SPEC_VERSION
): Promise<MockServer> {
const recorded: JSONRPCRequest[] = [];
const capabilities = capabilitiesFromHandlers(handlers);
@ -61,10 +64,22 @@ export async function createServerStateful(
});
server.setRequestHandler(schema, async (request) => {
try {
return (await handler(
const result = (await handler(
(request.params ?? {}) as Record<string, unknown>,
request as JSONRPCRequest
)) as Record<string, unknown>;
// The SDK builds the response envelope; validate the
// harness-authored result against its typed definition.
validateWireMessage(
specVersion,
{ jsonrpc: '2.0', id: 0, result },
{
origin: 'harness',
context: `stateful mock result for '${method}'`,
requestMethod: method
}
);
return result;
} catch (e) {
if (e instanceof McpError) throw e;
throw new McpError(
@ -85,6 +100,10 @@ export async function createServerStateful(
// preamble) at the HTTP layer so unregistered methods are captured too,
// matching the stateless impl and the MockServer.recorded contract.
const body = req.body;
validateWireMessage(specVersion, body, {
origin: 'implementation',
context: `client request '${body?.method ?? '(unknown)'}' to stateful mock`
});
if (
body?.method &&
body.method !== 'initialize' &&

View file

@ -9,10 +9,11 @@
*/
import express from 'express';
import type { SpecVersion } from '../types';
import { DRAFT_PROTOCOL_VERSION, type SpecVersion } from '../types';
import type { JSONRPCRequest } from '../spec-types/2025-11-25';
import type { MockServer, RequestHandlers } from './index';
import { STATELESS_SPEC_VERSIONS } from '../connection/select';
import { validateWireMessage } from '../validation/wire-schema';
import { capabilitiesFromHandlers } from './stateful';
/**
@ -190,6 +191,7 @@ export async function createServerStateless(
const supportedVersions: readonly string[] = specVersion
? [specVersion]
: STATELESS_SPEC_VERSIONS;
const wireVersion = specVersion ?? DRAFT_PROTOCOL_VERSION;
const app = express();
app.use(express.json());
@ -200,16 +202,32 @@ export async function createServerStateless(
// requests are captured too, matching the stateful impl and the
// MockServer.recorded contract.
const body = req.body as Record<string, unknown> | undefined;
validateWireMessage(wireVersion, req.body, {
origin: 'implementation',
context: `client request '${body?.method ?? '(unknown)'}' to stateless mock`
});
if (body?.method && body.method !== 'server/discover') {
recorded.push(req.body as JSONRPCRequest);
}
const sendJson = (status: number, payload: object, method?: string) => {
validateWireMessage(wireVersion, payload, {
origin: 'harness',
context: `stateless mock response${method ? ` to '${method}'` : ''}`,
requestMethod: method
});
return res.status(status).json(payload);
};
const v = validateStatelessRequest(req, capabilities, supportedVersions);
if (v.kind !== 'route') {
return res.status(v.status).json(v.body);
return sendJson(
v.status,
v.body,
v.kind === 'handled' ? (body?.method as string) : undefined
);
}
const { id, method, params } = v;
const error = (status: number, code: number, message: string) =>
res.status(status).json({ jsonrpc: '2.0', id, error: { code, message } });
sendJson(status, { jsonrpc: '2.0', id, error: { code, message } });
const handler = handlers[method];
if (!handler) {
@ -217,11 +235,15 @@ export async function createServerStateless(
}
try {
const result = await handler(params, req.body as JSONRPCRequest);
return res.json({
jsonrpc: '2.0',
id,
result: withRequiredDraftResultFields(method, result)
});
return sendJson(
200,
{
jsonrpc: '2.0',
id,
result: withRequiredDraftResultFields(method, result)
},
method
);
} catch (e) {
return error(500, -32603, e instanceof Error ? e.message : String(e));
}

View file

@ -10,6 +10,10 @@ import {
} from '../types';
import { getScenario, isScenarioApplicableAt } from '../scenarios';
import { createServerFor, type ScenarioContext } from '../mock-server';
import {
resetWireValidation,
wireSchemaChecks
} from '../validation/wire-schema';
import { createResultDir, formatPrettyChecks } from './utils';
export interface ClientExecutionResult {
@ -182,6 +186,7 @@ export async function runConformanceTest(
};
console.error(`Starting scenario: ${scenarioName}`);
resetWireValidation();
const urls = await scenario.start(ctx);
console.error(`Executing client: ${clientCommand} ${urls.serverUrl}`);
@ -215,6 +220,7 @@ export async function runConformanceTest(
}
const checks = scenario.getChecks();
checks.push(...wireSchemaChecks(resolvedVersion));
if (resultDir) {
await fs.writeFile(
@ -366,6 +372,7 @@ export async function runInteractiveMode(
};
console.log(`Starting scenario: ${scenarioName}`);
resetWireValidation();
const urls = await scenario.start(ctx);
console.log(`Server URL: ${urls.serverUrl}`);
@ -375,6 +382,7 @@ export async function runInteractiveMode(
console.log('\nShutting down...');
const checks = scenario.getChecks();
checks.push(...wireSchemaChecks(resolvedVersion));
if (resultDir) {
await fs.writeFile(

View file

@ -8,6 +8,10 @@ import {
} from '../types';
import { getClientScenario, isScenarioApplicableAt } from '../scenarios';
import { connectFor, type RunContext } from '../connection';
import {
resetWireValidation,
wireSchemaChecks
} from '../validation/wire-schema';
import { createResultDir, formatPrettyChecks } from './utils';
/**
@ -93,7 +97,9 @@ export async function runServerConformanceTest(
specVersion: resolvedSpecVersion,
connect: (opts) => connectFor(resolvedSpecVersion)(serverUrl, opts)
};
resetWireValidation();
const checks = await scenario.run(ctx);
checks.push(...wireSchemaChecks(resolvedSpecVersion));
if (resultDir) {
await fs.writeFile(

View file

@ -46,7 +46,7 @@ Implement a tool named \`test_elicitation_sep1034_defaults\` (no arguments) that
const checks: ConformanceCheck[] = [];
try {
const connection = await connectToServer(serverUrl);
const connection = await connectToServer(serverUrl, {}, ctx.specVersion);
let capturedRequest: any = null;
connection.client.setRequestHandler(

View file

@ -47,7 +47,7 @@ Implement a tool named \`test_elicitation_sep1330_enums\` (no arguments) that re
const checks: ConformanceCheck[] = [];
try {
const connection = await connectToServer(serverUrl);
const connection = await connectToServer(serverUrl, {}, ctx.specVersion);
let capturedRequest: any = null;
connection.client.setRequestHandler(

View file

@ -56,6 +56,9 @@ describe('http-custom-header-server-validation — missing fixture policy', () =
jsonrpc: '2.0',
id: reqBody.id,
result: {
resultType: 'complete',
ttlMs: 0,
cacheScope: 'private',
tools: [
{
name: 'plain_tool',
@ -99,6 +102,9 @@ describe('http-custom-header-server-validation — missing fixture policy', () =
jsonrpc: '2.0',
id: reqBody.id,
result: {
resultType: 'complete',
ttlMs: 0,
cacheScope: 'private',
tools: [
{
name: 'numeric_only',
@ -169,7 +175,16 @@ describe('http-header-validation — zero-tools Mcp-Name cases', () => {
if (body.method === 'tools/list') {
return {
status: 200,
body: { jsonrpc: '2.0', id: body.id, result: { tools: [] } }
body: {
jsonrpc: '2.0',
id: body.id,
result: {
resultType: 'complete',
ttlMs: 0,
cacheScope: 'private',
tools: []
}
}
};
}
return {

View file

@ -22,9 +22,12 @@ import { sendStatelessRequest, JsonRpcResponse } from '../../connection';
export async function sendRpc(
serverUrl: string,
method: string,
params?: Record<string, unknown>
params?: Record<string, unknown>,
options?: { skipValidation?: boolean }
): Promise<JsonRpcResponse> {
const response = await sendStatelessRequest(serverUrl, method, params);
const response = await sendStatelessRequest(serverUrl, method, params, {
skipValidation: options?.skipValidation
});
if (!response.body) {
throw new Error(
`Expected a JSON-RPC response for ${method}, got HTTP ${response.status} (${response.contentType ?? 'no content-type'})`

View file

@ -1567,14 +1567,21 @@ and return a JSON-RPC error or a new InputRequiredResult.`;
const checks: ConformanceCheck[] = [];
try {
// Send inputResponses with invalid structure (number instead of object for the response)
const resp = await sendRpc(serverUrl, 'tools/call', {
name: 'test_input_required_result_elicitation',
arguments: {},
inputResponses: {
user_name: 12345 as unknown as Record<string, unknown>
}
});
// Send inputResponses with invalid structure (number instead of object
// for the response). Deliberately schema-invalid, so wire-schema
// validation is skipped for this call.
const resp = await sendRpc(
serverUrl,
'tools/call',
{
name: 'test_input_required_result_elicitation',
arguments: {},
inputResponses: {
user_name: 12345 as unknown as Record<string, unknown>
}
},
{ skipValidation: true }
);
const validateErrors: string[] = [];
@ -1599,12 +1606,18 @@ and return a JSON-RPC error or a new InputRequiredResult.`;
details: { result: resp.result, error: resp.error }
});
// Also test: send completely malformed inputResponses (null)
const resp2 = await sendRpc(serverUrl, 'tools/call', {
name: 'test_input_required_result_elicitation',
arguments: {},
inputResponses: null as unknown as Record<string, unknown>
});
// Also test: send completely malformed inputResponses (null).
// Deliberately schema-invalid; skip wire-schema validation.
const resp2 = await sendRpc(
serverUrl,
'tools/call',
{
name: 'test_input_required_result_elicitation',
arguments: {},
inputResponses: null as unknown as Record<string, unknown>
},
{ skipValidation: true }
);
const protocolErrors: string[] = [];

View file

@ -31,7 +31,11 @@ describe('ServerInitializeScenario', () => {
testContext(serverUrl)
);
expect(connectToServer).toHaveBeenCalledWith(serverUrl);
expect(connectToServer).toHaveBeenCalledWith(
serverUrl,
{},
testContext(serverUrl).specVersion
);
expect(closeMock).toHaveBeenCalled();
expect(fetchMock).toHaveBeenCalledWith(
serverUrl,

View file

@ -45,7 +45,7 @@ and validates session ID format if one is assigned.`;
const checks: ConformanceCheck[] = [];
try {
const connection = await connectToServer(serverUrl);
const connection = await connectToServer(serverUrl, {}, ctx.specVersion);
// The connection process already does initialization
// Check that we have a connected client

Some files were not shown because too many files have changed in this diff Show more