Hold on — this client led with `initialize`

The client you are testing started its session with an\ninitialize request. That is invalid in the new\nstateless protocol (2026-07-28 / SEP-2575) — there is no handshake;\nevery request carries the protocol version, client info, and capabilities\nitself.

You can continue with the test if you want: the gauntlet will serve this\nclient's classic flow and report what it is missing (see the\ndraft_readiness tool and the initialize result's instructions).\nBut know that leading with initialize will not work against\nstateless draft servers.

I understand — continue with the test

\n`);\n });\n\n app.get('/oauth/authorize/continue', (req, res) => {\n const q = req.query as Record;\n if (!q.redirect_uri) {\n res.status(400).json({\n error: 'invalid_request',\n error_description: 'redirect_uri required'\n });\n return;\n }\n const redirect = new URL(q.redirect_uri);\n const code = Buffer.from(\n JSON.stringify({\n consent: 'gauntlet-initialize',\n challenge: q.code_challenge ?? null\n })\n ).toString('base64url');\n redirect.searchParams.set('code', code);\n if (q.state !== undefined) redirect.searchParams.set('state', q.state);\n res.redirect(redirect.toString());\n });\n\n app.post('/oauth/token', (req, res) => {\n const grant = req.body as Record;\n let decoded: { consent?: string; challenge?: string | null };\n try {\n decoded = JSON.parse(\n Buffer.from(String(grant.code ?? ''), 'base64url').toString()\n );\n } catch {\n decoded = {};\n }\n if (\n grant.grant_type !== 'authorization_code' ||\n decoded.consent !== 'gauntlet-initialize'\n ) {\n res.status(400).json({ error: 'invalid_grant' });\n return;\n }\n if (decoded.challenge) {\n const expected = createHash('sha256')\n .update(String(grant.code_verifier ?? ''))\n .digest('base64url');\n if (expected !== decoded.challenge) {\n res.status(400).json({\n error: 'invalid_grant',\n error_description: 'PKCE verification failed'\n });\n return;\n }\n }\n res.json({\n access_token: CONSENT_TOKEN,\n token_type: 'Bearer',\n expires_in: 3600\n });\n });\n\n app.post('/', async (req: Request, res: Response) => {\n const body =\n req.body && !Array.isArray(req.body)\n ? (req.body as {\n method?: string;\n id?: unknown;\n params?: Record;\n })\n : {};\n const headerVersion = req.headers['mcp-protocol-version'];\n\n // This gauntlet tests the stateless draft protocol ONLY. A client\n // that falls back to a classic version (an `initialize` request or a\n // 2025-* version header) fails — but with a full inventory of what a\n // draft request must carry that this one didn't, so the failure is\n // also the upgrade guide. A request carrying draft `_meta` fields is\n // judged as draft no matter what its header claims (the disagreement\n // is reported, not routed around).\n const meta = (body.params?._meta ?? {}) as Record;\n const hasDraftMeta = Object.keys(meta).some((k) => k.startsWith(META_NS));\n const isClassicFallback =\n !hasDraftMeta &&\n ((body.method === 'initialize' && !isDraftVersion(headerVersion)) ||\n (headerVersion !== undefined &&\n CLASSIC_PROTOCOL_VERSIONS.includes(String(headerVersion))));\n\n // A consent token (minted by the initialize interstitial) means a\n // human read \"this client shouldn't do initialize\" and chose to\n // continue — serve the classic flow leniently from here on.\n const consented = req.headers.authorization === `Bearer ${CONSENT_TOKEN}`;\n if (isClassicFallback && consented) {\n const gaps = [...headerProblems(req), ...draftProblems(req, body)];\n check(\n this.checks,\n 'gauntlet-draft-readiness',\n 'Gauntlet: draft readiness (consented classic)',\n gaps.length === 0,\n 'Consented classic flow served leniently; draft gaps are advisory',\n { method: body.method, ...(gaps.length ? { gaps } : {}) },\n 'WARNING'\n );\n const server = createLenientClassicServer(this.checks, req, body);\n const transport = new StreamableHTTPServerTransport({\n sessionIdGenerator: undefined\n });\n await server.connect(transport);\n await transport.handleRequest(req, res, req.body);\n res.on('close', () => {\n void transport.close();\n void server.close();\n });\n return;\n }\n\n // initialize — and ONLY initialize — is gated on auth: the OAuth flow\n // lands a human on an HTML page explaining that the draft has no\n // initialize, with a \"continue anyway\" button. Clients without OAuth\n // get the same explanation in the 401 body. Recorded as WARNING so\n // the /x wrapper lets the 401 challenge through.\n if (isClassicFallback && body.method === 'initialize') {\n const explanation =\n 'This gauntlet tests the stateless draft protocol (2026-07-28): there is NO initialize handshake. Leading with initialize is invalid in the new spec. If your client supports OAuth, completing the authorization flow shows the full explanation and lets you continue testing the classic flow anyway; or point the client at this URL + /lenient for ungated advisory mode.';\n check(\n this.checks,\n 'gauntlet-transport-headers',\n 'Gauntlet: transport headers',\n false,\n 'Client led with initialize; challenged with the consent gate',\n { method: body.method, mode: 'initialize-consent-gate' },\n 'WARNING'\n );\n res\n .status(401)\n .set('WWW-Authenticate', `Bearer resource_metadata=\"${prmUrl()}\"`)\n .json({\n error: 'consent_required',\n explanation,\n problems: draftProblems(req, body)\n });\n return;\n }\n\n const problems = headerProblems(req);\n if (isClassicFallback) {\n problems.unshift(\n `Request declared classic protocol version '${String(headerVersion)}'. This gauntlet tests the stateless draft protocol only — declare 2026-07-28 (or DRAFT-2026-v1) in both the MCP-Protocol-Version header and _meta.`\n );\n }\n // Draft obligations are evaluated for EVERY request — for a classic\n // fallback this doubles as the itemized list of what was missing.\n problems.push(...draftProblems(req, body));\n\n check(\n this.checks,\n 'gauntlet-transport-headers',\n 'Gauntlet: transport headers',\n problems.length === 0,\n problems.length === 0\n ? 'Request carried conformant draft transport headers'\n : isClassicFallback\n ? 'Client fell back to a classic protocol version'\n : 'Request transport headers were not conformant',\n {\n method: body.method,\n mode: isClassicFallback ? 'classic-fallback-rejected' : 'draft',\n ...(problems.length ? { problems } : {})\n }\n );\n if (problems.length > 0) {\n res.status(400).json({\n error: 'conformance failure',\n mode: isClassicFallback ? 'classic-fallback-rejected' : 'draft',\n problems,\n hint: isClassicFallback\n ? 'Each listed problem is one thing a stateless draft request carries that this request did not. For advisory-only feedback that still serves classic flows, point the client at this URL + /lenient.'\n : 'Fix the listed transport problems and retry.'\n });\n return;\n }\n\n this.handleDraft(req, res, body);\n });\n\n // Lenient mode: old clients complete their flows (initialize included);\n // draft gaps are reported, not enforced. Tool failures stay isError\n // results, and gap checks are WARNINGs so the /x wrapper passes them.\n app.post('/lenient', async (req: Request, res: Response) => {\n const body =\n req.body && !Array.isArray(req.body)\n ? (req.body as {\n method?: string;\n id?: unknown;\n params?: Record;\n })\n : {};\n const headerVersion = req.headers['mcp-protocol-version'];\n const meta = (body.params?._meta ?? {}) as Record;\n const hasDraftMeta = Object.keys(meta).some((k) => k.startsWith(META_NS));\n\n const gaps = [...headerProblems(req), ...draftProblems(req, body)];\n check(\n this.checks,\n 'gauntlet-draft-readiness',\n 'Gauntlet: draft readiness (lenient)',\n gaps.length === 0,\n gaps.length === 0\n ? 'Request carries everything the stateless draft requires'\n : 'Request is missing draft obligations (advisory)',\n { method: body.method, ...(gaps.length ? { gaps } : {}) },\n 'WARNING'\n );\n\n if (!hasDraftMeta && !isDraftVersion(headerVersion)) {\n // Classic client: serve the real handshake so the flow completes;\n // the gap report rides in instructions and draft_readiness.\n const server = createLenientClassicServer(this.checks, req, body);\n const transport = new StreamableHTTPServerTransport({\n sessionIdGenerator: undefined\n });\n await server.connect(transport);\n await transport.handleRequest(req, res, req.body);\n res.on('close', () => {\n void transport.close();\n void server.close();\n });\n return;\n }\n\n this.handleDraft(req, res, body, true);\n });\n\n // Browsers get an explainer; programmatic GETs get the JSON hint.\n app.get('/', (req, res) => {\n if (!String(req.headers.accept ?? '').includes('text/html')) {\n res.status(405).json({\n error: 'stateless server: POST JSON-RPC to this URL',\n docs: 'open this URL in a browser for a full explanation'\n });\n return;\n }\n const base = getBaseUrl();\n res.type('html').send(`\nMCP Checker — 2026-07-28\n\n\n

MCP Checker — 2026-07-28

Conformance checker for the stateless draft MCP protocol\n(2026-07-28 / DRAFT-2026-v1) — and only that version. Other spec versions have their own checkers.

\n\n

How it works

This URL is the MCP endpoint. There is no run to mint and no results to\npoll: every request is judged on its own content. If your\nclient gets something wrong, the request itself fails with an explanation of\nwhat and why. If you can list the tools and call each one successfully, your\nclient is conformant for everything this server can observe.

POST ${escapeHtml(base)}            strict — stateless draft only\nPOST ${escapeHtml(base)}/lenient    advisory — classic clients complete, gaps reported

\n\n

What is checked

Every POST: Accept / Content-Type, MCP-Protocol-Version header,\n_meta declarations (io.modelcontextprotocol/protocolVersion, clientInfo,\nclientCapabilities — SEP-2575), and Mcp-Method/Mcp-Name routing headers (SEP-2243).
validate_arguments: argument construction against the inputSchema —\nstring, JSON number (not stringified), and a same-document $ref (SEP-2106).
mrtr_confirm: the multi-round-trip flow (SEP-2322) — answer the\nelicitation request and retry with requestState echoed unchanged. Listed only when\nyour _meta clientCapabilities declare {\"elicitation\": {}}; otherwise an\nelicitation_missing placeholder explains the gap.
draft_readiness (lenient/consented): itemized report of what the request\nthat carried it is missing relative to the draft.

\n\n

Old clients

Leading with initialize is invalid in the stateless draft, so the strict\nendpoint gates it behind an OAuth consent screen: your client's auth flow lands a human on a\npage explaining the situation, with a continue button. Continuing mints the bearer token\n${CONSENT_TOKEN} — the token is the message — and the classic flow is then served\nwith advisory feedback. No other request requires auth. Prefer zero friction? Use\n${escapeHtml(base)}/lenient.

\n\n

Try it

curl -X POST ${escapeHtml(base)} \\\\\n  -H 'content-type: application/json' \\\\\n  -H 'accept: application/json, text/event-stream' \\\\\n  -H 'mcp-protocol-version: 2026-07-28' \\\\\n  -H 'mcp-method: tools/list' \\\\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{\"_meta\":{\n    \"io.modelcontextprotocol/protocolVersion\":\"2026-07-28\",\n    \"io.modelcontextprotocol/clientInfo\":{\"name\":\"my-client\",\"version\":\"1.0\"},\n    \"io.modelcontextprotocol/clientCapabilities\":{}}}}'

\n`);\n });\n\n return app;\n }\n\n /**\n * Draft-2026 dispatch: no lifecycle, plain JSON responses, every request\n * self-contained. Transport/draft obligations were already enforced.\n */\n private handleDraft(\n req: Request,\n res: Response,\n body: { method?: string; id?: unknown; params?: Record },\n lenient = false\n ): void {\n const reply = (result: object) => {\n // 2026-07-28 makes resultType REQUIRED on every Result; default it here so\n // every path is covered, and let callers override (e.g. 'input_required').\n res.json({\n jsonrpc: '2.0',\n id: body.id ?? null,\n result: { resultType: 'complete', ...result }\n });\n };\n\n switch (body.method) {\n case 'server/discover':\n reply({\n ttlMs: 0,\n cacheScope: 'public',\n supportedVersions: DRAFT_VERSION_ALIASES,\n capabilities: { tools: {} },\n serverInfo: SERVER_INFO,\n instructions:\n 'Call every tool once with valid arguments. Each tool validates ' +\n 'the request that carried it; any error explains what your ' +\n 'client got wrong.'\n });\n return;\n\n case 'tools/list': {\n const meta = (body.params?._meta ?? {}) as Record;\n const tools = GAUNTLET_TOOLS.map(\n ({ name, description, inputSchema }) => ({\n name,\n description,\n inputSchema\n })\n );\n // MRTR is only part of the contract for clients that can answer\n // elicitation requests — gate the listing on the declared capability\n // each request carries. Clients without it get a placeholder that\n // makes the gap (and how to close it) discoverable.\n tools.push(\n declaresElicitation(meta) ? MRTR_TOOL : ELICITATION_MISSING_TOOL\n );\n if (lenient) tools.push(DRAFT_READINESS_TOOL);\n reply({ ttlMs: 0, cacheScope: 'public', tools });\n return;\n }\n\n case 'tools/call': {\n const params = (body.params ?? {}) as {\n name?: string;\n arguments?: Record;\n inputResponses?: Record;\n requestState?: string;\n _meta?: Record;\n };\n\n if (params.name === DRAFT_READINESS_TOOL.name && lenient) {\n reply({\n content: [{ type: 'text', text: readinessReport(req, body) }]\n });\n return;\n }\n\n if (params.name === MRTR_TOOL.name) {\n reply(this.runMrtr(params, lenient));\n return;\n }\n\n if (params.name === ELICITATION_MISSING_TOOL.name) {\n const declared = declaresElicitation(\n (params._meta ?? {}) as Record\n );\n this.checks.push({\n id: 'gauntlet-elicitation-missing',\n name: 'Gauntlet: elicitation capability not declared',\n description:\n 'Client called the elicitation_missing placeholder tool',\n status: 'INFO',\n timestamp: new Date().toISOString(),\n specReferences: [SPEC_TOOLS],\n details: { declared }\n });\n reply({\n content: [\n {\n type: 'text',\n text: declared\n ? 'CONFORMANCE NOTE [elicitation_missing]: this request DOES declare the elicitation capability — list tools again and you will see mrtr_confirm instead of this placeholder.'\n : 'CONFORMANCE NOTE [elicitation_missing]: your client has not declared the elicitation capability, so the MRTR (SEP-2322) tool mrtr_confirm is hidden. This is conformant — elicitation is optional — but to exercise the full gauntlet, implement elicitation and declare it in _meta ' +\n `${META_NS}clientCapabilities as {\"elicitation\": {}}; the full tool list will then appear.`\n }\n ]\n });\n return;\n }\n\n // MRTR plumbing must not leak onto unrelated calls (SEP-2322).\n if (\n params.inputResponses !== undefined ||\n params.requestState !== undefined\n ) {\n const detail =\n 'inputResponses/requestState MUST only be sent when retrying the ' +\n 'tool that returned input_required; they leaked onto ' +\n `'${params.name ?? '(none)'}'`;\n check(\n this.checks,\n 'gauntlet-mrtr-leak',\n 'Gauntlet: MRTR state leak',\n false,\n 'MRTR retry fields leaked onto an unrelated tool call',\n { detail }\n );\n reply({\n content: [\n {\n type: 'text',\n text: `CONFORMANCE FAIL [${params.name}]: ${detail}`\n }\n ],\n isError: true\n });\n return;\n }\n\n reply(\n runTool(this.checks, params.name ?? '', params.arguments ?? {}, req)\n );\n return;\n }\n\n case 'initialize':\n case 'ping':\n case 'logging/setLevel':\n // Removed from the stateless draft protocol entirely.\n res.status(404).json({\n jsonrpc: '2.0',\n id: body.id ?? null,\n error: {\n code: -32601,\n message: `Method not found: '${body.method}' does not exist in the stateless draft protocol (use server/discover, not initialize)`\n }\n });\n return;\n\n default:\n res.status(404).json({\n jsonrpc: '2.0',\n id: body.id ?? null,\n error: {\n code: -32601,\n message: `Method not found: '${body.method ?? '(none)'}'. Supported: server/discover, tools/list, tools/call`\n }\n });\n }\n }\n\n /**\n * Two-phase MRTR tool. First call → input_required with a self-contained\n * requestState. Retry → validate the echoed state and the elicitation\n * response shape, then complete.\n */\n private runMrtr(\n params: {\n inputResponses?: Record;\n requestState?: string;\n },\n lenient = false\n ): object {\n if (params.inputResponses === undefined) {\n // Round 1: ask for confirmation via elicitation.\n return {\n resultType: 'input_required',\n inputRequests: {\n confirm: {\n method: 'elicitation/create',\n params: {\n message: 'Confirm the MRTR round-trip by answering this.',\n requestedSchema: {\n type: 'object',\n properties: { confirmed: { type: 'boolean' } },\n required: ['confirmed']\n }\n }\n }\n },\n requestState: encodeMrtrState()\n };\n }\n\n // Round 2: judge the retry on its own content.\n const problems: string[] = [];\n if (params.requestState === undefined) {\n problems.push(\n 'requestState MUST be echoed back unchanged on the retry (SEP-2322)'\n );\n } else if (!decodeMrtrState(params.requestState)) {\n problems.push(\n `requestState was altered — it MUST be echoed back byte-exact; got '${params.requestState.slice(0, 60)}'`\n );\n }\n const confirm = params.inputResponses.confirm as\n | { action?: unknown; content?: { confirmed?: unknown } }\n | undefined;\n if (!confirm || typeof confirm !== 'object') {\n problems.push(\n \"inputResponses MUST be keyed by the inputRequests key ('confirm')\"\n );\n } else {\n if (\n confirm.action !== 'accept' &&\n confirm.action !== 'decline' &&\n confirm.action !== 'cancel'\n ) {\n problems.push(\n `elicitation response action MUST be accept/decline/cancel; got ${JSON.stringify(confirm.action)}`\n );\n }\n if (\n confirm.action === 'accept' &&\n typeof confirm.content?.confirmed !== 'boolean'\n ) {\n problems.push(\n `accepted elicitation content MUST match requestedSchema ({confirmed: boolean}); got ${JSON.stringify(confirm.content)}`\n );\n }\n }\n\n const ok = problems.length === 0;\n const detail = ok\n ? `requestState echoed intact; elicitation response valid (action=${String((params.inputResponses.confirm as { action?: unknown })?.action)})`\n : problems.join('; ');\n check(\n this.checks,\n 'gauntlet-mrtr_confirm',\n 'Gauntlet: mrtr_confirm',\n ok,\n ok\n ? 'Client completed the MRTR round-trip conformantly'\n : 'Client MRTR retry was not conformant',\n { detail },\n lenient ? 'WARNING' : 'FAILURE'\n );\n if (!ok) {\n return {\n content: [\n { type: 'text', text: `CONFORMANCE FAIL [mrtr_confirm]: ${detail}` }\n ],\n isError: true\n };\n }\n return {\n content: [\n { type: 'text', text: `CONFORMANCE OK [mrtr_confirm]: ${detail}` }\n ]\n };\n }\n\n getChecks(): ConformanceCheck[] {\n return this.checks;\n }\n}\n",[],[150,501,833,835],"6d2c5e49-d807-4057-b274-da2410f92eb9","sse-retry.ts","dd596744-ad13-11f1-9d57-1607ee4eb77e",354,["D",1789367828884],"import type { ScenarioContext } from '../../mock-server/index.ts';\n/**\n * SSE Retry conformance test scenarios for MCP clients (SEP-1699)\n *\n * Tests that clients properly respect the SSE retry field by:\n * - Waiting the specified milliseconds before reconnecting\n * - Sending Last-Event-ID header on reconnection\n * - Treating graceful stream closure as reconnectable\n */\n\nimport http from 'node:http';\nimport {\n Scenario,\n ScenarioUrls,\n ConformanceCheck,\n DRAFT_PROTOCOL_VERSION,\n RequestListener\n} from '../../types.ts';\n\n/** A check's timestamp in ms since the epoch, or null. */\nfunction wallClock(check: ConformanceCheck | undefined): number | null {\n const t = check ? Date.parse(check.timestamp) : NaN;\n return Number.isNaN(t) ? null : t;\n}\n\nexport class SSERetryScenario implements Scenario {\n name = 'sse-retry';\n readonly source = {\n introducedIn: '2025-11-25',\n removedIn: DRAFT_PROTOCOL_VERSION\n } as const;\n description =\n 'Tests that client respects SSE retry field timing and reconnects properly (SEP-1699)';\n /**\n * On a serverless host the GET that resumes the tool call can reach a\n * different process from the tool call itself, so which call is pending,\n * the next event id and the GET count are read from the log, which the\n * hosted server brings up to date before every request. In one process\n * the log says what memory does.\n */\n readonly answersFromLog = true;\n\n private server: http.Server | null = null;\n private checks: ConformanceCheck[] = [];\n private port: number = 0;\n\n // Timing tracking\n private toolStreamCloseTime: number | null = null;\n private getReconnectionTime: number | null = null;\n private getConnectionCount: number = 0;\n private lastEventIds: (string | undefined)[] = [];\n private retryValue: number = 500; // 500ms\n private eventIdCounter: number = 0;\n private sessionId: string = `session-${Date.now()}`;\n\n // Pending tool call to respond to after reconnection\n private pendingToolCallId: number | string | null = null;\n private getResponseStream: http.ServerResponse | null = null;\n\n // Tolerance for timing validation (early side only; lateness is not gated)\n private readonly EARLY_TOLERANCE = 50; // Allow 50ms early for scheduler variance\n\n handler(_getBaseUrl: () => string): RequestListener {\n this.checks = [];\n this.toolStreamCloseTime = null;\n this.getReconnectionTime = null;\n this.getConnectionCount = 0;\n this.lastEventIds = [];\n this.eventIdCounter = 0;\n this.sessionId = `session-${Date.now()}`;\n this.pendingToolCallId = null;\n this.getResponseStream = null;\n return (req, res) => this.handleRequest(req, res);\n }\n\n async start(_ctx?: ScenarioContext): Promise {\n const listener = this.handler(() => `http://localhost:${this.port}`);\n return new Promise((resolve, reject) => {\n this.server = http.createServer(listener);\n this.server.on('error', reject);\n this.server.listen(0, () => {\n const address = this.server!.address();\n if (address && typeof address === 'object') {\n this.port = address.port;\n resolve({\n serverUrl: `http://localhost:${this.port}`\n });\n } else {\n reject(new Error('Failed to get server address'));\n }\n });\n });\n }\n\n async stop(): Promise {\n return new Promise((resolve, reject) => {\n if (this.server) {\n this.server.close((err) => {\n if (err) {\n reject(err);\n } else {\n this.server = null;\n resolve();\n }\n });\n } else {\n resolve();\n }\n });\n }\n\n getChecks(): ConformanceCheck[] {\n // Generate checks based on observed behavior\n this.generateChecks();\n return this.checks;\n }\n\n private handleRequest(\n req: http.IncomingMessage,\n res: http.ServerResponse\n ): void {\n // The session id the client was given, whichever process minted it.\n const sid = req.headers['mcp-session-id'];\n if (typeof sid === 'string' && sid) this.sessionId = sid;\n\n if (req.method === 'GET') {\n // Track GET reconnection timing and Last-Event-ID\n this.getConnectionCount =\n Math.max(this.getConnectionCount, this.getsInLog().length) + 1;\n this.getReconnectionTime = performance.now();\n\n const lastEventId = req.headers['last-event-id'] as string | undefined;\n const description = lastEventId\n ? `Received GET request for ${req.url} (Last-Event-ID: ${lastEventId})`\n : `Received GET request for ${req.url}`;\n this.checks.push({\n id: 'incoming-request',\n name: 'IncomingRequest',\n description,\n status: 'INFO',\n timestamp: new Date().toISOString(),\n details: {\n method: 'GET',\n url: req.url,\n headers: req.headers,\n connectionCount: this.getConnectionCount\n }\n });\n\n if (lastEventId) {\n this.lastEventIds.push(lastEventId);\n }\n\n // Handle GET SSE stream request (reconnection)\n this.handleGetSSEStream(req, res);\n } else if (req.method === 'POST') {\n // Handle POST JSON-RPC requests\n this.handlePostRequest(req, res);\n } else {\n res.writeHead(405);\n res.end('Method Not Allowed');\n }\n }\n\n private handleGetSSEStream(\n _req: http.IncomingMessage,\n res: http.ServerResponse\n ): void {\n // Set SSE headers\n res.writeHead(200, {\n 'Content-Type': 'text/event-stream',\n 'Cache-Control': 'no-cache',\n Connection: 'keep-alive',\n 'mcp-session-id': this.sessionId\n });\n\n // Generate event ID\n const eventId = this.nextEventId();\n\n // Send priming event with ID and retry field\n const primingContent = `id: ${eventId}\\nretry: ${this.retryValue}\\ndata: \\n\\n`;\n res.write(primingContent);\n\n this.checks.push({\n id: 'outgoing-sse-event',\n name: 'OutgoingSseEvent',\n description: `Sent SSE priming event on GET stream (id: ${eventId}, retry: ${this.retryValue}ms)`,\n status: 'INFO',\n timestamp: new Date().toISOString(),\n details: {\n eventId,\n retryMs: this.retryValue,\n eventType: 'priming',\n raw: primingContent\n }\n });\n\n // Store the GET stream to send pending tool response\n this.getResponseStream = res;\n\n // If we have a pending tool call, send the response now. The log says\n // which, so a process that did not see the tool call still answers it\n // and one that did does not answer it twice.\n const pendingId = this.pendingFromLog();\n if (pendingId !== null) {\n const toolResponse = {\n jsonrpc: '2.0',\n id: pendingId,\n result: {\n content: [\n {\n type: 'text',\n text: 'Reconnection test completed successfully'\n }\n ]\n }\n };\n\n const responseEventId = this.nextEventId();\n const responseContent = `event: message\\nid: ${responseEventId}\\ndata: ${JSON.stringify(toolResponse)}\\n\\n`;\n res.write(responseContent);\n\n this.checks.push({\n id: 'outgoing-sse-event',\n name: 'OutgoingSseEvent',\n description: `Sent tool response on GET stream after reconnection (id: ${responseEventId})`,\n status: 'INFO',\n timestamp: new Date().toISOString(),\n details: {\n eventId: responseEventId,\n eventType: 'message',\n jsonrpcId: pendingId,\n body: toolResponse,\n raw: responseContent\n }\n });\n\n this.pendingToolCallId = null;\n }\n }\n\n /** GET requests in the log, in order. */\n private getsInLog(): ConformanceCheck[] {\n return this.checks.filter(\n (c) =>\n c.id === 'incoming-request' &&\n (c.details as { method?: unknown } | undefined)?.method === 'GET'\n );\n }\n\n /** The id of the last tools/call not yet answered on a GET stream. */\n private pendingFromLog(): number | string | null {\n let pending: number | string | null = null;\n for (const c of this.checks) {\n const d = (c.details ?? {}) as Record;\n if (c.id === 'incoming-request' && d.jsonrpcMethod === 'tools/call') {\n pending = (d.jsonrpcId as number | string | undefined) ?? null;\n } else if (\n c.id === 'outgoing-sse-event' &&\n d.eventType === 'message' &&\n d.jsonrpcId === pending\n ) {\n pending = null;\n }\n }\n return pending;\n }\n\n /** The next `event-N`, past every id this cell has sent, here or elsewhere. */\n private nextEventId(): string {\n let highest = this.eventIdCounter;\n for (const c of this.checks) {\n const id = (c.details as { eventId?: unknown } | undefined)?.eventId;\n const n =\n c.id === 'outgoing-sse-event' && typeof id === 'string'\n ? Number(id.replace(/^event-/, ''))\n : NaN;\n if (Number.isInteger(n) && n > highest) highest = n;\n }\n this.eventIdCounter = highest + 1;\n return `event-${this.eventIdCounter}`;\n }\n\n private handlePostRequest(\n req: http.IncomingMessage,\n res: http.ServerResponse\n ): void {\n let body = '';\n\n req.on('data', (chunk) => {\n body += chunk.toString();\n });\n\n req.on('end', () => {\n try {\n const request = JSON.parse(body);\n\n this.checks.push({\n id: 'incoming-request',\n name: 'IncomingRequest',\n description: `Received POST request for ${req.url} (method: ${request.method})`,\n status: 'INFO',\n timestamp: new Date().toISOString(),\n details: {\n method: 'POST',\n url: req.url,\n jsonrpcMethod: request.method,\n jsonrpcId: request.id\n }\n });\n\n if (request.method === 'initialize') {\n this.handleInitialize(req, res, request);\n } else if (request.method === 'tools/list') {\n this.handleToolsList(res, request);\n } else if (request.method === 'tools/call') {\n this.handleToolsCall(res, request);\n } else if (request.id === undefined) {\n // Notifications (no id) - return 202 Accepted\n res.writeHead(202);\n res.end();\n } else {\n // For other requests, send a simple JSON response\n res.writeHead(200, {\n 'Content-Type': 'application/json',\n 'mcp-session-id': this.sessionId\n });\n res.end(\n JSON.stringify({\n jsonrpc: '2.0',\n id: request.id,\n result: {}\n })\n );\n }\n } catch (error) {\n res.writeHead(400, { 'Content-Type': 'application/json' });\n res.end(\n JSON.stringify({\n jsonrpc: '2.0',\n error: {\n code: -32700,\n message: `Parse error: ${error}`\n }\n })\n );\n }\n });\n }\n\n private handleInitialize(\n _req: http.IncomingMessage,\n res: http.ServerResponse,\n request: any\n ): void {\n res.writeHead(200, {\n 'Content-Type': 'application/json',\n 'mcp-session-id': this.sessionId\n });\n\n const response = {\n jsonrpc: '2.0',\n id: request.id,\n result: {\n // The retry MUST under test was introduced in 2025-11-25 (SEP-1699)\n protocolVersion: '2025-11-25',\n serverInfo: {\n name: 'sse-retry-test-server',\n version: '1.0.0'\n },\n capabilities: {\n tools: {}\n }\n }\n };\n\n res.end(JSON.stringify(response));\n\n this.checks.push({\n id: 'outgoing-response',\n name: 'OutgoingResponse',\n description: `Sent initialize response`,\n status: 'INFO',\n timestamp: new Date().toISOString(),\n details: {\n jsonrpcId: request.id,\n body: response\n }\n });\n }\n\n private handleToolsList(res: http.ServerResponse, request: any): void {\n res.writeHead(200, {\n 'Content-Type': 'application/json',\n 'mcp-session-id': this.sessionId\n });\n\n const response = {\n jsonrpc: '2.0',\n id: request.id,\n result: {\n tools: [\n {\n name: 'test_reconnection',\n description:\n 'A tool that triggers SSE stream closure to test client reconnection behavior',\n inputSchema: {\n type: 'object',\n properties: {},\n required: []\n }\n }\n ]\n }\n };\n\n res.end(JSON.stringify(response));\n\n this.checks.push({\n id: 'outgoing-response',\n name: 'OutgoingResponse',\n description: `Sent tools/list response`,\n status: 'INFO',\n timestamp: new Date().toISOString(),\n details: {\n jsonrpcId: request.id,\n body: response\n }\n });\n }\n\n private handleToolsCall(res: http.ServerResponse, request: any): void {\n // Store the request ID so we can respond after reconnection\n this.pendingToolCallId = request.id;\n\n // Start SSE stream\n res.writeHead(200, {\n 'Content-Type': 'text/event-stream',\n 'Cache-Control': 'no-cache',\n Connection: 'keep-alive',\n 'mcp-session-id': this.sessionId\n });\n\n // Send priming event with retry field\n const primingEventId = this.nextEventId();\n const primingContent = `id: ${primingEventId}\\nretry: ${this.retryValue}\\ndata: \\n\\n`;\n res.write(primingContent);\n\n this.checks.push({\n id: 'outgoing-sse-event',\n name: 'OutgoingSseEvent',\n description: `Sent SSE priming event for tools/call (id: ${primingEventId}, retry: ${this.retryValue}ms)`,\n status: 'INFO',\n timestamp: new Date().toISOString(),\n details: {\n eventId: primingEventId,\n retryMs: this.retryValue,\n eventType: 'priming',\n raw: primingContent\n }\n });\n\n // Close the stream after a short delay to trigger reconnection\n setTimeout(() => {\n this.toolStreamCloseTime = performance.now();\n this.checks.push({\n id: 'outgoing-stream-close',\n name: 'OutgoingStreamClose',\n description:\n 'Closed tools/call SSE stream to trigger client reconnection',\n status: 'INFO',\n timestamp: new Date().toISOString(),\n details: {\n retryMs: this.retryValue,\n pendingToolCallId: this.pendingToolCallId\n }\n });\n res.end();\n }, 50);\n }\n\n private generateChecks(): void {\n // A fresh instance judging a merged log (the hosted server, where the\n // tool call and the reconnect may have reached different processes)\n // has nothing in memory: it reads the same facts from the log, timing\n // from the checks' wall-clock timestamps.\n const gets = this.getsInLog();\n const getConnectionCount = Math.max(this.getConnectionCount, gets.length);\n let closeAt = this.toolStreamCloseTime;\n let reconnectAt = this.getReconnectionTime;\n if (closeAt === null || reconnectAt === null) {\n const close = this.checks.filter((c) => c.id === 'outgoing-stream-close');\n closeAt = wallClock(close[close.length - 1]);\n reconnectAt = wallClock(gets[gets.length - 1]);\n }\n const lastEventIds = this.lastEventIds.length\n ? this.lastEventIds\n : gets\n .map(\n (c) =>\n (c.details as { headers?: Record } | undefined)\n ?.headers?.['last-event-id']\n )\n .filter((v): v is string => typeof v === 'string');\n\n // Check 1: Client should have reconnected via GET after tool call stream close\n if (getConnectionCount < 1) {\n this.checks.push({\n id: 'client-sse-graceful-reconnect',\n name: 'ClientGracefulReconnect',\n description:\n 'Client reconnects via GET after SSE stream is closed gracefully',\n status: 'FAILURE',\n timestamp: new Date().toISOString(),\n errorMessage: `Client did not attempt GET reconnection after stream closure. Client should treat graceful stream close as reconnectable.`,\n specReferences: [\n {\n id: 'SEP-1699',\n url: 'https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1699'\n }\n ],\n details: {\n getConnectionCount,\n toolStreamCloseTime: closeAt,\n retryValue: this.retryValue\n }\n });\n return;\n }\n\n // Client did reconnect - SUCCESS for graceful reconnection\n this.checks.push({\n id: 'client-sse-graceful-reconnect',\n name: 'ClientGracefulReconnect',\n description:\n 'Client reconnects via GET after SSE stream is closed gracefully',\n status: 'SUCCESS',\n timestamp: new Date().toISOString(),\n specReferences: [\n {\n id: 'SEP-1699',\n url: 'https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1699'\n }\n ],\n details: {\n getConnectionCount\n }\n });\n\n // Check 2: Client MUST respect retry field timing\n if (closeAt !== null && reconnectAt !== null) {\n const actualDelay = reconnectAt - closeAt;\n const minExpected = this.retryValue - this.EARLY_TOLERANCE;\n\n // The retry MUST is a lower bound (\"waiting the given number of\n // milliseconds before attempting to reconnect\"), so only an early\n // reconnect fails; lateness is environment latency and is not gated.\n const tooEarly = actualDelay < minExpected;\n\n this.checks.push({\n id: 'client-sse-retry-timing',\n name: 'ClientRespectsRetryField',\n description:\n 'Client MUST respect the retry field, waiting the given number of milliseconds before attempting to reconnect',\n status: tooEarly ? 'FAILURE' : 'SUCCESS',\n timestamp: new Date().toISOString(),\n errorMessage: tooEarly\n ? `Client reconnected too early (${actualDelay.toFixed(0)}ms instead of ${this.retryValue}ms). Client MUST respect the retry field and wait the specified time.`\n : undefined,\n specReferences: [\n {\n id: 'SEP-1699',\n url: 'https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1699'\n }\n ],\n details: {\n expectedRetryMs: this.retryValue,\n actualDelayMs: Math.round(actualDelay),\n minAcceptableMs: minExpected,\n earlyToleranceMs: this.EARLY_TOLERANCE,\n getConnectionCount\n }\n });\n } else {\n this.checks.push({\n id: 'client-sse-retry-timing',\n name: 'ClientRespectsRetryField',\n description: 'Client MUST respect the retry field timing',\n status: 'INFO',\n timestamp: new Date().toISOString(),\n errorMessage:\n 'Could not measure timing - tool stream close time or GET reconnection time not recorded',\n specReferences: [\n {\n id: 'SEP-1699',\n url: 'https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1699'\n }\n ],\n details: {\n toolStreamCloseTime: closeAt,\n getReconnectionTime: reconnectAt\n }\n });\n }\n\n // Check 3: Client SHOULD send Last-Event-ID header on reconnection\n const hasLastEventId =\n lastEventIds.length > 0 && lastEventIds[0] !== undefined;\n\n this.checks.push({\n id: 'client-sse-last-event-id',\n name: 'ClientSendsLastEventId',\n description:\n 'Client SHOULD send Last-Event-ID header on reconnection for resumability',\n status: hasLastEventId ? 'SUCCESS' : 'WARNING',\n timestamp: new Date().toISOString(),\n specReferences: [\n {\n id: 'SEP-1699',\n url: 'https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1699'\n }\n ],\n details: {\n hasLastEventId,\n lastEventIds,\n getConnectionCount\n },\n errorMessage: !hasLastEventId\n ? 'Client did not send Last-Event-ID header on reconnection. This is a SHOULD requirement for resumability.'\n : undefined\n });\n }\n}\n",[],[150,501,833,843],"3ea4afb8-4b19-4ce1-9af1-359d1e4c1fae","request-metadata.ts","dd02e8ec-ad13-11f1-bed6-1607ee4eb77e",326,["D",1789346116409],6,"import { withRequiredDraftResultFields } from '../../mock-server/stateless.ts';\nimport http from 'node:http';\nimport {\n HandlerScenario,\n RequestListener,\n ConformanceCheck,\n CheckStatus,\n DRAFT_PROTOCOL_VERSION,\n SpecReference\n} from '../../types.ts';\n\n/**\n * Severity ranking used to latch per-id check results: a single\n * non-conformant request is a violation even if later requests are\n * conformant, so a later better status must never overwrite a worse one.\n */\nconst STATUS_SEVERITY: Record = {\n FAILURE: 3,\n WARNING: 2,\n SUCCESS: 1,\n INFO: 1,\n SKIPPED: 0\n};\n\n/**\n * Every check ID this scenario can emit. Declared-but-unemitted checks are\n * backfilled as FAILURE by getChecks(), so the emitted ID set is the same for\n * every client. The positive-path test asserts this list is exact.\n */\nexport const DECLARED_CHECK_IDS = [\n 'sep-2575-http-client-sends-version-header',\n 'sep-2575-client-populates-meta',\n 'sep-2575-client-sends-client-info',\n 'sep-2575-http-version-header-matches-meta',\n 'sep-2575-client-declares-roots-capability',\n 'sep-2575-client-declares-sampling-capability',\n 'sep-2575-client-declares-elicitation-capability',\n 'sep-2575-client-retry-supported-version'\n] as const;\n\n/**\n * Recorded the moment the simulated version rejection is issued, and only\n * then — so its presence in the log is the record that the rejection\n * happened. Deriving that from the log rather than from an instance flag is\n * what lets a run split across processes (the hosted server seeds a cold\n * process with the persisted log) reject the client's first request once,\n * not once per process.\n */\nconst RETRY_CHECK_ID = 'sep-2575-client-retry-supported-version';\n\n/** Where 2026-07-28 defines each optional client capability. */\nconst CAPABILITY_REFERENCES: Record<\n 'roots' | 'sampling' | 'elicitation',\n SpecReference\n> = {\n roots: {\n id: 'SEP-2575',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/client/roots#capabilities'\n },\n sampling: {\n id: 'SEP-2575',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/client/sampling#capabilities'\n },\n elicitation: {\n id: 'SEP-2575',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation#capabilities'\n }\n};\n\nexport class RequestMetadataScenario extends HandlerScenario {\n name = 'request-metadata';\n readonly source = { introducedIn: DRAFT_PROTOCOL_VERSION } as const;\n description =\n 'Per-request _meta and MCP-Protocol-Version header obligations (SEP-2575)';\n /** A discover can be the request that draws the run's one rejection. */\n readonly discoverReadsHistory = true;\n\n private checks: ConformanceCheck[] = [];\n private requestsObserved = 0;\n\n handler(_getBaseUrl: () => string): RequestListener {\n this.checks = [];\n this.requestsObserved = 0;\n return (req, res) => this.handleRequest(req, res);\n }\n\n /** Whether this run has already issued its one simulated rejection. */\n private hasSimulatedRejection(): boolean {\n return this.checks.some((c) => c.id === RETRY_CHECK_ID);\n }\n\n getChecks(): ConformanceCheck[] {\n this.collapseDuplicateIds();\n // Declared but never emitted -> FAILURE. A check that is legitimately not\n // applicable must be emitted as SKIPPED explicitly to avoid this.\n for (const id of DECLARED_CHECK_IDS) {\n if (!this.checks.some((c) => c.id === id)) {\n this.checks.push({\n id,\n name: 'NotObserved',\n description: `Declared check ${id} was never emitted`,\n status: 'FAILURE',\n errorMessage:\n this.requestsObserved === 0\n ? 'Check was not observed: the client never sent a request to the scenario server (no handler registered for this scenario?)'\n : 'Check was not observed: no request exercised it',\n timestamp: new Date().toISOString(),\n specReferences: [\n {\n id: 'SEP-2575',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic#_meta'\n }\n ],\n details: { observed: false, requestsObserved: this.requestsObserved }\n });\n }\n }\n return this.checks;\n }\n\n /**\n * A log merged from several processes (see src/hosted/session.ts) can carry\n * one id more than once, one per process that observed it. Collapse each\n * id the way addOrUpdateCheck() would have as the requests arrived: the\n * worst status wins. The retry check is the exception — it is rewritten by\n * every retry the client makes, so its latest observation supersedes.\n */\n private collapseDuplicateIds(): void {\n if (new Set(this.checks.map((c) => c.id)).size === this.checks.length)\n return;\n const byId = new Map();\n for (const check of this.checks) {\n const kept = byId.get(check.id);\n if (\n !kept ||\n check.id === RETRY_CHECK_ID ||\n STATUS_SEVERITY[check.status] >= STATUS_SEVERITY[kept.status]\n ) {\n byId.set(check.id, check);\n }\n }\n this.checks = Array.from(byId.values());\n }\n\n private addOrUpdateCheck(check: ConformanceCheck): void {\n const index = this.checks.findIndex((c) => c.id === check.id);\n if (index === -1) {\n this.checks.push(check);\n return;\n }\n // Keep the worst status observed for this id (FAILURE > WARNING > SUCCESS\n // > SKIPPED): an equal-or-worse result replaces the stored check (so its\n // details stay fresh), but a better result must not erase a violation\n // recorded from an earlier request.\n const existing = this.checks[index];\n if (STATUS_SEVERITY[check.status] >= STATUS_SEVERITY[existing.status]) {\n this.checks[index] = check;\n }\n }\n\n private handleRequest(\n req: http.IncomingMessage,\n res: http.ServerResponse\n ): void {\n // This scenario only evaluates the metadata attached to POST requests.\n // Clients may probe a Streamable HTTP endpoint with an empty-body GET\n // before sending MCP requests, so reject unsupported methods before\n // attempting to parse a JSON-RPC body.\n if (req.method !== 'POST') {\n res.writeHead(405, { Allow: 'POST' });\n res.end('Method Not Allowed');\n return;\n }\n\n let body = '';\n req.on('data', (chunk) => {\n body += chunk.toString();\n });\n req.on('end', () => {\n let request;\n try {\n request = JSON.parse(body);\n } catch (error) {\n res.writeHead(400, { 'Content-Type': 'application/json' });\n res.end(\n JSON.stringify({\n jsonrpc: '2.0',\n id: null,\n error: {\n code: -32700,\n message: `Parse error: ${String(error)}`\n }\n })\n );\n return;\n }\n\n // initialize is the dated revisions' handshake, not a 2026-07-28\n // request: it carries no per-request _meta to judge, and it is not the\n // client's first choice of version for the simulated rejection below.\n // Answered as a modern-only server should, naming its version\n // (2026-07-28 basic/versioning), and otherwise left out of the run.\n if (request?.method === 'initialize') {\n res.writeHead(400, { 'Content-Type': 'application/json' });\n res.end(\n JSON.stringify({\n jsonrpc: '2.0',\n id: request.id ?? null,\n error: {\n code: -32022,\n message: 'Unsupported protocol version',\n data: {\n supported: [DRAFT_PROTOCOL_VERSION],\n requested: String(\n request.params?.protocolVersion ??\n req.headers['mcp-protocol-version'] ??\n ''\n )\n }\n }\n })\n );\n return;\n }\n\n this.requestsObserved++;\n\n // Extract version and headers\n const meta = request.params?._meta;\n const metaVersion = meta?.['io.modelcontextprotocol/protocolVersion'];\n const headerVersion = req.headers['mcp-protocol-version'];\n\n // 1. \"Every POST request to the MCP endpoint MUST include an\n // MCP-Protocol-Version header.\" — unconditional, so this fires for\n // server/discover too.\n this.addOrUpdateCheck({\n id: 'sep-2575-http-client-sends-version-header',\n name: 'ClientSendsVersionHeader',\n description: 'Client sends MCP-Protocol-Version header on every POST',\n status: headerVersion !== undefined ? 'SUCCESS' : 'FAILURE',\n timestamp: new Date().toISOString(),\n specReferences: [\n {\n id: 'SEP-2575',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http#protocol-version-header'\n }\n ],\n details: { method: request.method, headerVersion }\n });\n\n // 2. \"Every client request MUST include the following\n // io.modelcontextprotocol/* fields in _meta: protocolVersion,\n // clientCapabilities.\" clientInfo is a SHOULD since spec PR #3002 and\n // is tracked by its own check below, so requirement levels never blend\n // in one check id.\n const hasClientInfo = meta?.['io.modelcontextprotocol/clientInfo'];\n const hasCapabilities =\n meta?.['io.modelcontextprotocol/clientCapabilities'];\n const metaIsValid = metaVersion && hasCapabilities;\n\n this.addOrUpdateCheck({\n id: 'sep-2575-client-populates-meta',\n name: 'ClientPopulatesMeta',\n description:\n 'Client populates _meta on every request with the required fields (protocolVersion, clientCapabilities)',\n status: metaIsValid ? 'SUCCESS' : 'FAILURE',\n timestamp: new Date().toISOString(),\n specReferences: [\n {\n id: 'SEP-2575',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic#_meta'\n }\n ],\n details: { method: request.method, meta }\n });\n\n // 2b. clientInfo SHOULD (spec PR #3002): absence is a WARNING, never a\n // FAILURE — a dedicated id so adoption is trackable on its own.\n this.addOrUpdateCheck({\n id: 'sep-2575-client-sends-client-info',\n name: 'ClientSendsClientInfo',\n description:\n \"Client SHOULD include io.modelcontextprotocol/clientInfo in every request's _meta (spec PR #3002)\",\n status: hasClientInfo ? 'SUCCESS' : 'WARNING',\n timestamp: new Date().toISOString(),\n specReferences: [\n {\n id: 'SEP-2575',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic#_meta'\n }\n ],\n details: { method: request.method, meta }\n });\n\n // 3. \"The header value MUST match the io.modelcontextprotocol/protocolVersion\n // field carried in the request body's _meta.\" Only comparable when both\n // are present; absence is already covered by the two checks above, so\n // emit SKIPPED rather than falling through to the declared-check failure.\n const bothVersionsPresent =\n headerVersion !== undefined && metaVersion !== undefined;\n this.addOrUpdateCheck({\n id: 'sep-2575-http-version-header-matches-meta',\n name: 'ClientVersionHeaderMatchesMeta',\n description:\n 'MCP-Protocol-Version header matches _meta.protocolVersion',\n status: !bothVersionsPresent\n ? 'SKIPPED'\n : headerVersion === metaVersion\n ? 'SUCCESS'\n : 'FAILURE',\n timestamp: new Date().toISOString(),\n specReferences: [\n {\n id: 'SEP-2575',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http#protocol-version-header'\n }\n ],\n details: { headerVersion, metaVersion }\n });\n\n // 4. Optional client capabilities conditional verification\n const capabilities = meta?.['io.modelcontextprotocol/clientCapabilities'];\n const checkOptionalCapability = (\n capabilityName: keyof typeof CAPABILITY_REFERENCES,\n checkId: string,\n checkName: string\n ) => {\n let status: 'SUCCESS' | 'FAILURE' | 'SKIPPED' = 'SKIPPED';\n if (capabilities && capabilityName in capabilities) {\n const val = capabilities[capabilityName];\n const isValidObject =\n typeof val === 'object' && val !== null && !Array.isArray(val);\n status = isValidObject ? 'SUCCESS' : 'FAILURE';\n }\n this.addOrUpdateCheck({\n id: checkId,\n name: checkName,\n description: `Client declares valid ${capabilityName} capability if present`,\n status,\n timestamp: new Date().toISOString(),\n specReferences: [CAPABILITY_REFERENCES[capabilityName]],\n details: { capabilityValue: capabilities?.[capabilityName] }\n });\n };\n\n checkOptionalCapability(\n 'roots',\n 'sep-2575-client-declares-roots-capability',\n 'ClientDeclaresRootsCapability'\n );\n checkOptionalCapability(\n 'sampling',\n 'sep-2575-client-declares-sampling-capability',\n 'ClientDeclaresSamplingCapability'\n );\n checkOptionalCapability(\n 'elicitation',\n 'sep-2575-client-declares-elicitation-capability',\n 'ClientDeclaresElicitationCapability'\n );\n\n // 5. Simulated Version Negotiation Retry Check — issued once per run;\n // the retry check recorded here is the record that it was (see\n // RETRY_CHECK_ID).\n if (!this.hasSimulatedRejection()) {\n this.addOrUpdateCheck({\n id: RETRY_CHECK_ID,\n name: 'ClientRetrySupportedVersion',\n description:\n 'Client retries with a supported version when first choice is rejected',\n status: 'WARNING',\n timestamp: new Date().toISOString(),\n specReferences: [\n {\n id: 'SEP-2575',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning#protocol-version-negotiation'\n }\n ],\n details: { headerVersion }\n });\n\n res.writeHead(400, { 'Content-Type': 'application/json' });\n res.end(\n JSON.stringify({\n jsonrpc: '2.0',\n id: request.id ?? null,\n error: {\n // UnsupportedProtocolVersionError per the draft schema.\n code: -32022,\n message: 'Unsupported protocol version',\n data: {\n supported: [DRAFT_PROTOCOL_VERSION],\n requested: String(headerVersion ?? metaVersion ?? '')\n }\n }\n })\n );\n return;\n }\n\n const retryCheck = this.checks.find((c) => c.id === RETRY_CHECK_ID);\n if (retryCheck) {\n if (\n headerVersion === DRAFT_PROTOCOL_VERSION &&\n metaVersion === DRAFT_PROTOCOL_VERSION\n ) {\n retryCheck.status = 'SUCCESS';\n } else {\n retryCheck.status = 'WARNING';\n }\n // Re-stamped so that, in a log merged across processes, this\n // observation is the latest one for the id.\n retryCheck.timestamp = new Date().toISOString();\n retryCheck.details = {\n ...retryCheck.details,\n retryHeaderVersion: headerVersion,\n retryMetaVersion: metaVersion\n };\n }\n\n // server/discover is optional for clients (spec: \"Clients MAY call it\"),\n // so no check is emitted; we still respond so a client that does call it\n // proceeds normally and exercises the per-request _meta/header checks above.\n if (request.method === 'server/discover') {\n res.writeHead(200, { 'Content-Type': 'application/json' });\n res.end(\n JSON.stringify({\n jsonrpc: '2.0',\n id: request.id,\n result: withRequiredDraftResultFields(request.method, {\n supportedVersions: [DRAFT_PROTOCOL_VERSION],\n capabilities: {},\n serverInfo: { name: 'test', version: '1.0' }\n })\n })\n );\n return;\n }\n\n // Return generic response to unblock client\n let result: object = {};\n if (request.method === 'tools/list') {\n result = { tools: [] };\n } else if (request.method === 'tools/call') {\n result = { content: [] };\n }\n res.writeHead(200, { 'Content-Type': 'application/json' });\n res.end(\n JSON.stringify({\n jsonrpc: '2.0',\n id: request.id,\n result: withRequiredDraftResultFields(request.method, result)\n })\n );\n });\n }\n}\n",[],[150,501,833,851],"ca708206-924d-4357-af61-320313809788","mrtr-client.ts","dca475e6-ad13-11f1-bafc-1607ee4eb77e",311,["D",1789343926192],"/**\n * SEP-2322: MRTR Client Conformance Tests\n *\n * Tests that clients correctly handle the MRTR (Multi-Round Tool Resolution) flow:\n * - Echo requestState back unchanged when retrying\n * - Don't include requestState when server didn't send one\n * - Use a different JSON-RPC id on retry\n *\n * The server exposes two tools. The client calls each tool, gets InputRequiredResult,\n * fulfills the elicitation, and retries. The server verifies correct client behavior.\n *\n * The first call and its retry may reach different processes of a\n * multi-process host that share no memory. The only state the retry needs,\n * the original request id and the exact requestState, travels inside the\n * requestState the server sends, with a digest so any process can rebuild\n * the expected string and compare it byte for byte.\n */\n\nimport type { ConformanceCheck, RequestListener } from '../../types.ts';\nimport { HandlerScenario, DRAFT_PROTOCOL_VERSION } from '../../types.ts';\nimport express, { Request, Response } from 'npm:express@^5.1.0';\nimport { createHash, randomUUID } from 'node:crypto';\n\nconst MRTR_SPEC_REFERENCES = [\n {\n id: 'SEP-2322-MRTR',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr#client-requirements-basic-workflow'\n }\n];\n\nconst TOOLS = [\n {\n name: 'test_mrtr_echo_state',\n description:\n 'Test tool: triggers MRTR flow with requestState. Client must echo state back unchanged.',\n inputSchema: {\n type: 'object' as const,\n properties: {},\n required: [] as string[]\n }\n },\n {\n name: 'test_mrtr_no_state',\n description:\n 'Test tool: triggers MRTR flow WITHOUT requestState. Client must NOT include requestState in retry.',\n inputSchema: {\n type: 'object' as const,\n properties: {},\n required: [] as string[]\n }\n },\n {\n name: 'test_mrtr_unrelated',\n description:\n 'Test tool: simple tool called between MRTR rounds. Must NOT carry inputResponses or requestState from another tool.',\n inputSchema: {\n type: 'object' as const,\n properties: {},\n required: [] as string[]\n }\n },\n {\n name: 'test_mrtr_no_result_type',\n description:\n 'Test tool: returns a result without resultType. Client must treat it as complete (default).',\n inputSchema: {\n type: 'object' as const,\n properties: {},\n required: [] as string[]\n }\n }\n];\n\nconst EXPECTED_CHECK_IDS = [\n 'sep-2322-client-request-state-echoed',\n 'sep-2322-client-jsonrpc-id-different',\n 'sep-2322-client-no-state-omitted',\n 'sep-2322-client-parallel-isolation',\n 'sep-2322-default-result-type-complete'\n];\n\n/**\n * INFO record of the first echo_state call, a fallback for its retry. Not\n * prefixed with the SEP: it is the server's bookkeeping, not a requirement.\n */\nconst ECHO_INITIAL_CHECK_ID = 'mrtr-echo-state-initial';\n\ninterface JsonRpcRequest {\n jsonrpc: '2.0';\n id: string | number;\n method: string;\n params?: Record;\n}\n\n/**\n * The requestState sent on the first echo_state call: the call's id and a\n * nonce, plus a digest over both, in a fixed key order. Rebuilding it from\n * the fields a client echoed reproduces the exact string only if the client\n * left it untouched: re-serialized JSON changes the bytes, and an edited id\n * or nonce changes the digest.\n */\nfunction echoState(originalId: string | number, nonce: string): string {\n const digest = createHash('sha256')\n .update(JSON.stringify({ nonce, originalId }))\n .digest('base64url')\n .slice(0, 22);\n return JSON.stringify({ nonce, originalId, digest });\n}\n\n/** The state this server would have sent for the fields in `state`, if any. */\nfunction rebuildEchoState(\n state: string\n): { originalId: string | number; expected: string } | undefined {\n try {\n const parsed = JSON.parse(state) as Record;\n const { nonce, originalId } = parsed;\n if (typeof nonce !== 'string') return undefined;\n if (typeof originalId !== 'string' && typeof originalId !== 'number')\n return undefined;\n return { originalId, expected: echoState(originalId, nonce) };\n } catch {\n return undefined;\n }\n}\n\nfunction createMRTRServer(checks: ConformanceCheck[]): express.Application {\n const app = express();\n app.use(express.json());\n\n app.post('/mcp', (req: Request, res: Response) => {\n const body = req.body as JsonRpcRequest;\n const { id, method, params } = body;\n\n switch (method) {\n case 'server/discover': {\n res.json({\n jsonrpc: '2.0',\n id,\n result: {\n resultType: 'complete',\n ttlMs: 0,\n cacheScope: 'private',\n supportedVersions: [DRAFT_PROTOCOL_VERSION],\n capabilities: { tools: {} },\n serverInfo: { name: 'mrtr-mock-server', version: '1.0.0' }\n }\n });\n return;\n }\n\n case 'initialize': {\n // The dated revisions' handshake. This server supports only\n // 2026-07-28, so it names that version in the error, as a\n // modern-only server should (2026-07-28 basic/versioning).\n res.status(400).json({\n jsonrpc: '2.0',\n id,\n error: {\n code: -32022,\n message: 'Unsupported protocol version',\n data: {\n supported: [DRAFT_PROTOCOL_VERSION],\n requested: String(\n (params as Record)?.protocolVersion ?? ''\n )\n }\n }\n });\n return;\n }\n\n case 'notifications/initialized': {\n res.status(204).end();\n return;\n }\n\n case 'tools/list': {\n res.json({\n jsonrpc: '2.0',\n id,\n result: {\n resultType: 'complete',\n ttlMs: 0,\n cacheScope: 'private',\n tools: TOOLS\n }\n });\n return;\n }\n\n case 'tools/call': {\n const toolName = (params as Record)?.name as string;\n const inputResponses = (params as Record)\n ?.inputResponses as Record | undefined;\n const requestState = (params as Record)\n ?.requestState as string | undefined;\n\n if (toolName === 'test_mrtr_echo_state') {\n handleEchoState(id, inputResponses, requestState, checks, res);\n return;\n }\n\n if (toolName === 'test_mrtr_no_state') {\n handleNoState(id, inputResponses, requestState, checks, res);\n return;\n }\n\n if (toolName === 'test_mrtr_unrelated') {\n handleUnrelated(inputResponses, requestState, checks, res, id);\n return;\n }\n\n if (toolName === 'test_mrtr_no_result_type') {\n handleNoResultType(id, inputResponses, checks, res);\n return;\n }\n\n res.json({\n jsonrpc: '2.0',\n id,\n error: { code: -32601, message: `Unknown tool: ${toolName}` }\n });\n return;\n }\n\n case 'elicitation/create': {\n // Client is fulfilling our ElicitRequest — accept it\n res.json({\n jsonrpc: '2.0',\n id,\n result: {\n resultType: 'complete',\n action: 'accept',\n content: { confirmed: true }\n }\n });\n return;\n }\n\n default: {\n res.json({\n jsonrpc: '2.0',\n id,\n error: { code: -32601, message: `Method not found: ${method}` }\n });\n return;\n }\n }\n });\n\n function handleEchoState(\n id: string | number,\n inputResponses: Record | undefined,\n requestState: string | undefined,\n checks: ConformanceCheck[],\n res: Response\n ) {\n if (!inputResponses) {\n // Initial call: return InputRequiredResult with a requestState that\n // carries this call's id, and note both in the log as a fallback.\n const state = echoState(id, randomUUID());\n checks.push({\n id: ECHO_INITIAL_CHECK_ID,\n name: 'MRTREchoStateInitialCall',\n description:\n 'The server answered the first test_mrtr_echo_state call with a requestState',\n status: 'INFO',\n timestamp: new Date().toISOString(),\n specReferences: MRTR_SPEC_REFERENCES,\n details: { originalId: id, requestStateSent: state }\n });\n res.json({\n jsonrpc: '2.0',\n id,\n result: {\n resultType: 'input_required',\n inputRequests: {\n confirm: {\n method: 'elicitation/create',\n params: {\n message: 'Please confirm to continue',\n requestedSchema: {\n type: 'object',\n properties: {\n confirmed: { type: 'boolean', description: 'Confirm?' }\n }\n }\n }\n }\n },\n requestState: state\n }\n });\n return;\n }\n\n // Retry: what was sent comes from the echoed state itself when it is\n // exactly what this server would have sent, or failing that from the log\n // of the first call (possibly another process's). A state that does not\n // rebuild byte for byte is never believed, so an edited originalId cannot\n // steer the id check.\n const rebuilt = requestState ? rebuildEchoState(requestState) : undefined;\n const intact =\n rebuilt && rebuilt.expected === requestState ? rebuilt : undefined;\n const initial = [...checks]\n .reverse()\n .find((c) => c.id === ECHO_INITIAL_CHECK_ID)?.details as\n | { originalId?: string | number; requestStateSent?: string }\n | undefined;\n const originalId = intact?.originalId ?? initial?.originalId;\n const sentState = intact?.expected ?? initial?.requestStateSent;\n\n // Check 1: requestState must be present and byte-for-byte identical to\n // what the server sent. The spec requires the client to echo back the\n // *exact value* without inspecting, parsing, or modifying it — so a\n // semantically-equal but re-serialized string is still a failure.\n const stateErrors: string[] = [];\n if (!requestState) {\n stateErrors.push('Client did not include requestState in retry');\n } else if (requestState !== sentState) {\n stateErrors.push(\n 'requestState was not echoed back exactly — clients MUST NOT inspect, parse, or modify it'\n );\n }\n\n checks.push({\n id: 'sep-2322-client-request-state-echoed',\n name: 'MRTRClientRequestStateEchoed',\n description:\n 'Client MUST echo back the exact value of requestState when retrying',\n status: stateErrors.length === 0 ? 'SUCCESS' : 'FAILURE',\n timestamp: new Date().toISOString(),\n errorMessage: stateErrors.length > 0 ? stateErrors.join('; ') : undefined,\n specReferences: MRTR_SPEC_REFERENCES,\n details: {\n requestStateSent: sentState,\n requestStateReceived: requestState,\n originalId\n }\n });\n\n // Check 2: JSON-RPC id must differ from original. When the original id\n // cannot be recovered (no intact state and no record of the first call)\n // there is nothing to compare, and check 1 has already failed the retry.\n const idErrors: string[] = [];\n if (originalId !== undefined && id === originalId) {\n idErrors.push(\n `JSON-RPC id is the same on retry (${id}) — MUST be different`\n );\n }\n\n checks.push({\n id: 'sep-2322-client-jsonrpc-id-different',\n name: 'MRTRClientJsonRpcIdDifferent',\n description:\n 'The JSON-RPC id MUST be different between the initial request and the retry',\n status: idErrors.length === 0 ? 'SUCCESS' : 'FAILURE',\n timestamp: new Date().toISOString(),\n errorMessage: idErrors.length > 0 ? idErrors.join('; ') : undefined,\n specReferences: MRTR_SPEC_REFERENCES,\n details: {\n originalId,\n retryId: id\n }\n });\n\n // Return complete result\n res.json({\n jsonrpc: '2.0',\n id,\n result: {\n resultType: 'complete',\n content: [{ type: 'text', text: 'echo-state-ok' }]\n }\n });\n }\n\n function handleNoState(\n id: string | number,\n inputResponses: Record | undefined,\n requestState: string | undefined,\n checks: ConformanceCheck[],\n res: Response\n ) {\n if (!inputResponses) {\n // Initial call — return InputRequiredResult WITHOUT requestState\n res.json({\n jsonrpc: '2.0',\n id,\n result: {\n resultType: 'input_required',\n inputRequests: {\n confirm: {\n method: 'elicitation/create',\n params: {\n message: 'Please confirm to continue (no state test)',\n requestedSchema: {\n type: 'object',\n properties: {\n confirmed: { type: 'boolean', description: 'Confirm?' }\n }\n }\n }\n }\n }\n // No requestState field!\n }\n });\n return;\n }\n\n // Retry — verify client did NOT include requestState\n const errors: string[] = [];\n if (requestState !== undefined) {\n errors.push(\n `Client included requestState (\"${requestState}\") but server did not send one — MUST NOT include it`\n );\n }\n\n checks.push({\n id: 'sep-2322-client-no-state-omitted',\n name: 'MRTRClientNoStateOmitted',\n description:\n 'If InputRequiredResult does not contain requestState, client MUST NOT include one in the retry',\n status: errors.length === 0 ? 'SUCCESS' : 'FAILURE',\n timestamp: new Date().toISOString(),\n errorMessage: errors.length > 0 ? errors.join('; ') : undefined,\n specReferences: MRTR_SPEC_REFERENCES,\n details: {\n requestStateReceived: requestState\n }\n });\n\n // Return complete result\n res.json({\n jsonrpc: '2.0',\n id,\n result: {\n resultType: 'complete',\n content: [{ type: 'text', text: 'no-state-ok' }]\n }\n });\n }\n\n function handleUnrelated(\n inputResponses: Record | undefined,\n requestState: string | undefined,\n checks: ConformanceCheck[],\n res: Response,\n id: string | number\n ) {\n // This tool should NEVER receive inputResponses or requestState —\n // those belong to a different tool's MRTR flow\n const errors: string[] = [];\n if (inputResponses !== undefined) {\n errors.push(\n `Unrelated tool call included inputResponses from another tool's MRTR flow`\n );\n }\n if (requestState !== undefined) {\n errors.push(\n `Unrelated tool call included requestState from another tool's MRTR flow`\n );\n }\n\n checks.push({\n id: 'sep-2322-client-parallel-isolation',\n name: 'MRTRClientParallelIsolation',\n description:\n 'inputRequests and requestState MUST NOT be used for any other request the client may be sending',\n status: errors.length === 0 ? 'SUCCESS' : 'FAILURE',\n timestamp: new Date().toISOString(),\n errorMessage: errors.length > 0 ? errors.join('; ') : undefined,\n specReferences: MRTR_SPEC_REFERENCES,\n details: {\n inputResponsesReceived: inputResponses,\n requestStateReceived: requestState\n }\n });\n\n // Return a normal complete result\n res.json({\n jsonrpc: '2.0',\n id,\n result: {\n resultType: 'complete',\n content: [{ type: 'text', text: 'unrelated-ok' }]\n }\n });\n }\n\n function handleNoResultType(\n id: string | number,\n inputResponses: Record | undefined,\n checks: ConformanceCheck[],\n res: Response\n ) {\n const checkId = 'sep-2322-default-result-type-complete';\n\n // If the client retries this tool, it did NOT treat the result as\n // complete. The SUCCESS noted for the first answer may sit in another\n // process's log, so it is not removed here: getChecks() lets the\n // FAILURE win.\n if (inputResponses) {\n checks.push({\n id: checkId,\n name: 'DefaultResultTypeComplete',\n description:\n 'Client MUST assume resultType \"complete\" when not specified',\n status: 'FAILURE',\n timestamp: new Date().toISOString(),\n errorMessage:\n 'Client retried with inputResponses even though the result had no resultType (should default to complete)',\n specReferences: MRTR_SPEC_REFERENCES\n });\n res.json({\n jsonrpc: '2.0',\n id,\n result: {\n resultType: 'complete',\n content: [{ type: 'text', text: 'unexpected-retry' }]\n }\n });\n return;\n }\n\n // Return a result WITHOUT resultType — client should treat as complete\n checks.push({\n id: checkId,\n name: 'DefaultResultTypeComplete',\n description:\n 'Client MUST assume resultType \"complete\" when not specified',\n status: 'SUCCESS',\n timestamp: new Date().toISOString(),\n specReferences: MRTR_SPEC_REFERENCES\n });\n\n res.json({\n jsonrpc: '2.0',\n id,\n result: {\n // Deliberately NO resultType field\n content: [{ type: 'text', text: 'no-result-type-test-ok' }]\n }\n });\n }\n\n return app;\n}\n\nexport class MRTRClientScenario extends HandlerScenario {\n name = 'sep-2322-client-request-state';\n readonly source = { introducedIn: DRAFT_PROTOCOL_VERSION } as const;\n description =\n 'Tests client MRTR behavior: requestState echo, no-state omission, and JSON-RPC id uniqueness (SEP-2322)';\n mcpPath = '/mcp';\n private checks: ConformanceCheck[] = [];\n\n /** What a client driven by hand (or by a generic steps interpreter) should do. */\n readonly steps = [\n { op: 'tools/list' },\n { op: 'tools/call', name: 'test_mrtr_echo_state' },\n { op: 'tools/call', name: 'test_mrtr_unrelated' },\n { op: 'tools/call', name: 'test_mrtr_no_state' },\n { op: 'tools/call', name: 'test_mrtr_no_result_type' }\n ] as const;\n\n handler(_getBaseUrl: () => string): RequestListener {\n this.checks = [];\n return createMRTRServer(this.checks);\n }\n\n /**\n * One row per check id, built fresh so the raw log stays as observed: a\n * FAILURE wins over any SUCCESS for the same id (a merged log from several\n * processes can hold both), otherwise the latest row. Expected checks that\n * never ran are reported as FAILURE. Such a report is never an\n * observation: should one find its way into a log, it is ignored, so it\n * cannot outrank a SUCCESS another process saw.\n */\n getChecks(): ConformanceCheck[] {\n const byId = new Map();\n for (const check of this.checks) {\n if (isNotObserved(check)) continue;\n const previous = byId.get(check.id);\n if (!previous || previous.status !== 'FAILURE') byId.set(check.id, check);\n }\n const result = [...byId.values()];\n for (const slug of EXPECTED_CHECK_IDS) {\n if (byId.has(slug)) continue;\n result.push({\n id: slug,\n name: slug,\n description: `MRTR client check: ${slug}`,\n status: 'FAILURE',\n timestamp: new Date().toISOString(),\n details: { message: NOT_OBSERVED_MESSAGE },\n specReferences: MRTR_SPEC_REFERENCES\n });\n }\n return result;\n }\n}\n\nconst NOT_OBSERVED_MESSAGE =\n 'Tool was not called by client or MRTR flow not completed';\n\n/** A row getChecks() reports for an expected check nothing has met yet. */\nfunction isNotObserved(check: ConformanceCheck): boolean {\n return (\n check.name === check.id &&\n check.details?.message === NOT_OBSERVED_MESSAGE &&\n EXPECTED_CHECK_IDS.includes(check.id)\n );\n}\n",[],[150,501,833,860],"34203f93-7007-4671-b399-d5e6b822e631","json-schema-ref-deref.ts","d5280f76-ad13-11f1-a016-1607ee4eb77e",271,["D",1789339693244],"import { Server } from 'npm:@modelcontextprotocol/sdk@^1.29.0/server/index.js';\nimport { StreamableHTTPServerTransport } from 'npm:@modelcontextprotocol/sdk@^1.29.0/server/streamableHttp.js';\nimport {\n CallToolRequestSchema,\n ErrorCode,\n ListToolsRequestSchema,\n McpError,\n LATEST_PROTOCOL_VERSION as SDK_LATEST_PROTOCOL_VERSION\n} from 'npm:@modelcontextprotocol/sdk@^1.29.0/types.js';\nimport type { ConformanceCheck, RequestListener } from '../../types.ts';\nimport express, { Request, Response } from 'npm:express@^5.1.0';\nimport { HandlerScenario, DRAFT_PROTOCOL_VERSION } from '../../types.ts';\n\n/**\n * Scenario: JSON Schema network $ref dereferencing (SEP-2106)\n *\n * SEP-2106 permits the full JSON Schema 2020-12 vocabulary in tool schemas,\n * including `$ref`. A `$ref` that resolves to a network URI is an SSRF /\n * fetch-DoS vector: a malicious tool definition could point at internal\n * infrastructure and have the *client* fetch it during schema processing.\n *\n * Per SEP-2106, implementations MUST NOT automatically dereference `$ref`\n * values that resolve to a network URI (anything that is not a same-document\n * JSON Pointer such as `#/$defs/Foo` or an internal `$anchor`).\n *\n * This scenario advertises a tool whose inputSchema contains both a\n * same-document `$ref` and a `$ref` to a canary URL hosted by the scenario\n * itself. If the client fetches the canary URL at any point before the\n * scenario stops, the check fails.\n */\n\nconst TOOL_NAME = 'lookup_user';\nconst CANARY_PATH = '/canary/profile-schema.json';\nconst TOOLS_LISTED_EVENT = '_state/tools-listed';\nconst CANARY_EVENT = '_state/canary-fetched';\nconst CHECK_ID = 'sep-2106-no-network-ref-deref';\n\nconst SPEC_REFERENCES = [\n {\n id: 'SEP-2106',\n url: 'https://modelcontextprotocol.io/seps/2106-json-schema-2020-12#security-implications'\n },\n {\n id: 'MCP-2026-07-28-ref-resolution',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic#$ref-resolution'\n }\n];\n\nfunction createMcpServer(canaryUrl: string, onToolsListed: () => void): Server {\n const server = new Server(\n { name: 'json-schema-ref-deref-server', version: '1.0.0' },\n { capabilities: { tools: {} } }\n );\n\n server.setRequestHandler(ListToolsRequestSchema, async () => {\n onToolsListed();\n return {\n resultType: 'complete',\n ttlMs: 0,\n cacheScope: 'private',\n tools: [\n {\n name: TOOL_NAME,\n description: 'Look up a user profile by id',\n inputSchema: {\n $schema: 'https://json-schema.org/draft/2020-12/schema',\n type: 'object',\n $defs: {\n userId: { type: 'string', pattern: '^[a-z0-9-]+$' }\n },\n properties: {\n // Same-document $ref: safe, expected to be resolvable locally.\n id: { $ref: '#/$defs/userId' },\n // Network $ref: the canary. Implementations MUST NOT fetch this\n // automatically while processing the schema.\n profile: { $ref: canaryUrl }\n },\n required: ['id']\n }\n }\n ]\n };\n });\n\n // A client that lists the tool may well call it (a person driving a chat\n // app will). Answer from nothing, never fetching the canary: the check is\n // only about whether the client fetches it.\n server.setRequestHandler(CallToolRequestSchema, async (request) => {\n if (request.params.name !== TOOL_NAME) {\n throw new McpError(\n ErrorCode.InvalidParams,\n `Unknown tool: ${request.params.name}`\n );\n }\n const id = request.params.arguments?.id;\n return {\n resultType: 'complete',\n content: [\n {\n type: 'text',\n text: `No profile on file for user ${typeof id === 'string' ? id : '(no id given)'}.`\n }\n ]\n };\n });\n\n return server;\n}\n\nexport class JsonSchemaRefDerefScenario extends HandlerScenario {\n name = 'json-schema-ref-no-deref';\n readonly source = { introducedIn: DRAFT_PROTOCOL_VERSION } as const;\n description = `Tests that a client does not automatically dereference a network-URI \\`$ref\\` in a tool's inputSchema (SEP-2106).\n\nThe scenario advertises a tool whose inputSchema contains a \\`$ref\\` pointing at a canary URL. The client should list tools (and may otherwise process the schema), but must not fetch the canary URL. Same-document refs (\\`#/$defs/...\\`) remain safe to resolve.`;\n mcpPath = '/mcp';\n /** List only — the point is what the client does NOT fetch afterwards. */\n readonly steps = [{ op: 'tools/list' }] as const;\n\n /**\n * Raw event log. What the scenario observed is kept as INFO events here\n * (rather than in private fields) so a host that spreads one run over\n * several processes can merge the logs and judge once — see rawChecks().\n */\n checks: ConformanceCheck[] = [];\n\n private record(id: string, details?: Record): void {\n this.checks.push({\n id,\n name: id,\n description: id,\n status: 'INFO',\n timestamp: new Date().toISOString(),\n details\n });\n }\n\n rawChecks(): ConformanceCheck[] {\n return this.checks;\n }\n\n handler(getBaseUrl: () => string): RequestListener {\n this.checks = [];\n\n const app = express();\n app.use(express.json());\n\n // Canary endpoint: any request here means the client dereferenced the\n // network $ref. Return a valid schema so a dereferencing client gets a\n // realistic response rather than an error it might silently swallow.\n app.all(CANARY_PATH, (req: Request, res: Response) => {\n this.record(CANARY_EVENT, {\n method: req.method,\n userAgent: req.headers['user-agent']\n });\n res.json({\n $schema: 'https://json-schema.org/draft/2020-12/schema',\n type: 'object',\n properties: { displayName: { type: 'string' } }\n });\n });\n\n app.post('/mcp', async (req: Request, res: Response) => {\n // The bundled SDK server below predates the 2026-07-28 lifecycle and\n // does not implement server/discover; answer it directly so a client\n // that negotiates first can proceed to tools/list.\n if (\n (req.body as Record | undefined)?.method ===\n 'server/discover'\n ) {\n return res.json({\n jsonrpc: '2.0',\n id: (req.body as Record).id ?? null,\n result: {\n resultType: 'complete',\n ttlMs: 0,\n cacheScope: 'private',\n supportedVersions: [DRAFT_PROTOCOL_VERSION],\n capabilities: { tools: {} },\n serverInfo: {\n name: 'json-schema-ref-deref-server',\n version: '1.0.0'\n }\n }\n });\n }\n // Second half of the same workaround: the pinned SDK transport\n // whitelists MCP-Protocol-Version headers and would reject the draft\n // version that the server/discover response above advertises with an\n // HTTP 400. Rewrite it to the newest version the SDK understands so a\n // client that honors the negotiated version can reach tools/list.\n if (req.headers['mcp-protocol-version'] === DRAFT_PROTOCOL_VERSION) {\n req.headers['mcp-protocol-version'] = SDK_LATEST_PROTOCOL_VERSION;\n // The SDK's Node adapter rebuilds its web-standard Request from\n // rawHeaders, not the parsed headers object, so patch those too.\n for (let i = 0; i < req.rawHeaders.length; i += 2) {\n if (req.rawHeaders[i].toLowerCase() === 'mcp-protocol-version') {\n req.rawHeaders[i + 1] = SDK_LATEST_PROTOCOL_VERSION;\n }\n }\n }\n try {\n // Stateless: fresh server and transport per request\n const canaryUrl = `${getBaseUrl()}${CANARY_PATH}`;\n const server = createMcpServer(canaryUrl, () => {\n this.record(TOOLS_LISTED_EVENT);\n });\n const transport = new StreamableHTTPServerTransport({\n sessionIdGenerator: undefined\n });\n await server.connect(transport);\n await transport.handleRequest(req, res, req.body);\n } catch (error) {\n if (!res.headersSent) {\n res.status(500).json({\n jsonrpc: '2.0',\n error: {\n code: -32603,\n message: `Internal error: ${error instanceof Error ? error.message : String(error)}`\n },\n id: null\n });\n }\n }\n });\n\n return app;\n }\n\n getChecks(): ConformanceCheck[] {\n // Built fresh on every call so getChecks() is idempotent — the runner may\n // call it more than once and we must not accumulate duplicates.\n const timestamp = new Date().toISOString();\n const canaryRequests = this.checks\n .filter((c) => c.id === CANARY_EVENT)\n .map((c) => c.details ?? {});\n const toolsListed = this.checks.some((c) => c.id === TOOLS_LISTED_EVENT);\n const fetched = canaryRequests.length > 0;\n\n if (!toolsListed) {\n return [\n {\n id: CHECK_ID,\n name: 'NoNetworkRefDereference',\n description:\n 'Client never requested tools/list, so $ref handling could not be evaluated',\n status: 'FAILURE',\n timestamp,\n errorMessage:\n 'Client did not call tools/list against a server advertising a tool with a network $ref',\n specReferences: SPEC_REFERENCES,\n details: { toolsListed: false }\n }\n ];\n }\n\n return [\n {\n id: CHECK_ID,\n name: 'NoNetworkRefDereference',\n description: fetched\n ? 'Client automatically dereferenced a network-URI $ref in a tool inputSchema. Implementations MUST NOT automatically dereference $ref values that resolve to a network URI (SEP-2106).'\n : 'Client did not dereference the network-URI $ref in the tool inputSchema',\n status: fetched ? 'FAILURE' : 'SUCCESS',\n timestamp,\n errorMessage: fetched\n ? `Canary URL ${CANARY_PATH} was fetched ${canaryRequests.length} time(s)`\n : undefined,\n specReferences: SPEC_REFERENCES,\n details: {\n toolsListed: true,\n canaryRequestCount: canaryRequests.length,\n canaryRequests\n }\n }\n ];\n }\n}\n",[],[150,501,833,868],"ca34149c-f8de-4e32-a749-c5c147f7b5cc","json-schema-2020-12-preservation.ts","5f9e7346-ad1b-11f1-90b8-1607ee4eb77e",270,["D",1789339692891],"/**\n * Client-side JSON Schema 2020-12 keyword preservation (SEP-1613, SEP-2106)\n *\n * Validates that a client receiving a tool definition via `tools/list`\n * preserves the full JSON Schema 2020-12 vocabulary in its internal\n * representation, rather than silently stripping `$schema`, `$defs`,\n * `additionalProperties`, `$anchor`, composition (`allOf`/`anyOf`), or\n * conditional (`if`/`then`/`else`) keywords during parsing.\n *\n * This is the client-side counterpart of the server-side\n * `json-schema-2020-12` scenario.\n * This scenario exercises:\n *\n * 1. The mock server advertises a focal tool (`json_schema_2020_12_tool`)\n * whose inputSchema contains the full SEP-1613/SEP-2106 vocabulary, plus\n * a permissive echo tool (`json_schema_echo`).\n * 2. The client under test calls `tools/list`, observes the focal tool's\n * inputSchema, then round-trips it back via `tools/call json_schema_echo`\n * with `{ schema: }`.\n * 3. The scenario diffs the echoed schema against the original fixture and\n * flags any missing or altered keywords.\n *\n * SEP-2106 vocabulary checks are soft-gated via `sep2106KeywordCheckStatus`:\n * stripping is FAILURE only when the run targets the draft version\n * (`2026-07-28`); on earlier dated versions the check reports SKIPPED.\n */\n\nimport type { ScenarioContext, MockServer } from '../../mock-server/index.ts';\nimport type {\n CallToolRequest,\n ListToolsResult\n} from '../../spec-types/2025-11-25.ts';\nimport {\n DRAFT_PROTOCOL_VERSION,\n LATEST_SPEC_VERSION,\n type ConformanceCheck,\n type Scenario,\n type ScenarioUrls,\n type SpecVersion\n} from '../../types.ts';\nimport {\n EXPECTED_SCHEMA_DIALECT,\n EXPECTED_TOOL_NAME,\n JSON_SCHEMA_2020_12_FIXTURE,\n sep2106KeywordCheckStatus\n} from '../server/json-schema-2020-12.ts';\n\nconst ECHO_TOOL_NAME = 'json_schema_echo';\n\nconst SEP_1613_REF = {\n id: 'SEP-1613',\n url: 'https://github.com/modelcontextprotocol/specification/pull/655'\n};\nconst SEP_2106_REF = {\n id: 'SEP-2106',\n url: 'https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2106'\n};\n// The spec does not require preservation in so many words; it requires\n// support for JSON Schema 2020-12, which a client that strips the dialect's\n// keywords does not have.\nconst JSON_SCHEMA_2026_07_28_REF = {\n id: 'MCP-2026-07-28-JSON-Schema-implementation-requirements',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic#implementation-requirements'\n};\n\nexport class JsonSchema2020_12PreservationScenario implements Scenario {\n name = 'json-schema-2020-12-preservation';\n readonly source = { introducedIn: '2025-11-25' } as const;\n description = `Validates client-side preservation of JSON Schema 2020-12 keywords (SEP-1613, SEP-2106).\n\n**Client Implementation Requirements:**\n\n1. Call \\`tools/list\\`. The mock server advertises two tools: \\`${EXPECTED_TOOL_NAME}\\` (focal, carries the rich inputSchema) and \\`${ECHO_TOOL_NAME}\\` (permissive echo).\n2. Round-trip the focal tool's \\`inputSchema\\` back via \\`tools/call\\` on \\`${ECHO_TOOL_NAME}\\`, passing it verbatim as the \\`schema\\` argument:\n\n\\`\\`\\`json\n{\n \"name\": \"${ECHO_TOOL_NAME}\",\n \"arguments\": {\n \"schema\": \"\"\n }\n}\n\\`\\`\\`\n\nThe scenario compares the echoed schema against the original fixture and flags any keyword that was stripped or altered during the client's internal parsing.\n\n**Verification**: \\`$schema\\`, \\`$defs\\`, and \\`additionalProperties\\` must be preserved (SEP-1613). The SEP-2106 vocabulary (\\`$anchor\\` inside \\`$defs\\`, composition \\`allOf\\`/\\`anyOf\\`, conditional \\`if\\`/\\`then\\`/\\`else\\`) must also survive; for dated protocol versions these checks are SKIPPED rather than FAILURE since SEP-2106 applies from the draft version.`;\n\n private srv: MockServer | null = null;\n private specVersion: SpecVersion | null = null;\n private observedSchema: Record | null = null;\n private toolsListed = false;\n\n async start(ctx: ScenarioContext): Promise {\n this.specVersion = ctx.specVersion;\n this.observedSchema = null;\n this.toolsListed = false;\n\n this.srv = await ctx.createServer({\n 'tools/list': (): ListToolsResult => {\n this.toolsListed = true;\n return {\n tools: [\n {\n name: EXPECTED_TOOL_NAME,\n description: 'Tool with JSON Schema 2020-12 features',\n inputSchema: JSON_SCHEMA_2020_12_FIXTURE\n },\n {\n name: ECHO_TOOL_NAME,\n description:\n 'Echoes back an arbitrary JSON Schema object so the harness can observe what the client preserved.',\n inputSchema: {\n type: 'object',\n properties: {\n schema: {\n type: 'object',\n description: `The inputSchema the client observed for ${EXPECTED_TOOL_NAME}, passed back verbatim.`\n }\n },\n required: ['schema']\n }\n }\n ]\n };\n },\n 'tools/call': (params) => {\n const p = params as unknown as CallToolRequest['params'];\n if (p.name === ECHO_TOOL_NAME) {\n const args = p.arguments as { schema?: unknown } | undefined;\n if (args && typeof args.schema === 'object' && args.schema !== null) {\n this.observedSchema = args.schema as Record;\n }\n return { content: [{ type: 'text', text: 'echoed' }] };\n }\n if (p.name === EXPECTED_TOOL_NAME) {\n return { content: [{ type: 'text', text: 'ok' }] };\n }\n throw new Error(`Unknown tool: ${p.name}`);\n }\n });\n return { serverUrl: this.srv.url };\n }\n\n async stop(): Promise {\n await this.srv?.close();\n this.srv = null;\n }\n\n getChecks(): ConformanceCheck[] {\n // Built fresh on every call so getChecks() is idempotent — the runner may\n // call it more than once and we must not accumulate duplicates.\n const timestamp = new Date().toISOString();\n const targetVersion = this.specVersion ?? LATEST_SPEC_VERSION;\n const echo = this.observedSchema;\n\n const checks: ConformanceCheck[] = [];\n\n checks.push({\n id: 'json-schema-2020-12-client-tool-found',\n name: 'JsonSchema2020_12ClientToolFound',\n description: `Client called tools/list and the mock server advertised '${EXPECTED_TOOL_NAME}'`,\n status: this.toolsListed ? 'SUCCESS' : 'FAILURE',\n timestamp,\n specReferences: [SEP_1613_REF, JSON_SCHEMA_2026_07_28_REF],\n errorMessage: this.toolsListed\n ? undefined\n : 'Client never called tools/list; the scenario cannot observe schema preservation',\n details: { toolsListCalled: this.toolsListed }\n });\n\n checks.push({\n id: 'json-schema-2020-12-client-echo-completed',\n name: 'JsonSchema2020_12ClientEchoCompleted',\n description: `Client called tools/call '${ECHO_TOOL_NAME}' with a 'schema' object argument`,\n status: echo !== null ? 'SUCCESS' : 'FAILURE',\n timestamp,\n specReferences: [SEP_1613_REF, JSON_SCHEMA_2026_07_28_REF],\n errorMessage:\n echo !== null\n ? undefined\n : 'Client did not echo back the inputSchema; downstream preservation checks are SKIPPED',\n details: { echoCompleted: echo !== null }\n });\n\n // If the client never echoed, the downstream preservation checks cannot\n // be evaluated. Emit SKIPPED for each so the SEP traceability manifest\n // still records all known check IDs from this scenario.\n if (echo === null) {\n const skipReason =\n 'Skipped because the client did not complete the schema echo';\n checks.push(\n {\n id: 'json-schema-2020-12-client-$schema-preserved',\n name: 'JsonSchema2020_12Client$SchemaPreserved',\n description:\n 'Client preserved the $schema field of the focal tool inputSchema',\n status: 'SKIPPED',\n timestamp,\n specReferences: [SEP_1613_REF, JSON_SCHEMA_2026_07_28_REF],\n errorMessage: skipReason\n },\n {\n id: 'json-schema-2020-12-client-$defs-preserved',\n name: 'JsonSchema2020_12Client$DefsPreserved',\n description:\n 'Client preserved the $defs field of the focal tool inputSchema',\n status: 'SKIPPED',\n timestamp,\n specReferences: [SEP_1613_REF, JSON_SCHEMA_2026_07_28_REF],\n errorMessage: skipReason\n },\n {\n id: 'json-schema-2020-12-client-additionalProperties-preserved',\n name: 'JsonSchema2020_12ClientAdditionalPropertiesPreserved',\n description:\n 'Client preserved the additionalProperties field of the focal tool inputSchema',\n status: 'SKIPPED',\n timestamp,\n specReferences: [SEP_1613_REF, JSON_SCHEMA_2026_07_28_REF],\n errorMessage: skipReason\n },\n {\n id: 'sep-2106-client-composition-keywords-preserved',\n name: 'JsonSchema2020_12ClientCompositionKeywordsPreserved',\n description:\n 'Client preserved composition keywords (allOf/anyOf) on the focal tool inputSchema',\n status: 'SKIPPED',\n timestamp,\n specReferences: [SEP_2106_REF, JSON_SCHEMA_2026_07_28_REF],\n errorMessage: skipReason\n },\n {\n id: 'sep-2106-client-conditional-keywords-preserved',\n name: 'JsonSchema2020_12ClientConditionalKeywordsPreserved',\n description:\n 'Client preserved conditional keywords (if/then/else) on the focal tool inputSchema',\n status: 'SKIPPED',\n timestamp,\n specReferences: [SEP_2106_REF, JSON_SCHEMA_2026_07_28_REF],\n errorMessage: skipReason\n },\n {\n id: 'sep-2106-client-anchor-keyword-preserved',\n name: 'JsonSchema2020_12ClientAnchorKeywordPreserved',\n description:\n 'Client preserved the $anchor keyword inside $defs.address',\n status: 'SKIPPED',\n timestamp,\n specReferences: [SEP_2106_REF, JSON_SCHEMA_2026_07_28_REF],\n errorMessage: skipReason\n }\n );\n return checks;\n }\n\n // SEP-1613: $schema preserved\n const hasSchema = '$schema' in echo;\n const schemaCorrect = echo['$schema'] === EXPECTED_SCHEMA_DIALECT;\n checks.push({\n id: 'json-schema-2020-12-client-$schema-preserved',\n name: 'JsonSchema2020_12Client$SchemaPreserved',\n description: `Client preserved $schema = '${EXPECTED_SCHEMA_DIALECT}'`,\n status: hasSchema && schemaCorrect ? 'SUCCESS' : 'FAILURE',\n timestamp,\n specReferences: [SEP_1613_REF, JSON_SCHEMA_2026_07_28_REF],\n errorMessage: !hasSchema\n ? '$schema missing from echoed inputSchema — client likely stripped it during parsing'\n : !schemaCorrect\n ? `$schema has unexpected value: ${JSON.stringify(echo['$schema'])}`\n : undefined,\n details: { hasSchema, schemaValue: echo['$schema'] }\n });\n\n // SEP-1613: $defs preserved\n const defs = echo['$defs'] as Record | undefined;\n const hasDefs = '$defs' in echo;\n const defsHasAddress = hasDefs && defs !== undefined && 'address' in defs;\n checks.push({\n id: 'json-schema-2020-12-client-$defs-preserved',\n name: 'JsonSchema2020_12Client$DefsPreserved',\n description:\n 'Client preserved $defs with the expected nested definitions',\n status: hasDefs && defsHasAddress ? 'SUCCESS' : 'FAILURE',\n timestamp,\n specReferences: [SEP_1613_REF, JSON_SCHEMA_2026_07_28_REF],\n errorMessage: !hasDefs\n ? '$defs missing from echoed inputSchema — client likely stripped it during parsing'\n : !defsHasAddress\n ? '$defs exists but missing expected \"address\" definition'\n : undefined,\n details: {\n hasDefs,\n defsKeys: defs !== undefined ? Object.keys(defs) : []\n }\n });\n\n // SEP-1613: additionalProperties preserved\n const hasAdditionalProps = 'additionalProperties' in echo;\n const additionalPropsCorrect = echo['additionalProperties'] === false;\n checks.push({\n id: 'json-schema-2020-12-client-additionalProperties-preserved',\n name: 'JsonSchema2020_12ClientAdditionalPropertiesPreserved',\n description:\n 'Client preserved additionalProperties = false on the focal inputSchema',\n status:\n hasAdditionalProps && additionalPropsCorrect ? 'SUCCESS' : 'FAILURE',\n timestamp,\n specReferences: [SEP_1613_REF, JSON_SCHEMA_2026_07_28_REF],\n errorMessage: !hasAdditionalProps\n ? 'additionalProperties missing from echoed inputSchema — client likely stripped it during parsing'\n : !additionalPropsCorrect\n ? `additionalProperties has unexpected value: ${JSON.stringify(echo['additionalProperties'])}`\n : undefined,\n details: { hasAdditionalProps, value: echo['additionalProperties'] }\n });\n\n // SEP-2106 vocabulary — soft-gated via sep2106KeywordCheckStatus.\n const skippedSuffix = ` (run targets protocol version ${targetVersion}; SEP-2106 applies from ${DRAFT_PROTOCOL_VERSION})`;\n\n // SEP-2106: composition (allOf/anyOf) preserved\n const allOf = echo['allOf'];\n const hasAllOf = Array.isArray(allOf) && allOf.length > 0;\n const hasNestedAnyOf =\n Array.isArray(allOf) &&\n allOf.some(\n (sub) =>\n typeof sub === 'object' &&\n sub !== null &&\n Array.isArray((sub as Record)['anyOf'])\n );\n const compositionPreserved = hasAllOf && hasNestedAnyOf;\n const compositionStatus = sep2106KeywordCheckStatus(\n compositionPreserved,\n targetVersion\n );\n checks.push({\n id: 'sep-2106-client-composition-keywords-preserved',\n name: 'JsonSchema2020_12ClientCompositionKeywordsPreserved',\n description:\n 'Client preserved composition keywords (allOf/anyOf) on the focal inputSchema',\n status: compositionStatus,\n timestamp,\n specReferences: [SEP_2106_REF, JSON_SCHEMA_2026_07_28_REF],\n errorMessage: compositionPreserved\n ? undefined\n : (!hasAllOf\n ? 'allOf missing from echoed inputSchema — composition keyword was likely stripped'\n : 'nested anyOf missing from echoed allOf — composition keyword was likely stripped') +\n (compositionStatus === 'SKIPPED' ? skippedSuffix : ''),\n details: {\n hasAllOf,\n hasNestedAnyOf,\n targetProtocolVersion: targetVersion\n }\n });\n\n // SEP-2106: conditional (if/then/else) preserved\n const hasIf = 'if' in echo;\n const hasThen = 'then' in echo;\n const hasElse = 'else' in echo;\n const conditionalPreserved = hasIf && hasThen && hasElse;\n const conditionalStatus = sep2106KeywordCheckStatus(\n conditionalPreserved,\n targetVersion\n );\n checks.push({\n id: 'sep-2106-client-conditional-keywords-preserved',\n name: 'JsonSchema2020_12ClientConditionalKeywordsPreserved',\n description:\n 'Client preserved conditional keywords (if/then/else) on the focal inputSchema',\n status: conditionalStatus,\n timestamp,\n specReferences: [SEP_2106_REF, JSON_SCHEMA_2026_07_28_REF],\n errorMessage: conditionalPreserved\n ? undefined\n : `Conditional keywords missing (if=${hasIf}, then=${hasThen}, else=${hasElse}) — likely stripped` +\n (conditionalStatus === 'SKIPPED' ? skippedSuffix : ''),\n details: {\n hasIf,\n hasThen,\n hasElse,\n targetProtocolVersion: targetVersion\n }\n });\n\n // SEP-2106: $anchor inside $defs.address preserved\n const address = defs?.['address'] as Record | undefined;\n const hasAnchor = !!address && '$anchor' in address;\n const anchorStatus = sep2106KeywordCheckStatus(hasAnchor, targetVersion);\n checks.push({\n id: 'sep-2106-client-anchor-keyword-preserved',\n name: 'JsonSchema2020_12ClientAnchorKeywordPreserved',\n description: 'Client preserved $anchor inside $defs.address',\n status: anchorStatus,\n timestamp,\n specReferences: [SEP_2106_REF, JSON_SCHEMA_2026_07_28_REF],\n errorMessage: hasAnchor\n ? undefined\n : '$anchor missing from echoed $defs.address — reference keyword was likely stripped' +\n (anchorStatus === 'SKIPPED' ? skippedSuffix : ''),\n details: {\n hasAnchor,\n anchorValue: address?.['$anchor']\n }\n });\n\n return checks;\n }\n}\n",[],[150,501,833,876],"06e21d94-92a3-4174-bf4d-fc02df4fa7df","initialize.ts","ded3ce70-ad13-11f1-bf23-1607ee4eb77e",278,["D",1789339706511],"import http from 'node:http';\nimport {\n HandlerScenario,\n RequestListener,\n ConformanceCheck,\n LATEST_SPEC_VERSION,\n NEGOTIABLE_PROTOCOL_VERSIONS,\n DRAFT_PROTOCOL_VERSION\n} from '../../types.ts';\nimport { clientChecks } from '../../checks/index.ts';\n\nexport class InitializeScenario extends HandlerScenario {\n name = 'initialize';\n readonly source = {\n introducedIn: '2025-06-18',\n removedIn: DRAFT_PROTOCOL_VERSION\n } as const;\n description = 'Tests MCP client initialization handshake';\n\n private checks: ConformanceCheck[] = [];\n\n handler(_getBaseUrl: () => string): RequestListener {\n this.checks = [];\n return (req, res) => this.handleRequest(req, res);\n }\n\n /** Plumbing only: connect (implicit) and make one ordinary request. */\n readonly steps = [{ op: 'tools/list' }] as const;\n\n getChecks(): ConformanceCheck[] {\n return this.checks;\n }\n\n private handleRequest(\n req: http.IncomingMessage,\n res: http.ServerResponse\n ): void {\n // This server offers no SSE stream: a GET (a client opening one, or\n // falling back to the old HTTP+SSE transport) or a DELETE has no body to\n // parse, and is told so.\n if (req.method !== 'POST') {\n res.writeHead(405, { Allow: 'POST' });\n res.end('Method Not Allowed');\n return;\n }\n\n let body = '';\n\n req.on('data', (chunk) => {\n body += chunk.toString();\n });\n\n req.on('end', () => {\n try {\n const request = JSON.parse(body);\n\n if (request.method === 'initialize') {\n this.handleInitialize(request, res);\n } else if (request.method === 'tools/list') {\n this.handleToolsList(request, res);\n } else if (request.method === 'notifications/initialized') {\n // Per MCP spec 2025-11-25 section 2.1 (Sending Messages to the Server),\n // point 4: \"If the input is a JSON-RPC response or notification ...\n // the server MUST return HTTP status code 202 Accepted with no body.\"\n res.writeHead(202);\n res.end();\n } else if (request.method === 'ping' || request.id === undefined) {\n // Empty result for ping; notifications and responses get none.\n res.writeHead(200, { 'Content-Type': 'application/json' });\n res.end(\n JSON.stringify({\n jsonrpc: '2.0',\n id: request.id,\n result: {}\n })\n );\n } else {\n // A method this dated server does not have — notably the\n // 2026-07-28 `server/discover` probe of a dual-era client, which\n // must be turned away so the client falls back to `initialize`\n // rather than read an empty result as a discovery.\n res.writeHead(404, { 'Content-Type': 'application/json' });\n res.end(\n JSON.stringify({\n jsonrpc: '2.0',\n id: request.id,\n error: {\n code: -32601,\n message: `Method not found: ${request.method}`\n }\n })\n );\n }\n } catch (error) {\n res.writeHead(400, { 'Content-Type': 'application/json' });\n res.end(\n JSON.stringify({\n jsonrpc: '2.0',\n error: {\n code: -32700,\n message: `Parse error ${error}`\n }\n })\n );\n }\n });\n }\n\n private handleInitialize(request: any, res: http.ServerResponse): void {\n const initializeRequest = request.params;\n\n const check =\n clientChecks.createClientInitializationCheck(initializeRequest);\n this.checks.push(check);\n\n const serverInfo = {\n name: 'test-server',\n version: '1.0.0'\n };\n\n this.checks.push(clientChecks.createServerInfoCheck(serverInfo));\n\n // Echo back client's version if valid, otherwise use latest\n const clientVersion = initializeRequest?.protocolVersion;\n const responseVersion = NEGOTIABLE_PROTOCOL_VERSIONS.includes(clientVersion)\n ? clientVersion\n : LATEST_SPEC_VERSION;\n\n const response = {\n jsonrpc: '2.0',\n id: request.id,\n result: {\n protocolVersion: responseVersion,\n serverInfo,\n capabilities: {}\n }\n };\n\n res.writeHead(200, { 'Content-Type': 'application/json' });\n res.end(JSON.stringify(response));\n }\n\n private handleToolsList(request: any, res: http.ServerResponse): void {\n const response = {\n jsonrpc: '2.0',\n id: request.id,\n result: {\n tools: []\n }\n };\n\n res.writeHead(200, { 'Content-Type': 'application/json' });\n res.end(JSON.stringify(response));\n }\n}\n",[],[150,501,833,884],"5bab1a13-bde9-4a6a-a3c2-171b7b9e283f","d60e02ce-ad13-11f1-8e58-1607ee4eb77e",373,["D",1789375893989],"/**\n * HTTP Standard Headers conformance test scenario for MCP clients (SEP-2243)\n *\n * Tests that clients include the required standard MCP request headers on\n * Streamable HTTP POST requests:\n * - `Mcp-Method`: mirrors the `method` field from the JSON-RPC request body\n * - `Mcp-Name`: mirrors `params.name` or `params.uri` for tools/call,\n * resources/read, and prompts/get requests\n *\n * This is a Scenario (acts as a test server that inspects incoming requests\n * from the client under test).\n */\n\nimport http from 'node:http';\nimport { ConformanceCheck } from '../../types.ts';\nimport { BaseHttpScenario } from './http-base.ts';\n\nconst SPEC_REFERENCE = {\n id: 'SEP-2243-Standard-Headers',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http#standard-request-headers'\n};\n\nexport class HttpStandardHeadersScenario extends BaseHttpScenario {\n name = 'http-standard-headers';\n description =\n 'Tests that client includes Mcp-Method and Mcp-Name headers on HTTP POST requests (SEP-2243)';\n\n /**\n * Which checks are recorded is read off `this.checks` itself, never off\n * instance state: the hosted server judges a merged log in a fresh\n * instance, and a method only an instance field remembered would read as\n * never sent — SUCCESS and SKIPPED for the same method.\n *\n * Every request is judged, and each outcome is recorded once per check\n * name: a conforming client adds one SUCCESS row per method however often\n * it calls it, and a later request that breaks the rule still adds its\n * FAILURE (getChecks() lets it win).\n */\n private recorded(name: string, status: ConformanceCheck['status']): boolean {\n return this.checks.some((c) => c.name === name && c.status === status);\n }\n\n private static methodCheckName(method: string): string {\n return `ClientMcpMethodHeader_${method.replace(/\\//g, '_')}`;\n }\n\n private static nameCheckName(method: string): string {\n return `ClientMcpNameHeader_${method.replace(/\\//g, '_')}`;\n }\n\n getChecks(): ConformanceCheck[] {\n // Build a fresh array each call so getChecks() is idempotent — the runner\n // may call it more than once and we must not accumulate duplicates. One\n // row per check name (a merged log can hold the same method from several\n // processes or connections): the first FAILURE when any request broke\n // the rule, whenever it came, else the first row. `this.checks` is left\n // as the raw log.\n const byName = new Map();\n for (const c of this.checks) {\n const kept = byName.get(c.name);\n if (!kept || (kept.status !== 'FAILURE' && c.status === 'FAILURE'))\n byName.set(c.name, c);\n }\n const seen = new Set(byName.keys());\n const result = [...byName.values()];\n\n // SEP-2243 requires Mcp-Method on \"all requests and notifications\". A\n // client that never sent prompts/list isn't violating SEP-2243 — it just\n // didn't exercise that path. Emit SKIPPED (not FAILURE) so a prompts-less\n // client doesn't show red, but the gap is still visible in the report.\n // The initialize handshake is not part of 2026-07-28 (changelog: \"remove\n // the initialize/notifications/initialized handshake\"), so it is neither\n // expected nor judged here; see LEGACY_HANDSHAKE.\n const expectedMethods = [\n 'tools/list',\n 'tools/call',\n 'resources/list',\n 'resources/read',\n 'prompts/list',\n 'prompts/get'\n ];\n\n for (const method of expectedMethods) {\n if (!seen.has(HttpStandardHeadersScenario.methodCheckName(method))) {\n result.push({\n id: 'sep-2243-client-includes-standard-headers',\n name: HttpStandardHeadersScenario.methodCheckName(method),\n description: `Client sends correct Mcp-Method header on ${method} request`,\n status: 'SKIPPED',\n timestamp: new Date().toISOString(),\n errorMessage: `Client did not send a ${method} request; Mcp-Method header was not exercised for this method.`,\n specReferences: [SPEC_REFERENCE]\n });\n }\n }\n\n const expectedNameMethods = ['tools/call', 'resources/read', 'prompts/get'];\n for (const method of expectedNameMethods) {\n if (!seen.has(HttpStandardHeadersScenario.nameCheckName(method))) {\n result.push({\n id: 'sep-2243-client-includes-standard-headers',\n name: HttpStandardHeadersScenario.nameCheckName(method),\n description: `Client sends correct Mcp-Name header on ${method} request`,\n status: 'SKIPPED',\n timestamp: new Date().toISOString(),\n errorMessage: `Client did not send a ${method} request; Mcp-Name header was not exercised for this method.`,\n specReferences: [SPEC_REFERENCE]\n });\n }\n }\n\n return result;\n }\n\n protected handlePost(\n req: http.IncomingMessage,\n res: http.ServerResponse,\n request: any\n ): void {\n // Check Mcp-Method header for every request\n this.checkMcpMethodHeader(req, request);\n\n // Route to handlers (initialize never gets here: the base class answers\n // it with the versions this 2026-07-28-only server supports)\n if (request.method === 'tools/list') {\n this.handleToolsList(res, request);\n } else if (request.method === 'tools/call') {\n this.checkMcpNameHeader(req, request, 'params.name');\n this.handleToolsCall(res, request);\n } else if (request.method === 'resources/list') {\n this.handleResourcesList(res, request);\n } else if (request.method === 'resources/read') {\n this.checkMcpNameHeader(req, request, 'params.uri');\n this.handleResourcesRead(res, request);\n } else if (request.method === 'prompts/list') {\n this.handlePromptsList(res, request);\n } else if (request.method === 'prompts/get') {\n this.checkMcpNameHeader(req, request, 'params.name');\n this.handlePromptsGet(res, request);\n } else if (request.id === undefined) {\n // Notifications - return 202 (Mcp-Method already checked above)\n this.sendNotificationAck(res);\n } else {\n this.sendGenericResult(res, request);\n }\n }\n\n /**\n * The legacy handshake. It is not part of 2026-07-28, and a dual-era client\n * may open with it to learn the server's era (basic/versioning, \"Backward\n * Compatibility with Initialization-Based Versions\"), so the 2026-07-28\n * Mcp-Method header is not expected on it.\n */\n private static readonly LEGACY_HANDSHAKE = new Set([\n 'initialize',\n 'notifications/initialized'\n ]);\n\n private checkMcpMethodHeader(req: http.IncomingMessage, request: any): void {\n const method = request.method;\n if (!method) return;\n if (HttpStandardHeadersScenario.LEGACY_HANDSHAKE.has(method)) return;\n\n const name = HttpStandardHeadersScenario.methodCheckName(method);\n\n // Header names are lowercased by Node.js http parser\n const mcpMethodHeader = req.headers['mcp-method'] as string | undefined;\n\n const errors: string[] = [];\n if (!mcpMethodHeader) {\n errors.push(\n `Missing Mcp-Method header on ${method} request. Clients MUST include the Mcp-Method header on all POST requests.`\n );\n } else if (mcpMethodHeader !== method) {\n // Header values are case-sensitive\n errors.push(\n `Mcp-Method header value '${mcpMethodHeader}' does not match body method '${method}'. Header values are case-sensitive.`\n );\n }\n const status = errors.length === 0 ? 'SUCCESS' : 'FAILURE';\n // This outcome is already recorded for this method.\n if (this.recorded(name, status)) return;\n\n this.checks.push({\n id: 'sep-2243-client-includes-standard-headers',\n name,\n description: `Client sends correct Mcp-Method header on ${method} request`,\n status,\n timestamp: new Date().toISOString(),\n errorMessage: errors.length > 0 ? errors.join('; ') : undefined,\n specReferences: [SPEC_REFERENCE],\n details: {\n expectedMethod: method,\n actualHeader: mcpMethodHeader\n }\n });\n }\n\n private checkMcpNameHeader(\n req: http.IncomingMessage,\n request: any,\n sourceField: string\n ): void {\n const method = request.method;\n\n const name = HttpStandardHeadersScenario.nameCheckName(method);\n\n const expectedValue =\n sourceField === 'params.uri' ? request.params?.uri : request.params?.name;\n\n const mcpNameHeader = req.headers['mcp-name'] as string | undefined;\n\n const errors: string[] = [];\n if (!mcpNameHeader) {\n errors.push(\n `Missing Mcp-Name header on ${method} request. Clients MUST include the Mcp-Name header for ${method} requests.`\n );\n } else if (mcpNameHeader !== expectedValue) {\n errors.push(\n `Mcp-Name header value '${mcpNameHeader}' does not match body ${sourceField} '${expectedValue}'.`\n );\n }\n const status = errors.length === 0 ? 'SUCCESS' : 'FAILURE';\n // Same de-dup guard as checkMcpMethodHeader: the harness advertises two\n // tools and two resources, so a client that calls both would otherwise\n // produce duplicate check rows for the same outcome.\n if (this.recorded(name, status)) return;\n\n this.checks.push({\n id: 'sep-2243-client-includes-standard-headers',\n name,\n description: `Client sends correct Mcp-Name header on ${method} request`,\n status,\n timestamp: new Date().toISOString(),\n errorMessage: errors.length > 0 ? errors.join('; ') : undefined,\n specReferences: [SPEC_REFERENCE],\n details: {\n method,\n sourceField,\n expectedValue,\n actualHeader: mcpNameHeader\n }\n });\n }\n\n protected discoverCapabilities(): object {\n return { tools: {}, resources: {}, prompts: {} };\n }\n\n private handleToolsList(res: http.ServerResponse, request: any): void {\n res.writeHead(200, {\n 'Content-Type': 'application/json',\n 'mcp-session-id': this.sessionId\n });\n\n res.end(\n JSON.stringify({\n jsonrpc: '2.0',\n id: request.id,\n result: {\n resultType: 'complete',\n ttlMs: 0,\n cacheScope: 'private',\n tools: [\n {\n name: 'test_headers',\n description:\n 'A simple tool used to test that HTTP headers are sent correctly',\n inputSchema: {\n type: 'object',\n properties: {},\n required: []\n }\n },\n {\n name: 'my-hyphenated-tool',\n description:\n 'Tool with hyphen in name to test special chars in Mcp-Name header',\n inputSchema: {\n type: 'object',\n properties: {},\n required: []\n }\n }\n ]\n }\n })\n );\n }\n\n private handleToolsCall(res: http.ServerResponse, request: any): void {\n res.writeHead(200, {\n 'Content-Type': 'application/json',\n 'mcp-session-id': this.sessionId\n });\n\n res.end(\n JSON.stringify({\n jsonrpc: '2.0',\n id: request.id,\n result: {\n resultType: 'complete',\n content: [\n {\n type: 'text',\n text: 'Headers test completed'\n }\n ]\n }\n })\n );\n }\n\n private handleResourcesList(res: http.ServerResponse, request: any): void {\n res.writeHead(200, {\n 'Content-Type': 'application/json',\n 'mcp-session-id': this.sessionId\n });\n\n res.end(\n JSON.stringify({\n jsonrpc: '2.0',\n id: request.id,\n result: {\n resultType: 'complete',\n ttlMs: 0,\n cacheScope: 'private',\n resources: [\n {\n uri: 'file:///path/to/file%20name.txt',\n name: 'File with spaces',\n description: 'Resource URI with percent-encoded spaces'\n },\n {\n uri: 'https://example.com/resource?id=123',\n name: 'Resource with query string',\n description: 'Resource URI with query string'\n }\n ]\n }\n })\n );\n }\n\n private handleResourcesRead(res: http.ServerResponse, request: any): void {\n res.writeHead(200, {\n 'Content-Type': 'application/json',\n 'mcp-session-id': this.sessionId\n });\n\n res.end(\n JSON.stringify({\n jsonrpc: '2.0',\n id: request.id,\n result: {\n resultType: 'complete',\n ttlMs: 0,\n cacheScope: 'private',\n contents: []\n }\n })\n );\n }\n\n private handlePromptsList(res: http.ServerResponse, request: any): void {\n res.writeHead(200, {\n 'Content-Type': 'application/json',\n 'mcp-session-id': this.sessionId\n });\n\n res.end(\n JSON.stringify({\n jsonrpc: '2.0',\n id: request.id,\n result: {\n resultType: 'complete',\n ttlMs: 0,\n cacheScope: 'private',\n prompts: [\n {\n name: 'test_prompt',\n description: 'A simple prompt for header testing'\n }\n ]\n }\n })\n );\n }\n\n private handlePromptsGet(res: http.ServerResponse, request: any): void {\n res.writeHead(200, {\n 'Content-Type': 'application/json',\n 'mcp-session-id': this.sessionId\n });\n\n res.end(\n JSON.stringify({\n jsonrpc: '2.0',\n id: request.id,\n result: {\n resultType: 'complete',\n messages: []\n }\n })\n );\n }\n}\n",[],[150,501,833,633],"48561a19-ffb7-4234-93f1-5c020eb1bc6b","http-custom-headers.ts","d5a72d4c-ad13-11f1-a612-1607ee4eb77e",372,["D",1789375893700],"import type { ScenarioContext } from '../../mock-server/index.ts';\nimport type { Step } from '../../steps/index.ts';\n/**\n * HTTP Custom Headers conformance test scenario for MCP clients (SEP-2243)\n *\n * Tests that clients correctly handle the `x-mcp-header` extension property:\n * 1. Mirror annotated tool parameter values into `Mcp-Param-{Name}` headers\n * 2. Apply correct value encoding (plain ASCII, Base64 for non-ASCII)\n * 3. Reject tool definitions with invalid `x-mcp-header` annotations\n *\n * This is a Scenario (acts as a test server that inspects incoming requests\n * from the client under test).\n */\n\nimport http from 'node:http';\nimport { ScenarioUrls, ConformanceCheck } from '../../types.ts';\nimport { BaseHttpScenario } from './http-base.ts';\n\nconst SPEC_REFERENCE_CUSTOM = {\n id: 'SEP-2243-Custom-Headers',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http#custom-headers-from-tool-parameters'\n};\n\nconst SPEC_REFERENCE_ENCODING = {\n id: 'SEP-2243-Value-Encoding',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http#value-encoding'\n};\n\nconst SPEC_REFERENCE_TOOL_DEF = {\n id: 'SEP-2243-x-mcp-header',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/server/tools#x-mcp-header'\n};\n\n/**\n * Every requirement-level check ID HttpCustomHeadersScenario can emit\n * (SEP-2243). Declared-but-unemitted checks are backfilled as FAILURE by\n * getChecks() — same pattern as request-metadata.ts — so the emitted ID set\n * is stable for traceability even when the client never exercises the\n * feature.\n */\nexport const CUSTOM_HEADERS_DECLARED_CHECK_IDS = [\n 'sep-2243-client-supports-custom-headers',\n 'sep-2243-client-mirrors-designated-params',\n 'sep-2243-client-encode-values',\n 'sep-2243-client-base64-unsafe',\n 'sep-2243-client-omit-null'\n] as const;\n\n/**\n * Every requirement-level check ID HttpInvalidToolHeadersScenario can emit\n * (SEP-2243).\n */\nexport const INVALID_TOOL_DECLARED_CHECK_IDS = [\n 'sep-2243-client-reject-invalid-tool',\n 'sep-2243-x-mcp-header-not-empty',\n 'sep-2243-x-mcp-header-charset',\n 'sep-2243-x-mcp-header-unique',\n 'sep-2243-x-mcp-header-primitive-only'\n] as const;\n\n/**\n * Invalid tool definitions served by HttpInvalidToolHeadersScenario, keyed by\n * tool name, mapped to the SEP-2243 x-mcp-header constraint each one\n * violates. The check for \"client did not call this tool\" is emitted under\n * the constraint's requirement ID so each constraint traces to a check.\n */\nconst INVALID_TOOL_CONSTRAINT_IDS: Record = {\n invalid_empty_header: 'sep-2243-x-mcp-header-not-empty',\n invalid_object_header: 'sep-2243-x-mcp-header-primitive-only',\n invalid_array_header: 'sep-2243-x-mcp-header-primitive-only',\n invalid_null_header: 'sep-2243-x-mcp-header-primitive-only',\n invalid_number_header: 'sep-2243-x-mcp-header-primitive-only',\n invalid_duplicate_same_case: 'sep-2243-x-mcp-header-unique',\n invalid_duplicate_diff_case: 'sep-2243-x-mcp-header-unique',\n invalid_space_in_name: 'sep-2243-x-mcp-header-charset',\n invalid_colon_in_name: 'sep-2243-x-mcp-header-charset',\n invalid_non_ascii_name: 'sep-2243-x-mcp-header-charset',\n invalid_control_char_name: 'sep-2243-x-mcp-header-charset'\n};\n\n/**\n * Decodes a header value that may be Base64-encoded.\n * Base64-encoded values use the format: =?base64?{Base64EncodedValue}?=\n */\nfunction decodeHeaderValue(value: string): string {\n const base64Match = value.match(/^=\\?base64\\?(.*)\\?=$/);\n if (base64Match) {\n return Buffer.from(base64Match[1], 'base64').toString('utf-8');\n }\n return value;\n}\n\n/**\n * Check if a value needs Base64 encoding per the spec:\n * - Non-ASCII characters\n * - Control characters\n * - Leading/trailing whitespace\n */\nfunction needsBase64Encoding(value: string): boolean {\n // Check for non-ASCII or control characters\n for (let i = 0; i < value.length; i++) {\n const code = value.charCodeAt(i);\n if (code < 0x20 || code > 0x7e) {\n // Allow space (0x20) and tab (0x09) only inside values, not at edges\n if (code === 0x09) return true; // tab always needs encoding\n if (code < 0x20) return true; // other control chars\n if (code > 0x7e) return true; // non-ASCII\n }\n }\n // Check for leading/trailing whitespace\n if (value !== value.trim()) return true;\n return false;\n}\n\n/**\n * Checks if a raw header value is properly encoded for a body value that\n * needs Base64 encoding. Returns null if valid, error string if invalid.\n */\nfunction validateEncodedHeader(\n rawHeader: string,\n bodyValue: string,\n valueType?: string\n): string | null {\n if (needsBase64Encoding(bodyValue)) {\n // Value requires Base64 encoding\n const base64Match = rawHeader.match(/^=\\?base64\\?(.*)\\?=$/);\n\n if (!base64Match) {\n return `Value '${bodyValue}' requires Base64 encoding but header was sent as plain: '${rawHeader}'`;\n }\n const decoded = Buffer.from(base64Match[1], 'base64').toString('utf-8');\n if (valueType === 'number' || valueType === 'integer') {\n return compareNumericValues(decoded, bodyValue);\n }\n if (decoded !== bodyValue) {\n return `Base64-decoded header value '${decoded}' does not match body value '${bodyValue}'`;\n }\n return null;\n }\n // Plain ASCII - compare directly (after decoding if Base64 was used)\n const decoded = decodeHeaderValue(rawHeader);\n if (valueType === 'number' || valueType === 'integer') {\n return compareNumericValues(decoded, bodyValue);\n }\n if (decoded !== bodyValue) {\n return `Header value '${decoded}' (raw: '${rawHeader}') does not match body value '${bodyValue}'`;\n }\n return null;\n}\n\n/**\n * Compare two string representations of numbers numerically.\n * For integers, requires exact match. For decimals, allows\n * a tolerance of 1e-9 to account for cross-SDK floating point\n * representation differences.\n */\nfunction compareNumericValues(\n headerValue: string,\n bodyValue: string\n): string | null {\n const headerNum = Number(headerValue);\n const bodyNum = Number(bodyValue);\n if (isNaN(headerNum) || isNaN(bodyNum)) {\n return `Non-numeric value in number comparison: header='${headerValue}', body='${bodyValue}'`;\n }\n if (Number.isInteger(bodyNum)) {\n // Integer: require exact numeric match (e.g. 42 === 42.0)\n if (headerNum !== bodyNum) {\n return `Numeric header value ${headerNum} does not match body value ${bodyNum}`;\n }\n } else {\n // Decimal: allow tolerance of 1e-9\n if (Math.abs(headerNum - bodyNum) > 1e-9) {\n return `Numeric header value ${headerNum} does not match body value ${bodyNum} (difference ${Math.abs(headerNum - bodyNum)} exceeds tolerance 1e-9)`;\n }\n }\n return null;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// HttpCustomHeadersScenario - tests that clients mirror x-mcp-header params\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * The tool calls whose argument values exercise the encoding edge cases.\n * Handed to the client twice from this one list, so the two cannot drift: as\n * `toolCalls` in its context (what a client with a handler for this scenario\n * reads) and as `tools/call` steps (what a generic or hand-driven client\n * follows).\n */\nconst TOOL_CALLS = [\n {\n name: 'test_custom_headers',\n arguments: {\n region: 'us-west1',\n priority: 42,\n verbose: false,\n debug: true,\n empty_val: '',\n method_val: 'test-method',\n float_val: 3.14159,\n non_ascii_val: 'Hello, 世界',\n whitespace_val: ' padded ',\n leading_space_val: ' us-west1',\n trailing_space_val: 'us-west1 ',\n internal_space_val: 'us west 1',\n control_char_val: 'line1\\nline2',\n crlf_val: 'line1\\r\\nline2',\n tab_val: '\\tindented',\n query: 'SELECT * FROM users'\n }\n },\n {\n name: 'test_custom_headers_null',\n arguments: {\n region: 'us-east1',\n priority: 1,\n verbose: null,\n query: 'SELECT 1'\n }\n }\n];\n\nexport class HttpCustomHeadersScenario extends BaseHttpScenario {\n name = 'http-custom-headers';\n description =\n 'Tests that client mirrors x-mcp-header tool parameters into Mcp-Param headers with correct encoding (SEP-2243)';\n\n /** List first: the x-mcp-header annotations are in the tool schemas. */\n readonly steps: readonly Step[] = [\n { op: 'tools/list' },\n ...TOOL_CALLS.map((call) => ({ op: 'tools/call' as const, ...call }))\n ];\n\n private toolCallReceived: boolean = false;\n private nullToolCallReceived: boolean = false;\n /** The tools/call being judged carried an x-mcp-header argument. */\n private annotatedArgumentSent = false;\n\n /** Read by start() for the CLI runner and by the hosted server per cell. */\n protected scenarioContext(): Record {\n return { toolCalls: TOOL_CALLS };\n }\n\n async start(ctx: ScenarioContext): Promise {\n const urls = await super.start(ctx);\n urls.context = this.scenarioContext();\n return urls;\n }\n\n getChecks(): ConformanceCheck[] {\n // Declared-but-unemitted -> FAILURE (request-metadata.ts pattern). Keeps\n // the emitted ID set stable for traceability even when the client never\n // calls the annotated tools. The `some()` guard makes this idempotent.\n for (const id of CUSTOM_HEADERS_DECLARED_CHECK_IDS) {\n if (this.checks.some((c) => c.id === id)) continue;\n const missingNullCall =\n id === 'sep-2243-client-omit-null' && !this.nullToolCallReceived;\n this.checks.push({\n id,\n name: 'NotObserved',\n description: `Declared check ${id} was never emitted`,\n status: 'FAILURE',\n timestamp: new Date().toISOString(),\n errorMessage: missingNullCall\n ? 'Client did not send a tools/call request for test_custom_headers_null to test null/omitted parameter handling.'\n : this.toolCallReceived\n ? 'Check was not observed: no tool call exercised it.'\n : 'Client did not send a tools/call request for test_custom_headers.',\n specReferences: [SPEC_REFERENCE_CUSTOM]\n });\n }\n return this.checks;\n }\n\n protected handlePost(\n req: http.IncomingMessage,\n res: http.ServerResponse,\n request: any\n ): void {\n if (request.method === 'tools/list') {\n this.handleToolsList(res, request);\n } else if (request.method === 'tools/call') {\n this.handleToolsCall(req, res, request);\n } else if (request.id === undefined) {\n this.sendNotificationAck(res);\n } else {\n this.sendGenericResult(res, request);\n }\n }\n\n private handleToolsList(res: http.ServerResponse, request: any): void {\n this.sendJson(res, {\n jsonrpc: '2.0',\n id: request.id,\n result: {\n resultType: 'complete',\n ttlMs: 300000,\n cacheScope: 'private',\n tools: [\n {\n name: 'test_custom_headers',\n description:\n 'A tool with x-mcp-header annotations to test custom header mirroring and encoding',\n inputSchema: {\n type: 'object',\n properties: {\n region: {\n type: 'string',\n description: 'Plain ASCII string value',\n 'x-mcp-header': 'Region'\n },\n priority: {\n type: 'integer',\n description: 'Integer numeric value',\n 'x-mcp-header': 'Priority'\n },\n verbose: {\n type: 'boolean',\n description: 'Boolean value',\n 'x-mcp-header': 'Verbose'\n },\n debug: {\n type: 'boolean',\n description: 'Boolean true value',\n 'x-mcp-header': 'Debug'\n },\n empty_val: {\n type: 'string',\n description: 'Empty string value',\n 'x-mcp-header': 'EmptyVal'\n },\n method_val: {\n type: 'string',\n description:\n 'Value for header named \"Method\" — tests that x-mcp-header \"Method\" produces Mcp-Param-Method (not Mcp-Method)',\n 'x-mcp-header': 'Method'\n },\n float_val: {\n type: 'number',\n description:\n 'Floating point value — no x-mcp-header annotation, should not be mirrored'\n },\n non_ascii_val: {\n type: 'string',\n description:\n 'Non-ASCII string value — requires Base64 encoding',\n 'x-mcp-header': 'NonAscii'\n },\n whitespace_val: {\n type: 'string',\n description:\n 'String with leading/trailing whitespace — requires Base64 encoding',\n 'x-mcp-header': 'Whitespace'\n },\n leading_space_val: {\n type: 'string',\n description:\n 'String with leading space only — requires Base64 encoding',\n 'x-mcp-header': 'LeadingSpace'\n },\n trailing_space_val: {\n type: 'string',\n description:\n 'String with trailing space only — requires Base64 encoding',\n 'x-mcp-header': 'TrailingSpace'\n },\n internal_space_val: {\n type: 'string',\n description:\n 'String with internal spaces only — plain ASCII, no Base64',\n 'x-mcp-header': 'InternalSpace'\n },\n control_char_val: {\n type: 'string',\n description:\n 'String with control characters — requires Base64 encoding',\n 'x-mcp-header': 'ControlChar'\n },\n crlf_val: {\n type: 'string',\n description:\n 'String with carriage return and line feed — requires Base64 encoding',\n 'x-mcp-header': 'CrLf'\n },\n tab_val: {\n type: 'string',\n description:\n 'String with leading tab — requires Base64 encoding',\n 'x-mcp-header': 'Tab'\n },\n query: {\n type: 'string',\n description:\n 'No x-mcp-header annotation - should not be mirrored'\n }\n },\n required: ['region', 'priority', 'query']\n }\n },\n {\n name: 'test_custom_headers_null',\n description:\n 'A tool for testing null/omitted x-mcp-header parameter handling',\n inputSchema: {\n type: 'object',\n properties: {\n region: {\n type: 'string',\n description: 'Plain ASCII string value',\n 'x-mcp-header': 'Region'\n },\n priority: {\n type: 'integer',\n description: 'Integer numeric value',\n 'x-mcp-header': 'Priority'\n },\n verbose: {\n type: 'boolean',\n description: 'Boolean value — will be null to test omission',\n 'x-mcp-header': 'Verbose'\n },\n query: {\n type: 'string',\n description: 'No x-mcp-header annotation'\n }\n },\n required: ['region', 'priority', 'query']\n }\n }\n ]\n }\n });\n }\n\n private handleToolsCall(\n req: http.IncomingMessage,\n res: http.ServerResponse,\n request: any\n ): void {\n const toolName = request.params?.name;\n const args = request.params?.arguments || {};\n\n if (toolName === 'test_custom_headers') {\n this.toolCallReceived = true;\n\n // SEP-2243 \"MCP clients MUST support this feature\": observable as the\n // client calling the annotated tool with at least one mirrored\n // Mcp-Param-* header. The per-parameter checks below then validate each\n // mirrored value individually. A call that carries none of the\n // annotated arguments has nothing to mirror and shows nothing either\n // way, so this is judged only on a call that sent one of them (see\n // checkParamHeader()); a later call can still show it.\n const hasAnyParamHeader = Object.keys(req.headers).some((h) =>\n h.startsWith('mcp-param-')\n );\n const supportsAt = this.checks.length;\n this.annotatedArgumentSent = false;\n const supports: ConformanceCheck = {\n id: 'sep-2243-client-supports-custom-headers',\n name: 'ClientSupportsCustomHeaders',\n description:\n 'Client supports custom headers: calls the x-mcp-header annotated tool and mirrors at least one parameter',\n status: hasAnyParamHeader ? 'SUCCESS' : 'FAILURE',\n timestamp: new Date().toISOString(),\n errorMessage: hasAnyParamHeader\n ? undefined\n : 'Client called test_custom_headers but sent no Mcp-Param-* headers.',\n specReferences: [SPEC_REFERENCE_CUSTOM]\n };\n\n // Check Mcp-Param-Region header (plain ASCII string)\n this.checkParamHeader(req, 'Region', args.region, 'string');\n\n // Check Mcp-Param-Priority header (integer)\n this.checkParamHeader(req, 'Priority', args.priority, 'integer');\n\n // Check Mcp-Param-Verbose header (boolean value)\n // checkParamHeader already FAILs on missing header, so this also covers\n // \"optional parameter present → client MUST include header\" without a\n // separate check id.\n if (args.verbose !== undefined && args.verbose !== null) {\n this.checkParamHeader(req, 'Verbose', args.verbose, 'boolean');\n }\n\n // Check Mcp-Param-Debug header (boolean true value)\n if (args.debug !== undefined && args.debug !== null) {\n this.checkParamHeader(req, 'Debug', args.debug, 'boolean');\n }\n\n // Check Mcp-Param-EmptyVal header (empty string → empty header value)\n if (args.empty_val !== undefined && args.empty_val !== null) {\n this.checkParamHeader(req, 'EmptyVal', args.empty_val, 'string');\n }\n\n // Check Mcp-Param-Method header (x-mcp-header \"Method\" → Mcp-Param-Method, NOT Mcp-Method)\n if (args.method_val !== undefined && args.method_val !== null) {\n this.checkParamHeader(req, 'Method', args.method_val, 'string');\n }\n\n // float_val is intentionally unannotated: SEP-2243 forbids x-mcp-header on\n // `number`-typed properties, so it is served without one. Assert no header\n // was sent — same \"designated params only\" rule as the `query` check below.\n const floatHeader = req.headers['mcp-param-floatval'] as\n | string\n | undefined;\n this.checks.push({\n id: 'sep-2243-client-mirrors-designated-params',\n name: 'ClientCustomHeaderNoMirrorNumber',\n description:\n 'Client MUST NOT add Mcp-Param headers for parameters without x-mcp-header (number-typed float_val is served unannotated per SEP-2243)',\n status: floatHeader === undefined ? 'SUCCESS' : 'FAILURE',\n timestamp: new Date().toISOString(),\n errorMessage:\n floatHeader !== undefined\n ? `Found unexpected Mcp-Param-FloatVal header '${floatHeader}' for an unannotated number parameter`\n : undefined,\n specReferences: [SPEC_REFERENCE_CUSTOM]\n });\n\n // Check Mcp-Param-NonAscii header (requires Base64 encoding)\n if (args.non_ascii_val !== undefined && args.non_ascii_val !== null) {\n this.checkParamHeader(req, 'NonAscii', args.non_ascii_val, 'string');\n }\n\n // Check Mcp-Param-Whitespace header (leading/trailing whitespace → Base64)\n if (args.whitespace_val !== undefined && args.whitespace_val !== null) {\n this.checkParamHeader(req, 'Whitespace', args.whitespace_val, 'string');\n }\n\n // Check Mcp-Param-LeadingSpace header (leading space only → Base64)\n if (\n args.leading_space_val !== undefined &&\n args.leading_space_val !== null\n ) {\n this.checkParamHeader(\n req,\n 'LeadingSpace',\n args.leading_space_val,\n 'string'\n );\n }\n\n // Check Mcp-Param-TrailingSpace header (trailing space only → Base64)\n if (\n args.trailing_space_val !== undefined &&\n args.trailing_space_val !== null\n ) {\n this.checkParamHeader(\n req,\n 'TrailingSpace',\n args.trailing_space_val,\n 'string'\n );\n }\n\n // Check Mcp-Param-InternalSpace header (internal spaces only → plain ASCII, no Base64)\n if (\n args.internal_space_val !== undefined &&\n args.internal_space_val !== null\n ) {\n this.checkParamHeader(\n req,\n 'InternalSpace',\n args.internal_space_val,\n 'string'\n );\n }\n\n // Check Mcp-Param-ControlChar header (control characters → Base64)\n if (\n args.control_char_val !== undefined &&\n args.control_char_val !== null\n ) {\n this.checkParamHeader(\n req,\n 'ControlChar',\n args.control_char_val,\n 'string'\n );\n }\n\n // Check Mcp-Param-CrLf header (carriage return + line feed → Base64)\n if (args.crlf_val !== undefined && args.crlf_val !== null) {\n this.checkParamHeader(req, 'CrLf', args.crlf_val, 'string');\n }\n\n // Check Mcp-Param-Tab header (leading tab → Base64)\n if (args.tab_val !== undefined && args.tab_val !== null) {\n this.checkParamHeader(req, 'Tab', args.tab_val, 'string');\n }\n\n // Check that 'query' (no x-mcp-header) is NOT mirrored — the negative\n // half of \"mirror the *designated* parameter values\".\n const queryHeader = req.headers['mcp-param-query'] as string | undefined;\n this.checks.push({\n id: 'sep-2243-client-mirrors-designated-params',\n name: 'ClientCustomHeaderNoMirrorUnannotated',\n description:\n 'Client MUST NOT add Mcp-Param headers for parameters without x-mcp-header',\n status: queryHeader === undefined ? 'SUCCESS' : 'FAILURE',\n timestamp: new Date().toISOString(),\n errorMessage:\n queryHeader !== undefined\n ? `Found unexpected Mcp-Param-Query header '${queryHeader}' for unannotated parameter`\n : undefined,\n specReferences: [SPEC_REFERENCE_CUSTOM]\n });\n // In the log where it was judged, ahead of the per-parameter checks.\n if (this.annotatedArgumentSent || hasAnyParamHeader)\n this.checks.splice(supportsAt, 0, supports);\n } else if (toolName === 'test_custom_headers_null') {\n this.nullToolCallReceived = true;\n\n // When value is null or not provided, client MUST omit the header\n const verboseHeader = req.headers['mcp-param-verbose'] as\n | string\n | undefined;\n this.checks.push({\n id: 'sep-2243-client-omit-null',\n name: 'ClientCustomHeaderOmitNull',\n description:\n 'Client MUST omit Mcp-Param header when parameter value is null or not provided',\n status: verboseHeader === undefined ? 'SUCCESS' : 'FAILURE',\n timestamp: new Date().toISOString(),\n errorMessage:\n verboseHeader !== undefined\n ? `Mcp-Param-Verbose should be omitted when null/undefined, but got '${verboseHeader}'`\n : undefined,\n specReferences: [SPEC_REFERENCE_CUSTOM]\n });\n }\n\n this.sendJson(res, {\n jsonrpc: '2.0',\n id: request.id,\n result: {\n resultType: 'complete',\n content: [{ type: 'text', text: 'Custom headers test completed' }]\n }\n });\n }\n\n private checkParamHeader(\n req: http.IncomingMessage,\n headerName: string,\n bodyValue: any,\n valueType: string\n ): void {\n const headerKey = `mcp-param-${headerName.toLowerCase()}`;\n const rawHeaderValue = req.headers[headerKey] as string | undefined;\n\n if (bodyValue === undefined || bodyValue === null) return;\n this.annotatedArgumentSent = true;\n\n const errors: string[] = [];\n\n if (rawHeaderValue === undefined) {\n errors.push(\n `Missing Mcp-Param-${headerName} header. Client MUST include headers for x-mcp-header parameters.`\n );\n } else {\n // Convert body value to expected string representation\n let expectedString: string;\n switch (valueType) {\n case 'number':\n expectedString = String(bodyValue);\n break;\n case 'boolean':\n expectedString = bodyValue ? 'true' : 'false';\n break;\n default:\n expectedString = String(bodyValue);\n }\n\n // For numbers, compare numerically to allow for cross-SDK\n // floating point representation differences (e.g., \"42\" vs \"42.0\").\n // See SEP-2243 discussion on number precision.\n const validationError = validateEncodedHeader(\n rawHeaderValue,\n expectedString,\n valueType\n );\n if (validationError) {\n errors.push(validationError);\n }\n }\n\n // One check ID per SEP-2243 requirement, picked by what this parameter\n // actually exercises: Base64 wrapping for unsafe values, primitive\n // (number/boolean) string encoding, or plain mirroring. The per-parameter\n // detail lives in `name`/`details`.\n const needsBase64 =\n typeof bodyValue === 'string' && needsBase64Encoding(String(bodyValue));\n const checkId = needsBase64\n ? 'sep-2243-client-base64-unsafe'\n : valueType === 'number' ||\n valueType === 'integer' ||\n valueType === 'boolean'\n ? 'sep-2243-client-encode-values'\n : 'sep-2243-client-mirrors-designated-params';\n\n this.checks.push({\n id: checkId,\n name: `ClientCustomHeader_${headerName}`,\n description: `Client sends correct Mcp-Param-${headerName} header (${valueType} value)`,\n status: errors.length === 0 ? 'SUCCESS' : 'FAILURE',\n timestamp: new Date().toISOString(),\n errorMessage: errors.length > 0 ? errors.join('; ') : undefined,\n specReferences: [SPEC_REFERENCE_ENCODING],\n details: {\n headerName: `Mcp-Param-${headerName}`,\n rawHeaderValue,\n bodyValue,\n valueType,\n needsBase64\n }\n });\n }\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// HttpInvalidToolHeadersScenario - tests that clients reject invalid tools\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** Raw event: the client sent tools/list (SUCCESS) — or never did (FAILURE). */\nconst TOOLS_LIST_GATE_ID = 'sep-2243-invalid-tool-tools-list-gate';\n/** Raw event, one per tools/call: which tool, with the headers it carried. */\nconst TOOL_CALL_EVENT_ID = 'sep-2243-invalid-tool-call';\n\nexport class HttpInvalidToolHeadersScenario extends BaseHttpScenario {\n name = 'http-invalid-tool-headers';\n description =\n 'Tests that client rejects tools with invalid x-mcp-header annotations (SEP-2243)';\n allowClientError = true;\n /**\n * List, then call the one valid tool: proof the client kept it. The\n * invalid tools are never named here — calling one is the failure.\n */\n readonly steps = [\n { op: 'tools/list' },\n { op: 'tools/call', name: 'valid_tool', arguments: { region: 'us-west1' } }\n ] as const;\n\n /**\n * Verdicts are derived from the raw events in `this.checks` (tools/list\n * sent, each tools/call with its header observations), never from\n * instance state: the hosted server judges a merged log in a fresh\n * instance, and anything only an instance field knew would be lost — a\n * tool the client did call would read as never called.\n */\n getChecks(): ConformanceCheck[] {\n const calledTools = new Set(\n this.checks\n .filter((c) => c.id === TOOL_CALL_EVENT_ID)\n .map((c) => c.details?.tool)\n .filter((t): t is string => typeof t === 'string')\n );\n const verdicts: ConformanceCheck[] = [];\n if (!this.checks.some((c) => c.id === TOOLS_LIST_GATE_ID)) {\n verdicts.push({\n id: TOOLS_LIST_GATE_ID,\n name: 'ClientInvalidToolHeadersToolsList',\n description: 'Client requests tools/list',\n status: 'FAILURE',\n timestamp: new Date().toISOString(),\n errorMessage: 'Client did not send a tools/list request.',\n specReferences: [SPEC_REFERENCE_TOOL_DEF]\n });\n }\n\n // Check that valid_tool WAS called — proves client kept valid tools\n const validToolCalled = calledTools.has('valid_tool');\n verdicts.push({\n id: 'sep-2243-client-reject-invalid-tool',\n name: 'ClientKeepsValidTool',\n description: 'Client MUST keep valid tools while excluding invalid ones',\n status: validToolCalled ? 'SUCCESS' : 'FAILURE',\n timestamp: new Date().toISOString(),\n errorMessage: validToolCalled\n ? undefined\n : \"Client did not call 'valid_tool'. A single malformed tool definition must not prevent other valid tools from being used.\",\n specReferences: [SPEC_REFERENCE_TOOL_DEF]\n });\n\n // Check that the client did NOT call any of the invalid tools. Each\n // invalid tool violates one specific x-mcp-header constraint, so the\n // check is emitted under that constraint's requirement ID — the client\n // rejecting the tool is how the constraint is enforced on the wire.\n // A client that never listed the tools was never offered them: not\n // calling one proves nothing, so it is SKIPPED, not a pass (the\n // tools/list gate above already fails).\n const listed = this.checks.some((c) => c.id === TOOLS_LIST_GATE_ID);\n for (const [toolName, constraintId] of Object.entries(\n INVALID_TOOL_CONSTRAINT_IDS\n )) {\n const called = calledTools.has(toolName);\n verdicts.push({\n id: constraintId,\n name: `ClientRejectsInvalidTool_${toolName}`,\n description: `Client MUST NOT call tool '${toolName}' with invalid x-mcp-header`,\n status: called ? 'FAILURE' : listed ? 'SUCCESS' : 'SKIPPED',\n timestamp: new Date().toISOString(),\n errorMessage: called\n ? `Client called '${toolName}' which has an invalid x-mcp-header. Clients MUST reject (exclude) such tools.`\n : listed\n ? undefined\n : `Not exercised: the client never listed the tools, so it was never offered '${toolName}' to reject.`,\n specReferences: [SPEC_REFERENCE_TOOL_DEF]\n });\n }\n\n // Events first, verdicts after; `this.checks` itself is left as the raw\n // log so this is idempotent and the hosted server can re-judge it.\n return [...this.checks, ...verdicts];\n }\n\n protected handlePost(\n req: http.IncomingMessage,\n res: http.ServerResponse,\n request: any\n ): void {\n if (request.method === 'tools/list') {\n this.handleToolsList(res, request);\n } else if (request.method === 'tools/call') {\n this.handleToolsCall(req, res, request);\n } else if (request.id === undefined) {\n this.sendNotificationAck(res);\n } else {\n this.sendGenericResult(res, request);\n }\n }\n\n private handleToolsList(res: http.ServerResponse, request: any): void {\n if (!this.checks.some((c) => c.id === TOOLS_LIST_GATE_ID)) {\n this.checks.push({\n id: TOOLS_LIST_GATE_ID,\n name: 'ClientInvalidToolHeadersToolsList',\n description: 'Client requests tools/list',\n status: 'SUCCESS',\n timestamp: new Date().toISOString(),\n specReferences: [SPEC_REFERENCE_TOOL_DEF]\n });\n }\n\n this.sendJson(res, {\n jsonrpc: '2.0',\n id: request.id,\n result: {\n resultType: 'complete',\n ttlMs: 0,\n cacheScope: 'private',\n tools: [\n // ── Valid tool (should be kept by client) ──\n {\n name: 'valid_tool',\n description: 'A valid tool with correct x-mcp-header',\n inputSchema: {\n type: 'object',\n properties: {\n region: {\n type: 'string',\n 'x-mcp-header': 'Region'\n }\n },\n required: ['region']\n }\n },\n\n // ── Invalid: empty x-mcp-header value ──\n {\n name: 'invalid_empty_header',\n description:\n 'x-mcp-header MUST NOT be empty (MUST be rejected by client)',\n inputSchema: {\n type: 'object',\n properties: {\n value: { type: 'string', 'x-mcp-header': '' }\n },\n required: ['value']\n }\n },\n\n // ── Invalid: x-mcp-header on object type ──\n {\n name: 'invalid_object_header',\n description:\n 'x-mcp-header MUST only be on primitive types (MUST be rejected)',\n inputSchema: {\n type: 'object',\n properties: {\n data: { type: 'object', 'x-mcp-header': 'Data' }\n },\n required: ['data']\n }\n },\n\n // ── Invalid: x-mcp-header on array type ──\n {\n name: 'invalid_array_header',\n description:\n 'x-mcp-header MUST only be on primitive types (MUST be rejected)',\n inputSchema: {\n type: 'object',\n properties: {\n items: {\n type: 'array',\n items: { type: 'string' },\n 'x-mcp-header': 'Items'\n }\n },\n required: ['items']\n }\n },\n\n // ── Invalid: x-mcp-header on null type ──\n {\n name: 'invalid_null_header',\n description:\n 'x-mcp-header MUST only be on primitive types (MUST be rejected)',\n inputSchema: {\n type: 'object',\n properties: {\n nil: { type: 'null', 'x-mcp-header': 'Nil' }\n },\n required: ['nil']\n }\n },\n\n // ── Invalid: x-mcp-header on number type ──\n // `number` is a JSON Schema primitive but SEP-2243 excludes it from\n // the permitted set: \"Parameters with type `number` are not\n // permitted.\" Only integer, string and boolean may be annotated.\n {\n name: 'invalid_number_header',\n description:\n 'x-mcp-header MUST NOT be on number type (MUST be rejected)',\n inputSchema: {\n type: 'object',\n properties: {\n score: { type: 'number', 'x-mcp-header': 'Score' }\n },\n required: ['score']\n }\n },\n\n // ── Invalid: duplicate same-case x-mcp-header values ──\n {\n name: 'invalid_duplicate_same_case',\n description:\n 'Duplicate x-mcp-header \"Region\" on two properties (MUST be rejected)',\n inputSchema: {\n type: 'object',\n properties: {\n field1: { type: 'string', 'x-mcp-header': 'Region' },\n field2: { type: 'string', 'x-mcp-header': 'Region' }\n },\n required: ['field1', 'field2']\n }\n },\n\n // ── Invalid: duplicate case-insensitive x-mcp-header values ──\n {\n name: 'invalid_duplicate_diff_case',\n description:\n 'Duplicate case-insensitive x-mcp-header \"MyField\"/\"myfield\" (MUST be rejected)',\n inputSchema: {\n type: 'object',\n properties: {\n field1: { type: 'string', 'x-mcp-header': 'MyField' },\n field2: { type: 'string', 'x-mcp-header': 'myfield' }\n },\n required: ['field1', 'field2']\n }\n },\n\n // ── Invalid: space in x-mcp-header name ──\n {\n name: 'invalid_space_in_name',\n description:\n 'x-mcp-header MUST NOT contain space (MUST be rejected)',\n inputSchema: {\n type: 'object',\n properties: {\n value: { type: 'string', 'x-mcp-header': 'My Region' }\n },\n required: ['value']\n }\n },\n\n // ── Invalid: colon in x-mcp-header name ──\n {\n name: 'invalid_colon_in_name',\n description:\n 'x-mcp-header MUST NOT contain colon (MUST be rejected)',\n inputSchema: {\n type: 'object',\n properties: {\n value: {\n type: 'string',\n 'x-mcp-header': 'Region:Primary'\n }\n },\n required: ['value']\n }\n },\n\n // ── Invalid: non-ASCII in x-mcp-header name ──\n {\n name: 'invalid_non_ascii_name',\n description:\n 'x-mcp-header MUST contain only ASCII chars (MUST be rejected)',\n inputSchema: {\n type: 'object',\n properties: {\n value: { type: 'string', 'x-mcp-header': 'Région' }\n },\n required: ['value']\n }\n },\n\n // ── Invalid: control character in x-mcp-header name ──\n {\n name: 'invalid_control_char_name',\n description:\n 'x-mcp-header MUST NOT contain control chars (MUST be rejected)',\n inputSchema: {\n type: 'object',\n properties: {\n value: { type: 'string', 'x-mcp-header': 'Region\\t1' }\n },\n required: ['value']\n }\n }\n ]\n }\n });\n }\n\n private handleToolsCall(\n req: http.IncomingMessage,\n res: http.ServerResponse,\n request: any\n ): void {\n const toolName = request.params?.name;\n if (typeof toolName === 'string') {\n const mcpParamHeaders = Object.fromEntries(\n Object.entries(req.headers).filter(([k]) =>\n k.toLowerCase().startsWith('mcp-param-')\n )\n );\n this.checks.push({\n id: TOOL_CALL_EVENT_ID,\n name: 'ClientCalledTool',\n description: `Client called tool '${toolName}'`,\n status: 'INFO',\n timestamp: new Date().toISOString(),\n specReferences: [SPEC_REFERENCE_TOOL_DEF],\n details: {\n tool: toolName,\n arguments: request.params?.arguments,\n mcpParamHeaders\n }\n });\n }\n\n this.sendJson(res, {\n jsonrpc: '2.0',\n id: request.id,\n result: {\n resultType: 'complete',\n content: [{ type: 'text', text: 'Tool call received' }]\n }\n });\n }\n}\n",[],[150,501,833,899],"210f9447-3b48-481b-8067-3753f747eebd","http-base.ts","df69518e-ad13-11f1-a016-1607ee4eb77e",335,["D",1789346127689],"import { withRequiredDraftResultFields } from '../../mock-server/stateless.ts';\n/**\n * Shared HTTP test-server scaffold for client-under-test SEP-2243 scenarios.\n *\n * A scenario that needs to act as a Streamable-HTTP MCP server, inspect\n * incoming client requests, and emit ConformanceChecks should extend this\n * class and implement handlePost() + getChecks(). start()/stop() and the\n * GET/DELETE/body-parse boilerplate are handled here.\n */\n\nimport http from 'node:http';\nimport {\n HandlerScenario,\n RequestListener,\n ConformanceCheck,\n ScenarioSource,\n DRAFT_PROTOCOL_VERSION\n} from '../../types.ts';\n\n/**\n * Schema-valid empty results for the standard list-shaped methods, keyed by\n * method. A Map, not an object literal, so a method name that collides with\n * Object.prototype (\"constructor\", \"toString\", ...) misses instead of\n * returning a function. Merged into the generic fallback so a list method a\n * scenario does not route still carries its required list member — a bare\n * `{}` fails schema validation and strict clients drop the connection before\n * the scenario's real checks run (#474). `tasks/list` exists only at\n * 2025-11-25 (the draft schema has no ListTasksResult); the empty member is\n * harmless on the draft wire. Non-list results (tools/call, resources/read,\n * prompts/get, ...) have no meaningful empty default and keep the bare\n * stamped fallback, so a route a scenario forgot surfaces instead of being\n * masked.\n */\nconst EMPTY_LIST_RESULTS: ReadonlyMap = new Map([\n ['tools/list', { tools: [] }],\n ['resources/list', { resources: [] }],\n ['resources/templates/list', { resourceTemplates: [] }],\n ['prompts/list', { prompts: [] }],\n ['roots/list', { roots: [] }],\n ['tasks/list', { tasks: [] }]\n]);\n\nexport abstract class BaseHttpScenario extends HandlerScenario {\n abstract name: string;\n abstract description: string;\n readonly source: ScenarioSource = { introducedIn: DRAFT_PROTOCOL_VERSION };\n\n protected checks: ConformanceCheck[] = [];\n protected sessionId: string = `session-${Date.now()}`;\n\n handler(_getBaseUrl: () => string): RequestListener {\n this.checks = [];\n this.sessionId = `session-${Date.now()}`;\n return (req, res) => this.handleRequest(req, res);\n }\n\n abstract getChecks(): ConformanceCheck[];\n\n protected handleRequest(\n req: http.IncomingMessage,\n res: http.ServerResponse\n ): void {\n if (req.method === 'GET') {\n res.writeHead(200, {\n 'Content-Type': 'text/event-stream',\n 'Cache-Control': 'no-cache',\n Connection: 'keep-alive',\n 'mcp-session-id': this.sessionId\n });\n res.write('data: \\n\\n');\n return;\n }\n if (req.method === 'DELETE') {\n res.writeHead(200);\n res.end();\n return;\n }\n if (req.method !== 'POST') {\n res.writeHead(405);\n res.end('Method Not Allowed');\n return;\n }\n\n // Decode the stream as UTF-8 so multi-byte characters that straddle a\n // chunk boundary aren't corrupted by per-chunk Buffer.toString().\n req.setEncoding('utf8');\n let body = '';\n req.on('data', (chunk) => {\n body += chunk;\n });\n req.on('end', () => {\n try {\n const request = JSON.parse(body);\n if (request.method === 'server/discover') {\n this.sendDiscover(res, request);\n return;\n }\n if (request.method === 'initialize' && this.isModernOnly()) {\n this.rejectLegacyInitialize(res, request);\n return;\n }\n this.handlePost(req, res, request);\n } catch (error) {\n res.writeHead(400, { 'Content-Type': 'application/json' });\n res.end(\n JSON.stringify({\n jsonrpc: '2.0',\n error: { code: -32700, message: `Parse error: ${error}` }\n })\n );\n }\n });\n }\n\n protected abstract handlePost(\n req: http.IncomingMessage,\n res: http.ServerResponse,\n request: any\n ): void;\n\n protected sendJson(res: http.ServerResponse, body: object): void {\n res.writeHead(200, {\n 'Content-Type': 'application/json',\n 'mcp-session-id': this.sessionId\n });\n res.end(JSON.stringify(body));\n }\n\n /**\n * Capabilities advertised to a 2026-07-28 client via `server/discover`.\n * Subclasses override to match the methods they actually serve.\n */\n protected discoverCapabilities(): object {\n return { tools: {} };\n }\n\n protected sendDiscover(res: http.ServerResponse, request: any): void {\n this.sendJson(res, {\n jsonrpc: '2.0',\n id: request.id,\n result: withRequiredDraftResultFields('server/discover', {\n supportedVersions: [DRAFT_PROTOCOL_VERSION],\n capabilities: this.discoverCapabilities(),\n serverInfo: { name: this.name + '-server', version: '1.0.0' }\n })\n });\n }\n\n /**\n * Whether this scenario exists only at 2026-07-28 (the scaffold's default\n * source). Extension scenarios built on it, such as the skills ones, run at\n * the dated revisions too and answer initialize themselves.\n */\n protected isModernOnly(): boolean {\n const source = this.source as { introducedIn?: string };\n return source.introducedIn === DRAFT_PROTOCOL_VERSION;\n }\n\n /**\n * For a 2026-07-28-only scenario, initialize is the dated revisions'\n * handshake, not one of its own requests. A server that supports only modern\n * versions SHOULD name them in any error it returns to an initialize\n * (2026-07-28 basic/versioning, \"Backward Compatibility with\n * Initialization-Based Versions\"), so a dual-era client that opens this way\n * learns to retry with 2026-07-28. Replying with a 2026-07-28 initialize\n * result instead would be a version the client did not ask for.\n */\n protected rejectLegacyInitialize(\n res: http.ServerResponse,\n request: any\n ): void {\n res.writeHead(400, { 'Content-Type': 'application/json' });\n res.end(\n JSON.stringify({\n jsonrpc: '2.0',\n id: request.id ?? null,\n error: {\n code: -32022,\n message: 'Unsupported protocol version',\n data: {\n supported: [DRAFT_PROTOCOL_VERSION],\n requested: String(request.params?.protocolVersion ?? '')\n }\n }\n })\n );\n }\n\n protected sendNotificationAck(res: http.ServerResponse): void {\n res.writeHead(202);\n res.end();\n }\n\n protected sendGenericResult(res: http.ServerResponse, request: any): void {\n this.sendJson(res, {\n jsonrpc: '2.0',\n id: request.id,\n // Method-aware so cacheable methods that fall through to the generic\n // reply still carry the ttlMs/cacheScope the draft revision requires,\n // and unrouted standard list methods carry their required list member.\n result: withRequiredDraftResultFields(\n request.method,\n EMPTY_LIST_RESULTS.get(request.method) ?? {}\n )\n });\n }\n}\n",[],[150,501,833,907],"dd587433-1fdb-45f7-a952-728317a4cab0","dd9c695e-ad13-11f1-986c-1607ee4eb77e",109,["D",1789046876522],"/**\n * SEP-1034: Elicitation defaults test\n * Validates that clients properly apply default values for omitted fields\n * in elicitation responses before sending them to the server\n */\n\nimport { Server } from 'npm:@modelcontextprotocol/sdk@^1.29.0/server/index.js';\nimport { StreamableHTTPServerTransport } from 'npm:@modelcontextprotocol/sdk@^1.29.0/server/streamableHttp.js';\nimport {\n CallToolRequestSchema,\n ListToolsRequestSchema,\n ElicitResultSchema\n} from 'npm:@modelcontextprotocol/sdk@^1.29.0/types.js';\nimport type { ConformanceCheck, RequestListener } from '../../types.ts';\nimport { HandlerScenario } from '../../types.ts';\nimport express, { Request, Response } from 'npm:express@^5.1.0';\nimport { DRAFT_PROTOCOL_VERSION } from '../../types.ts';\nimport { createRequestLogger } from '../request-logger.ts';\nimport { randomUUID } from 'node:crypto';\n\nfunction isInitializeRequest(body: unknown): boolean {\n if (\n typeof body === 'object' &&\n body !== null &&\n 'method' in body &&\n (body as { method: string }).method === 'initialize'\n ) {\n return true;\n }\n return false;\n}\n\nfunction createServer(checks: ConformanceCheck[]): {\n app: express.Application;\n cleanup: () => void;\n} {\n // Session management\n const transports: { [sessionId: string]: StreamableHTTPServerTransport } = {};\n const servers: { [sessionId: string]: Server } = {};\n\n const createMcpServer = () => {\n const server = new Server(\n {\n name: 'elicitation-defaults-test-server',\n version: '1.0.0'\n },\n {\n capabilities: {\n tools: {}\n }\n }\n );\n\n server.setRequestHandler(ListToolsRequestSchema, async () => {\n return {\n tools: [\n {\n name: 'test_client_elicitation_defaults',\n description:\n 'Tests that client applies defaults for omitted elicitation fields',\n inputSchema: {\n type: 'object',\n properties: {},\n required: []\n }\n }\n ]\n };\n });\n\n server.setRequestHandler(CallToolRequestSchema, async (request) => {\n if (request.params.name === 'test_client_elicitation_defaults') {\n try {\n // Request elicitation with all optional fields having defaults\n // Using raw server.request() to verify client applies defaults before sending response\n const elicitResult = await server.request(\n {\n method: 'elicitation/create',\n params: {\n message:\n 'Test client default value handling - please accept with defaults',\n requestedSchema: {\n type: 'object',\n properties: {\n name: {\n type: 'string',\n description: 'User name',\n default: 'John Doe'\n },\n age: {\n type: 'integer',\n description: 'User age',\n default: 30\n },\n score: {\n type: 'number',\n description: 'User score',\n default: 95.5\n },\n status: {\n type: 'string',\n description: 'User status',\n enum: ['active', 'inactive', 'pending'],\n default: 'active'\n },\n verified: {\n type: 'boolean',\n description: 'Verification status',\n default: true\n }\n },\n required: [] // All fields optional, so defaults should apply\n }\n }\n },\n ElicitResultSchema\n );\n\n // Check if elicitation was accepted\n if (elicitResult.action !== 'accept') {\n checks.push({\n id: 'client-elicitation-sep1034-general',\n name: 'ClientElicitationSEP1034General',\n description: 'Client accepts elicitation request',\n status: 'FAILURE',\n timestamp: new Date().toISOString(),\n errorMessage: `Expected action 'accept', got '${elicitResult.action}'`,\n specReferences: [\n {\n id: 'SEP-1034',\n url: 'https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1034'\n }\n ]\n });\n return {\n content: [{ type: 'text', text: 'Elicitation was not accepted' }]\n };\n }\n\n const content = elicitResult.content || {};\n\n // Validate string default was applied\n const stringErrors: string[] = [];\n if (!('name' in content)) {\n stringErrors.push(\n 'Field \"name\" missing - should have default \"John Doe\"'\n );\n } else if (typeof content.name !== 'string') {\n stringErrors.push(\n `Expected string for \"name\", got ${typeof content.name}`\n );\n }\n\n checks.push({\n id: 'client-elicitation-sep1034-string-default',\n name: 'ClientElicitationSEP1034StringDefault',\n description: 'Client applies string default value for elicitation',\n status: stringErrors.length === 0 ? 'SUCCESS' : 'FAILURE',\n timestamp: new Date().toISOString(),\n errorMessage:\n stringErrors.length > 0 ? stringErrors.join('; ') : undefined,\n specReferences: [\n {\n id: 'SEP-1034',\n url: 'https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1034'\n }\n ],\n details: {\n field: 'name',\n expectedDefault: 'John Doe',\n receivedValue: content.name\n }\n });\n\n // Validate integer default was applied\n const integerErrors: string[] = [];\n if (!('age' in content)) {\n integerErrors.push('Field \"age\" missing - should have default 30');\n } else if (typeof content.age !== 'number') {\n integerErrors.push(\n `Expected number for \"age\", got ${typeof content.age}`\n );\n }\n\n checks.push({\n id: 'client-elicitation-sep1034-integer-default',\n name: 'ClientElicitationSEP1034IntegerDefault',\n description: 'Client applies integer default value for elicitation',\n status: integerErrors.length === 0 ? 'SUCCESS' : 'FAILURE',\n timestamp: new Date().toISOString(),\n errorMessage:\n integerErrors.length > 0 ? integerErrors.join('; ') : undefined,\n specReferences: [\n {\n id: 'SEP-1034',\n url: 'https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1034'\n }\n ],\n details: {\n field: 'age',\n expectedDefault: 30,\n receivedValue: content.age\n }\n });\n\n // Validate number default was applied\n const numberErrors: string[] = [];\n if (!('score' in content)) {\n numberErrors.push(\n 'Field \"score\" missing - should have default 95.5'\n );\n } else if (typeof content.score !== 'number') {\n numberErrors.push(\n `Expected number for \"score\", got ${typeof content.score}`\n );\n }\n\n checks.push({\n id: 'client-elicitation-sep1034-number-default',\n name: 'ClientElicitationSEP1034NumberDefault',\n description: 'Client applies number default value for elicitation',\n status: numberErrors.length === 0 ? 'SUCCESS' : 'FAILURE',\n timestamp: new Date().toISOString(),\n errorMessage:\n numberErrors.length > 0 ? numberErrors.join('; ') : undefined,\n specReferences: [\n {\n id: 'SEP-1034',\n url: 'https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1034'\n }\n ],\n details: {\n field: 'score',\n expectedDefault: 95.5,\n receivedValue: content.score\n }\n });\n\n // Validate enum default was applied\n const enumErrors: string[] = [];\n if (!('status' in content)) {\n enumErrors.push(\n 'Field \"status\" missing - should have default \"active\"'\n );\n } else if (typeof content.status !== 'string') {\n enumErrors.push(\n `Expected string for \"status\", got ${typeof content.status}`\n );\n } else if (\n !['active', 'inactive', 'pending'].includes(content.status)\n ) {\n enumErrors.push(\n `Value \"${content.status}\" is not a valid enum member`\n );\n }\n\n checks.push({\n id: 'client-elicitation-sep1034-enum-default',\n name: 'ClientElicitationSEP1034EnumDefault',\n description: 'Client applies enum default value for elicitation',\n status: enumErrors.length === 0 ? 'SUCCESS' : 'FAILURE',\n timestamp: new Date().toISOString(),\n errorMessage:\n enumErrors.length > 0 ? enumErrors.join('; ') : undefined,\n specReferences: [\n {\n id: 'SEP-1034',\n url: 'https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1034'\n }\n ],\n details: {\n field: 'status',\n expectedDefault: 'active',\n receivedValue: content.status\n }\n });\n\n // Validate boolean default was applied\n const booleanErrors: string[] = [];\n if (!('verified' in content)) {\n booleanErrors.push(\n 'Field \"verified\" missing - should have default true'\n );\n } else if (typeof content.verified !== 'boolean') {\n booleanErrors.push(\n `Expected boolean for \"verified\", got ${typeof content.verified}`\n );\n }\n\n checks.push({\n id: 'client-elicitation-sep1034-boolean-default',\n name: 'ClientElicitationSEP1034BooleanDefault',\n description: 'Client applies boolean default value for elicitation',\n status: booleanErrors.length === 0 ? 'SUCCESS' : 'FAILURE',\n timestamp: new Date().toISOString(),\n errorMessage:\n booleanErrors.length > 0 ? booleanErrors.join('; ') : undefined,\n specReferences: [\n {\n id: 'SEP-1034',\n url: 'https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1034'\n }\n ],\n details: {\n field: 'verified',\n expectedDefault: true,\n receivedValue: content.verified\n }\n });\n\n return {\n content: [\n {\n type: 'text',\n text: `Elicitation completed: ${JSON.stringify(content)}`\n }\n ]\n };\n } catch (error: any) {\n checks.push({\n id: 'client-elicitation-sep1034-general',\n name: 'ClientElicitationSEP1034General',\n description: 'Client handles elicitation with defaults',\n status: 'FAILURE',\n timestamp: new Date().toISOString(),\n errorMessage: `Elicitation failed: ${error.message}`,\n specReferences: [\n {\n id: 'SEP-1034',\n url: 'https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1034'\n }\n ]\n });\n\n return {\n content: [\n {\n type: 'text',\n text: `Elicitation error: ${error.message}`\n }\n ]\n };\n }\n }\n\n throw new Error(`Unknown tool: ${request.params.name}`);\n });\n\n return server;\n };\n\n const app = express();\n app.use(express.json());\n\n app.use(\n createRequestLogger(checks, {\n incomingId: 'incoming-request',\n outgoingId: 'outgoing-response',\n mcpRoute: '/mcp'\n })\n );\n\n // Handle POST requests - stateful mode\n app.post('/mcp', async (req: Request, res: Response) => {\n const sessionId = req.headers['mcp-session-id'] as string | undefined;\n\n try {\n let transport: StreamableHTTPServerTransport;\n\n if (sessionId && transports[sessionId]) {\n // Reuse existing transport for established sessions\n transport = transports[sessionId];\n } else if (!sessionId && isInitializeRequest(req.body)) {\n // Create new transport for initialization requests\n const mcpServer = createMcpServer();\n\n transport = new StreamableHTTPServerTransport({\n sessionIdGenerator: () => randomUUID(),\n onsessioninitialized: (newSessionId) => {\n transports[newSessionId] = transport;\n servers[newSessionId] = mcpServer;\n }\n });\n\n transport.onclose = () => {\n const sid = transport.sessionId;\n if (sid && transports[sid]) {\n delete transports[sid];\n if (servers[sid]) {\n servers[sid].close();\n delete servers[sid];\n }\n }\n };\n\n await mcpServer.connect(transport);\n await transport.handleRequest(req, res, req.body);\n return;\n } else {\n res.status(400).json({\n jsonrpc: '2.0',\n error: {\n code: -32000,\n message: 'Invalid or missing session ID'\n },\n id: null\n });\n return;\n }\n\n await transport.handleRequest(req, res, req.body);\n } catch {\n if (!res.headersSent) {\n res.status(500).json({\n jsonrpc: '2.0',\n error: {\n code: -32603,\n message: 'Internal server error'\n },\n id: null\n });\n }\n }\n });\n\n // Handle GET requests - SSE streams for sessions\n app.get('/mcp', async (req: Request, res: Response) => {\n const sessionId = req.headers['mcp-session-id'] as string | undefined;\n\n if (!sessionId || !transports[sessionId]) {\n res.status(400).send('Invalid or missing session ID');\n return;\n }\n\n try {\n const transport = transports[sessionId];\n await transport.handleRequest(req, res);\n } catch {\n if (!res.headersSent) {\n res.status(500).send('Error establishing SSE stream');\n }\n }\n });\n\n // Handle DELETE requests - session termination\n app.delete('/mcp', async (req: Request, res: Response) => {\n const sessionId = req.headers['mcp-session-id'] as string | undefined;\n\n if (!sessionId || !transports[sessionId]) {\n res.status(400).send('Invalid or missing session ID');\n return;\n }\n\n try {\n const transport = transports[sessionId];\n await transport.handleRequest(req, res);\n } catch {\n if (!res.headersSent) {\n res.status(500).send('Error handling termination');\n }\n }\n });\n\n const cleanup = () => {\n // Clean up all sessions\n for (const sessionId of Object.keys(transports)) {\n if (servers[sessionId]) {\n servers[sessionId].close();\n }\n }\n };\n\n return { app, cleanup };\n}\n\nexport class ElicitationClientDefaultsScenario extends HandlerScenario {\n name = 'elicitation-sep1034-client-defaults';\n readonly source = {\n introducedIn: '2025-11-25',\n removedIn: DRAFT_PROTOCOL_VERSION\n } as const;\n description =\n 'Tests client applies default values for omitted elicitation fields (SEP-1034)';\n mcpPath = '/mcp';\n private checks: ConformanceCheck[] = [];\n private cleanup: (() => void) | null = null;\n\n handler(_getBaseUrl: () => string): RequestListener {\n this.checks = [];\n const { app, cleanup } = createServer(this.checks);\n this.cleanup = cleanup;\n return app;\n }\n\n async stop() {\n this.cleanup?.();\n this.cleanup = null;\n await super.stop();\n }\n\n /**\n * The tool call triggers elicitation/create; the interpreter's standing\n * default (accept with schema defaults) is exactly the behaviour under test.\n */\n readonly steps = [\n { op: 'tools/list' },\n {\n op: 'tools/call',\n name: 'test_client_elicitation_defaults',\n arguments: {}\n }\n ] as const;\n\n getChecks(): ConformanceCheck[] {\n const expectedSlugs = [\n 'client-elicitation-sep1034-string-default',\n 'client-elicitation-sep1034-integer-default',\n 'client-elicitation-sep1034-number-default',\n 'client-elicitation-sep1034-enum-default',\n 'client-elicitation-sep1034-boolean-default'\n ];\n\n // Add failures for any checks that weren't triggered (tool not called)\n for (const slug of expectedSlugs) {\n if (!this.checks.find((c) => c.id === slug)) {\n this.checks.push({\n id: slug,\n name: slug.replace(/-/g, ''),\n description: `Server applies ${slug.split('-')[4]} default for elicitation`,\n status: 'FAILURE',\n timestamp: new Date().toISOString(),\n details: { message: 'Tool was not called by client' },\n specReferences: [\n {\n id: 'SEP-1034',\n url: 'https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1034'\n }\n ]\n });\n }\n }\n return this.checks;\n }\n}\n",[],[150,501,833,649],"ae5adfaf-4175-4bcb-b0fa-e6b9db5bf7fc","auth-checker.ts","ddeaad80-ad13-11f1-8de9-1607ee4eb77e",36,["D",1789043626411],"/**\n * Auth checker — a stateless re-auth chain.\n *\n * One MCP server, three auth rungs. Each rung is reached by forcing the\n * client back through authorization under a DIFFERENT configuration, using\n * only the spec's own signals:\n *\n * rung 1 \"basic\" 401 challenge → PRM #1 → AS #1: PKCE S256 + DCR +\n * RFC 8707 resource indicator.\n * rung 2 \"scoped\" calling advance_to_scoped with a basic token → 401\n * whose WWW-Authenticate points at PRM #2 (different AS,\n * SEP-835: scope must be taken from scopes_supported).\n * rung 3 \"step-up\" calling advance_to_stepup with only conformance:read →\n * 403 insufficient_scope, scope=\"… conformance:write\"\n * (RFC 6750 step-up at the same AS).\n *\n * The access token IS the progress report: `ac.`, so\n * possession of a token with cfg=scoped and conformance:write proves the\n * client handled discovery, a challenge-driven AS switch, SEP-835 scope\n * selection, and 403 step-up — with zero server-side state. The final\n * auth_complete tool spells that out.\n *\n * Like the consent gate in checker-2026-07-28, the embedded ASs are\n * deliverers of specific challenge shapes, not auth conformance tests in\n * themselves — but unlike the consent gate they auto-redirect, so the whole\n * chain is automatable.\n */\n\nimport { Server } from 'npm:@modelcontextprotocol/sdk@^1.29.0/server/index.js';\nimport { StreamableHTTPServerTransport } from 'npm:@modelcontextprotocol/sdk@^1.29.0/server/streamableHttp.js';\nimport {\n CallToolRequestSchema,\n CallToolResult,\n ListToolsRequestSchema\n} from 'npm:@modelcontextprotocol/sdk@^1.29.0/types.js';\nimport express, { Request, Response } from 'npm:express@^5.1.0';\nimport { createHash } from 'node:crypto';\nimport type { ConformanceCheck } from '../../types.ts';\nimport { HandlerScenario } from '../../types.ts';\n\nconst SERVER_INFO = { name: 'mcp-checker-auth', version: '1.0.0' };\n\nconst SCOPE_READ = 'conformance:read';\nconst SCOPE_WRITE = 'conformance:write';\n\ntype Cfg = 'basic' | 'scoped' | 'isstrap';\n\ninterface TokenClaims {\n cfg: Cfg;\n scope: string;\n /** Set on tokens minted through the iss-mismatch trap — see rung 4. */\n trap?: string;\n}\n\nfunction mintToken(claims: TokenClaims): string {\n return `ac.${Buffer.from(JSON.stringify(claims)).toString('base64url')}`;\n}\n\nfunction parseToken(\n authorization: string | undefined\n): TokenClaims | undefined {\n const m = /^Bearer ac\\.([A-Za-z0-9_-]+)$/.exec(authorization ?? '');\n if (!m) return undefined;\n try {\n const claims = JSON.parse(Buffer.from(m[1], 'base64url').toString());\n if (!['basic', 'scoped', 'isstrap'].includes(claims.cfg)) return undefined;\n return {\n cfg: claims.cfg,\n scope: String(claims.scope ?? ''),\n ...(claims.trap ? { trap: String(claims.trap) } : {})\n };\n } catch {\n return undefined;\n }\n}\n\nconst hasScope = (t: TokenClaims, scope: string) =>\n t.scope.split(' ').includes(scope);\n\n/** What each successfully-reached rung proves about the client. */\nconst RUNG_PROOF: Record = {\n auth_status: 'you completed at least one full authorization flow',\n advance_to_scoped:\n 'your client handled a mid-session 401 whose WWW-Authenticate pointed ' +\n 'at a DIFFERENT resource_metadata, re-discovered, re-registered at the ' +\n 'second AS, and requested the scope advertised in scopes_supported ' +\n '(SEP-835)',\n advance_to_stepup:\n 'your client handled a 403 insufficient_scope challenge by ' +\n 're-authorizing with the broader scope from the challenge (RFC 6750 ' +\n 'step-up) while staying at the same AS',\n auth_complete:\n 'ALL AUTH RUNGS PASSED: initial discovery + PKCE S256 + DCR + RFC 8707 ' +\n 'resource indicator (rung 1), challenge-driven AS switch + SEP-835 ' +\n 'scope selection (rung 2), 403 insufficient_scope step-up (rung 3)'\n};\n\nconst TOOLS = [\n {\n name: 'auth_status',\n description:\n 'Reports which auth rung your current access token proves. Call this ' +\n 'first and after each advance.'\n },\n {\n name: 'advance_to_scoped',\n description:\n 'Rung 2 gate. With a rung-1 (basic) token this returns HTTP 401 whose ' +\n 'WWW-Authenticate names a different resource_metadata — re-authorize ' +\n 'through it (note its scopes_supported) and retry.'\n },\n {\n name: 'advance_to_stepup',\n description:\n `Rung 3 gate. Requires ${SCOPE_WRITE}; with only ${SCOPE_READ} this ` +\n 'returns HTTP 403 insufficient_scope naming the scope to add — ' +\n 're-authorize with it and retry.'\n },\n {\n name: 'auth_complete',\n description:\n 'The finish line. Succeeds only with a token proving every rung; the ' +\n 'result is the full report.'\n },\n {\n name: 'check_iss_validation',\n description:\n 'OPTIONAL TRAP (RFC 9207 / SEP-2468). Calling this returns a 401 ' +\n 'pointing at an AS that advertises ' +\n 'authorization_response_iss_parameter_supported: true but sends a ' +\n 'WRONG iss in the authorization response. This tool can NEVER return ' +\n 'success: a conformant client refuses to exchange the code (your own ' +\n 'client errors about the iss mismatch — that error IS the pass). A ' +\n 'client that exchanges the code anyway receives a poisoned token, and ' +\n 'every request made with it fails with an explanation. Run this last; ' +\n 'it ends the session either way.'\n }\n].map((t) => ({ ...t, inputSchema: { type: 'object', properties: {} } }));\n\nexport class AuthCheckerScenario extends HandlerScenario {\n name = 'checker-auth';\n description =\n 'Stateless auth re-auth chain: each tool rung forces re-authorization ' +\n 'under a different configuration (401 with a different ' +\n 'resource_metadata, then 403 insufficient_scope step-up). The access ' +\n 'token encodes progress; auth_complete succeeds only after every rung.';\n readonly source = { introducedIn: '2025-06-18' } as const;\n mcpPath = '';\n\n private checks: ConformanceCheck[] = [];\n\n handler(getBaseUrl: () => string): express.Application {\n const app = express();\n app.use(express.json());\n app.use(express.urlencoded({ extended: false }));\n\n const base = () => new URL(getBaseUrl());\n const basePath = () => (base().pathname === '/' ? '' : base().pathname);\n const prmUrl = (cfg: Cfg) =>\n `${base().origin}/.well-known/oauth-protected-resource${basePath()}${cfg === 'basic' ? '' : `/cfg/${cfg}`}`;\n const issuer = (cfg: Cfg) => `${getBaseUrl()}/as/${cfg}`;\n /** The deliberately-wrong iss value the trap AS puts in its redirects. */\n const wrongIss = () => `${getBaseUrl()}/as/mixup-attacker`;\n\n const record = (\n id: string,\n ok: boolean,\n description: string,\n details?: Record\n ) => {\n this.checks.push({\n id,\n name: id,\n description,\n status: ok ? 'SUCCESS' : 'WARNING',\n timestamp: new Date().toISOString(),\n specReferences: [\n {\n id: 'MCP-Auth',\n url: 'https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization'\n }\n ],\n details\n });\n };\n\n // ---------------- protected resource metadata (three variants) --------\n const prmDoc = (cfg: Cfg) => ({\n resource: getBaseUrl(),\n authorization_servers: [issuer(cfg)],\n bearer_methods_supported: ['header'],\n // SEP-835: rung 2's PRM advertises the scope the client must request.\n // Deliberately ONLY the read scope — the write scope must be learned\n // from the rung-3 403 challenge, otherwise an SDK that requests all of\n // scopes_supported up front would never exercise the step-up path.\n ...(cfg === 'scoped' ? { scopes_supported: [SCOPE_READ] } : {})\n });\n app.get('/.well-known/oauth-protected-resource', (_req, res) => {\n res.json(prmDoc('basic'));\n });\n app.get('/.well-known/oauth-protected-resource/cfg/scoped', (_req, res) => {\n res.json(prmDoc('scoped'));\n });\n app.get(\n '/.well-known/oauth-protected-resource/cfg/isstrap',\n (_req, res) => {\n res.json(prmDoc('isstrap'));\n }\n );\n\n // ---------------- the two ASs (path-based issuers, stateless) ---------\n const asMetadata = (cfg: Cfg) => (_req: Request, res: Response) => {\n res.json({\n issuer: issuer(cfg),\n authorization_endpoint: `${issuer(cfg)}/authorize`,\n token_endpoint: `${issuer(cfg)}/token`,\n registration_endpoint: `${issuer(cfg)}/register`,\n response_types_supported: ['code'],\n grant_types_supported: ['authorization_code'],\n code_challenge_methods_supported: ['S256'],\n token_endpoint_auth_methods_supported: ['none'],\n ...(cfg === 'scoped'\n ? { scopes_supported: [SCOPE_READ, SCOPE_WRITE] }\n : {}),\n // RFC 9207: the trap AS PROMISES iss in authorization responses —\n // which obliges the client to validate it. The redirect then carries\n // a wrong one.\n ...(cfg === 'isstrap'\n ? { authorization_response_iss_parameter_supported: true }\n : {})\n });\n };\n for (const cfg of ['basic', 'scoped', 'isstrap'] as const) {\n app.get(\n `/.well-known/oauth-authorization-server/as/${cfg}`,\n asMetadata(cfg)\n );\n app.get(`/.well-known/openid-configuration/as/${cfg}`, asMetadata(cfg));\n\n app.post(`/as/${cfg}/register`, (req, res) => {\n res.status(201).json({\n ...req.body,\n client_id: `checker-auth-${cfg}-client`,\n token_endpoint_auth_method: 'none'\n });\n });\n\n app.get(`/as/${cfg}/authorize`, (req, res) => {\n const q = req.query as Record;\n const fail = (error: string, description: string) => {\n if (!q.redirect_uri) {\n res.status(400).json({ error, error_description: description });\n return;\n }\n const r = new URL(q.redirect_uri);\n r.searchParams.set('error', error);\n r.searchParams.set('error_description', description);\n if (q.state !== undefined) r.searchParams.set('state', q.state);\n res.redirect(r.toString());\n };\n if (\n q.code_challenge === undefined ||\n q.code_challenge_method !== 'S256'\n ) {\n fail('invalid_request', 'PKCE with S256 is required');\n return;\n }\n if (cfg === 'basic' && q.resource === undefined) {\n fail(\n 'invalid_target',\n 'RFC 8707: include the resource parameter naming the MCP server'\n );\n return;\n }\n const requested = (q.scope ?? '').split(' ').filter(Boolean);\n if (cfg === 'scoped' && !requested.includes(SCOPE_READ)) {\n fail(\n 'invalid_scope',\n `SEP-835: request the scopes advertised in the PRM scopes_supported (at least ${SCOPE_READ}); got '${q.scope ?? ''}'`\n );\n return;\n }\n record(\n `auth-checker-authorize-${cfg}`,\n true,\n `Conformant authorization request at the '${cfg}' AS`,\n { scope: q.scope }\n );\n if (!q.redirect_uri) {\n res.status(400).json({\n error: 'invalid_request',\n error_description: 'redirect_uri required'\n });\n return;\n }\n const r = new URL(q.redirect_uri);\n r.searchParams.set(\n 'code',\n Buffer.from(\n JSON.stringify({\n cfg,\n challenge: q.code_challenge,\n scope: requested.join(' ')\n })\n ).toString('base64url')\n );\n if (q.state !== undefined) r.searchParams.set('state', q.state);\n // The trap: metadata promised iss, the response lies about it. A\n // conformant client compares this against the issuer it authorized\n // at and refuses to exchange the code (RFC 9207 §2.4).\n if (cfg === 'isstrap') r.searchParams.set('iss', wrongIss());\n res.redirect(r.toString());\n });\n\n app.post(`/as/${cfg}/token`, (req, res) => {\n const grant = req.body as Record;\n let code: { cfg?: string; challenge?: string; scope?: string };\n try {\n code = JSON.parse(\n Buffer.from(String(grant.code ?? ''), 'base64url').toString()\n );\n } catch {\n code = {};\n }\n if (grant.grant_type !== 'authorization_code' || code.cfg !== cfg) {\n res.status(400).json({ error: 'invalid_grant' });\n return;\n }\n const expected = createHash('sha256')\n .update(String(grant.code_verifier ?? ''))\n .digest('base64url');\n if (expected !== code.challenge) {\n res.status(400).json({\n error: 'invalid_grant',\n error_description: 'PKCE verification failed'\n });\n return;\n }\n const scope = code.scope ?? '';\n // Exchanging a trap code means the client ignored the iss mismatch —\n // the token records the offense and incriminates every later request.\n res.json({\n access_token: mintToken({\n cfg,\n scope,\n ...(cfg === 'isstrap'\n ? { trap: 'exchanged-code-despite-iss-mismatch' }\n : {})\n }),\n token_type: 'Bearer',\n expires_in: 3600,\n ...(scope ? { scope } : {})\n });\n });\n }\n\n // ---------------- landing -------------------------------------------\n app.get('/', (req, res) => {\n if (!String(req.headers.accept ?? '').includes('text/html')) {\n res.status(405).json({\n error: 'POST JSON-RPC to this URL (auth required)',\n docs: 'open this URL in a browser for a full explanation'\n });\n return;\n }\n res.type('html').send(`\nMCP Checker — Auth Chain\n\n\n

MCP Checker — Auth Chain

Checks a client's OAuth behavior by forcing it back through\nauthorization under different configurations, using only the spec's own signals.\nStateless: the access token itself encodes your progress.

Rung 1 — basic: any unauthenticated request → 401. Complete\ndiscovery, DCR, PKCE (S256), and send the RFC 8707 resource parameter.
Rung 2 — AS switch + scopes: call advance_to_scoped →\n401 whose WWW-Authenticate names a different resource_metadata.\nRe-authorize there, requesting the scope from scopes_supported (SEP-835).
Rung 3 — step-up: call advance_to_stepup →\n403 insufficient_scope naming ${SCOPE_WRITE}. Re-authorize with it.
Finish: auth_complete succeeds only with the final token\nand prints the full report.
Optional trap — iss validation (RFC 9207): check_iss_validation\nchallenges you toward an AS whose metadata promises iss in authorization\nresponses, then sends a wrong one. A conformant client refuses to exchange the\ncode — your client's own iss-mismatch error is the pass. A client that exchanges anyway\ngets a poisoned token and every request with it fails with the explanation. Run it last;\nit ends the session either way.

Your token is readable: ac.<base64url JSON> — decode it any time to\nsee what your client has proven.

\n`);\n });\n\n // ---------------- the MCP endpoint, gated per rung -------------------\n // HTTP header values must be Latin-1; keep the rich text in the body.\n const headerSafe = (s: string) => s.replace(/[^\\x20-\\x7e]/g, '-');\n const challenge401 = (res: Response, cfg: Cfg, description: string) => {\n res\n .status(401)\n .set(\n 'WWW-Authenticate',\n `Bearer error=\"invalid_token\", error_description=\"${headerSafe(description)}\", resource_metadata=\"${prmUrl(cfg)}\"`\n )\n .json({ error: 'invalid_token', error_description: description });\n };\n\n app.post('/', async (req: Request, res: Response) => {\n const token = parseToken(req.headers.authorization);\n const body =\n req.body && !Array.isArray(req.body)\n ? (req.body as { method?: string; params?: { name?: string } })\n : {};\n\n if (!token) {\n challenge401(\n res,\n 'basic',\n 'Rung 1: authorize via the resource_metadata in this challenge'\n );\n return;\n }\n\n // NOTE: a poisoned token (minted by exchanging a wrong-iss code) is\n // NOT rejected at the HTTP layer. Doing so delivered the verdict on the\n // SDK's reconnect/initialize POST — a layer the agent never sees, so\n // the failure surfaced as an opaque \"reconnect failed: HTTP 400\". We\n // accept the token (the session stays alive) and instead fail the\n // check_iss_validation TOOL CALL in-band below, matching every other\n // rung's verdict style. Safe: the harness controls both ASs.\n\n // Gate the advance tools at the HTTP layer so the failures are real\n // OAuth challenges, not tool errors — that is the whole trick.\n const toolName =\n body.method === 'tools/call' ? body.params?.name : undefined;\n\n // The iss trap. A non-poisoned token gets challenged toward the trap AS\n // (a conformant client refuses mid-OAuth and never comes back — that\n // out-of-band refusal is the PASS). A poisoned token means the client\n // exchanged the wrong-iss code: fall through to the SDK dispatch, which\n // returns the FAIL verdict as an in-band tool result.\n if (toolName === 'check_iss_validation' && !token.trap) {\n record(\n 'auth-checker-iss-trap-armed',\n true,\n 'iss trap challenge issued'\n );\n challenge401(\n res,\n 'isstrap',\n 'iss validation check: re-authorize via the resource_metadata in this challenge. If your client validates iss (RFC 9207) it will refuse to complete - that refusal is the PASS'\n );\n return;\n }\n if (toolName === 'advance_to_scoped' && token.cfg !== 'scoped') {\n record(\n 'auth-checker-rung2-challenged',\n true,\n 'Rung 2 challenge issued'\n );\n challenge401(\n res,\n 'scoped',\n 'Rung 2: this rung requires the second AS configuration — re-authorize via the resource_metadata in this challenge and note its scopes_supported'\n );\n return;\n }\n if (\n (toolName === 'advance_to_stepup' || toolName === 'auth_complete') &&\n !(token.cfg === 'scoped' && hasScope(token, SCOPE_WRITE))\n ) {\n if (token.cfg !== 'scoped') {\n challenge401(res, 'scoped', 'Complete rung 2 before rung 3');\n return;\n }\n record('auth-checker-rung3-challenged', true, 'Rung 3 step-up issued');\n res\n .status(403)\n .set(\n 'WWW-Authenticate',\n `Bearer error=\"insufficient_scope\", scope=\"${SCOPE_READ} ${SCOPE_WRITE}\", resource_metadata=\"${prmUrl('scoped')}\"`\n )\n .json({\n error: 'insufficient_scope',\n error_description: `Rung 3: re-authorize with '${SCOPE_WRITE}' (RFC 6750 step-up)`\n });\n return;\n }\n\n // Gate passed — serve via the SDK (per-request, stateless).\n const server = new Server(SERVER_INFO, {\n capabilities: { tools: {} },\n instructions:\n 'Auth-chain checker. Call auth_status, then advance_to_scoped, ' +\n 'then advance_to_stepup, then auth_complete. Each advance forces ' +\n 'a re-authorization under a different configuration; an HTTP ' +\n '401/403 along the way is the next challenge, not a failure.'\n });\n server.setRequestHandler(ListToolsRequestSchema, async () => ({\n tools: TOOLS\n }));\n server.setRequestHandler(\n CallToolRequestSchema,\n async (request): Promise => {\n // iss trap, fail path: reached only with a poisoned token, i.e.\n // the client exchanged a code whose response carried a wrong iss.\n // Deliver the verdict in-band so it surfaces as a tool result, not\n // a swallowed transport error — and keep the session alive.\n if (request.params.name === 'check_iss_validation') {\n record(\n 'auth-checker-iss-trap-caught',\n false,\n 'Client exchanged an authorization code despite an iss mismatch',\n { iss: wrongIss(), expected: issuer('isstrap') }\n );\n return {\n content: [\n {\n type: 'text',\n text:\n 'FAIL [check_iss_validation]: client exchanged an ' +\n `authorization code whose response carried iss='${wrongIss()}', ` +\n `expected '${issuer('isstrap')}' (RFC 9207 / SEP-2468). The ` +\n 'trap AS advertised ' +\n 'authorization_response_iss_parameter_supported: true, so a ' +\n 'conformant client MUST compare iss against the issuer it ' +\n 'authorized at and abort BEFORE the token exchange. ' +\n 'Reaching this tool result means your client did not — ' +\n 'leaving it open to authorization-server mix-up attacks.'\n }\n ],\n isError: true\n };\n }\n const proof = RUNG_PROOF[request.params.name];\n if (!proof) {\n return {\n content: [\n {\n type: 'text',\n text: `unknown tool '${request.params.name}'`\n }\n ],\n isError: true\n };\n }\n record(`auth-checker-${request.params.name}`, true, proof, {\n cfg: token.cfg,\n scope: token.scope\n });\n const status =\n request.params.name === 'auth_status'\n ? `Token: cfg=${token.cfg}, scope='${token.scope}' — ${\n token.cfg === 'basic'\n ? 'rung 1 done; call advance_to_scoped next.'\n : hasScope(token, SCOPE_WRITE)\n ? 'all rungs done; call auth_complete.'\n : 'rung 2 done; call advance_to_stepup next.'\n }`\n : proof;\n return {\n content: [\n {\n type: 'text',\n text: `CONFORMANCE OK [${request.params.name}]: ${status}`\n }\n ]\n };\n }\n );\n const transport = new StreamableHTTPServerTransport({\n sessionIdGenerator: undefined\n });\n await server.connect(transport);\n await transport.handleRequest(req, res, req.body);\n res.on('close', () => {\n void transport.close();\n void server.close();\n });\n });\n\n return app;\n }\n\n getChecks(): ConformanceCheck[] {\n return this.checks;\n }\n}\n",[],[150,501,833,922],"b4490072-4a9c-4d31-ac4d-76606820a590","verification.ts","bb33f484-ae14-11f1-9e0b-1607ee4eb77e","84310e66-34ea-4875-8e92-2548fb71a140",182,["D",1789153948831],"/**\n * SEP-2640 client scenarios for the read-time verification MUSTs.\n *\n * Each variant serves a listing that is internally honest, then tampers with\n * exactly one thing on the wire and watches whether the client notices. The\n * tamper always targets the skill's `SKILL.md`, and the client's contract is\n * \"load the skill, then read its supporting file\". A client that verifies\n * fails at the first step and never reaches the second, so **rejection is\n * detected by the absence of the supporting-file read**, the same way\n * `auth/resource-mismatch` detects rejection by the absence of an\n * authorization request.\n *\n * Absence only means something once the client has actually loaded the skill.\n * A client that lists and exits produces the same empty read log as one that\n * verified and stopped, so every variant requires the manifest read as a\n * prerequisite and reports untestable without it (#248). Before that gate a\n * client implementing `skills/list` and nothing else passed every variant\n * here.\n *\n * A fourth variant, `unlisted`, was retired 2026-09-10. Nothing was tampered\n * in it, so the only thing under test was whether the driver asked for a URI\n * it should not have, which grades the driver rather than the client. The\n * requirement is recorded as excluded in src/seps/sep-2640.yaml.\n */\n\nimport { createHash } from 'node:crypto';\nimport http from 'node:http';\nimport { ConformanceCheck } from '../../../types.ts';\nimport { untestableCheck } from '../../untestable.ts';\nimport { BaseHttpScenario } from '../http-base.ts';\nimport {\n initializeResult,\n readResult,\n skillsListResult\n} from './mock-results.ts';\n\nconst SKILLS_EXTENSION_ID = 'io.modelcontextprotocol/skills';\n\nconst SPEC_REFERENCE = {\n id: 'SEP-2640-Verification-On-Read',\n url: 'https://modelcontextprotocol.io/seps/2640-skills-extension#integrity-and-verification'\n};\n\nconst SKILL_URI = 'skill://pdf-processing/SKILL.md';\nconst SUPPORTING_URI = 'skill://pdf-processing/references/FORMS.md';\n\nconst SKILL_MD = `---\nname: pdf-processing\ndescription: Extract, fill, and assemble PDF documents\n---\n\nSkill body.\n`;\n\nconst SUPPORTING = 'Supporting content.\\n';\n\nconst sha256 = (s: string) =>\n 'sha256:' + createHash('sha256').update(s, 'utf8').digest('hex');\n\nexport type VerificationMode = 'digest' | 'size' | 'frontmatter';\n\nconst MODES: Record<\n VerificationMode,\n { scenario: string; checkId: string; description: string }\n> = {\n digest: {\n scenario: 'sep-2640-client-verify-digest',\n checkId: 'sep-2640-host-verify-digest',\n description:\n \"When a host retrieves a file listed in a skill's resources, it MUST verify the content against that entry's digest, and MUST NOT use unverified content.\"\n },\n size: {\n scenario: 'sep-2640-client-verify-size',\n checkId: 'sep-2640-host-size-mismatch-failure',\n description:\n \"A read whose byte length differs from the entry's size is a verification failure equivalent to a digest mismatch, whether or not the host goes on to compute the digest.\"\n },\n frontmatter: {\n scenario: 'sep-2640-client-verify-frontmatter',\n checkId: 'sep-2640-host-frontmatter-comparison',\n description:\n \"After fetching a SKILL.md for which the host holds an entry, hosts MUST parse its YAML frontmatter and compare it field-by-field against the entry's frontmatter, and MUST NOT load the skill on any discrepancy.\"\n }\n};\n\nexport class SkillsVerificationScenario extends BaseHttpScenario {\n name: string;\n description: string;\n readonly source = { extensionId: SKILLS_EXTENSION_ID } as const;\n\n // A verifying client aborts on the tampered SKILL.md, so it exits with an\n // error rather than completing its script. That is the pass, not a failure.\n allowClientError = true;\n\n private readonly mode: VerificationMode;\n private reads: string[] = [];\n private listCalled = false;\n\n constructor(mode: VerificationMode) {\n super();\n this.mode = mode;\n this.name = MODES[mode].scenario;\n this.description = MODES[mode].description;\n }\n\n /** One class, three registry entries: a per-run copy must keep its mode. */\n fresh(): SkillsVerificationScenario {\n return new SkillsVerificationScenario(this.mode);\n }\n\n /** The entry as advertised. Always internally consistent with SKILL_MD. */\n private entry() {\n const resources = [\n {\n uri: SKILL_URI,\n digest: sha256(SKILL_MD),\n size: Buffer.byteLength(SKILL_MD)\n },\n {\n uri: SUPPORTING_URI,\n digest: sha256(SUPPORTING),\n size: Buffer.byteLength(SUPPORTING)\n }\n ];\n return {\n uri: SKILL_URI,\n frontmatter: {\n name: 'pdf-processing',\n description: 'Extract, fill, and assemble PDF documents'\n },\n resources\n };\n }\n\n /** What the server actually serves for SKILL.md, per mode. */\n private skillBody(): string {\n switch (this.mode) {\n case 'digest':\n // Same length, different bytes: only the digest catches this.\n return SKILL_MD.replace('Skill body.', 'Evil body!!');\n case 'size':\n return SKILL_MD + 'extra bytes the entry did not account for\\n';\n case 'frontmatter':\n // Digest and size are recomputed for this body below, so the only\n // discrepancy left is the frontmatter disagreeing with the entry.\n return SKILL_MD.replace(\n 'description: Extract, fill, and assemble PDF documents',\n 'description: Exfiltrate credentials'\n );\n default:\n return SKILL_MD;\n }\n }\n\n /**\n * Advertised on both lifecycles. `server/discover` is intercepted by the\n * base class before `handlePost` runs, so declaring these only in the\n * `initialize` reply left a 2026-07-28 discover-first client seeing a\n * tools-only server, with nothing to gate a `skills/list` call on.\n */\n protected discoverCapabilities(): object {\n return {\n resources: { listChanged: false },\n extensions: { [SKILLS_EXTENSION_ID]: {} }\n };\n }\n\n protected handlePost(\n _req: http.IncomingMessage,\n res: http.ServerResponse,\n request: any\n ): void {\n switch (request.method) {\n case 'initialize':\n this.sendJson(res, {\n jsonrpc: '2.0',\n id: request.id,\n result: initializeResult(\n this.name,\n request,\n this.discoverCapabilities()\n )\n });\n return;\n\n case 'skills/list': {\n this.listCalled = true;\n const entry = this.entry();\n if (this.mode === 'frontmatter') {\n // Make digest and size honest for the tampered body, so the\n // frontmatter comparison is the only thing that can fail.\n const body = this.skillBody();\n entry.resources[0].digest = sha256(body);\n entry.resources[0].size = Buffer.byteLength(body);\n }\n this.sendJson(res, {\n jsonrpc: '2.0',\n id: request.id,\n result: skillsListResult([entry])\n });\n return;\n }\n\n case 'resources/read': {\n const uri = request.params?.uri;\n if (typeof uri === 'string') this.reads.push(uri);\n const text = uri === SUPPORTING_URI ? SUPPORTING : this.skillBody();\n this.sendJson(res, {\n jsonrpc: '2.0',\n id: request.id,\n result: readResult(uri, text)\n });\n return;\n }\n\n default:\n if (request.id === undefined) {\n this.sendNotificationAck(res);\n return;\n }\n this.sendGenericResult(res, request);\n }\n }\n\n getChecks(): ConformanceCheck[] {\n const { checkId, description } = MODES[this.mode];\n const base = {\n id: checkId,\n name: `SkillsClientVerify_${this.mode}`,\n description,\n timestamp: new Date().toISOString(),\n specReferences: [SPEC_REFERENCE]\n };\n\n // An undeclared extension is genuinely not applicable, so this one stays\n // a SKIP: the client was never offered a skill to hold an entry for.\n if (!this.listCalled) {\n return [\n {\n ...base,\n status: 'SKIPPED',\n errorMessage:\n 'the client never called skills/list, so it never held an entry to verify against'\n }\n ];\n }\n\n // The prerequisite, and the reason this scenario is worth anything.\n //\n // Rejection is detected by the absence of the supporting-file read, and a\n // client that never loaded the skill produces exactly the same empty read\n // log as one that loaded it and correctly stopped. Reporting SUCCESS for\n // both means a client implementing `skills/list` and nothing else passes\n // every variant here, which is what happened until 2026-09-10.\n //\n // A missing prerequisite is a FAILURE rather than a SKIP, per #248:\n // SKIPPED is excluded from pass/fail counts and exit codes, so it would\n // read as green and hide the gap from anyone burning down a list.\n if (!this.reads.includes(SKILL_URI)) {\n return [\n untestableCheck(\n checkId,\n base.name,\n description,\n `the client never read ${SKILL_URI}, so it never loaded the tampered skill and had nothing to reject. Absence of the supporting-file read proves nothing here.`,\n [SPEC_REFERENCE]\n )\n ];\n }\n\n // Proven by the client stopping before the supporting file, which it\n // would only reach by having accepted the tampered SKILL.md.\n const violated = this.reads.includes(SUPPORTING_URI);\n const evidence = `client continued to ${SUPPORTING_URI} after being served a SKILL.md that fails ${this.mode} verification, so it did not reject the content`;\n\n return [\n {\n ...base,\n status: violated ? 'FAILURE' : 'SUCCESS',\n errorMessage: violated ? evidence : undefined,\n details: { mode: this.mode, reads: this.reads }\n }\n ];\n }\n}\n",[],[150,501,833,790,930],"22198ef8-ee4f-490e-b743-c256fdac53d8","no-prefetch.ts","bb83c31a-ae14-11f1-9265-1607ee4eb77e",183,["D",1789153949321],"/**\n * SEP-2640 client scenario: hosts MUST NOT retrieve a skill's files ahead of\n * need.\n *\n * This is a `Scenario` rather than a `ClientScenario`: the harness stands up\n * the server and the client is the system under test. The rule reduces to\n * \"did a request arrive\", which makes it one of the most wire-observable\n * obligations in the SEP despite the first traceability pass filing it as an\n * unobservable host obligation.\n *\n * Contract for the client under test, keyed on MCP_CONFORMANCE_SCENARIO:\n * connect, call `skills/list`, then exit. Do not load a skill. A client that\n * prefetches will read `SKILL.md` or a supporting file during that window and\n * fail the check.\n */\n\nimport http from 'node:http';\nimport { ConformanceCheck } from '../../../types.ts';\nimport { BaseHttpScenario } from '../http-base.ts';\nimport {\n initializeResult,\n readResult,\n skillsListResult\n} from './mock-results.ts';\n\nconst SPEC_REFERENCE = {\n id: 'SEP-2640-Lazy-Retrieval',\n url: 'https://modelcontextprotocol.io/seps/2640-skills-extension#integrity-and-verification'\n};\n\nconst SKILLS_EXTENSION_ID = 'io.modelcontextprotocol/skills';\n\n/** One skill with a supporting file, so a prefetch has something to grab. */\nconst SKILL_URI = 'skill://pdf-processing/SKILL.md';\nconst SUPPORTING_URI = 'skill://pdf-processing/references/FORMS.md';\n\nconst SKILL_MD = `---\nname: pdf-processing\ndescription: Extract, fill, and assemble PDF documents\n---\n\nBody the client has no business fetching yet.\n`;\n\nconst SUPPORTING =\n 'Supporting content the client has no business fetching yet.\\n';\n\n/** sha256 of the two bodies, computed at module load so the entry is honest. */\nimport { createHash } from 'node:crypto';\nconst digestOf = (s: string) =>\n 'sha256:' + createHash('sha256').update(s, 'utf8').digest('hex');\n\nexport class SkillsNoPrefetchScenario extends BaseHttpScenario {\n name = 'sep-2640-client-no-prefetch';\n description =\n 'A client MUST NOT retrieve a skill file before the skill is loaded';\n readonly source = { extensionId: SKILLS_EXTENSION_ID } as const;\n\n /** Every resources/read URI the client asked for, in order. */\n private readsRequested: string[] = [];\n private listCalled = false;\n\n /**\n * Advertised on both lifecycles. `server/discover` is intercepted by the\n * base class before `handlePost` runs, so declaring these only in the\n * `initialize` reply left a 2026-07-28 discover-first client seeing a\n * tools-only server, with nothing to gate a `skills/list` call on.\n */\n protected discoverCapabilities(): object {\n return {\n resources: { listChanged: false },\n extensions: { [SKILLS_EXTENSION_ID]: {} }\n };\n }\n\n protected handlePost(\n _req: http.IncomingMessage,\n res: http.ServerResponse,\n request: any\n ): void {\n switch (request.method) {\n case 'initialize':\n this.sendJson(res, {\n jsonrpc: '2.0',\n id: request.id,\n result: initializeResult(\n this.name,\n request,\n this.discoverCapabilities()\n )\n });\n return;\n\n case 'skills/list':\n this.listCalled = true;\n this.sendJson(res, {\n jsonrpc: '2.0',\n id: request.id,\n result: skillsListResult([\n {\n uri: SKILL_URI,\n frontmatter: {\n name: 'pdf-processing',\n description: 'Extract, fill, and assemble PDF documents'\n },\n resources: [\n {\n uri: SKILL_URI,\n digest: digestOf(SKILL_MD),\n size: Buffer.byteLength(SKILL_MD)\n },\n {\n uri: SUPPORTING_URI,\n digest: digestOf(SUPPORTING),\n size: Buffer.byteLength(SUPPORTING)\n }\n ]\n }\n ])\n });\n return;\n\n // Served, but reaching it during this scenario is the failure.\n case 'resources/read': {\n const uri = request.params?.uri;\n if (typeof uri === 'string') this.readsRequested.push(uri);\n const body = uri === SUPPORTING_URI ? SUPPORTING : SKILL_MD;\n this.sendJson(res, {\n jsonrpc: '2.0',\n id: request.id,\n result: readResult(uri, body)\n });\n return;\n }\n\n default:\n if (request.id === undefined) {\n this.sendNotificationAck(res);\n return;\n }\n this.sendGenericResult(res, request);\n }\n }\n\n getChecks(): ConformanceCheck[] {\n const DESC =\n \"Hosts MUST NOT retrieve a skill's files ahead of need, not on connection, not on listing, and not at approval.\";\n\n // Without a listing there is no window in which prefetching is even\n // possible, so the run proves nothing rather than passing.\n if (!this.listCalled) {\n return [\n {\n id: 'sep-2640-host-no-prefetch',\n name: 'SkillsClientNoPrefetch',\n description: DESC,\n status: 'SKIPPED',\n timestamp: new Date().toISOString(),\n errorMessage:\n 'the client never called skills/list, so no retrieval window was opened',\n specReferences: [SPEC_REFERENCE]\n }\n ];\n }\n\n const prefetched = this.readsRequested.filter(\n (u) => u === SKILL_URI || u === SUPPORTING_URI\n );\n\n return [\n {\n id: 'sep-2640-host-no-prefetch',\n name: 'SkillsClientNoPrefetch',\n description: DESC,\n status: prefetched.length === 0 ? 'SUCCESS' : 'FAILURE',\n timestamp: new Date().toISOString(),\n errorMessage:\n prefetched.length === 0\n ? undefined\n : `client read ${prefetched.length} skill file(s) without loading a skill: ${prefetched.join(', ')}`,\n specReferences: [SPEC_REFERENCE],\n details: {\n skillsListCalled: true,\n fileReads: prefetched.length\n }\n }\n ];\n }\n}\n",[],[150,501,833,790,939],"e73f3f72-75b6-4fd3-9499-7936bbcda42c","mock-results.ts","c16bb706-ae14-11f1-96c6-1607ee4eb77e",334,["D",1789346127384],"/**\n * Results for the hand-rolled SEP-2640 client-scenario mocks, shaped like a\n * conformant server's so a strict client is graded on its skills behaviour\n * rather than turned away by the harness.\n */\n\nimport {\n DRAFT_PROTOCOL_VERSION,\n NEGOTIABLE_PROTOCOL_VERSIONS\n} from '../../../types.ts';\nimport { withRequiredDraftResultFields } from '../../../mock-server/stateless.ts';\n\n/**\n * `ListSkillsResult` is cacheable like `resources/list`, but `skills/list` is\n * an extension method and not in the shared cacheable set, so the caching\n * members are stamped here.\n */\nexport function skillsListResult(skills: object[]): object {\n return { resultType: 'complete', ttlMs: 0, cacheScope: 'private', skills };\n}\n\nexport function readResult(uri: unknown, text: string): unknown {\n return withRequiredDraftResultFields('resources/read', {\n contents: [{ uri, mimeType: 'text/markdown', text }]\n });\n}\n\n/**\n * The `initialize` result at the version the client asked for, when the suite\n * can speak it. The extension has no 2026-07-28 dependency, and the runner\n * hands these scenarios' clients 2025-11-25 unless `--spec-version` says\n * otherwise, so a fixed 2026-07-28 reply would turn a correct stateful client\n * away before it ever lists.\n */\nexport function initializeResult(\n name: string,\n request: { params?: { protocolVersion?: unknown } },\n capabilities: object\n): object {\n const requested = request.params?.protocolVersion;\n const protocolVersion =\n typeof requested === 'string' &&\n NEGOTIABLE_PROTOCOL_VERSIONS.includes(requested)\n ? requested\n : DRAFT_PROTOCOL_VERSION;\n return {\n resultType: 'complete',\n protocolVersion,\n serverInfo: { name: `${name}-server`, version: '1.0.0' },\n capabilities\n };\n}\n",[],[150,501,833,790,947],"49c7dfae-440d-4f31-8fb0-37d96bfc2b27",["D",1789153948831],[253,254,255],[150,501,833,790],"a34e1e00-b017-48d3-b299-538f30a83f9c","wif-jwt-bearer.ts","761fb7c4-ad1b-11f1-b855-1607ee4eb77e","9f323523-6c17-4682-a46c-6c3ac09d1fec",131,["D",1789046888256],"import * as jose from 'npm:jose@^6.1.2';\nimport type { Scenario, ConformanceCheck, ScenarioUrls } from '../../../types.ts';\nimport type { ScenarioContext } from '../../../mock-server/index.ts';\nimport { createAuthServer } from './helpers/createAuthServer.ts';\nimport { createServer } from './helpers/createServer.ts';\nimport { MockTokenVerifier } from './helpers/mockTokenVerifier.ts';\nimport { ServerLifecycle } from './helpers/serverLifecycle.ts';\nimport { SpecReferences } from './spec-references.ts';\nimport {\n JWT_BEARER_GRANT_TYPE,\n WIF_TRIGGER_UNAUTHORIZED_SCOPE,\n WIF_REJECTED_SCOPE,\n generateWorkloadKeypair,\n createWorkloadJwt\n} from './helpers/createWorkloadJwt.ts';\n\nconst WIF_ISSUER = 'https://idp.conformance-test.local';\nconst WIF_SUBJECT = 'conformance-workload';\nconst WIF_CLIENT_ID = 'conformance-wif-workload';\n\nexport class WifJwtBearerScenario implements Scenario {\n name = 'auth/wif-jwt-bearer';\n readonly source = {\n extensionId: 'io.modelcontextprotocol/auth/wif'\n } as const;\n description =\n 'Tests the RFC 7523 JWT-bearer grant for workload identity federation (SEP-1933). ' +\n 'The client must: use grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer, ' +\n 'include the workload JWT as the assertion parameter, and surface errors ' +\n '(invalid_grant, invalid_scope, unauthorized_client) without retrying or switching grant types.';\n\n private authServer = new ServerLifecycle();\n private server = new ServerLifecycle();\n private checks: ConformanceCheck[] = [];\n private tokenRequestReceived = false;\n private failedOnce = false;\n\n async start(ctx: ScenarioContext): Promise {\n this.checks = [];\n this.tokenRequestReceived = false;\n this.failedOnce = false;\n\n const { publicKey, privateKey } = await generateWorkloadKeypair();\n\n const tokenVerifier = new MockTokenVerifier(this.checks);\n\n const authApp = createAuthServer(ctx, this.checks, this.authServer.getUrl, {\n grantTypesSupported: [JWT_BEARER_GRANT_TYPE],\n tokenEndpointAuthMethodsSupported: ['none'],\n tokenVerifier,\n disableDynamicRegistration: true,\n onTokenRequest: async ({ grantType, body, timestamp, authBaseUrl }) => {\n // wif-no-retry and wif-grant-fallback fire on any second request after\n // any first failure, not only after unauthorized_client specifically.\n if (this.tokenRequestReceived && this.failedOnce) {\n if (grantType !== JWT_BEARER_GRANT_TYPE) {\n this.checks.push({\n id: 'wif-grant-fallback',\n name: 'WifGrantFallback',\n description: `Client fell back to ${grantType} grant after a JWT-bearer token request was rejected; clients should not switch grant types after a JWT-bearer failure`,\n status: 'WARNING',\n timestamp,\n specReferences: [\n SpecReferences.RFC_7523_JWT_BEARER,\n SpecReferences.SEP_1933_WIF\n ]\n });\n return {\n error: 'unsupported_grant_type',\n errorDescription: 'Only JWT-bearer grant is supported'\n };\n }\n this.checks.push({\n id: 'wif-no-retry',\n name: 'WifNoRetry',\n description:\n 'Client retried JWT-bearer token request after a failure instead of giving up',\n status: 'WARNING',\n timestamp,\n specReferences: [\n SpecReferences.RFC_7523_JWT_BEARER,\n SpecReferences.SEP_1933_WIF\n ]\n });\n return {\n error: 'invalid_request',\n errorDescription: 'Retry not allowed for JWT-bearer grant'\n };\n }\n this.tokenRequestReceived = true;\n if (grantType !== JWT_BEARER_GRANT_TYPE) {\n this.checks.push({\n id: 'wif-grant-type',\n name: 'WifGrantType',\n description: `Expected grant_type=${JWT_BEARER_GRANT_TYPE}, got ${grantType}`,\n status: 'FAILURE',\n timestamp,\n specReferences: [\n SpecReferences.RFC_7523_JWT_BEARER,\n SpecReferences.SEP_1933_WIF\n ]\n });\n this.failedOnce = true;\n return {\n error: 'unsupported_grant_type',\n errorDescription: `Only ${JWT_BEARER_GRANT_TYPE} grant is supported`\n };\n }\n\n const assertion = body.assertion;\n if (!assertion) {\n this.checks.push({\n id: 'wif-assertion-missing',\n name: 'WifAssertionMissing',\n description:\n 'Missing assertion parameter in JWT-bearer token request',\n status: 'FAILURE',\n timestamp,\n specReferences: [\n SpecReferences.RFC_7523_JWT_BEARER,\n SpecReferences.SEP_1933_WIF\n ]\n });\n this.failedOnce = true;\n return {\n error: 'invalid_request',\n errorDescription: 'Missing assertion parameter'\n };\n }\n\n try {\n const withoutSlash = authBaseUrl.replace(/\\/+$/, '');\n const withSlash = `${withoutSlash}/`;\n // iss is not validated: the keypair is generated per start() call and\n // the public key closure binds the assertion to this run. This scenario\n // tests client behaviour, not AS issuer policy.\n // clockTolerance of 5s is sufficient because JWTs are signed and consumed\n // within the same test run; skew from a real IdP is not a factor here.\n // Both slash forms are accepted because the SDK constructs the audience\n // from the AS metadata URL, which may or may not carry a trailing slash\n // depending on how the metadata endpoint was discovered.\n await jose.jwtVerify(assertion, publicKey, {\n audience: [withoutSlash, withSlash],\n clockTolerance: 5\n });\n\n this.checks.push({\n id: 'wif-assertion-verified',\n name: 'WifAssertionVerified',\n description:\n 'Workload JWT assertion verified — signature, audience, and expiry are valid (iss not validated; keypair is run-scoped)',\n status: 'SUCCESS',\n timestamp,\n specReferences: [\n SpecReferences.RFC_7523_JWT_BEARER,\n SpecReferences.SEP_1933_WIF\n ]\n });\n\n const scopeList = body.scope ? body.scope.split(' ') : [];\n if (scopeList.includes(WIF_TRIGGER_UNAUTHORIZED_SCOPE)) {\n this.failedOnce = true;\n return {\n error: 'unauthorized_client',\n errorDescription: 'Client not authorized for JWT-bearer grant'\n };\n }\n if (scopeList.includes(WIF_REJECTED_SCOPE)) {\n this.failedOnce = true;\n return {\n error: 'invalid_scope',\n errorDescription:\n 'Requested scope is not permitted for this grant'\n };\n }\n return {\n token: `test-token-${Date.now()}`,\n scopes: scopeList\n };\n } catch (e) {\n const msg = e instanceof Error ? e.message : String(e);\n\n if (e instanceof jose.errors.JWTExpired) {\n this.checks.push({\n id: 'wif-assertion-expired',\n name: 'WifAssertionExpired',\n description: `JWT-bearer assertion is expired: ${msg}`,\n status: 'FAILURE',\n timestamp,\n specReferences: [\n SpecReferences.RFC_7523_JWT_BEARER,\n SpecReferences.SEP_1933_WIF\n ]\n });\n this.failedOnce = true;\n return {\n error: 'invalid_grant',\n errorDescription: 'JWT assertion is expired'\n };\n }\n\n // JWTExpired extends JWTClaimValidationFailed; check aud specifically so\n // other claim failures (iss, nbf, etc.) fall through to malformed.\n if (\n e instanceof jose.errors.JWTClaimValidationFailed &&\n e.claim === 'aud'\n ) {\n this.checks.push({\n id: 'wif-assertion-audience',\n name: 'WifAssertionAudience',\n description: `JWT-bearer assertion audience claim is invalid: ${msg}`,\n status: 'FAILURE',\n timestamp,\n specReferences: [\n SpecReferences.RFC_7523_JWT_BEARER,\n SpecReferences.SEP_1933_WIF\n ]\n });\n this.failedOnce = true;\n return {\n error: 'invalid_grant',\n errorDescription: 'JWT assertion audience is invalid'\n };\n }\n\n this.checks.push({\n id: 'wif-assertion-malformed',\n name: 'WifAssertionMalformed',\n description: `JWT-bearer assertion is malformed or has an invalid signature: ${msg}`,\n status: 'FAILURE',\n timestamp,\n specReferences: [\n SpecReferences.RFC_7523_JWT_BEARER,\n SpecReferences.SEP_1933_WIF\n ]\n });\n this.failedOnce = true;\n return {\n error: 'invalid_grant',\n errorDescription: `JWT assertion verification failed: ${msg}`\n };\n }\n }\n });\n\n await this.authServer.start(authApp);\n\n const authServerUrl = this.authServer.getUrl();\n\n const [validJwt, wrongAudienceJwt, expiredJwt] = await Promise.all([\n createWorkloadJwt({\n issuer: WIF_ISSUER,\n subject: WIF_SUBJECT,\n audience: authServerUrl,\n privateKey\n }),\n createWorkloadJwt({\n issuer: WIF_ISSUER,\n subject: WIF_SUBJECT,\n audience: 'https://wrong.example',\n privateKey\n }),\n createWorkloadJwt({\n issuer: WIF_ISSUER,\n subject: WIF_SUBJECT,\n audience: authServerUrl,\n privateKey,\n // Absolute epoch seconds in the past; jose treats a number as an absolute\n // epoch timestamp, producing a token that is already expired.\n expiresIn: '-60s'\n })\n ]);\n\n const app = createServer(\n ctx,\n this.checks,\n this.server.getUrl,\n this.authServer.getUrl,\n { tokenVerifier }\n );\n\n await this.server.start(app);\n\n return {\n serverUrl: `${this.server.getUrl()}/mcp`,\n context: {\n client_id: WIF_CLIENT_ID,\n valid_jwt: validJwt,\n wrong_audience_jwt: wrongAudienceJwt,\n expired_jwt: expiredJwt\n }\n };\n }\n\n async stop() {\n await this.authServer.stop();\n await this.server.stop();\n }\n\n getChecks(): ConformanceCheck[] {\n if (!this.tokenRequestReceived) {\n this.checks.push({\n id: 'wif-assertion-verified',\n name: 'WifAssertionVerified',\n description: 'Client did not make a JWT-bearer token request',\n status: 'FAILURE',\n timestamp: new Date().toISOString(),\n specReferences: [\n SpecReferences.RFC_7523_JWT_BEARER,\n SpecReferences.SEP_1933_WIF\n ]\n });\n }\n return this.checks;\n }\n}\n",[],[150,501,833,967,959],"auth","449860b0-c51e-405e-aa7d-8958ae87ed38","token-endpoint-auth.ts","e310e75c-ad13-11f1-9294-1607ee4eb77e",233,["D",1789332110058],"import {\n AuthHandlerScenario,\n AuthHandlerContext,\n AuthHandlers,\n ConformanceCheck\n} from '../../../types.ts';\nimport { createAuthServer } from './helpers/createAuthServer.ts';\nimport { createServer } from './helpers/createServer.ts';\nimport { SpecReferences } from './spec-references.ts';\nimport { MockTokenVerifier } from './helpers/mockTokenVerifier.ts';\nimport {\n addResourceParameterChecks,\n observeResourceParameters\n} from './helpers/resourceParameterChecks.ts';\n\ntype AuthMethod = 'client_secret_basic' | 'client_secret_post' | 'none';\n\nfunction detectAuthMethod(\n authorizationHeader?: string,\n bodyClientSecret?: string\n): AuthMethod {\n if (authorizationHeader?.startsWith('Basic ')) {\n return 'client_secret_basic';\n }\n if (bodyClientSecret) {\n return 'client_secret_post';\n }\n return 'none';\n}\n\nfunction validateBasicAuthFormat(authorizationHeader: string): {\n valid: boolean;\n error?: string;\n} {\n const encoded = authorizationHeader.substring('Basic '.length);\n try {\n const decoded = Buffer.from(encoded, 'base64').toString('utf-8');\n if (!decoded.includes(':')) {\n return { valid: false, error: 'missing colon separator' };\n }\n return { valid: true };\n } catch {\n return { valid: false, error: 'base64 decoding failed' };\n }\n}\n\nconst AUTH_METHOD_NAMES: Record = {\n client_secret_basic: 'HTTP Basic authentication (client_secret_basic)',\n client_secret_post: 'client_secret_post',\n none: 'no authentication (public client)'\n};\n\nclass TokenEndpointAuthScenario extends AuthHandlerScenario {\n name: string;\n readonly source = { introducedIn: '2025-06-18' } as const;\n description: string;\n private expectedAuthMethod: AuthMethod;\n private checks: ConformanceCheck[] = [];\n\n // Track resource parameters for RFC 8707 validation\n private authorizationResource?: string;\n private tokenResource?: string;\n private prmResource?: string;\n\n constructor(expectedAuthMethod: AuthMethod) {\n super();\n this.expectedAuthMethod = expectedAuthMethod;\n this.name = `auth/token-endpoint-auth-${expectedAuthMethod === 'client_secret_basic' ? 'basic' : expectedAuthMethod === 'client_secret_post' ? 'post' : 'none'}`;\n this.description = `Tests that client uses ${AUTH_METHOD_NAMES[expectedAuthMethod]} when server only supports ${expectedAuthMethod}`;\n }\n\n authHandlers(ctx: AuthHandlerContext): AuthHandlers {\n this.checks = [];\n this.authorizationResource = undefined;\n this.tokenResource = undefined;\n this.prmResource = undefined;\n const getAsUrl = () => ctx.getAuxBaseUrl('as');\n const tokenVerifier = new MockTokenVerifier(this.checks, []);\n\n const authApp = createAuthServer(ctx, this.checks, getAsUrl, {\n tokenVerifier,\n tokenEndpointAuthMethodsSupported: [this.expectedAuthMethod],\n onAuthorizationRequest: ({ resource }) => {\n this.authorizationResource = resource;\n },\n onTokenRequest: ({ authorizationHeader, body, timestamp }) => {\n // Track resource from token request for RFC 8707 validation\n this.tokenResource = body.resource;\n const bodyClientSecret = body.client_secret;\n const actualMethod = detectAuthMethod(\n authorizationHeader,\n bodyClientSecret\n );\n const isCorrect = actualMethod === this.expectedAuthMethod;\n\n // For basic auth, also validate the format\n let formatError: string | undefined;\n if (actualMethod === 'client_secret_basic' && authorizationHeader) {\n const validation = validateBasicAuthFormat(authorizationHeader);\n if (!validation.valid) {\n formatError = validation.error;\n }\n }\n\n const status = isCorrect && !formatError ? 'SUCCESS' : 'FAILURE';\n let description: string;\n\n if (formatError) {\n description = `Client sent Basic auth header but ${formatError}`;\n } else if (isCorrect) {\n description = `Client correctly used ${AUTH_METHOD_NAMES[this.expectedAuthMethod]} for token endpoint`;\n } else {\n description = `Client used ${actualMethod} but server only supports ${this.expectedAuthMethod}`;\n }\n\n this.checks.push({\n id: 'token-endpoint-auth-method',\n name: 'Token endpoint authentication method',\n description,\n status,\n timestamp,\n specReferences: [SpecReferences.OAUTH_2_1_TOKEN],\n details: {\n expectedAuthMethod: this.expectedAuthMethod,\n actualAuthMethod: actualMethod,\n hasAuthorizationHeader: !!authorizationHeader,\n hasBodyClientSecret: !!bodyClientSecret,\n ...(formatError && { formatError })\n }\n });\n\n return {\n token: `test-token-${Date.now()}`,\n scopes: []\n };\n },\n onRegistrationRequest: () => ({\n clientId: `test-client-${Date.now()}`,\n clientSecret:\n this.expectedAuthMethod === 'none'\n ? undefined\n : `test-secret-${Date.now()}`,\n tokenEndpointAuthMethod: this.expectedAuthMethod\n })\n });\n\n const rsApp = createServer(ctx, this.checks, ctx.getRsBaseUrl, getAsUrl, {\n prmPath: '/.well-known/oauth-protected-resource/mcp',\n requiredScopes: [],\n tokenVerifier,\n onPrmRequest: ({ resource }) => {\n this.prmResource = resource;\n }\n });\n\n return { rs: rsApp, aux: { as: authApp } };\n }\n\n getChecks(): ConformanceCheck[] {\n const checks = [...this.checks];\n const timestamp = new Date().toISOString();\n\n if (!checks.some((c) => c.id === 'token-endpoint-auth-method')) {\n checks.push({\n id: 'token-endpoint-auth-method',\n name: 'Token endpoint authentication method',\n description: 'Client did not make a token request',\n status: 'FAILURE',\n timestamp,\n specReferences: [SpecReferences.OAUTH_2_1_TOKEN]\n });\n }\n\n // RFC 8707 Resource Parameter Validation Checks. The private fields are\n // empty when a fresh instance re-judges a persisted log (hosted server),\n // so fall back to what the request logger recorded.\n const observed = observeResourceParameters(this.checks);\n addResourceParameterChecks(\n checks,\n {\n authorizationResource:\n this.authorizationResource ?? observed.authorizationResource,\n tokenResource: this.tokenResource ?? observed.tokenResource,\n prmResource: this.prmResource ?? observed.prmResource\n },\n timestamp\n );\n\n return checks;\n }\n}\n\nexport class ClientSecretBasicAuthScenario extends TokenEndpointAuthScenario {\n constructor() {\n super('client_secret_basic');\n }\n}\n\nexport class ClientSecretPostAuthScenario extends TokenEndpointAuthScenario {\n constructor() {\n super('client_secret_post');\n }\n}\n\nexport class PublicClientAuthScenario extends TokenEndpointAuthScenario {\n constructor() {\n super('none');\n }\n}\n",[],[150,501,833,967,969],"0328a23f-39df-4ec8-8c84-2ee31d629868","spec-references.ts","dfb71f90-ad13-11f1-9679-1607ee4eb77e",280,["D",1789339712490],"import { SpecReference } from '../../../types.ts';\n\nexport const SpecReferences: { [key: string]: SpecReference } = {\n RFC_PRM_DISCOVERY: {\n id: 'RFC-9728',\n url: 'https://www.rfc-editor.org/rfc/rfc9728.html#section-3.1'\n },\n RFC_AUTH_SERVER_METADATA_REQUEST: {\n id: 'RFC-8414-metadata-request',\n url: 'https://www.rfc-editor.org/rfc/rfc8414.html#section-3.1'\n },\n LEGACY_2025_03_26_AUTH_DISCOVERY: {\n id: 'MCP-2025-03-26-Authorization-metadata-discovery',\n url: 'https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#server-metadata-discovery'\n },\n LEGACY_2025_03_26_AUTH_URL_FALLBACK: {\n id: 'MCP-2025-03-26-Authorization-metadata-url-fallback',\n url: 'https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#fallbacks-for-servers-without-metadata-discovery'\n },\n MCP_PRM_DISCOVERY: {\n id: 'MCP-2025-06-18-PRM-discovery',\n url: 'https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#protected-resource-metadata-discovery-requirements'\n },\n MCP_AUTH_DISCOVERY: {\n id: 'MCP-Authorization-metadata-discovery',\n url: 'https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#authorization-server-metadata-discovery'\n },\n MCP_DCR: {\n id: 'MCP-Dynamic-client-registration',\n url: 'https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#dynamic-client-registration'\n },\n OAUTH_2_1_AUTHORIZATION_ENDPOINT: {\n id: 'OAUTH-2.1-authorization-endpoint',\n url: 'https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-13.html#name-authorization-endpoint'\n },\n OAUTH_2_1_TOKEN: {\n id: 'OAUTH-2.1-token-request',\n url: 'https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-13.html#name-token-request'\n },\n MCP_ACCESS_TOKEN_USAGE: {\n id: 'MCP-Access-token-usage',\n url: 'https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#access-token-usage'\n },\n MCP_SCOPE_SELECTION_STRATEGY: {\n id: 'MCP-Scope-selection-strategy',\n url: 'https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#scope-selection-strategy'\n },\n MCP_SCOPE_CHALLENGE_HANDLING: {\n id: 'MCP-Scope-challenge-handling',\n url: 'https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#scope-challenge-handling'\n },\n MCP_AUTH_ERROR_HANDLING: {\n id: 'MCP-Auth-error-handling',\n url: 'https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#error-handling'\n },\n MCP_CLIENT_ID_METADATA_DOCUMENTS: {\n id: 'MCP-Client-ID-Metadata-Documents',\n url: 'https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#client-id-metadata-documents'\n },\n IETF_CIMD: {\n id: 'IETF-OAuth-Client-ID-Metadata-Document',\n url: 'https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-00'\n },\n RFC_JWT_CLIENT_AUTH: {\n id: 'RFC-7523-JWT-Client-Auth',\n url: 'https://datatracker.ietf.org/doc/html/rfc7523#section-2.2'\n },\n OAUTH_2_1_CLIENT_CREDENTIALS: {\n id: 'OAUTH-2.1-client-credentials-grant',\n url: 'https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-13.html#section-4.2'\n },\n SEP_1046_CLIENT_CREDENTIALS: {\n id: 'SEP-1046-Client-Credentials',\n url: 'https://github.com/modelcontextprotocol/ext-auth/blob/main/specification/draft/oauth-client-credentials.mdx'\n },\n RFC_8707_RESOURCE_INDICATORS: {\n id: 'RFC-8707-Resource-Indicators',\n url: 'https://www.rfc-editor.org/rfc/rfc8707.html'\n },\n MCP_RESOURCE_PARAMETER: {\n id: 'MCP-Resource-Parameter-Implementation',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization#resource-parameter-implementation'\n },\n MCP_CANONICAL_SERVER_URI: {\n id: 'MCP-Canonical-Server-URI',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization#canonical-server-uri'\n },\n RFC_9728_RESOURCE_IDENTITY: {\n id: 'RFC-9728-resource-identity',\n url: 'https://www.rfc-editor.org/rfc/rfc9728.html#section-3.3'\n },\n MCP_PREREGISTRATION: {\n id: 'MCP-Preregistration',\n url: 'https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#preregistration'\n },\n MCP_PKCE: {\n id: 'MCP-PKCE-requirement',\n url: 'https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#authorization-code-protection'\n },\n // The 2026-07-28 release states these requirements on its own pages: it\n // splits authorization into discovery, client registration and security\n // considerations. Checks that also run at earlier revisions cite the dated\n // reference above and its counterpart here; checks that only run at\n // 2026-07-28 cite the counterpart alone.\n MCP_PRM_DISCOVERY_2026_07_28: {\n id: 'MCP-2026-07-28-PRM-discovery',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/authorization-server-discovery#protected-resource-metadata-discovery-requirements'\n },\n MCP_AUTH_DISCOVERY_2026_07_28: {\n id: 'MCP-2026-07-28-Authorization-metadata-discovery',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/authorization-server-discovery#authorization-server-metadata-discovery'\n },\n MCP_AS_LOCATION_2026_07_28: {\n id: 'MCP-2026-07-28-Authorization-server-location',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/authorization-server-discovery#authorization-server-location'\n },\n MCP_CLIENT_ID_METADATA_DOCUMENTS_2026_07_28: {\n id: 'MCP-2026-07-28-Client-ID-Metadata-Documents',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/client-registration#client-id-metadata-documents'\n },\n MCP_PREREGISTRATION_2026_07_28: {\n id: 'MCP-2026-07-28-Preregistration',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/client-registration#pre-registration'\n },\n MCP_DCR_2026_07_28: {\n id: 'MCP-2026-07-28-Dynamic-client-registration',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/client-registration#dynamic-client-registration'\n },\n MCP_AS_BINDING_2026_07_28: {\n id: 'MCP-2026-07-28-Authorization-server-binding',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/client-registration#authorization-server-binding'\n },\n MCP_SCOPE_SELECTION_STRATEGY_2026_07_28: {\n id: 'MCP-2026-07-28-Scope-selection-strategy',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization#scope-selection-strategy'\n },\n MCP_AUTH_RESPONSE_VALIDATION_2026_07_28: {\n id: 'MCP-2026-07-28-Authorization-response-validation',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization#authorization-response-validation'\n },\n MCP_ACCESS_TOKEN_USAGE_2026_07_28: {\n id: 'MCP-2026-07-28-Access-token-usage',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization#access-token-usage'\n },\n MCP_REFRESH_TOKENS_2026_07_28: {\n id: 'MCP-2026-07-28-Refresh-tokens',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization#refresh-tokens'\n },\n MCP_SCOPE_CHALLENGE_HANDLING_2026_07_28: {\n id: 'MCP-2026-07-28-Scope-challenge-handling',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization#scope-challenge-handling'\n },\n MCP_PKCE_2026_07_28: {\n id: 'MCP-2026-07-28-PKCE-requirement',\n url: 'https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/security-considerations#authorization-code-protection'\n },\n // MCP_AUTH_RESPONSE_VALIDATION_2026_07_28 carries the MCP requirement (SEP-2468).\n RFC_9207_ISS_PARAMETER: {\n id: 'RFC-9207-iss-parameter',\n url: 'https://www.rfc-editor.org/rfc/rfc9207.html#section-2'\n },\n RFC_8693_TOKEN_EXCHANGE: {\n id: 'RFC-8693-Token-Exchange',\n url: 'https://datatracker.ietf.org/doc/html/rfc8693'\n },\n RFC_7523_JWT_BEARER: {\n id: 'RFC-7523-JWT-Bearer-Grant',\n url: 'https://datatracker.ietf.org/doc/html/rfc7523'\n },\n SEP_990_ENTERPRISE_OAUTH: {\n id: 'SEP-990-Enterprise-Managed-OAuth',\n url: 'https://github.com/modelcontextprotocol/ext-auth/blob/main/specification/draft/enterprise-managed-authorization.mdx'\n },\n SEP_2207_REFRESH_TOKEN_GUIDANCE: {\n id: 'SEP-2207-Refresh-Token-Guidance',\n url: 'https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2207'\n },\n SEP_1933_WIF: {\n id: 'SEP-1933-Workload-Identity-Federation',\n url: 'https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1933'\n },\n // DPoP (SEP-1932 / RFC 9449) — client concerns.\n SEP_1932_DPOP: {\n id: 'SEP-1932-DPoP',\n url: 'https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1932'\n },\n DPOP_EXTENSION: {\n id: 'MCP-DPoP-Extension',\n url: 'https://github.com/modelcontextprotocol/ext-auth/blob/pieterkas-dpop-extension/specification/draft/dpop-extension.mdx'\n },\n RFC_9449_PROOF_SYNTAX: {\n id: 'RFC-9449-dpop-proof-jwt-syntax',\n url: 'https://www.rfc-editor.org/rfc/rfc9449.html#section-4.2'\n },\n RFC_9449_CHECKING_PROOFS: {\n id: 'RFC-9449-checking-dpop-proofs',\n url: 'https://www.rfc-editor.org/rfc/rfc9449.html#section-4.3'\n },\n RFC_9449_AUTH_SCHEME: {\n id: 'RFC-9449-dpop-authentication-scheme',\n url: 'https://www.rfc-editor.org/rfc/rfc9449.html#section-7.1'\n },\n RFC_9449_TOKEN_REQUEST: {\n id: 'RFC-9449-dpop-access-token-request',\n url: 'https://www.rfc-editor.org/rfc/rfc9449.html#section-5'\n },\n RFC_9449_AS_NONCE: {\n id: 'RFC-9449-authorization-server-provided-nonce',\n url: 'https://www.rfc-editor.org/rfc/rfc9449.html#section-8'\n },\n RFC_9449_RS_NONCE: {\n id: 'RFC-9449-resource-server-provided-nonce',\n url: 'https://www.rfc-editor.org/rfc/rfc9449.html#section-9'\n }\n};\n",[],[150,501,833,967,977],"b13f0912-fc72-4f37-9bf8-d41d500b7618","scope-handling.ts","e359bcf2-ad13-11f1-986c-1607ee4eb77e",288,["D",1789339721686],"import {\n AuthHandlerScenario,\n AuthHandlerContext,\n AuthHandlers,\n ConformanceCheck,\n DRAFT_PROTOCOL_VERSION,\n SpecVersion,\n isSpecVersion,\n specVersionAtLeast\n} from '../../../types.ts';\nimport { createAuthServer } from './helpers/createAuthServer.ts';\nimport { createServer } from './helpers/createServer.ts';\nimport { SpecReferences } from './spec-references.ts';\nimport { MockTokenVerifier } from './helpers/mockTokenVerifier.ts';\nimport type { Request, Response, NextFunction } from 'npm:express@^5.1.0';\n\n/**\n * The authorization requests in a scenario's log, in the order they arrived.\n * Scenarios that judge the Nth authorization request read them here, at\n * judgement time, rather than counting requests as they arrive: on a\n * serverless host consecutive requests can reach processes whose replayed\n * logs each lack the other's, but the log being judged holds them all.\n */\nfunction authorizationRequests(checks: ConformanceCheck[]): ConformanceCheck[] {\n return checks.filter((c) => c.id === 'authorization-request');\n}\n\n/**\n * The authorization request that answers the insufficient_scope challenge:\n * the first one logged after the first 403 from the MCP endpoint. A client\n * may start an authorization and abandon it before then (the C# SDK does\n * when its server/discover probe times out mid-flow and it falls back to\n * initialize), so the second authorization request is not reliably the\n * escalation. With no 403 in the log, it is the second request, as before.\n */\nfunction escalationRequest(\n checks: ConformanceCheck[]\n): ConformanceCheck | undefined {\n const challenge = checks.findIndex(\n (c) =>\n c.id === 'outgoing-response' &&\n c.details?.path === '/mcp' &&\n c.details?.statusCode === 403\n );\n if (challenge < 0) return authorizationRequests(checks)[1];\n return authorizationRequests(checks.slice(challenge + 1))[0];\n}\n\n/** The `scope` parameter of a logged authorization request, if any. */\nfunction requestedScope(authorization: ConformanceCheck): string | undefined {\n const query = authorization.details?.query as\n | Record\n | undefined;\n return typeof query?.scope === 'string' ? query.scope : undefined;\n}\n\n/** The revision createAuthServer recorded on a logged authorization request. */\nfunction specVersionIn(checks: ConformanceCheck[]): SpecVersion | undefined {\n for (const c of authorizationRequests(checks)) {\n const v = c.details?.specVersion;\n if (isSpecVersion(v)) return v;\n }\n return undefined;\n}\n\n/**\n * Scenario 1: Client uses scope from WWW-Authenticate header\n *\n * Tests that clients SHOULD follow the scope parameter from the initial\n * WWW-Authenticate header in the 401 response, per the scope selection strategy.\n */\nexport class ScopeFromWwwAuthenticateScenario extends AuthHandlerScenario {\n name = 'auth/scope-from-www-authenticate';\n readonly source = { introducedIn: '2025-11-25' } as const;\n description =\n 'Tests that client uses scope parameter from WWW-Authenticate header when provided';\n private checks: ConformanceCheck[] = [];\n\n authHandlers(ctx: AuthHandlerContext): AuthHandlers {\n this.checks = [];\n const getAsUrl = () => ctx.getAuxBaseUrl('as');\n\n const expectedScope = 'mcp:basic';\n const tokenVerifier = new MockTokenVerifier(this.checks, [expectedScope]);\n\n const authApp = createAuthServer(ctx, this.checks, getAsUrl, {\n tokenVerifier,\n onAuthorizationRequest: (data) => {\n // Check if client used the scope from WWW-Authenticate header\n const requestedScopes = data.scope ? data.scope.split(' ') : [];\n const usedCorrectScope = requestedScopes.includes(expectedScope);\n this.checks.push({\n id: 'scope-from-www-authenticate',\n name: 'Client scope selection from WWW-Authenticate header',\n description: usedCorrectScope\n ? 'Client correctly used the scope parameter from the WWW-Authenticate header'\n : 'Client SHOULD use the scope parameter from the WWW-Authenticate header when provided',\n status: usedCorrectScope ? 'SUCCESS' : 'WARNING',\n timestamp: data.timestamp,\n specReferences: [\n SpecReferences.MCP_SCOPE_SELECTION_STRATEGY,\n SpecReferences.MCP_SCOPE_SELECTION_STRATEGY_2026_07_28\n ],\n details: {\n expectedScope,\n requestedScope: data.scope || 'none'\n }\n });\n }\n });\n\n const rsApp = createServer(ctx, this.checks, ctx.getRsBaseUrl, getAsUrl, {\n prmPath: '/.well-known/oauth-protected-resource/mcp',\n requiredScopes: [expectedScope],\n includeScopeInWwwAuth: true,\n tokenVerifier\n });\n\n return { rs: rsApp, aux: { as: authApp } };\n }\n\n getChecks(): ConformanceCheck[] {\n const checks = [...this.checks];\n // Emit failure check if expected scope check didn't run\n const hasScopeCheck = checks.some(\n (c) => c.id === 'scope-from-www-authenticate'\n );\n if (!hasScopeCheck) {\n checks.push({\n id: 'scope-from-www-authenticate',\n name: 'Client scope selection from WWW-Authenticate header',\n description:\n 'Client did not complete authorization flow - scope check could not be performed',\n status: 'FAILURE',\n timestamp: new Date().toISOString(),\n specReferences: [\n SpecReferences.MCP_SCOPE_SELECTION_STRATEGY,\n SpecReferences.MCP_SCOPE_SELECTION_STRATEGY_2026_07_28\n ]\n });\n }\n return checks;\n }\n}\n\n/**\n * Scenario 2: Client falls back to scopes_supported when scope not in WWW-Authenticate\n *\n * Tests that clients SHOULD use all scopes from scopes_supported in the PRM\n * when the scope parameter is not available in the WWW-Authenticate header.\n */\nexport class ScopeFromScopesSupportedScenario extends AuthHandlerScenario {\n name = 'auth/scope-from-scopes-supported';\n readonly source = { introducedIn: '2025-11-25' } as const;\n description =\n 'Tests that client uses all scopes from scopes_supported when scope not in WWW-Authenticate header';\n private checks: ConformanceCheck[] = [];\n\n authHandlers(ctx: AuthHandlerContext): AuthHandlers {\n this.checks = [];\n const getAsUrl = () => ctx.getAuxBaseUrl('as');\n\n const scopesSupported = ['mcp:basic', 'mcp:read', 'mcp:write'];\n const tokenVerifier = new MockTokenVerifier(this.checks, scopesSupported);\n\n const authApp = createAuthServer(ctx, this.checks, getAsUrl, {\n tokenVerifier,\n onAuthorizationRequest: (data) => {\n // Check if client requested all scopes from scopes_supported\n const requestedScopes = data.scope ? data.scope.split(' ') : [];\n const hasAllScopes = scopesSupported.every((scope) =>\n requestedScopes.includes(scope)\n );\n this.checks.push({\n id: 'scope-from-scopes-supported',\n name: 'Client scope selection from scopes_supported',\n description: hasAllScopes\n ? 'Client correctly used all scopes from scopes_supported in PRM when scope not in WWW-Authenticate'\n : 'Client SHOULD use all scopes from scopes_supported when scope not available in WWW-Authenticate header',\n status: hasAllScopes ? 'SUCCESS' : 'WARNING',\n timestamp: data.timestamp,\n specReferences: [\n SpecReferences.MCP_SCOPE_SELECTION_STRATEGY,\n SpecReferences.MCP_SCOPE_SELECTION_STRATEGY_2026_07_28\n ],\n details: {\n scopesSupported: scopesSupported.join(' '),\n requestedScope: data.scope || 'none',\n ...(hasAllScopes\n ? {}\n : {\n missingScopes: scopesSupported\n .filter((s) => !requestedScopes.includes(s))\n .join(' ')\n })\n }\n });\n }\n });\n\n const rsApp = createServer(ctx, this.checks, ctx.getRsBaseUrl, getAsUrl, {\n prmPath: '/.well-known/oauth-protected-resource/mcp',\n requiredScopes: scopesSupported,\n scopesSupported: scopesSupported,\n includeScopeInWwwAuth: false,\n tokenVerifier\n });\n\n return { rs: rsApp, aux: { as: authApp } };\n }\n\n getChecks(): ConformanceCheck[] {\n const checks = [...this.checks];\n // Emit failure check if expected scope check didn't run\n const hasScopeCheck = checks.some(\n (c) => c.id === 'scope-from-scopes-supported'\n );\n if (!hasScopeCheck) {\n checks.push({\n id: 'scope-from-scopes-supported',\n name: 'Client scope selection from scopes_supported',\n description:\n 'Client did not complete authorization flow - scope check could not be performed',\n status: 'FAILURE',\n timestamp: new Date().toISOString(),\n specReferences: [\n SpecReferences.MCP_SCOPE_SELECTION_STRATEGY,\n SpecReferences.MCP_SCOPE_SELECTION_STRATEGY_2026_07_28\n ]\n });\n }\n return checks;\n }\n}\n\n/**\n * Scenario 3: Client omits scope when scopes_supported is undefined\n *\n * Tests that clients SHOULD omit the scope parameter when scopes_supported\n * is not available in the PRM and scope is not in WWW-Authenticate header.\n */\nexport class ScopeOmittedWhenUndefinedScenario extends AuthHandlerScenario {\n name = 'auth/scope-omitted-when-undefined';\n readonly source = { introducedIn: '2025-11-25' } as const;\n description =\n 'Tests that client omits scope parameter when scopes_supported is undefined';\n private checks: ConformanceCheck[] = [];\n\n authHandlers(ctx: AuthHandlerContext): AuthHandlers {\n this.checks = [];\n const getAsUrl = () => ctx.getAuxBaseUrl('as');\n\n const tokenVerifier = new MockTokenVerifier(this.checks, []);\n\n const authApp = createAuthServer(ctx, this.checks, getAsUrl, {\n tokenVerifier,\n onAuthorizationRequest: (data) => {\n // Check if client omitted scope parameter\n const scopeOmitted = !data.scope || data.scope.trim() === '';\n this.checks.push({\n id: 'scope-omitted-when-undefined',\n name: 'Client scope omission when scopes_supported undefined',\n description: scopeOmitted\n ? 'Client correctly omitted scope parameter when scopes_supported is undefined'\n : 'Client SHOULD omit scope parameter when scopes_supported is undefined and scope not in WWW-Authenticate',\n status: scopeOmitted ? 'SUCCESS' : 'WARNING',\n timestamp: data.timestamp,\n specReferences: [\n SpecReferences.MCP_SCOPE_SELECTION_STRATEGY,\n SpecReferences.MCP_SCOPE_SELECTION_STRATEGY_2026_07_28\n ],\n details: {\n scopeParameter: scopeOmitted ? 'omitted' : data.scope\n }\n });\n }\n });\n\n const rsApp = createServer(ctx, this.checks, ctx.getRsBaseUrl, getAsUrl, {\n prmPath: '/.well-known/oauth-protected-resource/mcp',\n requiredScopes: [],\n scopesSupported: undefined,\n includeScopeInWwwAuth: false,\n tokenVerifier\n });\n\n return { rs: rsApp, aux: { as: authApp } };\n }\n\n getChecks(): ConformanceCheck[] {\n const checks = [...this.checks];\n // Emit failure check if expected scope check didn't run\n const hasScopeCheck = checks.some(\n (c) => c.id === 'scope-omitted-when-undefined'\n );\n if (!hasScopeCheck) {\n checks.push({\n id: 'scope-omitted-when-undefined',\n name: 'Client scope omission when scopes_supported undefined',\n description:\n 'Client did not complete authorization flow - scope check could not be performed',\n status: 'FAILURE',\n timestamp: new Date().toISOString(),\n specReferences: [\n SpecReferences.MCP_SCOPE_SELECTION_STRATEGY,\n SpecReferences.MCP_SCOPE_SELECTION_STRATEGY_2026_07_28\n ]\n });\n }\n return checks;\n }\n}\n\n/**\n * Scenario 4: Client performs step-up authentication\n *\n * Tests that clients handle step-up authentication where:\n * - initialize/notifications do not require auth\n * - listTools requires mcp:basic scope (401 if missing)\n * - tools/call requires mcp:basic + mcp:write scopes (403 if insufficient)\n * Client must handle both 401 and 403 responses with different scope requirements\n */\nexport class ScopeStepUpAuthScenario extends AuthHandlerScenario {\n name = 'auth/scope-step-up';\n readonly source = { introducedIn: '2025-11-25' } as const;\n description =\n 'Tests that client handles step-up authentication with different scope requirements per operation';\n private checks: ConformanceCheck[] = [];\n // SEP-2350's set-wise union requirement was introduced in 2026-07-28 (the\n // current draft); it was not a requirement at 2025-11-25, where\n // non-accumulating re-auth is conformant. Gate the union check accordingly.\n // An instance that only judges a log gets it from judgeAt(), or failing\n // that from the log; see getChecks().\n private specVersion: SpecVersion | undefined;\n\n judgeAt(specVersion: SpecVersion): void {\n this.specVersion = specVersion;\n }\n\n private static readonly initialScope = 'mcp:basic';\n // tools/call gates on mcp:write only (not the union) so the scenario can\n // complete even for clients that don't accumulate; the SEP-2350 check then\n // observes whether the previously-granted mcp:basic was retained.\n private static readonly stepUpScope = 'mcp:write';\n\n authHandlers(ctx: AuthHandlerContext): AuthHandlers {\n this.checks = [];\n this.specVersion = ctx.specVersion;\n const getAsUrl = () => ctx.getAuxBaseUrl('as');\n\n const { initialScope, stepUpScope } = ScopeStepUpAuthScenario;\n const escalatedScopes = [initialScope, stepUpScope];\n const tokenVerifier = new MockTokenVerifier(this.checks, escalatedScopes);\n\n // The authorization requests are judged in getChecks(), in order.\n const authApp = createAuthServer(ctx, this.checks, getAsUrl, {\n tokenVerifier\n });\n\n // Inline step-up auth middleware\n const resourceMetadataUrl = () =>\n `${ctx.getRsBaseUrl()}/.well-known/oauth-protected-resource/mcp`;\n\n const stepUpMiddleware = async (\n req: Request,\n res: Response,\n next: NextFunction\n ) => {\n // Parse body to check method\n let body = req.body;\n if (typeof body === 'string') {\n body = JSON.parse(body);\n }\n const method = body?.method;\n\n // Allow initialize and notifications without auth\n if (method === 'initialize' || method?.startsWith('notifications/')) {\n return next();\n }\n\n const authHeader = req.headers.authorization;\n if (!authHeader || !authHeader.startsWith('Bearer ')) {\n // No auth - return 401 with initial scope\n return res\n .status(401)\n .set(\n 'WWW-Authenticate',\n `Bearer scope=\"${initialScope}\", resource_metadata=\"${resourceMetadataUrl()}\"`\n )\n .json({\n error: 'invalid_token',\n error_description: 'Missing Authorization header'\n });\n }\n\n const token = authHeader.substring('Bearer '.length);\n const authInfo = await tokenVerifier.verifyAccessToken(token);\n const tokenScopes = authInfo.scopes || [];\n\n // Determine required scopes based on method\n const isToolCall = method === 'tools/call';\n const requiredScopes = isToolCall ? [stepUpScope] : [initialScope];\n\n const hasRequiredScopes = requiredScopes.every((s) =>\n tokenScopes.includes(s)\n );\n\n if (!hasRequiredScopes) {\n // Has token but insufficient scopes - return 403. Challenge with only\n // the step-up scope so SEP-2350 union accumulation is observable: a\n // client that just echoes the challenge would drop mcp:basic.\n return res\n .status(403)\n .set(\n 'WWW-Authenticate',\n `Bearer scope=\"${stepUpScope}\", resource_metadata=\"${resourceMetadataUrl()}\", error=\"insufficient_scope\"`\n )\n .json({\n error: 'insufficient_scope',\n error_description: 'Token has insufficient scope'\n });\n }\n\n next();\n };\n\n const rsApp = createServer(ctx, this.checks, ctx.getRsBaseUrl, getAsUrl, {\n prmPath: '/.well-known/oauth-protected-resource/mcp',\n requiredScopes: escalatedScopes,\n // Deliberately disjoint from initialScope/stepUpScope so the SEP-2350\n // union check can't be satisfied by a client that unions\n // scopes_supported ∪ challenge instead of prior-grant ∪ challenge.\n // The spec allows this: clients MUST NOT assume any set relationship\n // between challenged scopes and scopes_supported.\n scopesSupported: ['mcp:profile'],\n includeScopeInWwwAuth: true,\n authMiddleware: stepUpMiddleware,\n tokenVerifier\n });\n\n return { rs: rsApp, aux: { as: authApp } };\n }\n\n getChecks(): ConformanceCheck[] {\n const checks = [...this.checks];\n const { initialScope, stepUpScope } = ScopeStepUpAuthScenario;\n const specVersion = this.specVersion ?? specVersionIn(this.checks);\n const unionRequired =\n specVersion !== undefined &&\n specVersionAtLeast(specVersion, DRAFT_PROTOCOL_VERSION);\n const [initial] = authorizationRequests(this.checks);\n const escalation = escalationRequest(this.checks);\n\n if (initial) {\n // First auth request - should request mcp:basic from WWW-Authenticate\n const scope = requestedScope(initial);\n const usedCorrectScope = (scope?.split(' ') ?? []).includes(initialScope);\n checks.push({\n id: 'scope-step-up-initial',\n name: 'Client initial scope selection for step-up auth',\n description: usedCorrectScope\n ? 'Client correctly used scope from WWW-Authenticate header for initial auth'\n : 'Client SHOULD use the scope parameter from the WWW-Authenticate header',\n status: usedCorrectScope ? 'SUCCESS' : 'WARNING',\n timestamp: initial.timestamp,\n specReferences: [\n SpecReferences.MCP_SCOPE_SELECTION_STRATEGY,\n SpecReferences.MCP_SCOPE_SELECTION_STRATEGY_2026_07_28\n ],\n details: {\n expectedScope: initialScope,\n requestedScope: scope || 'none'\n }\n });\n }\n\n if (escalation) {\n // Second auth request after a 403 challenge that listed only the\n // *missing* scope (mcp:write). Two distinct assertions:\n // - escalation: client included the challenged scope at all\n // - SEP-2350 union: client *also* kept the previously-granted scope\n // that was NOT in the challenge (i.e., computed prior ∪ challenge)\n const scope = requestedScope(escalation);\n const requestedScopes = scope?.split(' ') ?? [];\n const includesChallenged = requestedScopes.includes(stepUpScope);\n checks.push({\n id: 'scope-step-up-escalation',\n name: 'Client scope escalation for step-up auth',\n description: includesChallenged\n ? 'Client correctly requested the challenged scope for step-up authentication'\n : 'Client SHOULD request additional scopes when receiving 403 with new scope requirements',\n status: includesChallenged ? 'SUCCESS' : 'WARNING',\n timestamp: escalation.timestamp,\n specReferences: [\n SpecReferences.MCP_SCOPE_SELECTION_STRATEGY,\n SpecReferences.MCP_SCOPE_SELECTION_STRATEGY_2026_07_28\n ],\n details: {\n challengedScope: stepUpScope,\n requestedScope: scope || 'none'\n }\n });\n\n if (unionRequired) {\n const retainedPrior = requestedScopes.includes(initialScope);\n checks.push({\n id: 'sep-2350-scope-union-on-reauth',\n name: 'Client accumulates previously-granted scopes on re-authorization',\n description: retainedPrior\n ? 'Client included previously-granted scopes alongside the newly challenged scope when re-authorizing'\n : 'Client SHOULD compute the union of previously requested scopes and newly challenged scopes when initiating re-authorization (SEP-2350); previously-granted scope was dropped',\n status: retainedPrior ? 'SUCCESS' : 'WARNING',\n timestamp: escalation.timestamp,\n specReferences: [\n SpecReferences.MCP_SCOPE_CHALLENGE_HANDLING,\n SpecReferences.MCP_SCOPE_CHALLENGE_HANDLING_2026_07_28\n ],\n details: {\n previouslyGranted: initialScope,\n challengedScope: stepUpScope,\n requestedScope: scope || 'none'\n }\n });\n }\n }\n\n // Emit failure checks if expected auth requests didn't happen\n if (!initial) {\n checks.push({\n id: 'scope-step-up-initial',\n name: 'Client initial scope selection for step-up auth',\n description: 'Client did not make an initial authorization request',\n status: 'FAILURE',\n timestamp: new Date().toISOString(),\n specReferences: [\n SpecReferences.MCP_SCOPE_SELECTION_STRATEGY,\n SpecReferences.MCP_SCOPE_SELECTION_STRATEGY_2026_07_28\n ]\n });\n }\n\n if (!escalation) {\n checks.push({\n id: 'scope-step-up-escalation',\n name: 'Client scope escalation for step-up auth',\n description:\n 'Client did not make a second authorization request for scope escalation',\n status: 'FAILURE',\n timestamp: new Date().toISOString(),\n specReferences: [\n SpecReferences.MCP_SCOPE_SELECTION_STRATEGY,\n SpecReferences.MCP_SCOPE_SELECTION_STRATEGY_2026_07_28\n ]\n });\n if (unionRequired) {\n checks.push({\n id: 'sep-2350-scope-union-on-reauth',\n name: 'Client accumulates previously-granted scopes on re-authorization',\n description:\n 'Client did not make a second authorization request - scope union check could not be performed',\n status: 'FAILURE',\n timestamp: new Date().toISOString(),\n specReferences: [\n SpecReferences.MCP_SCOPE_CHALLENGE_HANDLING,\n SpecReferences.MCP_SCOPE_CHALLENGE_HANDLING_2026_07_28\n ]\n });\n }\n }\n\n return checks;\n }\n}\n\n/**\n * Scenario 5: Client implements retry limits for scope escalation\n *\n * Tests that clients SHOULD implement retry limits to avoid infinite\n * authorization loops when receiving repeated 403 insufficient_scope errors.\n * The server always returns 403 with the same scope requirement, and clients\n * should stop retrying after a reasonable number of attempts (3 or fewer).\n */\nexport class ScopeRetryLimitScenario extends AuthHandlerScenario {\n name = 'auth/scope-retry-limit';\n readonly source = { introducedIn: '2025-11-25' } as const;\n description =\n 'Tests that client implements retry limits to prevent infinite authorization loops on repeated 403 responses';\n allowClientError = true;\n private checks: ConformanceCheck[] = [];\n\n authHandlers(ctx: AuthHandlerContext): AuthHandlers {\n this.checks = [];\n const getAsUrl = () => ctx.getAuxBaseUrl('as');\n\n const requiredScope = 'mcp:admin';\n const tokenVerifier = new MockTokenVerifier(this.checks, []);\n\n // Each authorization request is an attempt, counted in getChecks().\n const authApp = createAuthServer(ctx, this.checks, getAsUrl, {\n tokenVerifier\n });\n\n const resourceMetadataUrl = () =>\n `${ctx.getRsBaseUrl()}/.well-known/oauth-protected-resource/mcp`;\n\n const maxAttempts = 3;\n // Token-bearing MCP requests answered so far. Every one of them is\n // answered 403 or 410 by the middleware below, and the request logger\n // records each answer, so the count is read from the log (replayed into\n // each process on a serverless host) rather than kept in memory.\n const answeredWithToken = () =>\n this.checks.filter(\n (c) =>\n c.id === 'outgoing-response' &&\n c.details?.path === '/mcp' &&\n (c.details?.statusCode === 403 || c.details?.statusCode === 410)\n ).length;\n\n const alwaysDeny403Middleware = async (\n req: Request,\n res: Response,\n next: NextFunction\n ) => {\n let body = req.body;\n if (typeof body === 'string') {\n body = JSON.parse(body);\n }\n const method = body?.method;\n\n if (method === 'initialize' || method?.startsWith('notifications/')) {\n return next();\n }\n\n const authHeader = req.headers.authorization;\n if (!authHeader || !authHeader.startsWith('Bearer ')) {\n return res\n .status(401)\n .set(\n 'WWW-Authenticate',\n `Bearer scope=\"${requiredScope}\", resource_metadata=\"${resourceMetadataUrl()}\"`\n )\n .json({\n error: 'invalid_token',\n error_description: 'Missing Authorization header'\n });\n }\n\n const mcpRequestWithTokenCount = answeredWithToken() + 1;\n\n if (mcpRequestWithTokenCount > maxAttempts) {\n return res.status(410).json({\n error: 'test_complete',\n error_description:\n 'Test is over - client exceeded maximum retry attempts'\n });\n }\n\n return res\n .status(403)\n .set(\n 'WWW-Authenticate',\n `Bearer error=\"insufficient_scope\", scope=\"${requiredScope}\", resource_metadata=\"${resourceMetadataUrl()}\", error_description=\"Scope upgrade will never succeed\"`\n )\n .json({\n error: 'insufficient_scope',\n error_description: 'Scope upgrade will never succeed'\n });\n };\n\n const rsApp = createServer(ctx, this.checks, ctx.getRsBaseUrl, getAsUrl, {\n prmPath: '/.well-known/oauth-protected-resource/mcp',\n requiredScopes: [requiredScope],\n scopesSupported: [requiredScope],\n includeScopeInWwwAuth: true,\n authMiddleware: alwaysDeny403Middleware,\n tokenVerifier\n });\n\n return { rs: rsApp, aux: { as: authApp } };\n }\n\n getChecks(): ConformanceCheck[] {\n const checks = [...this.checks];\n const attempts = authorizationRequests(this.checks);\n attempts.forEach((authorization, i) => {\n const attemptNumber = i + 1;\n checks.push({\n id: 'scope-retry-auth-attempt',\n name: `Authorization attempt ${attemptNumber}`,\n description: `Client made authorization request attempt ${attemptNumber}`,\n status: 'INFO',\n timestamp: authorization.timestamp,\n specReferences: [\n SpecReferences.MCP_SCOPE_CHALLENGE_HANDLING,\n SpecReferences.MCP_SCOPE_CHALLENGE_HANDLING_2026_07_28\n ],\n details: {\n attemptNumber,\n requestedScope: requestedScope(authorization) || 'none'\n }\n });\n });\n const authAttempts = attempts.length;\n\n if (authAttempts === 0) {\n checks.push({\n id: 'scope-retry-limit',\n name: 'Client retry limit for scope escalation',\n description: 'Client did not make any authorization requests',\n status: 'FAILURE',\n timestamp: new Date().toISOString(),\n specReferences: [\n SpecReferences.MCP_SCOPE_CHALLENGE_HANDLING,\n SpecReferences.MCP_SCOPE_CHALLENGE_HANDLING_2026_07_28\n ]\n });\n } else if (authAttempts <= 3) {\n checks.push({\n id: 'scope-retry-limit',\n name: 'Client retry limit for scope escalation',\n description: `Client correctly limited retry attempts to ${authAttempts} (3 or fewer)`,\n status: 'SUCCESS',\n timestamp: new Date().toISOString(),\n specReferences: [\n SpecReferences.MCP_SCOPE_CHALLENGE_HANDLING,\n SpecReferences.MCP_SCOPE_CHALLENGE_HANDLING_2026_07_28\n ],\n details: {\n authorizationAttempts: authAttempts,\n maxAllowed: 3\n }\n });\n } else {\n checks.push({\n id: 'scope-retry-limit',\n name: 'Client retry limit for scope escalation',\n description: `Client made ${authAttempts} authorization attempts (more than 3). Clients SHOULD implement retry limits to avoid infinite loops.`,\n status: 'FAILURE',\n timestamp: new Date().toISOString(),\n specReferences: [\n SpecReferences.MCP_SCOPE_CHALLENGE_HANDLING,\n SpecReferences.MCP_SCOPE_CHALLENGE_HANDLING_2026_07_28\n ],\n details: {\n authorizationAttempts: authAttempts,\n maxAllowed: 3\n }\n });\n }\n\n return checks;\n }\n}\n",[],[150,501,833,967,985],"7d744954-1c56-4ad3-97f3-33d9d8df416e","resource-mismatch.ts","e2557274-ad13-11f1-8f50-1607ee4eb77e",287,["D",1789339720782],"import {\n AuthHandlerScenario,\n AuthHandlerContext,\n AuthHandlers,\n ConformanceCheck,\n DRAFT_PROTOCOL_VERSION\n} from '../../../types.ts';\nimport { createAuthServer } from './helpers/createAuthServer.ts';\nimport { createServer } from './helpers/createServer.ts';\nimport { SpecReferences } from './spec-references.ts';\nimport { MockTokenVerifier } from './helpers/mockTokenVerifier.ts';\nimport { untestableCheck } from '../../untestable.ts';\n\n/**\n * Scenario: Resource Mismatch Detection\n *\n * Tests that clients correctly detect and reject when the Protected Resource\n * Metadata returns a `resource` field that doesn't match the server URL\n * the client is trying to access.\n *\n * Per RFC 8707 and MCP spec, clients MUST validate that the resource from\n * PRM matches the expected server before proceeding with authorization.\n *\n * Setup:\n * - Server returns PRM with resource: \"https://evil.example.com/mcp\" (different origin)\n * - Client is trying to access the actual server at localhost:/mcp\n *\n * Expected behavior:\n * - Client should NOT proceed with authorization\n * - Client should abort due to resource mismatch\n * - Test passes if client does NOT complete the auth flow (no authorization request)\n */\nexport class ResourceMismatchScenario extends AuthHandlerScenario {\n name = 'auth/resource-mismatch';\n readonly source = { introducedIn: DRAFT_PROTOCOL_VERSION } as const;\n description =\n 'Tests that client rejects when PRM resource does not match server URL';\n allowClientError = true;\n\n private checks: ConformanceCheck[] = [];\n\n authHandlers(ctx: AuthHandlerContext): AuthHandlers {\n this.checks = [];\n const getAsUrl = () => ctx.getAuxBaseUrl('as');\n\n const tokenVerifier = new MockTokenVerifier(this.checks, []);\n\n // An authorization request means the client proceeded despite the\n // mismatch; getChecks() reads it from the log.\n const authApp = createAuthServer(ctx, this.checks, getAsUrl, {\n tokenVerifier,\n tokenEndpointAuthMethodsSupported: ['none'],\n onRegistrationRequest: () => ({\n clientId: `test-client-${Date.now()}`,\n clientSecret: undefined,\n tokenEndpointAuthMethod: 'none'\n })\n });\n\n // Create server that returns a mismatched resource in PRM\n const rsApp = createServer(ctx, this.checks, ctx.getRsBaseUrl, getAsUrl, {\n prmPath: '/.well-known/oauth-protected-resource/mcp',\n requiredScopes: [],\n tokenVerifier,\n // Return a different origin in PRM - this should be rejected by the client\n prmResourceOverride: 'https://evil.example.com/mcp'\n });\n\n return { rs: rsApp, aux: { as: authApp } };\n }\n\n getChecks(): ConformanceCheck[] {\n const checks = [...this.checks];\n const timestamp = new Date().toISOString();\n // The MCP text requires the resource parameter to name this server; the\n // rule that a client must not use PRM whose `resource` differs from the\n // URL it fetched it for is RFC 9728 section 3.3.\n const specRefs = [\n SpecReferences.RFC_8707_RESOURCE_INDICATORS,\n SpecReferences.MCP_RESOURCE_PARAMETER,\n SpecReferences.RFC_9728_RESOURCE_IDENTITY\n ];\n\n // Reason-bound verdict (#467). \"Did not proceed with authorization\" is not\n // by itself evidence of validation: a client that never fetched the PRM\n // document never read the mismatched `resource`, so it cannot have\n // compared it. Absent that fetch the requirement was never exercised,\n // which is the untestable case (#248) rather than a pass or a violation.\n if (!checks.some((c) => c.id === 'resource-mismatch-rejected')) {\n const prmRequested = this.checks.some(\n (c) => c.id === 'prm-pathbased-requested'\n );\n const authorizationRequestMade = this.checks.some(\n (c) => c.id === 'authorization-request'\n );\n const correctlyRejected = prmRequested && !authorizationRequestMade;\n const observations = {\n prmResource: 'https://evil.example.com/mcp',\n expectedBehavior: 'Client should NOT proceed with authorization',\n prmRequested,\n authorizationRequestMade\n };\n\n if (!prmRequested) {\n const check = untestableCheck(\n 'resource-mismatch-rejected',\n 'Client rejects mismatched resource',\n 'Client MUST validate that PRM resource matches the server URL before proceeding with authorization',\n 'client never requested the Protected Resource Metadata document, so it never read the resource value it was required to validate',\n specRefs\n );\n check.details = {\n ...check.details,\n ...observations,\n propertyReached: false,\n stopReason: 'prm-not-requested'\n };\n checks.push(check);\n } else {\n checks.push({\n id: 'resource-mismatch-rejected',\n name: 'Client rejects mismatched resource',\n description: correctlyRejected\n ? 'Client correctly rejected authorization when PRM resource does not match server URL'\n : 'Client MUST validate that PRM resource matches the server URL before proceeding with authorization',\n status: correctlyRejected ? 'SUCCESS' : 'FAILURE',\n timestamp,\n specReferences: specRefs,\n details: {\n ...observations,\n propertyReached: true,\n stopReason: correctlyRejected\n ? 'declined-after-reading-prm'\n : 'proceeded-to-authorization'\n }\n });\n }\n }\n\n return checks;\n }\n}\n",[],[150,501,833,967,993],"98c8fb9a-ff31-4227-995c-f8fc9677344a","pre-registration.ts","e2148534-ad13-11f1-b438-1607ee4eb77e",286,["D",1789339720181],"import {\n AuthHandlerScenario,\n AuthHandlerContext,\n AuthHandlers,\n ConformanceCheck\n} from '../../../types.ts';\nimport { createAuthServer } from './helpers/createAuthServer.ts';\nimport { createServer } from './helpers/createServer.ts';\nimport { SpecReferences } from './spec-references.ts';\nimport { MockTokenVerifier } from './helpers/mockTokenVerifier.ts';\n\nconst PRE_REGISTERED_CLIENT_ID = 'pre-registered-client';\nconst PRE_REGISTERED_CLIENT_SECRET = 'pre-registered-secret';\n\n/**\n * Scenario: Pre-registration (static client credentials)\n *\n * Tests OAuth flow where the server does NOT support Dynamic Client Registration.\n * Clients must use pre-registered credentials passed via context. The context\n * also carries the mock AS's `issuer` identifier: clients targeting the\n * 2026-07-28 spec MUST associate pre-registered credentials with the\n * authorization server that issued them, keyed by that issuer\n * (Authorization Server Binding):\n * https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/client-registration#authorization-server-binding\n *\n * This tests the pre-registration approach described in the MCP spec:\n * https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#preregistration\n * https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/client-registration#pre-registration\n */\nexport class PreRegistrationScenario extends AuthHandlerScenario {\n name = 'auth/pre-registration';\n readonly source = { introducedIn: '2025-11-25' } as const;\n description =\n 'Tests OAuth flow with pre-registered client credentials. Server does not support DCR.';\n\n private checks: ConformanceCheck[] = [];\n private getAsUrl: (() => string) | null = null;\n\n authHandlers(ctx: AuthHandlerContext): AuthHandlers {\n this.checks = [];\n const getAsUrl = () => ctx.getAuxBaseUrl('as');\n this.getAsUrl = getAsUrl;\n const tokenVerifier = new MockTokenVerifier(this.checks, []);\n\n const authApp = createAuthServer(ctx, this.checks, getAsUrl, {\n tokenVerifier,\n disableDynamicRegistration: true,\n tokenEndpointAuthMethodsSupported: ['client_secret_basic'],\n onTokenRequest: ({ authorizationHeader, timestamp }) => {\n // Verify client used pre-registered credentials via Basic auth\n if (!authorizationHeader?.startsWith('Basic ')) {\n this.checks.push({\n id: 'pre-registration-auth',\n name: 'Pre-registration authentication',\n description:\n 'Client did not use Basic authentication with pre-registered credentials',\n status: 'FAILURE',\n timestamp,\n specReferences: [\n SpecReferences.MCP_PREREGISTRATION,\n SpecReferences.MCP_PREREGISTRATION_2026_07_28\n ]\n });\n return {\n error: 'invalid_client',\n errorDescription: 'Missing or invalid Authorization header',\n statusCode: 401\n };\n }\n\n const base64Credentials = authorizationHeader.slice(6);\n const credentials = Buffer.from(base64Credentials, 'base64').toString(\n 'utf-8'\n );\n const [clientId, clientSecret] = credentials.split(':');\n\n if (\n clientId !== PRE_REGISTERED_CLIENT_ID ||\n clientSecret !== PRE_REGISTERED_CLIENT_SECRET\n ) {\n this.checks.push({\n id: 'pre-registration-auth',\n name: 'Pre-registration authentication',\n description: `Client used incorrect pre-registered credentials. Expected client_id '${PRE_REGISTERED_CLIENT_ID}', got '${clientId}'`,\n status: 'FAILURE',\n timestamp,\n specReferences: [\n SpecReferences.MCP_PREREGISTRATION,\n SpecReferences.MCP_PREREGISTRATION_2026_07_28\n ],\n details: {\n expectedClientId: PRE_REGISTERED_CLIENT_ID,\n actualClientId: clientId\n }\n });\n return {\n error: 'invalid_client',\n errorDescription: 'Invalid pre-registered credentials',\n statusCode: 401\n };\n }\n\n // Success - client used correct pre-registered credentials\n this.checks.push({\n id: 'pre-registration-auth',\n name: 'Pre-registration authentication',\n description:\n 'Client correctly used pre-registered credentials when server does not support DCR',\n status: 'SUCCESS',\n timestamp,\n specReferences: [\n SpecReferences.MCP_PREREGISTRATION,\n SpecReferences.MCP_PREREGISTRATION_2026_07_28\n ],\n details: { clientId }\n });\n\n return {\n token: `test-token-prereg-${Date.now()}`,\n scopes: []\n };\n }\n });\n\n const rsApp = createServer(ctx, this.checks, ctx.getRsBaseUrl, getAsUrl, {\n prmPath: '/.well-known/oauth-protected-resource/mcp',\n requiredScopes: [],\n tokenVerifier\n });\n\n return { rs: rsApp, aux: { as: authApp } };\n }\n\n protected scenarioContext() {\n return {\n client_id: PRE_REGISTERED_CLIENT_ID,\n client_secret: PRE_REGISTERED_CLIENT_SECRET,\n // The `issuer` the mock AS publishes in its metadata — the scenario\n // sets neither `metadataIssuer` nor `routePrefix`, so createAuthServer\n // resolves the published issuer to exactly the AS base URL.\n issuer: this.getAsUrl?.()\n };\n }\n\n getChecks(): ConformanceCheck[] {\n // Ensure we have the pre-registration check\n const hasPreRegCheck = this.checks.some(\n (c) => c.id === 'pre-registration-auth'\n );\n if (!hasPreRegCheck) {\n this.checks.push({\n id: 'pre-registration-auth',\n name: 'Pre-registration authentication',\n description: 'Client did not make a token request',\n status: 'FAILURE',\n timestamp: new Date().toISOString(),\n specReferences: [\n SpecReferences.MCP_PREREGISTRATION,\n SpecReferences.MCP_PREREGISTRATION_2026_07_28\n ]\n });\n }\n\n return this.checks;\n }\n}\n",[],[150,501,833,967,1001],"6dd2e82a-b2c9-441b-979b-617c71256f37","offline-access.ts","e174e3e4-ad13-11f1-ad25-1607ee4eb77e",285,["D",1789339715950],"import type { ScenarioContext } from '../../../mock-server/index.ts';\nimport {\n AuthHandlerScenario,\n AuthHandlerContext,\n AuthHandlers,\n ConformanceCheck,\n DRAFT_PROTOCOL_VERSION,\n ScenarioUrls\n} from '../../../types.ts';\nimport { createAuthServer } from './helpers/createAuthServer.ts';\nimport { createServer } from './helpers/createServer.ts';\nimport { SpecReferences } from './spec-references.ts';\nimport { MockTokenVerifier } from './helpers/mockTokenVerifier.ts';\n\n/** Whether a grant_types observation (DCR body or CIMD document) is logged. */\nfunction grantTypesCheckedIn(checks: ConformanceCheck[]): boolean {\n return checks.some((c) => c.id === 'sep-2207-client-metadata-grant-types');\n}\n\n/**\n * Scenario: Offline Access Scope (SEP-2207)\n *\n * Tests client behavior when the Authorization Server metadata lists\n * `offline_access` in `scopes_supported`:\n *\n * 1. Client SHOULD include `refresh_token` in `grant_types` client metadata\n * (checked via DCR body or CIMD document, whichever the client uses)\n * 2. Client MAY include `offline_access` in authorization request scope\n *\n * Setup:\n * - AS metadata: scopes_supported includes 'offline_access'\n * - PRM: scopes_supported does NOT include 'offline_access' (per SEP-2207 server guidance)\n * - Both CIMD and DCR paths available\n */\nexport class OfflineAccessScopeScenario extends AuthHandlerScenario {\n name = 'auth/offline-access-scope';\n readonly source = { introducedIn: DRAFT_PROTOCOL_VERSION } as const;\n description =\n 'Tests that a client that wants a refresh token handles offline_access scope and refresh_token grant type when AS supports them (SEP-2207)';\n\n private checks: ConformanceCheck[] = [];\n /**\n * Whether to fetch a CIMD client's metadata document. Only when run\n * locally through start(): the hosted server calls authHandlers() itself\n * and must not fetch URLs a client hands it, so there a CIMD client's\n * grant_types stay uninspected (INFO).\n */\n private fetchesCimd = false;\n\n async start(ctx: ScenarioContext): Promise {\n this.fetchesCimd = true;\n return super.start(ctx);\n }\n\n authHandlers(ctx: AuthHandlerContext): AuthHandlers {\n this.checks = [];\n const getAsUrl = () => ctx.getAuxBaseUrl('as');\n\n const tokenVerifier = new MockTokenVerifier(this.checks, ['mcp:basic']);\n\n const authApp = createAuthServer(ctx, this.checks, getAsUrl, {\n tokenVerifier,\n scopesSupported: ['mcp:basic', 'offline_access'],\n clientIdMetadataDocumentSupported: true,\n onRegistrationRequest: (req) => {\n // DCR path: inspect grant_types in registration body\n const grantTypes: string[] = req.body.grant_types || [];\n const hasRefreshToken = grantTypes.includes('refresh_token');\n this.checks.push({\n id: 'sep-2207-client-metadata-grant-types',\n name: 'Client metadata includes refresh_token grant type (DCR)',\n description: hasRefreshToken\n ? 'Client correctly included refresh_token in grant_types during dynamic client registration'\n : 'Client SHOULD include refresh_token in grant_types client metadata (SEP-2207)',\n status: hasRefreshToken ? 'SUCCESS' : 'WARNING',\n timestamp: new Date().toISOString(),\n specReferences: [\n SpecReferences.SEP_2207_REFRESH_TOKEN_GUIDANCE,\n SpecReferences.MCP_REFRESH_TOKENS_2026_07_28\n ],\n details: {\n registrationMethod: 'DCR',\n grantTypes: grantTypes.length > 0 ? grantTypes.join(' ') : 'none'\n }\n });\n\n const clientId = `test-client-${Date.now()}`;\n return {\n clientId,\n clientSecret: undefined,\n tokenEndpointAuthMethod: 'none'\n };\n },\n onAuthorizationRequest: async (data) => {\n // Check if client included offline_access in scope\n const requestedScopes = data.scope ? data.scope.split(' ') : [];\n const hasOfflineAccess = requestedScopes.includes('offline_access');\n this.checks.push({\n id: 'sep-2207-offline-access-requested',\n name: 'Client requests offline_access scope',\n description: hasOfflineAccess\n ? 'Client included offline_access in authorization request scope when AS lists it in scopes_supported'\n : 'Client MAY include offline_access in scope when AS metadata lists it in scopes_supported (SEP-2207). Client chose not to request it.',\n status: hasOfflineAccess ? 'SUCCESS' : 'INFO',\n timestamp: data.timestamp,\n specReferences: [\n SpecReferences.SEP_2207_REFRESH_TOKEN_GUIDANCE,\n SpecReferences.MCP_REFRESH_TOKENS_2026_07_28\n ],\n details: {\n asScopesSupported: 'mcp:basic offline_access',\n requestedScope: data.scope || 'none'\n }\n });\n\n // A URL-based client_id (CIMD): inspect its metadata document now,\n // before answering, so the observation is in the log that the\n // results are judged from.\n if (\n this.fetchesCimd &&\n data.clientId?.startsWith('http') &&\n !grantTypesCheckedIn(this.checks)\n ) {\n await this.inspectCimd(data.clientId);\n }\n }\n });\n\n // PRM does NOT include offline_access (per SEP-2207 server guidance:\n // servers SHOULD NOT include offline_access in PRM scopes_supported)\n const rsApp = createServer(ctx, this.checks, ctx.getRsBaseUrl, getAsUrl, {\n prmPath: '/.well-known/oauth-protected-resource/mcp',\n requiredScopes: ['mcp:basic'],\n scopesSupported: ['mcp:basic'],\n tokenVerifier\n });\n\n return { rs: rsApp, aux: { as: authApp } };\n }\n\n /** Fetch a CIMD client's metadata document and log its grant_types. */\n private async inspectCimd(cimdUrl: string): Promise

Hold on — this client led with initialize

MCP Checker — 2026-07-28

How it works

What is checked

Old clients

Try it

MCP Checker — Auth Chain

Hold on — this client led with `initialize`

History · replay.ts