From e9cbf57fc00eb81496ef0ef3ff2a080146c5eebe Mon Sep 17 00:00:00 2001 From: Paul Carleton Date: Wed, 27 May 2026 18:52:54 +0000 Subject: [PATCH 1/9] Add hosted conformance server Mounts every (non-auth) client-testing scenario at /s/ on a single long-lived HTTP server, so clients-under-test can point at a public URL instead of being spawned by the runner. - src/hosted/: session manager + loopback proxy + express app - /results/[.html]: JSON or pretty-printed checks per session - /mcp: the hosted server is itself an MCP server with list_scenarios, start_session, get_results tools - examples/hosted/valtown.ts: self-contained Request->Response variant for serverless hosts that can't bind loopback ports - conformance hosted --port [--public-origin ] [--ttl ] Auth scenarios are excluded - they need a second public origin for the authorization server, which a single-host proxy can't expose. Co-Authored-By: Claude Opus 4.8 --- examples/hosted/valtown.ts | 377 +++++++++++++++++++++++++++++++++++++ src/hosted/README.md | 56 ++++++ src/hosted/hosted.test.ts | 153 +++++++++++++++ src/hosted/html.ts | 96 ++++++++++ src/hosted/index.ts | 37 ++++ src/hosted/proxy.ts | 80 ++++++++ src/hosted/server.ts | 308 ++++++++++++++++++++++++++++++ src/hosted/session.ts | 142 ++++++++++++++ src/index.ts | 22 +++ 9 files changed, 1271 insertions(+) create mode 100644 examples/hosted/valtown.ts create mode 100644 src/hosted/README.md create mode 100644 src/hosted/hosted.test.ts create mode 100644 src/hosted/html.ts create mode 100644 src/hosted/index.ts create mode 100644 src/hosted/proxy.ts create mode 100644 src/hosted/server.ts create mode 100644 src/hosted/session.ts diff --git a/examples/hosted/valtown.ts b/examples/hosted/valtown.ts new file mode 100644 index 00000000..82e25278 --- /dev/null +++ b/examples/hosted/valtown.ts @@ -0,0 +1,377 @@ +/** + * MCP conformance — val.town deployment. + * + * val.town can't bind loopback ports, so the proxy approach used by + * `conformance hosted` doesn't apply. This file instead re-implements a small + * set of scenarios as pure Request→Response handlers and serves them with the + * same URL shape: + * + * POST /s/ MCP endpoint (session created on first request) + * GET /results/ JSON checks + * GET /results/.html HTML report + * GET /scenarios JSON scenario list + * POST /mcp meta-MCP server (list_scenarios / get_results) + * + * Deploy: paste this file into a val.town HTTP val. State lives in module + * scope, which val.town keeps warm between requests; for durable storage swap + * `sessions` for `import { sqlite } from "https://esm.town/v/std/sqlite"`. + * + * Coverage is intentionally narrow (initialize, tools_call). Add more + * handlers to the `scenarios` map below as needed. + */ + +// --- types (inlined so this file is self-contained) ------------------------- + +type CheckStatus = 'SUCCESS' | 'FAILURE' | 'WARNING' | 'SKIPPED' | 'INFO'; + +interface ConformanceCheck { + id: string; + name: string; + description: string; + status: CheckStatus; + timestamp: string; + specReferences?: { id: string; url?: string }[]; + details?: Record; + errorMessage?: string; +} + +interface Session { + id: string; + scenario: string; + checks: ConformanceCheck[]; + createdAt: number; +} + +type JsonRpc = { + jsonrpc: '2.0'; + id?: number | string; + method?: string; + params?: any; +}; + +type ScenarioHandler = (msg: JsonRpc, session: Session) => object; + +// --- state ----------------------------------------------------------------- + +const NEGOTIABLE = ['2025-06-18', '2025-11-25', 'DRAFT-2026-v1']; +const sessions = new Map(); + +function newSession(scenario: string): Session { + const id = crypto.randomUUID().slice(0, 8); + const s: Session = { id, scenario, checks: [], createdAt: Date.now() }; + sessions.set(id, s); + return s; +} + +function push(s: Session, c: Omit): void { + s.checks.push({ ...c, timestamp: new Date().toISOString() }); +} + +// --- scenario handlers ----------------------------------------------------- + +const scenarios: Record< + string, + { description: string; handle: ScenarioHandler } +> = { + initialize: { + description: 'Tests MCP client initialization handshake', + handle(msg, s) { + if (msg.method === 'initialize') { + const p = msg.params ?? {}; + const ok = + typeof p.protocolVersion === 'string' && + p.clientInfo?.name && + p.clientInfo?.version; + push(s, { + id: 'mcp-client-initialization', + name: 'MCPClientInitialization', + description: + 'Validates that MCP client properly initializes with server', + status: ok ? 'SUCCESS' : 'FAILURE', + specReferences: [ + { + id: 'MCP-Lifecycle', + url: 'https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle' + } + ], + details: { + protocolVersionSent: p.protocolVersion, + clientName: p.clientInfo?.name, + clientVersion: p.clientInfo?.version + }, + errorMessage: ok ? undefined : 'missing protocolVersion or clientInfo' + }); + const v = NEGOTIABLE.includes(p.protocolVersion) + ? p.protocolVersion + : '2025-11-25'; + return { + protocolVersion: v, + serverInfo: { name: 'conformance-valtown', version: '0.1.0' }, + capabilities: {} + }; + } + return {}; + } + }, + + tools_call: { + description: 'Tests calling tools with various parameter types', + handle(msg, s) { + if (msg.method === 'initialize') { + return { + protocolVersion: '2025-11-25', + serverInfo: { name: 'add-numbers-server', version: '1.0.0' }, + capabilities: { tools: {} } + }; + } + if (msg.method === 'tools/list') { + return { + tools: [ + { + name: 'add_numbers', + description: 'Add two numbers together', + inputSchema: { + type: 'object', + properties: { a: { type: 'number' }, b: { type: 'number' } }, + required: ['a', 'b'] + } + } + ] + }; + } + if (msg.method === 'tools/call' && msg.params?.name === 'add_numbers') { + const { a, b } = msg.params.arguments ?? {}; + const ok = typeof a === 'number' && typeof b === 'number'; + push(s, { + id: 'tool-add-numbers', + name: 'ToolAddNumbers', + description: 'Validates that the add_numbers tool works correctly', + status: ok ? 'SUCCESS' : 'FAILURE', + specReferences: [ + { + id: 'MCP-Tools', + url: 'https://modelcontextprotocol.io/specification/2025-06-18/server/tools#calling-tools' + } + ], + details: { a, b, result: ok ? a + b : undefined } + }); + return { + content: [ + { + type: 'text', + text: ok ? `The sum of ${a} and ${b} is ${a + b}` : 'bad args' + } + ] + }; + } + return {}; + } + } +}; + +// --- meta MCP (the hosted server is itself an MCP server) ------------------ + +function metaMcp(msg: JsonRpc, origin: string): object { + if (msg.method === 'initialize') { + return { + protocolVersion: '2025-11-25', + serverInfo: { name: 'mcp-conformance-hosted', version: '0.1.0' }, + capabilities: { tools: {} } + }; + } + if (msg.method === 'tools/list') { + return { + tools: [ + { + name: 'list_scenarios', + description: 'List hostable scenarios.', + inputSchema: { type: 'object', properties: {} } + }, + { + name: 'get_results', + description: 'Fetch checks for a session.', + inputSchema: { + type: 'object', + properties: { session_id: { type: 'string' } }, + required: ['session_id'] + } + } + ] + }; + } + if (msg.method === 'tools/call') { + const { name, arguments: args = {} } = msg.params ?? {}; + if (name === 'list_scenarios') { + const list = Object.entries(scenarios).map(([n, s]) => ({ + name: n, + description: s.description, + mcpUrl: `${origin}/s/${n}` + })); + return { + content: [{ type: 'text', text: JSON.stringify(list, null, 2) }] + }; + } + if (name === 'get_results') { + const sess = sessions.get(args.session_id); + if (!sess) + return { + content: [{ type: 'text', text: `no session '${args.session_id}'` }], + isError: true + }; + return { + content: [ + { type: 'text', text: JSON.stringify(summarise(sess), null, 2) } + ] + }; + } + return { + content: [{ type: 'text', text: `unknown tool ${name}` }], + isError: true + }; + } + return {}; +} + +// --- http glue ------------------------------------------------------------- + +function summarise(s: Session) { + const n = (st: CheckStatus) => s.checks.filter((c) => c.status === st).length; + return { + sessionId: s.id, + scenario: s.scenario, + summary: { + passed: n('SUCCESS'), + failed: n('FAILURE'), + warnings: n('WARNING'), + total: s.checks.length + }, + checks: s.checks + }; +} + +function json(body: unknown, init: ResponseInit = {}): Response { + return new Response(JSON.stringify(body), { + ...init, + headers: { 'content-type': 'application/json', ...(init.headers ?? {}) } + }); +} + +function rpcOk( + id: JsonRpc['id'], + result: object, + headers: HeadersInit = {} +): Response { + return json({ jsonrpc: '2.0', id, result }, { headers }); +} + +export default async function (req: Request): Promise { + const url = new URL(req.url); + const origin = `${url.protocol}//${url.host}`; + + // GET / + if (url.pathname === '/' && req.method === 'GET') { + const rows = Object.keys(scenarios) + .map( + (n) => + `${n}${origin}/s/${n}` + ) + .join(''); + return new Response( + `MCP conformance` + + `` + + `

MCP conformance (val.town)

` + + `

Point your client at a scenario URL. Read mcp-session-id ` + + `from the response, then GET /results/<id>.

` + + `

Meta MCP server: ${origin}/mcp

` + + `${rows}
`, + { headers: { 'content-type': 'text/html' } } + ); + } + + // GET /scenarios + if (url.pathname === '/scenarios') { + return json( + Object.entries(scenarios).map(([name, s]) => ({ + name, + description: s.description + })) + ); + } + + // /results/[.html] + const r = url.pathname.match(/^\/results\/([^/.]+)(\.html)?$/); + if (r) { + const s = sessions.get(r[1]); + if (!s) return json({ error: 'unknown session' }, { status: 404 }); + if (r[2]) { + const items = s.checks + .map( + (c) => + `
` + + `${c.status} ${c.id} — ${c.description}` + + (c.errorMessage ? `
${c.errorMessage}` : '') + + `
` + ) + .join(''); + return new Response(`

${s.scenario}

${items}`, { + headers: { 'content-type': 'text/html' } + }); + } + return json(summarise(s)); + } + + // POST /mcp — meta server + if (url.pathname === '/mcp' && req.method === 'POST') { + const msg = (await req.json()) as JsonRpc; + if (msg.id === undefined) return new Response(null, { status: 202 }); + return rpcOk(msg.id, metaMcp(msg, origin)); + } + + // /s/ + const m = url.pathname.match(/^\/s\/([^/]+)/); + if (m) { + const name = m[1]; + const handler = scenarios[name]; + if (!handler) + return json({ error: `unknown scenario '${name}'` }, { status: 404 }); + + if (req.method === 'GET') { + // SSE endpoint — minimal keep-alive so SDK clients that open a GET stream don't error. + return new Response('data: \n\n', { + headers: { 'content-type': 'text/event-stream' } + }); + } + if (req.method === 'DELETE') return new Response(null, { status: 200 }); + if (req.method !== 'POST') + return new Response('Method Not Allowed', { status: 405 }); + + const sid = req.headers.get('mcp-session-id'); + let session = sid ? sessions.get(sid) : undefined; + if (!session || session.scenario !== name) session = newSession(name); + + const msg = (await req.json()) as JsonRpc; + push(session, { + id: 'incoming-request', + name: 'IncomingRequest', + description: `Received ${msg.method ?? 'notification'}`, + status: 'INFO', + details: { method: msg.method, params: msg.params } + }); + + // notifications: no response body + if (msg.id === undefined) { + return new Response(null, { + status: 202, + headers: { 'mcp-session-id': session.id } + }); + } + + const result = handler.handle(msg, session); + return rpcOk(msg.id, result, { + 'mcp-session-id': session.id, + link: `<${origin}/results/${session.id}>; rel="conformance-results"` + }); + } + + return new Response('not found', { status: 404 }); +} diff --git a/src/hosted/README.md b/src/hosted/README.md new file mode 100644 index 00000000..cbab37a3 --- /dev/null +++ b/src/hosted/README.md @@ -0,0 +1,56 @@ +# Hosted conformance server + +Runs the client-testing scenarios as a single long-lived HTTP server so a +client-under-test can point at a public URL instead of being spawned by the +runner. + +```bash +npx @modelcontextprotocol/conformance hosted --port 3000 +# or with a public origin behind a proxy: +npx @modelcontextprotocol/conformance hosted --port 3000 --public-origin https://conformance.example.com +``` + +## Routes + +| Route | Purpose | +| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `GET /` | Landing page with usage + scenario list | +| `GET /scenarios` | JSON list of hostable scenarios | +| `ALL /s/[/]` | MCP endpoint for ``. First request without `mcp-session-id` creates a session; the response carries `mcp-session-id` and a `Link: ; rel="conformance-results"` header. | +| `GET /results/` | JSON `{summary, checks}` | +| `GET /results/.html` | Pretty HTML report | +| `DELETE /results/` | Tear down the session early | +| `POST /mcp` | The hosted server is itself an MCP server with `list_scenarios`, `start_session`, `get_results` tools | + +## How it works + +Each session is a real `Scenario` instance started on a loopback port; the +hosted server proxies `/s/` to it and overlays the session id. That +means every scenario works **unchanged** as long as it only needs one origin. + +Excluded (`auth/*`): scenarios that spin up a separate authorization server +on a second port. The proxy can't expose two origins, and OAuth discovery +metadata hard-codes absolute URLs. Run those with the CLI runner. + +Sessions are reaped after `--ttl` ms idle (default 5 min). + +## val.town + +`examples/hosted/valtown.ts` is a self-contained fetch-handler version with +the same URL shape but no loopback proxy — scenarios are reimplemented as +`Request → Response` functions. It ships with `initialize` and `tools_call`; +add more entries to its `scenarios` map as needed. + +## Example + +```bash +# 1. point your client at the scenario URL +$ my-mcp-client https://conformance.example.com/s/tools_call + +# 2. read mcp-session-id from any response header, then: +$ curl https://conformance.example.com/results/TJeZ63Bw | jq .summary +{ "passed": 1, "failed": 0, "warnings": 0, "info": 4, "skipped": 0, "total": 5 } +``` + +Or drive the whole flow over MCP by connecting to `/mcp` and calling +`start_session` → run client → `get_results`. diff --git a/src/hosted/hosted.test.ts b/src/hosted/hosted.test.ts new file mode 100644 index 00000000..c7494341 --- /dev/null +++ b/src/hosted/hosted.test.ts @@ -0,0 +1,153 @@ +import { describe, it, expect, beforeAll, afterAll } from 'vitest'; +import { createHostedApp } from './server'; +import { SessionManager } from './session'; +import type { Server } from 'http'; + +describe('hosted server', () => { + let server: Server; + let sessions: SessionManager; + let base: string; + + beforeAll(async () => { + const hosted = createHostedApp(); + sessions = hosted.sessions; + await new Promise((resolve) => { + server = hosted.app.listen(0, () => { + const addr = server.address(); + if (addr && typeof addr === 'object') + base = `http://localhost:${addr.port}`; + resolve(); + }); + }); + }); + + afterAll(async () => { + await sessions.close(); + await new Promise((r) => server.close(() => r())); + }); + + it('lists scenarios', async () => { + const res = await fetch(`${base}/scenarios`); + expect(res.status).toBe(200); + const list = await res.json(); + expect(Array.isArray(list)).toBe(true); + expect(list.some((s: { name: string }) => s.name === 'initialize')).toBe( + true + ); + // auth scenarios excluded + expect(list.some((s: { name: string }) => s.name.startsWith('auth/'))).toBe( + false + ); + }); + + it('proxies to a scenario and records checks', async () => { + const init = await fetch(`${base}/s/initialize`, { + method: 'POST', + headers: { + 'content-type': 'application/json', + accept: 'application/json, text/event-stream' + }, + body: JSON.stringify({ + jsonrpc: '2.0', + id: 1, + method: 'initialize', + params: { + protocolVersion: '2025-06-18', + clientInfo: { name: 'vitest', version: '0' }, + capabilities: {} + } + }) + }); + expect(init.status).toBe(200); + const sid = init.headers.get('mcp-session-id'); + expect(sid).toBeTruthy(); + expect(init.headers.get('link')).toContain(`/results/${sid}`); + + const body = await init.json(); + expect(body.result.serverInfo.name).toBe('test-server'); + + const results = await fetch(`${base}/results/${sid}`); + const data = await results.json(); + expect(data.summary.passed).toBeGreaterThanOrEqual(1); + expect( + data.checks.some( + (c: { id: string }) => c.id === 'mcp-client-initialization' + ) + ).toBe(true); + }); + + it('reuses a session across requests', async () => { + const r1 = await fetch(`${base}/s/tools_call`, { + method: 'POST', + headers: { + 'content-type': 'application/json', + accept: 'application/json, text/event-stream' + }, + body: JSON.stringify({ + jsonrpc: '2.0', + id: 1, + method: 'initialize', + params: { + protocolVersion: '2025-06-18', + clientInfo: { name: 't', version: '0' }, + capabilities: {} + } + }) + }); + const sid = r1.headers.get('mcp-session-id')!; + // SDK transport responds as SSE; just confirm the request was routed. + expect(r1.status).toBe(200); + await r1.text(); + + const r2 = await fetch(`${base}/s/tools_call`, { + method: 'POST', + headers: { + 'content-type': 'application/json', + accept: 'application/json, text/event-stream', + 'mcp-session-id': sid + }, + body: JSON.stringify({ + jsonrpc: '2.0', + id: 2, + method: 'tools/call', + params: { name: 'add_numbers', arguments: { a: 2, b: 3 } } + }) + }); + expect(r2.status).toBe(200); + await r2.text(); + + const results = await fetch(`${base}/results/${sid}`).then((r) => r.json()); + expect( + results.checks.some((c: { id: string }) => c.id === 'tool-add-numbers') + ).toBe(true); + }); + + it('404s on unknown scenario', async () => { + const res = await fetch(`${base}/s/does-not-exist`, { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: '{}' + }); + expect(res.status).toBe(404); + }); + + it('exposes meta MCP tools', async () => { + const res = await fetch(`${base}/mcp`, { + method: 'POST', + headers: { + 'content-type': 'application/json', + accept: 'application/json, text/event-stream' + }, + body: JSON.stringify({ + jsonrpc: '2.0', + id: 1, + method: 'tools/list', + params: {} + }) + }); + const text = await res.text(); + expect(text).toContain('list_scenarios'); + expect(text).toContain('start_session'); + expect(text).toContain('get_results'); + }); +}); diff --git a/src/hosted/html.ts b/src/hosted/html.ts new file mode 100644 index 00000000..1af5bdcb --- /dev/null +++ b/src/hosted/html.ts @@ -0,0 +1,96 @@ +import { ConformanceCheck, CheckStatus } from '../types'; + +const STATUS_STYLE: Record = { + SUCCESS: 'background:#d1fae5;color:#065f46', + FAILURE: 'background:#fee2e2;color:#991b1b', + WARNING: 'background:#fef3c7;color:#92400e', + SKIPPED: 'background:#e5e7eb;color:#374151', + INFO: 'background:#dbeafe;color:#1e40af' +}; + +const css = ` + body{font:14px/1.5 ui-sans-serif,system-ui,sans-serif;max-width:960px; + margin:2rem auto;padding:0 1rem;color:#111} + code,pre{font:12px/1.4 ui-monospace,SFMono-Regular,Menlo,monospace} + pre{background:#f6f8fa;padding:.75rem;border-radius:6px;overflow:auto} + .pill{display:inline-block;padding:2px 8px;border-radius:10px; + font-size:11px;font-weight:600} + .check{border:1px solid #e5e7eb;border-radius:6px;padding:.75rem; + margin:.5rem 0} + .check h3{margin:0 0 .25rem;font-size:14px} + details>summary{cursor:pointer;color:#6b7280;font-size:12px} + table{border-collapse:collapse;width:100%} + td,th{text-align:left;padding:.4rem .6rem;border-bottom:1px solid #eee} + a{color:#2563eb} +`; + +function esc(s: string): string { + return s.replace( + /[&<>"]/g, + (c) => ({ '&': '&', '<': '<', '>': '>', '"': '"' })[c]! + ); +} + +export function renderLanding(origin: string, scenarios: string[]): string { + const rows = scenarios + .map( + (n) => + `${esc(n)}` + + `${esc(origin)}/s/${esc(n)}` + ) + .join(''); + return ` +MCP Conformance — hosted +

MCP Conformance — hosted

+

Point your MCP client at one of the scenario URLs below. The first request +creates a session; the response carries an mcp-session-id header +and a Link: <.../results/ID>; rel="conformance-results" +header. Fetch that URL (or append .html) for your checks.

+

This server is also an MCP server at ${esc(origin)}/mcp with +list_scenarios / start_session / +get_results tools.

+

Scenarios (${scenarios.length})

+${rows}
nameMCP URL
+

Example

+
$ npx @modelcontextprotocol/inspector ${esc(origin)}/s/initialize
+# then open ${esc(origin)}/results/<mcp-session-id>.html
`; +} + +export function renderResults( + scenario: string, + sessionId: string, + checks: ConformanceCheck[] +): string { + const items = checks + .map((c) => { + const pill = `${c.status}`; + const refs = (c.specReferences ?? []) + .map((r) => + r.url + ? `${esc(r.id)}` + : `${esc(r.id)}` + ) + .join(' · '); + const details = + c.details || c.errorMessage + ? `
details
${esc(
+              JSON.stringify(
+                { errorMessage: c.errorMessage, ...c.details },
+                null,
+                2
+              )
+            )}
` + : ''; + return `

${pill} ${esc(c.id)} — ${esc( + c.name + )}

${esc(c.description)}

${refs}

${details}
`; + }) + .join(''); + const passed = checks.filter((c) => c.status === 'SUCCESS').length; + const failed = checks.filter((c) => c.status === 'FAILURE').length; + return ` +${esc(scenario)} — ${sessionId} +

${esc(scenario)}

+

session ${esc(sessionId)} — ${passed} passed, ${failed} failed, +${checks.length} total

${items}`; +} diff --git a/src/hosted/index.ts b/src/hosted/index.ts new file mode 100644 index 00000000..3d2937ea --- /dev/null +++ b/src/hosted/index.ts @@ -0,0 +1,37 @@ +import { createHostedApp } from './server'; +import { listHostableScenarios } from './session'; + +export { createHostedApp } from './server'; +export { listHostableScenarios } from './session'; + +export interface HostedCliOptions { + port: number; + publicOrigin?: string; + ttlMs?: number; +} + +export async function runHostedServer(opts: HostedCliOptions): Promise { + const { app, sessions } = createHostedApp({ + publicOrigin: opts.publicOrigin, + ttlMs: opts.ttlMs + }); + + const server = app.listen(opts.port, () => { + const origin = opts.publicOrigin ?? `http://localhost:${opts.port}`; + console.error(`MCP conformance hosted server listening on ${origin}`); + console.error( + ` ${listHostableScenarios().length} scenarios mounted under ${origin}/s/` + ); + console.error(` meta MCP server at ${origin}/mcp`); + }); + + const shutdown = async () => { + console.error('\nshutting down...'); + await sessions.close(); + server.close(() => process.exit(0)); + }; + process.on('SIGINT', shutdown); + process.on('SIGTERM', shutdown); + + await new Promise(() => {}); +} diff --git a/src/hosted/proxy.ts b/src/hosted/proxy.ts new file mode 100644 index 00000000..ce62ebcb --- /dev/null +++ b/src/hosted/proxy.ts @@ -0,0 +1,80 @@ +/** + * Minimal HTTP proxy that forwards an incoming express request to a + * scenario's loopback server and streams the response back. + * + * We don't use http-proxy-middleware to keep the dependency surface small + * and because we need to inject/rewrite the mcp-session-id header. + */ + +import http from 'http'; +import { Request, Response } from 'express'; +import { HostedSession } from './session'; + +/** Header used to correlate a client with its hosted session. */ +export const SESSION_HEADER = 'mcp-session-id'; + +export function proxyToSession( + session: HostedSession, + req: Request, + res: Response, + /** Path on the target to hit. Defaults to the scenario's serverUrl path. */ + targetPath?: string +): void { + const target = session.targetUrl; + const path = targetPath ?? (target.pathname || '/'); + + // Forward most headers but drop hop-by-hop ones and host (loopback target). + const headers: http.OutgoingHttpHeaders = {}; + for (const [k, v] of Object.entries(req.headers)) { + if (k === 'host' || k === 'connection' || k === 'content-length') continue; + headers[k] = v; + } + // Some scenarios assign their own mcp-session-id; let theirs flow back, but + // make sure the client always sees ours so /results/ works. + headers[SESSION_HEADER] = req.header(SESSION_HEADER) ?? session.id; + + const upstream = http.request( + { + hostname: target.hostname, + port: target.port, + path, + method: req.method, + headers + }, + (upRes) => { + const outHeaders = { ...upRes.headers }; + // Always advertise our session id so the client can fetch results, + // regardless of what the scenario set. + outHeaders[SESSION_HEADER] = session.id; + res.writeHead(upRes.statusCode ?? 502, outHeaders); + upRes.pipe(res); + } + ); + + upstream.on('error', (err) => { + if (!res.headersSent) { + res.status(502).json({ + jsonrpc: '2.0', + id: null, + error: { + code: -32001, + message: `Upstream scenario error: ${err.message}` + } + }); + } else { + res.end(); + } + }); + + // Stream the body. express.json() may have already consumed it; if so, + // re-serialize. Otherwise pipe raw (covers SSE GETs / DELETEs / unparsed). + if (req.body !== undefined && Object.keys(req.body).length > 0) { + const body = JSON.stringify(req.body); + upstream.setHeader('content-length', Buffer.byteLength(body)); + upstream.end(body); + } else if (req.readable) { + req.pipe(upstream); + } else { + upstream.end(); + } +} diff --git a/src/hosted/server.ts b/src/hosted/server.ts new file mode 100644 index 00000000..874a3c49 --- /dev/null +++ b/src/hosted/server.ts @@ -0,0 +1,308 @@ +/** + * Hosted conformance server. + * + * Mounts every (non-auth) client-testing scenario at a stable path: + * + * POST /s/ MCP endpoint — first request creates a session, + * subsequent requests reuse it via mcp-session-id + * GET /results/ JSON ConformanceCheck[] for that session + * GET /results/.html Pretty HTML report + * GET /scenarios JSON list of hostable scenarios + * GET / Landing page with usage instructions + * POST /mcp The hosted server is itself an MCP server + * exposing list_scenarios / start_session / + * get_results tools. + * + * Under the hood each session is a real Scenario instance listening on a + * loopback port; requests are proxied. That means ~90% of scenarios work + * unchanged. Auth scenarios are excluded because they need a second + * publicly-reachable origin for the authorization server. + */ + +import express, { Request } from 'express'; +import { Server } from '@modelcontextprotocol/sdk/server/index.js'; +import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'; +import { + CallToolRequestSchema, + ListToolsRequestSchema, + CallToolResult +} from '@modelcontextprotocol/sdk/types.js'; +import { + SessionManager, + UnknownScenarioError, + listHostableScenarios +} from './session'; +import { proxyToSession, SESSION_HEADER } from './proxy'; +import { renderLanding, renderResults } from './html'; +import { getScenario } from '../scenarios'; +import { ConformanceCheck } from '../types'; + +export interface HostedServerOptions { + /** Public origin (scheme+host+port) used in generated links. Auto-detected from Host header if omitted. */ + publicOrigin?: string; + ttlMs?: number; +} + +export function createHostedApp(opts: HostedServerOptions = {}): { + app: express.Application; + sessions: SessionManager; +} { + const sessions = new SessionManager({ ttlMs: opts.ttlMs }); + const app = express(); + + // Only parse JSON on the routes that need it; keep the proxy route raw so + // streaming bodies (and non-JSON content types) pass through untouched. + const jsonBody = express.json(); + + function origin(req: Request): string { + if (opts.publicOrigin) return opts.publicOrigin; + const proto = (req.header('x-forwarded-proto') ?? req.protocol) || 'http'; + const host = req.header('x-forwarded-host') ?? req.header('host'); + return `${proto}://${host}`; + } + + // ---------- discovery ---------- + + app.get('/', (req, res) => { + res.type('html').send(renderLanding(origin(req), listHostableScenarios())); + }); + + app.get('/scenarios', (_req, res) => { + const list = listHostableScenarios().map((name) => { + const s = getScenario(name)!; + return { name, description: s.description, source: s.source }; + }); + res.json(list); + }); + + // ---------- scenario proxy ---------- + + // Match the scenario name plus any trailing sub-path (some scenarios serve + // /mcp, others /, some auth-adjacent ones serve well-known paths). + // Use a regex param so names containing '/' still work as a single segment + // group while the suffix captures everything after it. + app.all(/^\/s\/(.+?)(\/.*)?$/, jsonBody, async (req, res) => { + const scenarioName = req.params[0]; + const suffix = req.params[1] ?? ''; + + if (!getScenario(scenarioName)) { + res.status(404).json({ error: `unknown scenario '${scenarioName}'` }); + return; + } + + const incomingId = req.header(SESSION_HEADER); + let session = incomingId ? sessions.get(incomingId) : undefined; + + if (session && session.scenarioName !== scenarioName) { + // Client is reusing a session id against a different scenario path. + // Treat as a new session rather than silently mixing checks. + session = undefined; + } + + if (!session) { + try { + session = await sessions.create(scenarioName); + } catch (e) { + const msg = e instanceof Error ? e.message : String(e); + res.status(500).json({ error: msg }); + return; + } + // Tell the client where to find its results without making it parse the + // session id out of the response headers. + res.setHeader( + 'link', + `<${origin(req)}/results/${session.id}>; rel="conformance-results"` + ); + } + + // If the client appended a sub-path (/.well-known/..., /mcp, ...) honour + // it; otherwise hit whatever path the scenario advertised in serverUrl. + const targetPath = suffix || undefined; + proxyToSession(session, req, res, targetPath); + }); + + // ---------- results ---------- + + app.get('/results/:id.html', (req, res) => { + const id = req.params.id; + const session = sessions.get(id); + const checks = sessions.results(id); + if (!session || !checks) { + res.status(404).type('html').send(`

No session ${id}

`); + return; + } + res.type('html').send(renderResults(session.scenarioName, id, checks)); + }); + + app.get('/results/:id', (req, res) => { + const checks = sessions.results(req.params.id); + if (!checks) { + res.status(404).json({ error: 'unknown session' }); + return; + } + res.json(summarise(req.params.id, checks)); + }); + + app.delete('/results/:id', async (req, res) => { + await sessions.destroy(req.params.id); + res.status(204).end(); + }); + + // ---------- meta MCP server ---------- + + app.post('/mcp', jsonBody, async (req, res) => { + const server = createMetaMcpServer(sessions, origin(req)); + const transport = new StreamableHTTPServerTransport({ + sessionIdGenerator: undefined + }); + await server.connect(transport); + await transport.handleRequest(req, res, req.body); + res.on('close', () => { + transport.close(); + server.close(); + }); + }); + + return { app, sessions }; +} + +function summarise(id: string, checks: ConformanceCheck[]) { + const counts = { SUCCESS: 0, FAILURE: 0, WARNING: 0, SKIPPED: 0, INFO: 0 }; + for (const c of checks) counts[c.status]++; + return { + sessionId: id, + summary: { + passed: counts.SUCCESS, + failed: counts.FAILURE, + warnings: counts.WARNING, + info: counts.INFO, + skipped: counts.SKIPPED, + total: checks.length + }, + checks + }; +} + +/** + * The hosted server is itself an MCP server so an agent can drive the whole + * flow over MCP: discover scenarios, mint a session URL, then fetch results. + */ +function createMetaMcpServer( + sessions: SessionManager, + publicOrigin: string +): Server { + const server = new Server( + { name: 'mcp-conformance-hosted', version: '0.1.0' }, + { capabilities: { tools: {} } } + ); + + server.setRequestHandler(ListToolsRequestSchema, async () => ({ + tools: [ + { + name: 'list_scenarios', + description: + 'List client-conformance scenarios this hosted instance can serve.', + inputSchema: { type: 'object', properties: {} } + }, + { + name: 'start_session', + description: + 'Create a fresh session for a scenario and return the MCP URL to point the client-under-test at, plus the results URL.', + inputSchema: { + type: 'object', + properties: { + scenario: { + type: 'string', + description: 'Scenario name, e.g. "initialize" or "tools_call".' + } + }, + required: ['scenario'] + } + }, + { + name: 'get_results', + description: + 'Fetch the conformance checks recorded for a session. Returns the same shape as GET /results/.', + inputSchema: { + type: 'object', + properties: { + session_id: { type: 'string' } + }, + required: ['session_id'] + } + } + ] + })); + + server.setRequestHandler( + CallToolRequestSchema, + async (request): Promise => { + const args = (request.params.arguments ?? {}) as Record; + switch (request.params.name) { + case 'list_scenarios': { + const list = listHostableScenarios().map((name) => ({ + name, + description: getScenario(name)!.description + })); + return text(JSON.stringify(list, null, 2)); + } + case 'start_session': { + try { + const session = await sessions.create(args.scenario); + return text( + JSON.stringify( + { + sessionId: session.id, + mcpUrl: `${publicOrigin}/s/${session.scenarioName}`, + resultsUrl: `${publicOrigin}/results/${session.id}`, + resultsHtmlUrl: `${publicOrigin}/results/${session.id}.html`, + context: session.context, + note: + 'Point your client at mcpUrl and include header ' + + `"${SESSION_HEADER}: ${session.id}" on every request.` + }, + null, + 2 + ) + ); + } catch (e) { + if (e instanceof UnknownScenarioError) { + return { + content: [{ type: 'text', text: e.message }], + isError: true + }; + } + throw e; + } + } + case 'get_results': { + const checks = sessions.results(args.session_id); + if (!checks) { + return { + content: [ + { type: 'text', text: `No session '${args.session_id}'` } + ], + isError: true + }; + } + return text( + JSON.stringify(summarise(args.session_id, checks), null, 2) + ); + } + default: + return { + content: [ + { type: 'text', text: `Unknown tool ${request.params.name}` } + ], + isError: true + }; + } + } + ); + + return server; +} + +function text(t: string): CallToolResult { + return { content: [{ type: 'text', text: t }] }; +} diff --git a/src/hosted/session.ts b/src/hosted/session.ts new file mode 100644 index 00000000..072fc0d8 --- /dev/null +++ b/src/hosted/session.ts @@ -0,0 +1,142 @@ +/** + * Session management for the hosted conformance server. + * + * A "session" is one isolated run of a scenario. Each session owns its own + * Scenario instance (and therefore its own underlying http.Server bound to a + * loopback port). The hosted server proxies path-prefixed requests to that + * port and harvests checks via getChecks(). + * + * Sessions are keyed by a short id (also surfaced as mcp-session-id) so a + * client can hit a stable scenario URL like /s/initialize and still get + * isolated results at /results/. + */ + +import { randomBytes } from 'crypto'; +import { Scenario, ConformanceCheck } from '../types'; +import { getScenario, listScenarios } from '../scenarios'; + +export interface HostedSession { + id: string; + scenarioName: string; + scenario: Scenario; + /** Loopback URL the scenario is listening on (e.g. http://localhost:54321/mcp) */ + targetUrl: URL; + createdAt: number; + lastSeenAt: number; + /** Optional context the scenario wants delivered to the client */ + context?: Record; +} + +export interface SessionManagerOptions { + /** Idle ms after which a session is reaped. Default 5 minutes. */ + ttlMs?: number; + /** How often to sweep for expired sessions. Default 30s. */ + sweepIntervalMs?: number; +} + +export class SessionManager { + private sessions = new Map(); + private readonly ttlMs: number; + private sweeper: ReturnType; + + constructor(opts: SessionManagerOptions = {}) { + this.ttlMs = opts.ttlMs ?? 5 * 60_000; + const sweepIntervalMs = opts.sweepIntervalMs ?? 30_000; + this.sweeper = setInterval(() => this.sweep(), sweepIntervalMs); + // Don't keep the process alive just for the sweeper. + this.sweeper.unref?.(); + } + + /** Create a fresh scenario instance and start it on a loopback port. */ + async create(scenarioName: string): Promise { + const factory = getScenario(scenarioName); + if (!factory) { + throw new UnknownScenarioError(scenarioName); + } + // Each call to getScenario returns the same singleton, so re-instantiate + // via its constructor to get isolated state. + const ScenarioCtor = factory.constructor as new () => Scenario; + const scenario = new ScenarioCtor(); + + const urls = await scenario.start(); + const id = randomBytes(6).toString('base64url'); + const session: HostedSession = { + id, + scenarioName, + scenario, + targetUrl: new URL(urls.serverUrl), + createdAt: Date.now(), + lastSeenAt: Date.now(), + context: urls.context + }; + this.sessions.set(id, session); + return session; + } + + get(id: string): HostedSession | undefined { + const s = this.sessions.get(id); + if (s) s.lastSeenAt = Date.now(); + return s; + } + + list(): HostedSession[] { + return Array.from(this.sessions.values()); + } + + results(id: string): ConformanceCheck[] | undefined { + const s = this.sessions.get(id); + return s?.scenario.getChecks(); + } + + async destroy(id: string): Promise { + const s = this.sessions.get(id); + if (!s) return; + this.sessions.delete(id); + try { + await s.scenario.stop(); + } catch { + // best-effort; the loopback server may already be gone + } + } + + async close(): Promise { + clearInterval(this.sweeper); + await Promise.all( + Array.from(this.sessions.keys()).map((id) => this.destroy(id)) + ); + } + + private sweep(): void { + const now = Date.now(); + for (const [id, s] of this.sessions) { + if (now - s.lastSeenAt > this.ttlMs) { + void this.destroy(id); + } + } + } +} + +export class UnknownScenarioError extends Error { + constructor(name: string) { + super( + `Unknown scenario '${name}'. Available: ${listScenarios().join(', ')}` + ); + } +} + +/** + * Scenarios that the hosted runner can serve via path-proxy. + * + * Excluded: scenarios whose ScenarioUrls.authUrl is set (they spin up a + * second auth server on another port that the client must reach directly, + * which a single-origin proxy can't expose) and scenarios that depend on + * the runner spawning the client process. + */ +export function listHostableScenarios(): string[] { + return listScenarios().filter((name) => { + const s = getScenario(name); + // No good static way to know if authUrl will be set without starting it, + // so use the naming convention all auth scenarios share. + return s !== undefined && !name.startsWith('auth/'); + }); +} diff --git a/src/index.ts b/src/index.ts index 4fd84a51..3eb75177 100644 --- a/src/index.ts +++ b/src/index.ts @@ -49,6 +49,7 @@ import { createTierCheckCommand } from './tier-check'; import { createNewSepCommand } from './new-sep'; import { createSdkCommand } from './sdk-runner'; import { createTraceabilityCommand } from './traceability'; +import { runHostedServer } from './hosted'; import packageJson from '../package.json'; // Note on naming: `command` refers to which CLI command is calling this. @@ -557,6 +558,27 @@ program.addCommand(createSdkCommand()); // SEP traceability manifest command program.addCommand(createTraceabilityCommand()); +// Hosted server — mount scenarios on URL paths for remote clients +program + .command('hosted') + .description( + 'Run a long-lived HTTP server that exposes every (non-auth) client ' + + 'scenario at /s/ and serves results at /results/.' + ) + .option('--port ', 'Port to listen on', '3000') + .option( + '--public-origin ', + 'Origin to use in generated links (default: derived from Host header)' + ) + .option('--ttl ', 'Idle session TTL in milliseconds', '300000') + .action(async (options) => { + await runHostedServer({ + port: parseInt(options.port, 10), + publicOrigin: options.publicOrigin, + ttlMs: parseInt(options.ttl, 10) + }); + }); + // List scenarios command program .command('list') From b1fb9043a57cd02fcc11876bdd1f0c3312d690ee Mon Sep 17 00:00:00 2001 From: Paul Carleton Date: Wed, 27 May 2026 19:19:09 +0000 Subject: [PATCH 2/9] hosted: mount scenario handlers directly; path-embedded run-id for stateless MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replaces the loopback-proxy approach with direct mounting: - Scenario gains optional handler(getBaseUrl) -> RequestListener and mcpPath. New HandlerScenario base class implements start()/stop() as a thin wrapper around handler(), so the CLI runner and hosted runner share identical scenario code with no port binding required for hosted mode. - Refactored every non-auth scenario (initialize, tools_call, elicitation-defaults, sse-retry, request-metadata, mrtr-client, json-schema-ref-deref, plus all BaseHttpScenario subclasses) onto HandlerScenario. json-schema-ref-deref now derives its canary URL from getBaseUrl so it points at the public mounted path. - URL scheme is now /s// with the run-id in the path, not the mcp-session-id header — works for stateless-transport clients (every draft scenario using sessionIdGenerator: undefined). - Dropped src/hosted/proxy.ts. - examples/hosted/valtown.ts is now a Request->Response bridge around the real createHostedApp(), not a reimplementation, so the same scenarios run on val.town/Deno/Bun. sse-retry is 501'd through the buffered bridge but works under 'conformance hosted'. 236/236 tests pass (13 new). Co-Authored-By: Claude Opus 4.8 --- examples/hosted/valtown.test.ts | 62 +++ examples/hosted/valtown.ts | 459 ++++-------------- src/hosted/README.md | 82 ++-- src/hosted/hosted.test.ts | 266 ++++++---- src/hosted/html.ts | 23 +- src/hosted/proxy.ts | 80 --- src/hosted/server.ts | 321 +++++++----- src/hosted/session.ts | 151 +++--- src/scenarios/client/elicitation-defaults.ts | 28 +- src/scenarios/client/http-base.ts | 45 +- src/scenarios/client/initialize.ts | 48 +- src/scenarios/client/json-schema-ref-deref.ts | 38 +- src/scenarios/client/mrtr-client.ts | 25 +- src/scenarios/client/request-metadata.ts | 34 +- src/scenarios/client/sse-retry.ts | 27 +- src/scenarios/client/tools_call.ts | 24 +- src/types.ts | 72 +++ 17 files changed, 824 insertions(+), 961 deletions(-) create mode 100644 examples/hosted/valtown.test.ts delete mode 100644 src/hosted/proxy.ts diff --git a/examples/hosted/valtown.test.ts b/examples/hosted/valtown.test.ts new file mode 100644 index 00000000..cf278f28 --- /dev/null +++ b/examples/hosted/valtown.test.ts @@ -0,0 +1,62 @@ +import { describe, it, expect } from 'vitest'; +import handler from './valtown'; + +describe('val.town fetch bridge', () => { + async function post(path: string, body: object) { + return handler( + new Request(`http://test${path}`, { + method: 'POST', + headers: { + 'content-type': 'application/json', + accept: 'application/json, text/event-stream' + }, + body: JSON.stringify(body) + }) + ); + } + + it('serves a raw-http scenario and records checks', async () => { + const r = await post('/s/initialize/ft1', { + jsonrpc: '2.0', + id: 1, + method: 'initialize', + params: { + protocolVersion: '2025-06-18', + clientInfo: { name: 'ft', version: '0' }, + capabilities: {} + } + }); + expect(r.status).toBe(200); + expect(r.headers.get('link')).toContain('/results/ft1'); + const checks = await handler(new Request('http://test/results/ft1')).then( + (r) => r.json() + ); + expect(checks.summary.passed).toBeGreaterThanOrEqual(1); + }); + + it('serves an SDK-transport scenario (tools_call) statelessly', async () => { + await post('/s/tools_call/ft2/mcp', { + jsonrpc: '2.0', + id: 1, + method: 'initialize', + params: { + protocolVersion: '2025-06-18', + clientInfo: { name: 'ft', version: '0' }, + capabilities: {} + } + }).then((r) => r.text()); + const r = await post('/s/tools_call/ft2/mcp', { + jsonrpc: '2.0', + id: 2, + method: 'tools/call', + params: { name: 'add_numbers', arguments: { a: 7, b: 4 } } + }); + expect(r.status).toBe(200); + expect(await r.text()).toContain('The sum of 7 and 4 is 11'); + }); + + it('blocks sse-retry through the bridge', async () => { + const r = await handler(new Request('http://test/s/sse-retry/x')); + expect(r.status).toBe(501); + }); +}); diff --git a/examples/hosted/valtown.ts b/examples/hosted/valtown.ts index 82e25278..51a3c340 100644 --- a/examples/hosted/valtown.ts +++ b/examples/hosted/valtown.ts @@ -1,377 +1,120 @@ /** * MCP conformance — val.town deployment. * - * val.town can't bind loopback ports, so the proxy approach used by - * `conformance hosted` doesn't apply. This file instead re-implements a small - * set of scenarios as pure Request→Response handlers and serves them with the - * same URL shape: + * The hosted runner mounts each scenario's `handler()` (a Node + * `RequestListener`) under `/s//`. On val.town the entry + * point is a fetch handler, so we bridge web Request→Node req/res once and + * reuse the *real* scenario implementations from the package — no + * reimplementation, no loopback port. * - * POST /s/ MCP endpoint (session created on first request) - * GET /results/ JSON checks - * GET /results/.html HTML report - * GET /scenarios JSON scenario list - * POST /mcp meta-MCP server (list_scenarios / get_results) + * Deploy: create an HTTP val and paste: * - * Deploy: paste this file into a val.town HTTP val. State lives in module - * scope, which val.town keeps warm between requests; for durable storage swap - * `sessions` for `import { sqlite } from "https://esm.town/v/std/sqlite"`. + * import handler from "https://esm.sh/@modelcontextprotocol/conformance/examples/hosted/valtown.ts"; + * export default handler; * - * Coverage is intentionally narrow (initialize, tools_call). Add more - * handlers to the `scenarios` map below as needed. + * or copy this file in directly. Requires a runtime with Node-compat + * (`node:http`, `node:stream`) — val.town, Deno Deploy, Bun all qualify. + * + * Limitation: scenarios that rely on long-lived SSE streams or connection- + * close timing (`sse-retry`) won't behave correctly through a buffered + * Request→Response bridge. They're filtered out below. */ -// --- types (inlined so this file is self-contained) ------------------------- - -type CheckStatus = 'SUCCESS' | 'FAILURE' | 'WARNING' | 'SKIPPED' | 'INFO'; - -interface ConformanceCheck { - id: string; - name: string; - description: string; - status: CheckStatus; - timestamp: string; - specReferences?: { id: string; url?: string }[]; - details?: Record; - errorMessage?: string; -} - -interface Session { - id: string; - scenario: string; - checks: ConformanceCheck[]; - createdAt: number; -} - -type JsonRpc = { - jsonrpc: '2.0'; - id?: number | string; - method?: string; - params?: any; -}; - -type ScenarioHandler = (msg: JsonRpc, session: Session) => object; - -// --- state ----------------------------------------------------------------- - -const NEGOTIABLE = ['2025-06-18', '2025-11-25', 'DRAFT-2026-v1']; -const sessions = new Map(); - -function newSession(scenario: string): Session { - const id = crypto.randomUUID().slice(0, 8); - const s: Session = { id, scenario, checks: [], createdAt: Date.now() }; - sessions.set(id, s); - return s; -} - -function push(s: Session, c: Omit): void { - s.checks.push({ ...c, timestamp: new Date().toISOString() }); -} - -// --- scenario handlers ----------------------------------------------------- - -const scenarios: Record< - string, - { description: string; handle: ScenarioHandler } -> = { - initialize: { - description: 'Tests MCP client initialization handshake', - handle(msg, s) { - if (msg.method === 'initialize') { - const p = msg.params ?? {}; - const ok = - typeof p.protocolVersion === 'string' && - p.clientInfo?.name && - p.clientInfo?.version; - push(s, { - id: 'mcp-client-initialization', - name: 'MCPClientInitialization', - description: - 'Validates that MCP client properly initializes with server', - status: ok ? 'SUCCESS' : 'FAILURE', - specReferences: [ - { - id: 'MCP-Lifecycle', - url: 'https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle' - } - ], - details: { - protocolVersionSent: p.protocolVersion, - clientName: p.clientInfo?.name, - clientVersion: p.clientInfo?.version - }, - errorMessage: ok ? undefined : 'missing protocolVersion or clientInfo' - }); - const v = NEGOTIABLE.includes(p.protocolVersion) - ? p.protocolVersion - : '2025-11-25'; - return { - protocolVersion: v, - serverInfo: { name: 'conformance-valtown', version: '0.1.0' }, - capabilities: {} - }; - } - return {}; - } - }, - - tools_call: { - description: 'Tests calling tools with various parameter types', - handle(msg, s) { - if (msg.method === 'initialize') { - return { - protocolVersion: '2025-11-25', - serverInfo: { name: 'add-numbers-server', version: '1.0.0' }, - capabilities: { tools: {} } - }; - } - if (msg.method === 'tools/list') { - return { - tools: [ - { - name: 'add_numbers', - description: 'Add two numbers together', - inputSchema: { - type: 'object', - properties: { a: { type: 'number' }, b: { type: 'number' } }, - required: ['a', 'b'] - } - } - ] - }; - } - if (msg.method === 'tools/call' && msg.params?.name === 'add_numbers') { - const { a, b } = msg.params.arguments ?? {}; - const ok = typeof a === 'number' && typeof b === 'number'; - push(s, { - id: 'tool-add-numbers', - name: 'ToolAddNumbers', - description: 'Validates that the add_numbers tool works correctly', - status: ok ? 'SUCCESS' : 'FAILURE', - specReferences: [ - { - id: 'MCP-Tools', - url: 'https://modelcontextprotocol.io/specification/2025-06-18/server/tools#calling-tools' - } - ], - details: { a, b, result: ok ? a + b : undefined } - }); - return { - content: [ - { - type: 'text', - text: ok ? `The sum of ${a} and ${b} is ${a + b}` : 'bad args' - } - ] - }; - } - return {}; - } - } -}; - -// --- meta MCP (the hosted server is itself an MCP server) ------------------ - -function metaMcp(msg: JsonRpc, origin: string): object { - if (msg.method === 'initialize') { - return { - protocolVersion: '2025-11-25', - serverInfo: { name: 'mcp-conformance-hosted', version: '0.1.0' }, - capabilities: { tools: {} } - }; - } - if (msg.method === 'tools/list') { - return { - tools: [ - { - name: 'list_scenarios', - description: 'List hostable scenarios.', - inputSchema: { type: 'object', properties: {} } - }, - { - name: 'get_results', - description: 'Fetch checks for a session.', - inputSchema: { - type: 'object', - properties: { session_id: { type: 'string' } }, - required: ['session_id'] - } - } - ] - }; - } - if (msg.method === 'tools/call') { - const { name, arguments: args = {} } = msg.params ?? {}; - if (name === 'list_scenarios') { - const list = Object.entries(scenarios).map(([n, s]) => ({ - name: n, - description: s.description, - mcpUrl: `${origin}/s/${n}` - })); - return { - content: [{ type: 'text', text: JSON.stringify(list, null, 2) }] - }; - } - if (name === 'get_results') { - const sess = sessions.get(args.session_id); - if (!sess) - return { - content: [{ type: 'text', text: `no session '${args.session_id}'` }], - isError: true - }; - return { - content: [ - { type: 'text', text: JSON.stringify(summarise(sess), null, 2) } - ] - }; - } - return { - content: [{ type: 'text', text: `unknown tool ${name}` }], - isError: true - }; - } - return {}; -} - -// --- http glue ------------------------------------------------------------- - -function summarise(s: Session) { - const n = (st: CheckStatus) => s.checks.filter((c) => c.status === st).length; - return { - sessionId: s.id, - scenario: s.scenario, - summary: { - passed: n('SUCCESS'), - failed: n('FAILURE'), - warnings: n('WARNING'), - total: s.checks.length - }, - checks: s.checks - }; -} - -function json(body: unknown, init: ResponseInit = {}): Response { - return new Response(JSON.stringify(body), { - ...init, - headers: { 'content-type': 'application/json', ...(init.headers ?? {}) } - }); -} +import { IncomingMessage, ServerResponse } from 'node:http'; +import { Socket } from 'node:net'; +import { createHostedApp } from '../../src/hosted/server'; -function rpcOk( - id: JsonRpc['id'], - result: object, - headers: HeadersInit = {} -): Response { - return json({ jsonrpc: '2.0', id, result }, { headers }); -} +const NOT_FETCH_SAFE = new Set(['sse-retry']); -export default async function (req: Request): Promise { - const url = new URL(req.url); - const origin = `${url.protocol}//${url.host}`; +const { app } = createHostedApp(); - // GET / - if (url.pathname === '/' && req.method === 'GET') { - const rows = Object.keys(scenarios) - .map( - (n) => - `${n}${origin}/s/${n}` - ) - .join(''); - return new Response( - `MCP conformance` + - `` + - `

MCP conformance (val.town)

` + - `

Point your client at a scenario URL. Read mcp-session-id ` + - `from the response, then GET /results/<id>.

` + - `

Meta MCP server: ${origin}/mcp

` + - `${rows}
`, - { headers: { 'content-type': 'text/html' } } - ); - } +export default async function (request: Request): Promise { + const url = new URL(request.url); - // GET /scenarios - if (url.pathname === '/scenarios') { - return json( - Object.entries(scenarios).map(([name, s]) => ({ - name, - description: s.description - })) + // Short-circuit scenarios that need true streaming. + const m = url.pathname.match(/^\/s\/([^/]+)/); + if (m && NOT_FETCH_SAFE.has(m[1])) { + return Response.json( + { + error: `scenario '${m[1]}' relies on SSE stream lifecycle and is not available via the fetch bridge` + }, + { status: 501 } ); } - // /results/[.html] - const r = url.pathname.match(/^\/results\/([^/.]+)(\.html)?$/); - if (r) { - const s = sessions.get(r[1]); - if (!s) return json({ error: 'unknown session' }, { status: 404 }); - if (r[2]) { - const items = s.checks - .map( - (c) => - `
` + - `${c.status} ${c.id} — ${c.description}` + - (c.errorMessage ? `
${c.errorMessage}` : '') + - `
` - ) - .join(''); - return new Response(`

${s.scenario}

${items}`, { - headers: { 'content-type': 'text/html' } - }); + // --- web Request → Node IncomingMessage --- + const body = request.body + ? Buffer.from(await request.arrayBuffer()) + : undefined; + // Express's req.protocol/req.ip read socket.encrypted/.remoteAddress, and + // IncomingMessage._destroy calls socket.destroy(), so a real (unconnected) + // Socket with the encrypted flag patched on is the path of least surprise. + const socket = Object.assign(new Socket(), { encrypted: false }); + const nodeReq = new IncomingMessage(socket); + nodeReq.method = request.method; + nodeReq.url = url.pathname + url.search; + nodeReq.httpVersion = '1.1'; + nodeReq.httpVersionMajor = 1; + nodeReq.httpVersionMinor = 1; + nodeReq.headers = Object.fromEntries(request.headers); + nodeReq.headers.host ??= url.host; + if (body?.length) nodeReq.headers['content-length'] = String(body.length); + // The SDK's StreamableHTTPServerTransport converts Node→Web via + // @hono/node-server, which reads rawHeaders (the [k,v,k,v,...] array), + // not the parsed headers object. + nodeReq.rawHeaders = Object.entries(nodeReq.headers).flat() as string[]; + if (body?.length) nodeReq.push(body); + nodeReq.push(null); + + // --- Node ServerResponse → web Response --- + // Intercept the user-facing write surface (writeHead/setHeader/write/end) + // so we never touch ServerResponse's socket-coupled internals. This is the + // approach serverless-http and light-my-request take. + const nodeRes = new ServerResponse(nodeReq); + const chunks: Buffer[] = []; + let status = 200; + const headers = new Headers(); + + const captureHeaders = (h?: Record) => { + for (const [k, v] of Object.entries(h ?? {})) { + headers.set(k, Array.isArray(v) ? v.join(', ') : String(v)); } - return json(summarise(s)); - } - - // POST /mcp — meta server - if (url.pathname === '/mcp' && req.method === 'POST') { - const msg = (await req.json()) as JsonRpc; - if (msg.id === undefined) return new Response(null, { status: 202 }); - return rpcOk(msg.id, metaMcp(msg, origin)); - } - - // /s/ - const m = url.pathname.match(/^\/s\/([^/]+)/); - if (m) { - const name = m[1]; - const handler = scenarios[name]; - if (!handler) - return json({ error: `unknown scenario '${name}'` }, { status: 404 }); - - if (req.method === 'GET') { - // SSE endpoint — minimal keep-alive so SDK clients that open a GET stream don't error. - return new Response('data: \n\n', { - headers: { 'content-type': 'text/event-stream' } - }); - } - if (req.method === 'DELETE') return new Response(null, { status: 200 }); - if (req.method !== 'POST') - return new Response('Method Not Allowed', { status: 405 }); - - const sid = req.headers.get('mcp-session-id'); - let session = sid ? sessions.get(sid) : undefined; - if (!session || session.scenario !== name) session = newSession(name); - - const msg = (await req.json()) as JsonRpc; - push(session, { - id: 'incoming-request', - name: 'IncomingRequest', - description: `Received ${msg.method ?? 'notification'}`, - status: 'INFO', - details: { method: msg.method, params: msg.params } - }); - - // notifications: no response body - if (msg.id === undefined) { - return new Response(null, { - status: 202, - headers: { 'mcp-session-id': session.id } - }); + }; + nodeRes.setHeader = ((k: string, v: string | string[] | number) => { + headers.set(k, Array.isArray(v) ? v.join(', ') : String(v)); + return nodeRes; + }) as ServerResponse['setHeader']; + nodeRes.getHeader = (k: string) => headers.get(k.toLowerCase()) ?? undefined; + nodeRes.removeHeader = (k: string) => headers.delete(k); + nodeRes.writeHead = ((code: number, h?: Record) => { + status = code; + captureHeaders(h); + return nodeRes; + }) as ServerResponse['writeHead']; + nodeRes.write = ((c: string | Buffer, enc?: BufferEncoding) => { + if (c) chunks.push(typeof c === 'string' ? Buffer.from(c, enc) : c); + return true; + }) as ServerResponse['write']; + nodeRes.flushHeaders = () => {}; + Object.defineProperty(nodeRes, 'statusCode', { + get: () => status, + set: (v: number) => { + status = v; } + }); - const result = handler.handle(msg, session); - return rpcOk(msg.id, result, { - 'mcp-session-id': session.id, - link: `<${origin}/results/${session.id}>; rel="conformance-results"` - }); - } - - return new Response('not found', { status: 404 }); + return new Promise((resolve) => { + nodeRes.end = ((c?: string | Buffer, enc?: BufferEncoding) => { + if (c) chunks.push(typeof c === 'string' ? Buffer.from(c, enc) : c); + resolve( + new Response(chunks.length ? Buffer.concat(chunks) : null, { + status, + headers + }) + ); + return nodeRes; + }) as ServerResponse['end']; + + app(nodeReq, nodeRes); + }); } diff --git a/src/hosted/README.md b/src/hosted/README.md index cbab37a3..915d6010 100644 --- a/src/hosted/README.md +++ b/src/hosted/README.md @@ -6,51 +6,75 @@ runner. ```bash npx @modelcontextprotocol/conformance hosted --port 3000 -# or with a public origin behind a proxy: +# behind a reverse proxy: npx @modelcontextprotocol/conformance hosted --port 3000 --public-origin https://conformance.example.com ``` ## Routes -| Route | Purpose | -| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `GET /` | Landing page with usage + scenario list | -| `GET /scenarios` | JSON list of hostable scenarios | -| `ALL /s/[/]` | MCP endpoint for ``. First request without `mcp-session-id` creates a session; the response carries `mcp-session-id` and a `Link: ; rel="conformance-results"` header. | -| `GET /results/` | JSON `{summary, checks}` | -| `GET /results/.html` | Pretty HTML report | -| `DELETE /results/` | Tear down the session early | -| `POST /mcp` | The hosted server is itself an MCP server with `list_scenarios`, `start_session`, `get_results` tools | +| Route | Purpose | +| --------------------------------------- | ------------------------------------------------------------------------------------------------- | +| `GET /` | Landing page with usage + scenario list | +| `GET /scenarios` | JSON list of hostable scenarios | +| `ALL /s//[/]` | MCP endpoint. Run is created lazily on first hit; pick any `[A-Za-z0-9_-]{1,64}` run-id. | +| `GET /s/` | Mints a fresh run-id and returns `{runId, mcpUrl, resultsUrl}`. | +| `GET /results/` | JSON `{scenario, summary, checks}` | +| `GET /results/.html` | Pretty HTML report | +| `DELETE /results/` | Tear down the run early | +| `POST /mcp` | The hosted server is itself an MCP server with `list_scenarios`, `start_run`, `get_results` tools | ## How it works -Each session is a real `Scenario` instance started on a loopback port; the -hosted server proxies `/s/` to it and overlays the session id. That -means every scenario works **unchanged** as long as it only needs one origin. +Each scenario implements `handler(): RequestListener` (see `HandlerScenario` +in `src/types.ts`). The hosted server instantiates a fresh scenario per +`(scenario, run-id)`, mounts its handler under `/s//`, and +rewrites `req.url` to strip the prefix — **no loopback port, no proxy**. The +CLI runner's `start()`/`stop()` are now thin wrappers around the same +`handler()`, so both modes exercise identical code. -Excluded (`auth/*`): scenarios that spin up a separate authorization server -on a second port. The proxy can't expose two origins, and OAuth discovery -metadata hard-codes absolute URLs. Run those with the CLI runner. +### Stateless transport -Sessions are reaped after `--ttl` ms idle (default 5 min). +The run-id lives in the **URL path**, not the `mcp-session-id` header, so +correlation works for stateless-transport clients (every draft-spec scenario +that uses `sessionIdGenerator: undefined`). A client that never echoes a +session id still hits the same `/s//` and its checks +accumulate on that run. -## val.town +### Coverage -`examples/hosted/valtown.ts` is a self-contained fetch-handler version with -the same URL shape but no loopback proxy — scenarios are reimplemented as -`Request → Response` functions. It ships with `initialize` and `tools_call`; -add more entries to its `scenarios` map as needed. +Hostable = any scenario that implements `handler()`. Currently that's +everything **except** `auth/*` (need a second public origin for the +authorization server). `listHostableScenarios()` derives the list at runtime +from which scenarios expose `handler()`. + +`sse-retry` implements `handler()` and works under `conformance hosted`, but +its connection-close-timing checks won't be meaningful through a buffered +fetch bridge — see below. + +## Serverless / val.town + +`examples/hosted/valtown.ts` wraps `createHostedApp()` in a +`(Request) => Promise` bridge so the **same scenarios** run on +fetch-based runtimes (val.town, Deno Deploy, Bun, Workers with +`nodejs_compat`): + +```ts +import handler from 'npm:@modelcontextprotocol/conformance/examples/hosted/valtown'; +export default handler; +``` + +The bridge buffers the response, so streaming-SSE scenarios (`sse-retry`) are +returned as 501; everything else — including the SDK's +`StreamableHTTPServerTransport` in stateless mode — works. ## Example ```bash -# 1. point your client at the scenario URL -$ my-mcp-client https://conformance.example.com/s/tools_call - -# 2. read mcp-session-id from any response header, then: -$ curl https://conformance.example.com/results/TJeZ63Bw | jq .summary +# pick any run-id; results live at the matching path +$ npx @modelcontextprotocol/inspector https://conformance.example.com/s/tools_call/demo/mcp +$ curl https://conformance.example.com/results/demo | jq .summary { "passed": 1, "failed": 0, "warnings": 0, "info": 4, "skipped": 0, "total": 5 } ``` -Or drive the whole flow over MCP by connecting to `/mcp` and calling -`start_session` → run client → `get_results`. +Or drive it over MCP: connect to `/mcp`, call `start_run` → run client → +`get_results`. diff --git a/src/hosted/hosted.test.ts b/src/hosted/hosted.test.ts index c7494341..7e7fb2da 100644 --- a/src/hosted/hosted.test.ts +++ b/src/hosted/hosted.test.ts @@ -1,6 +1,6 @@ import { describe, it, expect, beforeAll, afterAll } from 'vitest'; import { createHostedApp } from './server'; -import { SessionManager } from './session'; +import { SessionManager, listHostableScenarios } from './session'; import type { Server } from 'http'; describe('hosted server', () => { @@ -26,128 +26,214 @@ describe('hosted server', () => { await new Promise((r) => server.close(() => r())); }); - it('lists scenarios', async () => { - const res = await fetch(`${base}/scenarios`); - expect(res.status).toBe(200); - const list = await res.json(); - expect(Array.isArray(list)).toBe(true); - expect(list.some((s: { name: string }) => s.name === 'initialize')).toBe( - true - ); - // auth scenarios excluded - expect(list.some((s: { name: string }) => s.name.startsWith('auth/'))).toBe( - false - ); - }); - - it('proxies to a scenario and records checks', async () => { - const init = await fetch(`${base}/s/initialize`, { + async function postMcp( + path: string, + body: object, + headers: Record = {} + ) { + return fetch(`${base}${path}`, { method: 'POST', headers: { 'content-type': 'application/json', - accept: 'application/json, text/event-stream' + accept: 'application/json, text/event-stream', + ...headers }, - body: JSON.stringify({ - jsonrpc: '2.0', - id: 1, - method: 'initialize', - params: { - protocolVersion: '2025-06-18', - clientInfo: { name: 'vitest', version: '0' }, - capabilities: {} - } - }) + body: JSON.stringify(body) }); - expect(init.status).toBe(200); - const sid = init.headers.get('mcp-session-id'); - expect(sid).toBeTruthy(); - expect(init.headers.get('link')).toContain(`/results/${sid}`); + } - const body = await init.json(); + it('lists only scenarios that implement handler()', async () => { + const list = await fetch(`${base}/scenarios`).then((r) => r.json()); + const names = list.map((s: { name: string }) => s.name); + expect(names).toContain('initialize'); + expect(names).toContain('http-standard-headers'); // draft, BaseHttpScenario + expect(names).toContain('sep-2322-client-request-state'); // draft, express + // auth scenarios have no handler() → excluded + expect(names.some((n: string) => n.startsWith('auth/'))).toBe(false); + }); + + it('mounts a raw-http scenario at /s// and records checks', async () => { + const res = await postMcp('/s/initialize/t1', { + jsonrpc: '2.0', + id: 1, + method: 'initialize', + params: { + protocolVersion: '2025-06-18', + clientInfo: { name: 'vitest', version: '0' }, + capabilities: {} + } + }); + expect(res.status).toBe(200); + expect(res.headers.get('link')).toContain('/results/t1'); + const body = await res.json(); expect(body.result.serverInfo.name).toBe('test-server'); - const results = await fetch(`${base}/results/${sid}`); - const data = await results.json(); - expect(data.summary.passed).toBeGreaterThanOrEqual(1); + const results = await fetch(`${base}/results/t1`).then((r) => r.json()); + expect(results.scenario).toBe('initialize'); expect( - data.checks.some( + results.checks.some( (c: { id: string }) => c.id === 'mcp-client-initialization' ) ).toBe(true); }); - it('reuses a session across requests', async () => { - const r1 = await fetch(`${base}/s/tools_call`, { - method: 'POST', - headers: { - 'content-type': 'application/json', - accept: 'application/json, text/event-stream' - }, - body: JSON.stringify({ - jsonrpc: '2.0', - id: 1, - method: 'initialize', - params: { - protocolVersion: '2025-06-18', - clientInfo: { name: 't', version: '0' }, - capabilities: {} - } - }) + it('mounts an express scenario, accumulating checks across stateless requests', async () => { + // tools_call uses StreamableHTTPServerTransport with sessionIdGenerator: undefined, + // i.e. fully stateless. Correlation must come from the path-embedded id. + const r1 = await postMcp('/s/tools_call/t2/mcp', { + jsonrpc: '2.0', + id: 1, + method: 'initialize', + params: { + protocolVersion: '2025-06-18', + clientInfo: { name: 'vitest', version: '0' }, + capabilities: {} + } }); - const sid = r1.headers.get('mcp-session-id')!; - // SDK transport responds as SSE; just confirm the request was routed. expect(r1.status).toBe(200); await r1.text(); - const r2 = await fetch(`${base}/s/tools_call`, { - method: 'POST', - headers: { - 'content-type': 'application/json', - accept: 'application/json, text/event-stream', - 'mcp-session-id': sid - }, - body: JSON.stringify({ - jsonrpc: '2.0', - id: 2, - method: 'tools/call', - params: { name: 'add_numbers', arguments: { a: 2, b: 3 } } - }) + const r2 = await postMcp('/s/tools_call/t2/mcp', { + jsonrpc: '2.0', + id: 2, + method: 'tools/call', + params: { name: 'add_numbers', arguments: { a: 2, b: 3 } } }); expect(r2.status).toBe(200); - await r2.text(); + expect(await r2.text()).toContain('The sum of 2 and 3 is 5'); - const results = await fetch(`${base}/results/${sid}`).then((r) => r.json()); + const results = await fetch(`${base}/results/t2`).then((r) => r.json()); expect( results.checks.some((c: { id: string }) => c.id === 'tool-add-numbers') ).toBe(true); }); - it('404s on unknown scenario', async () => { - const res = await fetch(`${base}/s/does-not-exist`, { - method: 'POST', - headers: { 'content-type': 'application/json' }, - body: '{}' + it('mounts a draft scenario (request-metadata) directly', async () => { + // request-metadata simulates a version rejection on the *first* request to + // exercise client retry, then accepts. Send twice — both with no + // mcp-session-id (stateless) — and confirm checks accumulate via path id. + const init = { + jsonrpc: '2.0', + id: 1, + method: 'initialize', + params: { + protocolVersion: 'DRAFT-2026-v1', + clientInfo: { name: 'vitest', version: '0' }, + capabilities: {} + } + }; + const headers = { 'mcp-protocol-version': 'DRAFT-2026-v1' }; + const r1 = await postMcp('/s/request-metadata/t3', init, headers); + expect(r1.status).toBe(400); + expect((await r1.json()).error.code).toBe(-32004); + const r2 = await postMcp('/s/request-metadata/t3', init, headers); + expect(r2.status).toBe(200); + await r2.text(); + + const results = await fetch(`${base}/results/t3`).then((r) => r.json()); + expect(results.scenario).toBe('request-metadata'); + expect( + results.checks.some( + (c: { id: string }) => + c.id === 'sep-2575-http-client-sends-version-header' + ) + ).toBe(true); + }); + + it('json-schema-ref-deref embeds the public mounted URL in the canary $ref', async () => { + const r1 = await postMcp('/s/json-schema-ref-no-deref/t4/mcp', { + jsonrpc: '2.0', + id: 1, + method: 'initialize', + params: { + protocolVersion: 'DRAFT-2026-v1', + clientInfo: { name: 'vitest', version: '0' }, + capabilities: {} + } + }); + await r1.text(); + const r2 = await postMcp('/s/json-schema-ref-no-deref/t4/mcp', { + jsonrpc: '2.0', + id: 2, + method: 'tools/list', + params: {} }); - expect(res.status).toBe(404); + const text = await r2.text(); + // Canary URL should be the *mounted* base, not localhost:randomport + expect(text).toContain( + `${base}/s/json-schema-ref-no-deref/t4/canary/profile-schema.json` + ); + }); + + it('GET /s/ mints a run and returns mcpUrl', async () => { + const res = await fetch(`${base}/s/tools_call`); + expect(res.status).toBe(200); + const body = await res.json(); + expect(body.runId).toMatch(/^[A-Za-z0-9_-]+$/); + expect(body.mcpUrl).toBe(`${base}/s/tools_call/${body.runId}/mcp`); + expect(body.resultsUrl).toBe(`${base}/results/${body.runId}`); + }); + + it('isolates runs with the same scenario but different ids', async () => { + await postMcp('/s/initialize/iso-a', { + jsonrpc: '2.0', + id: 1, + method: 'initialize', + params: { + protocolVersion: '2025-06-18', + clientInfo: { name: 'a', version: '0' }, + capabilities: {} + } + }).then((r) => r.text()); + await postMcp('/s/initialize/iso-b', { + jsonrpc: '2.0', + id: 1, + method: 'initialize', + params: { + protocolVersion: '2025-06-18', + clientInfo: { name: 'b', version: '0' }, + capabilities: {} + } + }).then((r) => r.text()); + + const a = await fetch(`${base}/results/iso-a`).then((r) => r.json()); + const b = await fetch(`${base}/results/iso-b`).then((r) => r.json()); + expect(a.checks[0].details.clientName).toBe('a'); + expect(b.checks[0].details.clientName).toBe('b'); + }); + + it('rejects unknown scenarios and bad run-ids', async () => { + expect( + (await postMcp('/s/does-not-exist/x', { jsonrpc: '2.0' })).status + ).toBe(404); + expect( + (await postMcp('/s/initialize/bad..id', { jsonrpc: '2.0' })).status + ).toBe(400); + // auth scenario exists but has no handler() + expect( + (await postMcp('/s/auth/basic-cimd/x', { jsonrpc: '2.0' })).status + ).toBe(501); }); it('exposes meta MCP tools', async () => { - const res = await fetch(`${base}/mcp`, { - method: 'POST', - headers: { - 'content-type': 'application/json', - accept: 'application/json, text/event-stream' - }, - body: JSON.stringify({ - jsonrpc: '2.0', - id: 1, - method: 'tools/list', - params: {} - }) + const res = await postMcp('/mcp', { + jsonrpc: '2.0', + id: 1, + method: 'tools/list', + params: {} }); const text = await res.text(); expect(text).toContain('list_scenarios'); - expect(text).toContain('start_session'); + expect(text).toContain('start_run'); expect(text).toContain('get_results'); }); + + it('every hostable scenario can be instantiated without binding a port', () => { + // Guard against regressions where a handler() implementation reaches for + // this._server / this.port etc. + for (const name of listHostableScenarios()) { + const run = sessions.getOrCreate(name, `probe-${name}`, () => 'http://x'); + expect(typeof run.listener).toBe('function'); + } + }); }); diff --git a/src/hosted/html.ts b/src/hosted/html.ts index 1af5bdcb..cbab3cfe 100644 --- a/src/hosted/html.ts +++ b/src/hosted/html.ts @@ -36,24 +36,29 @@ export function renderLanding(origin: string, scenarios: string[]): string { .map( (n) => `${esc(n)}` + - `${esc(origin)}/s/${esc(n)}` + `${esc(origin)}/s/${esc(n)}/<run-id>` + + `mint` ) .join(''); return ` MCP Conformance — hosted

MCP Conformance — hosted

-

Point your MCP client at one of the scenario URLs below. The first request -creates a session; the response carries an mcp-session-id header -and a Link: <.../results/ID>; rel="conformance-results" -header. Fetch that URL (or append .html) for your checks.

+

Point your MCP client at /s/<scenario>/<run-id>. +Pick any <run-id> (e.g. local-1) — the run is +created on first request, and because the id is in the path it works with +stateless transports too. Then GET +/results/<run-id> (append .html for a +report).

+

Too lazy to pick an id? GET /s/<scenario> mints one and +returns {mcpUrl, resultsUrl}.

This server is also an MCP server at ${esc(origin)}/mcp with -list_scenarios / start_session / +list_scenarios / start_run / get_results tools.

Scenarios (${scenarios.length})

-${rows}
nameMCP URL
+${rows}
nameMCP URL pattern

Example

-
$ npx @modelcontextprotocol/inspector ${esc(origin)}/s/initialize
-# then open ${esc(origin)}/results/<mcp-session-id>.html
`; +
$ npx @modelcontextprotocol/inspector ${esc(origin)}/s/initialize/demo
+$ curl ${esc(origin)}/results/demo | jq .summary
`; } export function renderResults( diff --git a/src/hosted/proxy.ts b/src/hosted/proxy.ts deleted file mode 100644 index ce62ebcb..00000000 --- a/src/hosted/proxy.ts +++ /dev/null @@ -1,80 +0,0 @@ -/** - * Minimal HTTP proxy that forwards an incoming express request to a - * scenario's loopback server and streams the response back. - * - * We don't use http-proxy-middleware to keep the dependency surface small - * and because we need to inject/rewrite the mcp-session-id header. - */ - -import http from 'http'; -import { Request, Response } from 'express'; -import { HostedSession } from './session'; - -/** Header used to correlate a client with its hosted session. */ -export const SESSION_HEADER = 'mcp-session-id'; - -export function proxyToSession( - session: HostedSession, - req: Request, - res: Response, - /** Path on the target to hit. Defaults to the scenario's serverUrl path. */ - targetPath?: string -): void { - const target = session.targetUrl; - const path = targetPath ?? (target.pathname || '/'); - - // Forward most headers but drop hop-by-hop ones and host (loopback target). - const headers: http.OutgoingHttpHeaders = {}; - for (const [k, v] of Object.entries(req.headers)) { - if (k === 'host' || k === 'connection' || k === 'content-length') continue; - headers[k] = v; - } - // Some scenarios assign their own mcp-session-id; let theirs flow back, but - // make sure the client always sees ours so /results/ works. - headers[SESSION_HEADER] = req.header(SESSION_HEADER) ?? session.id; - - const upstream = http.request( - { - hostname: target.hostname, - port: target.port, - path, - method: req.method, - headers - }, - (upRes) => { - const outHeaders = { ...upRes.headers }; - // Always advertise our session id so the client can fetch results, - // regardless of what the scenario set. - outHeaders[SESSION_HEADER] = session.id; - res.writeHead(upRes.statusCode ?? 502, outHeaders); - upRes.pipe(res); - } - ); - - upstream.on('error', (err) => { - if (!res.headersSent) { - res.status(502).json({ - jsonrpc: '2.0', - id: null, - error: { - code: -32001, - message: `Upstream scenario error: ${err.message}` - } - }); - } else { - res.end(); - } - }); - - // Stream the body. express.json() may have already consumed it; if so, - // re-serialize. Otherwise pipe raw (covers SSE GETs / DELETEs / unparsed). - if (req.body !== undefined && Object.keys(req.body).length > 0) { - const body = JSON.stringify(req.body); - upstream.setHeader('content-length', Buffer.byteLength(body)); - upstream.end(body); - } else if (req.readable) { - req.pipe(upstream); - } else { - upstream.end(); - } -} diff --git a/src/hosted/server.ts b/src/hosted/server.ts index 874a3c49..212e87ae 100644 --- a/src/hosted/server.ts +++ b/src/hosted/server.ts @@ -1,22 +1,23 @@ /** - * Hosted conformance server. + * Hosted conformance server — direct-mount, no loopback proxy. * - * Mounts every (non-auth) client-testing scenario at a stable path: + * URL scheme (run-id is path-embedded so stateless-transport clients work): * - * POST /s/ MCP endpoint — first request creates a session, - * subsequent requests reuse it via mcp-session-id - * GET /results/ JSON ConformanceCheck[] for that session - * GET /results/.html Pretty HTML report - * GET /scenarios JSON list of hostable scenarios - * GET / Landing page with usage instructions - * POST /mcp The hosted server is itself an MCP server - * exposing list_scenarios / start_session / - * get_results tools. + * ALL /s//[/] Mounted scenario handler. The run + * is created lazily on first hit; + * pick any you like. + * GET /s/ Convenience: mints a fresh run-id + * and returns {mcpUrl, resultsUrl}. + * GET /results/ JSON {summary, checks} + * GET /results/.html Pretty HTML report + * GET /scenarios JSON list of hostable scenarios + * GET / Landing page + * POST /mcp Meta-MCP: list_scenarios, + * start_run, get_results * - * Under the hood each session is a real Scenario instance listening on a - * loopback port; requests are proxied. That means ~90% of scenarios work - * unchanged. Auth scenarios are excluded because they need a second - * publicly-reachable origin for the authorization server. + * Scenarios are mounted via Scenario.handler() — the same RequestListener the + * CLI runner wraps in http.createServer — so there is no loopback port and + * this works on serverless hosts. Each run gets a fresh Scenario instance. */ import express, { Request } from 'express'; @@ -30,29 +31,28 @@ import { import { SessionManager, UnknownScenarioError, + NotHostableError, listHostableScenarios } from './session'; -import { proxyToSession, SESSION_HEADER } from './proxy'; import { renderLanding, renderResults } from './html'; import { getScenario } from '../scenarios'; import { ConformanceCheck } from '../types'; export interface HostedServerOptions { - /** Public origin (scheme+host+port) used in generated links. Auto-detected from Host header if omitted. */ publicOrigin?: string; ttlMs?: number; } +/** Only allow run-ids that are safe in a single path segment. */ +const RUN_ID_RE = /^[A-Za-z0-9_-]{1,64}$/; + export function createHostedApp(opts: HostedServerOptions = {}): { app: express.Application; sessions: SessionManager; } { const sessions = new SessionManager({ ttlMs: opts.ttlMs }); const app = express(); - - // Only parse JSON on the routes that need it; keep the proxy route raw so - // streaming bodies (and non-JSON content types) pass through untouched. - const jsonBody = express.json(); + const hostable = new Set(listHostableScenarios()); function origin(req: Request): string { if (opts.publicOrigin) return opts.publicOrigin; @@ -61,86 +61,152 @@ export function createHostedApp(opts: HostedServerOptions = {}): { return `${proto}://${host}`; } + function runBaseUrl(req: Request, scenario: string, runId: string): string { + return `${origin(req)}/s/${scenario}/${runId}`; + } + // ---------- discovery ---------- app.get('/', (req, res) => { - res.type('html').send(renderLanding(origin(req), listHostableScenarios())); + res.type('html').send(renderLanding(origin(req), Array.from(hostable))); }); app.get('/scenarios', (_req, res) => { - const list = listHostableScenarios().map((name) => { - const s = getScenario(name)!; - return { name, description: s.description, source: s.source }; - }); - res.json(list); + res.json( + Array.from(hostable).map((name) => { + const s = getScenario(name)!; + return { + name, + description: s.description, + source: s.source, + mcpPath: s.mcpPath ?? '' + }; + }) + ); }); - // ---------- scenario proxy ---------- + // ---------- scenario mounting ---------- + // + // We can't pre-register an express route per (scenario, run-id) because + // run-ids are open-ended. Instead a single catch-all route resolves the + // run, rewrites req.url to strip the /s// prefix, and hands + // off to the run's listener — exactly what app.use(prefix, fn) would do, + // but with a dynamic prefix. - // Match the scenario name plus any trailing sub-path (some scenarios serve - // /mcp, others /, some auth-adjacent ones serve well-known paths). - // Use a regex param so names containing '/' still work as a single segment - // group while the suffix captures everything after it. - app.all(/^\/s\/(.+?)(\/.*)?$/, jsonBody, async (req, res) => { - const scenarioName = req.params[0]; - const suffix = req.params[1] ?? ''; + app.all(/^\/s\/(.+)$/, (req, res, next) => { + const rest = req.params[0]; // "//" - if (!getScenario(scenarioName)) { - res.status(404).json({ error: `unknown scenario '${scenarioName}'` }); + // Scenario names can contain '/', so try progressively longer prefixes + // until one matches a known scenario. + const segments = rest.split('/'); + let nameLen = 0; + let scenarioName = ''; + for (let i = 1; i <= segments.length; i++) { + const candidate = segments.slice(0, i).join('/'); + if (hostable.has(candidate)) { + scenarioName = candidate; + nameLen = i; + break; + } + } + if (!scenarioName) { + // Distinguish "exists but not hostable" from "unknown" + for (let i = 1; i <= segments.length; i++) { + if (getScenario(segments.slice(0, i).join('/'))) { + res.status(501).json({ + error: `scenario '${segments.slice(0, i).join('/')}' is not hostable (no handler())` + }); + return; + } + } + res.status(404).json({ error: `unknown scenario '${segments[0]}'` }); return; } - const incomingId = req.header(SESSION_HEADER); - let session = incomingId ? sessions.get(incomingId) : undefined; - - if (session && session.scenarioName !== scenarioName) { - // Client is reusing a session id against a different scenario path. - // Treat as a new session rather than silently mixing checks. - session = undefined; - } + const runId = segments[nameLen]; + const suffix = '/' + segments.slice(nameLen + 1).join('/'); - if (!session) { + // GET /s/ with no run-id → mint one and tell the caller where + // to point their client. + if (!runId) { + if (req.method !== 'GET') { + res.status(400).json({ + error: + 'Missing run-id. Use /s//, or GET /s/ to mint one.' + }); + return; + } try { - session = await sessions.create(scenarioName); + const run = sessions.getOrCreate(scenarioName, undefined, (id) => + runBaseUrl(req, scenarioName, id) + ); + res.json({ + runId: run.id, + mcpUrl: `${runBaseUrl(req, scenarioName, run.id)}${run.mcpPath}`, + resultsUrl: `${origin(req)}/results/${run.id}`, + resultsHtmlUrl: `${origin(req)}/results/${run.id}.html`, + context: run.context + }); } catch (e) { - const msg = e instanceof Error ? e.message : String(e); - res.status(500).json({ error: msg }); - return; + next(e); } - // Tell the client where to find its results without making it parse the - // session id out of the response headers. - res.setHeader( - 'link', - `<${origin(req)}/results/${session.id}>; rel="conformance-results"` + return; + } + + if (!RUN_ID_RE.test(runId)) { + res.status(400).json({ error: 'invalid run-id' }); + return; + } + + let run; + try { + run = sessions.getOrCreate(scenarioName, runId, (id) => + runBaseUrl(req, scenarioName, id) ); + } catch (e) { + if (e instanceof UnknownScenarioError || e instanceof NotHostableError) { + res.status(400).json({ error: e.message }); + return; + } + throw e; } - // If the client appended a sub-path (/.well-known/..., /mcp, ...) honour - // it; otherwise hit whatever path the scenario advertised in serverUrl. - const targetPath = suffix || undefined; - proxyToSession(session, req, res, targetPath); + // Advertise where results live so a client can discover them without + // out-of-band knowledge of the URL scheme. + res.setHeader( + 'link', + `<${origin(req)}/results/${run.id}>; rel="conformance-results"` + ); + + // Rewrite to the path the scenario expects (it thinks it's at root). + // The query string is preserved because we keep the express req object. + req.url = suffix === '/' ? run.mcpPath || '/' : suffix; + run.listener(req, res); }); // ---------- results ---------- app.get('/results/:id.html', (req, res) => { - const id = req.params.id; - const session = sessions.get(id); - const checks = sessions.results(id); - if (!session || !checks) { - res.status(404).type('html').send(`

No session ${id}

`); + const run = sessions.get(req.params.id); + const checks = sessions.results(req.params.id); + if (!run || !checks) { + res + .status(404) + .type('html') + .send(`

No run ${req.params.id}

`); return; } - res.type('html').send(renderResults(session.scenarioName, id, checks)); + res.type('html').send(renderResults(run.scenarioName, run.id, checks)); }); app.get('/results/:id', (req, res) => { + const run = sessions.get(req.params.id); const checks = sessions.results(req.params.id); - if (!checks) { - res.status(404).json({ error: 'unknown session' }); + if (!run || !checks) { + res.status(404).json({ error: 'unknown run' }); return; } - res.json(summarise(req.params.id, checks)); + res.json(summarise(run.scenarioName, run.id, checks)); }); app.delete('/results/:id', async (req, res) => { @@ -150,8 +216,10 @@ export function createHostedApp(opts: HostedServerOptions = {}): { // ---------- meta MCP server ---------- - app.post('/mcp', jsonBody, async (req, res) => { - const server = createMetaMcpServer(sessions, origin(req)); + app.post('/mcp', express.json(), async (req, res) => { + const server = createMetaMcpServer(sessions, origin(req), (s, id) => + runBaseUrl(req, s, id) + ); const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined }); @@ -166,11 +234,12 @@ export function createHostedApp(opts: HostedServerOptions = {}): { return { app, sessions }; } -function summarise(id: string, checks: ConformanceCheck[]) { +function summarise(scenario: string, id: string, checks: ConformanceCheck[]) { const counts = { SUCCESS: 0, FAILURE: 0, WARNING: 0, SKIPPED: 0, INFO: 0 }; for (const c of checks) counts[c.status]++; return { - sessionId: id, + runId: id, + scenario, summary: { passed: counts.SUCCESS, failed: counts.FAILURE, @@ -183,16 +252,13 @@ function summarise(id: string, checks: ConformanceCheck[]) { }; } -/** - * The hosted server is itself an MCP server so an agent can drive the whole - * flow over MCP: discover scenarios, mint a session URL, then fetch results. - */ function createMetaMcpServer( sessions: SessionManager, - publicOrigin: string + publicOrigin: string, + runBaseUrl: (scenario: string, runId: string) => string ): Server { const server = new Server( - { name: 'mcp-conformance-hosted', version: '0.1.0' }, + { name: 'mcp-conformance-hosted', version: '0.2.0' }, { capabilities: { tools: {} } } ); @@ -205,15 +271,23 @@ function createMetaMcpServer( inputSchema: { type: 'object', properties: {} } }, { - name: 'start_session', + name: 'start_run', description: - 'Create a fresh session for a scenario and return the MCP URL to point the client-under-test at, plus the results URL.', + 'Create a fresh run for a scenario and return the MCP URL to point ' + + 'the client-under-test at, plus the results URL. The run-id is ' + + 'embedded in the path so this works with stateless transports.', inputSchema: { type: 'object', properties: { scenario: { type: 'string', description: 'Scenario name, e.g. "initialize" or "tools_call".' + }, + run_id: { + type: 'string', + description: + 'Optional. Supply your own [A-Za-z0-9_-]{1,64} id; ' + + 'otherwise one is generated.' } }, required: ['scenario'] @@ -222,13 +296,12 @@ function createMetaMcpServer( { name: 'get_results', description: - 'Fetch the conformance checks recorded for a session. Returns the same shape as GET /results/.', + 'Fetch the conformance checks recorded for a run. Same shape as ' + + 'GET /results/.', inputSchema: { type: 'object', - properties: { - session_id: { type: 'string' } - }, - required: ['session_id'] + properties: { run_id: { type: 'string' } }, + required: ['run_id'] } } ] @@ -239,63 +312,61 @@ function createMetaMcpServer( async (request): Promise => { const args = (request.params.arguments ?? {}) as Record; switch (request.params.name) { - case 'list_scenarios': { - const list = listHostableScenarios().map((name) => ({ - name, - description: getScenario(name)!.description - })); - return text(JSON.stringify(list, null, 2)); - } - case 'start_session': { + case 'list_scenarios': + return text( + JSON.stringify( + listHostableScenarios().map((name) => ({ + name, + description: getScenario(name)!.description + })), + null, + 2 + ) + ); + + case 'start_run': { + if (args.run_id && !RUN_ID_RE.test(args.run_id)) { + return errorText(`invalid run_id (must match ${RUN_ID_RE})`); + } try { - const session = await sessions.create(args.scenario); + const run = sessions.getOrCreate(args.scenario, args.run_id, (id) => + runBaseUrl(args.scenario, id) + ); return text( JSON.stringify( { - sessionId: session.id, - mcpUrl: `${publicOrigin}/s/${session.scenarioName}`, - resultsUrl: `${publicOrigin}/results/${session.id}`, - resultsHtmlUrl: `${publicOrigin}/results/${session.id}.html`, - context: session.context, - note: - 'Point your client at mcpUrl and include header ' + - `"${SESSION_HEADER}: ${session.id}" on every request.` + runId: run.id, + mcpUrl: `${runBaseUrl(run.scenarioName, run.id)}${run.mcpPath}`, + resultsUrl: `${publicOrigin}/results/${run.id}`, + resultsHtmlUrl: `${publicOrigin}/results/${run.id}.html`, + context: run.context }, null, 2 ) ); } catch (e) { - if (e instanceof UnknownScenarioError) { - return { - content: [{ type: 'text', text: e.message }], - isError: true - }; + if ( + e instanceof UnknownScenarioError || + e instanceof NotHostableError + ) { + return errorText(e.message); } throw e; } } + case 'get_results': { - const checks = sessions.results(args.session_id); - if (!checks) { - return { - content: [ - { type: 'text', text: `No session '${args.session_id}'` } - ], - isError: true - }; - } + const run = sessions.get(args.run_id); + const checks = sessions.results(args.run_id); + if (!run || !checks) return errorText(`no run '${args.run_id}'`); return text( - JSON.stringify(summarise(args.session_id, checks), null, 2) + JSON.stringify(summarise(run.scenarioName, run.id, checks), null, 2) ); } + default: - return { - content: [ - { type: 'text', text: `Unknown tool ${request.params.name}` } - ], - isError: true - }; + return errorText(`unknown tool ${request.params.name}`); } } ); @@ -306,3 +377,7 @@ function createMetaMcpServer( function text(t: string): CallToolResult { return { content: [{ type: 'text', text: t }] }; } + +function errorText(t: string): CallToolResult { + return { content: [{ type: 'text', text: t }], isError: true }; +} diff --git a/src/hosted/session.ts b/src/hosted/session.ts index 072fc0d8..c1d4586d 100644 --- a/src/hosted/session.ts +++ b/src/hosted/session.ts @@ -1,41 +1,38 @@ /** * Session management for the hosted conformance server. * - * A "session" is one isolated run of a scenario. Each session owns its own - * Scenario instance (and therefore its own underlying http.Server bound to a - * loopback port). The hosted server proxies path-prefixed requests to that - * port and harvests checks via getChecks(). - * - * Sessions are keyed by a short id (also surfaced as mcp-session-id) so a - * client can hit a stable scenario URL like /s/initialize and still get - * isolated results at /results/. + * A "run" is one isolated exercise of a scenario. Each run owns a fresh + * Scenario instance and the RequestListener it returns from handler() — no + * loopback port, no proxy. Runs are keyed by a path-embedded id so + * correlation works for stateless-transport clients that never echo + * mcp-session-id. */ import { randomBytes } from 'crypto'; -import { Scenario, ConformanceCheck } from '../types'; -import { getScenario, listScenarios } from '../scenarios'; +import { Scenario, ConformanceCheck, RequestListener } from '../types'; +import { getScenario, scenarios } from '../scenarios'; -export interface HostedSession { +export interface HostedRun { id: string; scenarioName: string; scenario: Scenario; - /** Loopback URL the scenario is listening on (e.g. http://localhost:54321/mcp) */ - targetUrl: URL; + /** The mounted handler — invoke directly with (req, res). */ + listener: RequestListener; + /** Sub-path under the run prefix where the MCP endpoint lives. */ + mcpPath: string; createdAt: number; lastSeenAt: number; - /** Optional context the scenario wants delivered to the client */ context?: Record; } export interface SessionManagerOptions { - /** Idle ms after which a session is reaped. Default 5 minutes. */ + /** Idle ms after which a run is reaped. Default 5 minutes. */ ttlMs?: number; - /** How often to sweep for expired sessions. Default 30s. */ sweepIntervalMs?: number; } export class SessionManager { - private sessions = new Map(); + private runs = new Map(); private readonly ttlMs: number; private sweeper: ReturnType; @@ -43,75 +40,88 @@ export class SessionManager { this.ttlMs = opts.ttlMs ?? 5 * 60_000; const sweepIntervalMs = opts.sweepIntervalMs ?? 30_000; this.sweeper = setInterval(() => this.sweep(), sweepIntervalMs); - // Don't keep the process alive just for the sweeper. this.sweeper.unref?.(); } - /** Create a fresh scenario instance and start it on a loopback port. */ - async create(scenarioName: string): Promise { - const factory = getScenario(scenarioName); - if (!factory) { - throw new UnknownScenarioError(scenarioName); + /** + * Get the run for (scenario, id), creating it on first reference. The id is + * caller-chosen so URLs are predictable; pass undefined to mint one. + */ + getOrCreate( + scenarioName: string, + id: string | undefined, + baseUrlFor: (runId: string) => string + ): HostedRun { + if (id) { + const existing = this.runs.get(id); + if (existing && existing.scenarioName === scenarioName) { + existing.lastSeenAt = Date.now(); + return existing; + } + // Same id reused for a different scenario → replace, don't merge checks. + if (existing) void this.destroy(id); } - // Each call to getScenario returns the same singleton, so re-instantiate - // via its constructor to get isolated state. - const ScenarioCtor = factory.constructor as new () => Scenario; - const scenario = new ScenarioCtor(); - - const urls = await scenario.start(); - const id = randomBytes(6).toString('base64url'); - const session: HostedSession = { - id, + + const proto = getScenario(scenarioName); + if (!proto) throw new UnknownScenarioError(scenarioName); + if (!proto.handler) throw new NotHostableError(scenarioName); + + const Ctor = proto.constructor as new () => Scenario; + const scenario = new Ctor(); + const runId = id ?? randomBytes(6).toString('base64url'); + const listener = scenario.handler!(() => baseUrlFor(runId)); + + const run: HostedRun = { + id: runId, scenarioName, scenario, - targetUrl: new URL(urls.serverUrl), + listener, + mcpPath: scenario.mcpPath ?? '', createdAt: Date.now(), - lastSeenAt: Date.now(), - context: urls.context + lastSeenAt: Date.now() }; - this.sessions.set(id, session); - return session; + this.runs.set(runId, run); + return run; } - get(id: string): HostedSession | undefined { - const s = this.sessions.get(id); - if (s) s.lastSeenAt = Date.now(); - return s; + get(id: string): HostedRun | undefined { + const r = this.runs.get(id); + if (r) r.lastSeenAt = Date.now(); + return r; } - list(): HostedSession[] { - return Array.from(this.sessions.values()); + results(id: string): ConformanceCheck[] | undefined { + return this.runs.get(id)?.scenario.getChecks(); } - results(id: string): ConformanceCheck[] | undefined { - const s = this.sessions.get(id); - return s?.scenario.getChecks(); + list(): HostedRun[] { + return Array.from(this.runs.values()); } async destroy(id: string): Promise { - const s = this.sessions.get(id); - if (!s) return; - this.sessions.delete(id); + const r = this.runs.get(id); + if (!r) return; + this.runs.delete(id); + // handler() never started a server, but some scenarios hold timers/streams + // that stop() cleans up. Safe to call even though start() wasn't. try { - await s.scenario.stop(); + await r.scenario.stop(); } catch { - // best-effort; the loopback server may already be gone + // best-effort } } async close(): Promise { clearInterval(this.sweeper); await Promise.all( - Array.from(this.sessions.keys()).map((id) => this.destroy(id)) + Array.from(this.runs.keys()).map((id) => this.destroy(id)) ); } private sweep(): void { const now = Date.now(); - for (const [id, s] of this.sessions) { - if (now - s.lastSeenAt > this.ttlMs) { - void this.destroy(id); - } + for (const [id, r] of this.runs) { + if (now - r.lastSeenAt > this.ttlMs) void this.destroy(id); } } } @@ -119,24 +129,23 @@ export class SessionManager { export class UnknownScenarioError extends Error { constructor(name: string) { super( - `Unknown scenario '${name}'. Available: ${listScenarios().join(', ')}` + `Unknown scenario '${name}'. Available: ${Array.from(scenarios.keys()).join(', ')}` ); } } -/** - * Scenarios that the hosted runner can serve via path-proxy. - * - * Excluded: scenarios whose ScenarioUrls.authUrl is set (they spin up a - * second auth server on another port that the client must reach directly, - * which a single-origin proxy can't expose) and scenarios that depend on - * the runner spawning the client process. - */ +export class NotHostableError extends Error { + constructor(name: string) { + super( + `Scenario '${name}' does not implement handler() and cannot run hosted ` + + `(typically auth scenarios that need a second origin).` + ); + } +} + +/** Scenarios that expose handler() and so can run without a loopback port. */ export function listHostableScenarios(): string[] { - return listScenarios().filter((name) => { - const s = getScenario(name); - // No good static way to know if authUrl will be set without starting it, - // so use the naming convention all auth scenarios share. - return s !== undefined && !name.startsWith('auth/'); - }); + return Array.from(scenarios.entries()) + .filter(([, s]) => typeof s.handler === 'function') + .map(([name]) => name); } diff --git a/src/scenarios/client/elicitation-defaults.ts b/src/scenarios/client/elicitation-defaults.ts index c78f3495..4d73c81e 100644 --- a/src/scenarios/client/elicitation-defaults.ts +++ b/src/scenarios/client/elicitation-defaults.ts @@ -11,9 +11,9 @@ import { ListToolsRequestSchema, ElicitResultSchema } from '@modelcontextprotocol/sdk/types.js'; -import type { Scenario, ConformanceCheck } from '../../types'; +import type { ConformanceCheck, RequestListener } from '../../types'; +import { HandlerScenario } from '../../types'; import express, { Request, Response } from 'express'; -import { ScenarioUrls } from '../../types'; import { createRequestLogger } from '../request-logger'; import { randomUUID } from 'crypto'; @@ -472,36 +472,26 @@ function createServer(checks: ConformanceCheck[]): { return { app, cleanup }; } -export class ElicitationClientDefaultsScenario implements Scenario { +export class ElicitationClientDefaultsScenario extends HandlerScenario { name = 'elicitation-sep1034-client-defaults'; readonly source = { introducedIn: '2025-11-25' } as const; description = 'Tests client applies default values for omitted elicitation fields (SEP-1034)'; - private app: express.Application | null = null; - private httpServer: any = null; + mcpPath = '/mcp'; private checks: ConformanceCheck[] = []; private cleanup: (() => void) | null = null; - async start(): Promise { + handler(_getBaseUrl: () => string): RequestListener { this.checks = []; const { app, cleanup } = createServer(this.checks); - this.app = app; this.cleanup = cleanup; - this.httpServer = this.app.listen(0); - const port = this.httpServer.address().port; - return { serverUrl: `http://localhost:${port}/mcp` }; + return app; } async stop() { - if (this.cleanup) { - this.cleanup(); - this.cleanup = null; - } - if (this.httpServer) { - await new Promise((resolve) => this.httpServer.close(resolve)); - this.httpServer = null; - } - this.app = null; + this.cleanup?.(); + this.cleanup = null; + await super.stop(); } getChecks(): ConformanceCheck[] { diff --git a/src/scenarios/client/http-base.ts b/src/scenarios/client/http-base.ts index 06c2afaf..f287c1f3 100644 --- a/src/scenarios/client/http-base.ts +++ b/src/scenarios/client/http-base.ts @@ -9,56 +9,25 @@ import http from 'http'; import { - Scenario, - ScenarioUrls, + HandlerScenario, + RequestListener, ConformanceCheck, ScenarioSource, DRAFT_PROTOCOL_VERSION } from '../../types.js'; -export abstract class BaseHttpScenario implements Scenario { +export abstract class BaseHttpScenario extends HandlerScenario { abstract name: string; abstract description: string; readonly source: ScenarioSource = { introducedIn: DRAFT_PROTOCOL_VERSION }; - allowClientError?: boolean; - protected server: http.Server | null = null; protected checks: ConformanceCheck[] = []; - protected port: number = 0; protected sessionId: string = `session-${Date.now()}`; - async start(): Promise { - return new Promise((resolve, reject) => { - this.server = http.createServer((req, res) => { - this.handleRequest(req, res); - }); - this.server.on('error', reject); - this.server.listen(0, () => { - const address = this.server!.address(); - if (address && typeof address === 'object') { - this.port = address.port; - resolve({ serverUrl: `http://localhost:${this.port}` }); - } else { - reject(new Error('Failed to get server address')); - } - }); - }); - } - - async stop(): Promise { - return new Promise((resolve, reject) => { - if (this.server) { - this.server.close((err) => { - if (err) reject(err); - else { - this.server = null; - resolve(); - } - }); - } else { - resolve(); - } - }); + handler(_getBaseUrl: () => string): RequestListener { + this.checks = []; + this.sessionId = `session-${Date.now()}`; + return (req, res) => this.handleRequest(req, res); } abstract getChecks(): ConformanceCheck[]; diff --git a/src/scenarios/client/initialize.ts b/src/scenarios/client/initialize.ts index b5e2aef2..d693be75 100644 --- a/src/scenarios/client/initialize.ts +++ b/src/scenarios/client/initialize.ts @@ -1,59 +1,23 @@ import http from 'http'; import { - Scenario, - ScenarioUrls, + HandlerScenario, + RequestListener, ConformanceCheck, LATEST_SPEC_VERSION, NEGOTIABLE_PROTOCOL_VERSIONS } from '../../types'; import { clientChecks } from '../../checks/index'; -export class InitializeScenario implements Scenario { +export class InitializeScenario extends HandlerScenario { name = 'initialize'; readonly source = { introducedIn: '2025-06-18' } as const; description = 'Tests MCP client initialization handshake'; - private server: http.Server | null = null; private checks: ConformanceCheck[] = []; - private port: number = 0; - - async start(): Promise { - return new Promise((resolve, reject) => { - this.server = http.createServer((req, res) => { - this.handleRequest(req, res); - }); - - this.server.on('error', reject); - - this.server.listen(0, () => { - const address = this.server!.address(); - if (address && typeof address === 'object') { - this.port = address.port; - resolve({ - serverUrl: `http://localhost:${this.port}` - }); - } else { - reject(new Error('Failed to get server address')); - } - }); - }); - } - async stop(): Promise { - return new Promise((resolve, reject) => { - if (this.server) { - this.server.close((err) => { - if (err) { - reject(err); - } else { - this.server = null; - resolve(); - } - }); - } else { - resolve(); - } - }); + handler(_getBaseUrl: () => string): RequestListener { + this.checks = []; + return (req, res) => this.handleRequest(req, res); } getChecks(): ConformanceCheck[] { diff --git a/src/scenarios/client/json-schema-ref-deref.ts b/src/scenarios/client/json-schema-ref-deref.ts index 91ccc9e0..13f5b773 100644 --- a/src/scenarios/client/json-schema-ref-deref.ts +++ b/src/scenarios/client/json-schema-ref-deref.ts @@ -1,9 +1,9 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js'; import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'; import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'; -import type { Scenario, ConformanceCheck } from '../../types'; +import type { ConformanceCheck, RequestListener } from '../../types'; import express, { Request, Response } from 'express'; -import { ScenarioUrls, DRAFT_PROTOCOL_VERSION } from '../../types'; +import { HandlerScenario, DRAFT_PROTOCOL_VERSION } from '../../types'; /** * Scenario: JSON Schema network $ref dereferencing (SEP-2106) @@ -70,19 +70,18 @@ function createMcpServer(canaryUrl: string, onToolsListed: () => void): Server { return server; } -export class JsonSchemaRefDerefScenario implements Scenario { +export class JsonSchemaRefDerefScenario extends HandlerScenario { name = 'json-schema-ref-no-deref'; readonly source = { introducedIn: DRAFT_PROTOCOL_VERSION } as const; description = `Tests that a client does not automatically dereference a network-URI \`$ref\` in a tool's inputSchema (SEP-2106). The 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.`; + mcpPath = '/mcp'; - private app: express.Application | null = null; - private httpServer: ReturnType | null = null; private canaryRequests: Array<{ method: string; userAgent?: string }> = []; private toolsListed = false; - async start(): Promise { + handler(getBaseUrl: () => string): RequestListener { this.canaryRequests = []; this.toolsListed = false; @@ -107,7 +106,8 @@ The scenario advertises a tool whose inputSchema contains a \`$ref\` pointing at app.post('/mcp', async (req: Request, res: Response) => { try { // Stateless: fresh server and transport per request - const server = createMcpServer(this.canaryUrl(), () => { + const canaryUrl = `${getBaseUrl()}${CANARY_PATH}`; + const server = createMcpServer(canaryUrl, () => { this.toolsListed = true; }); const transport = new StreamableHTTPServerTransport({ @@ -129,29 +129,7 @@ The scenario advertises a tool whose inputSchema contains a \`$ref\` pointing at } }); - this.app = app; - this.httpServer = app.listen(0); - return { serverUrl: `${this.baseUrl()}/mcp` }; - } - - private baseUrl(): string { - const address = this.httpServer?.address(); - if (!address || typeof address === 'string') { - throw new Error('Scenario server is not listening'); - } - return `http://localhost:${address.port}`; - } - - private canaryUrl(): string { - return `${this.baseUrl()}${CANARY_PATH}`; - } - - async stop() { - if (this.httpServer) { - await new Promise((resolve) => this.httpServer!.close(resolve)); - this.httpServer = null; - } - this.app = null; + return app; } getChecks(): ConformanceCheck[] { diff --git a/src/scenarios/client/mrtr-client.ts b/src/scenarios/client/mrtr-client.ts index 431fafe6..daf8a0ed 100644 --- a/src/scenarios/client/mrtr-client.ts +++ b/src/scenarios/client/mrtr-client.ts @@ -10,8 +10,8 @@ * fulfills the elicitation, and retries. The server verifies correct client behavior. */ -import type { Scenario, ConformanceCheck } from '../../types'; -import { DRAFT_PROTOCOL_VERSION, ScenarioUrls } from '../../types'; +import type { ConformanceCheck, RequestListener } from '../../types'; +import { HandlerScenario, DRAFT_PROTOCOL_VERSION } from '../../types'; import express, { Request, Response } from 'express'; import { randomUUID } from 'crypto'; @@ -431,30 +431,17 @@ function createMRTRServer(checks: ConformanceCheck[]): express.Application { return app; } -export class MRTRClientScenario implements Scenario { +export class MRTRClientScenario extends HandlerScenario { name = 'sep-2322-client-request-state'; readonly source = { introducedIn: DRAFT_PROTOCOL_VERSION } as const; description = 'Tests client MRTR behavior: requestState echo, no-state omission, and JSON-RPC id uniqueness (SEP-2322)'; - private app: express.Application | null = null; - private httpServer: ReturnType | null = null; + mcpPath = '/mcp'; private checks: ConformanceCheck[] = []; - async start(): Promise { + handler(_getBaseUrl: () => string): RequestListener { this.checks = []; - this.app = createMRTRServer(this.checks); - this.httpServer = this.app.listen(0); - const addr = this.httpServer.address(); - const port = typeof addr === 'object' && addr ? addr.port : 0; - return { serverUrl: `http://localhost:${port}/mcp` }; - } - - async stop() { - if (this.httpServer) { - await new Promise((resolve) => this.httpServer!.close(resolve)); - this.httpServer = null; - } - this.app = null; + return createMRTRServer(this.checks); } getChecks(): ConformanceCheck[] { diff --git a/src/scenarios/client/request-metadata.ts b/src/scenarios/client/request-metadata.ts index 9d9fd69d..ced1cb35 100644 --- a/src/scenarios/client/request-metadata.ts +++ b/src/scenarios/client/request-metadata.ts @@ -1,7 +1,7 @@ import http from 'http'; import { - Scenario, - ScenarioUrls, + HandlerScenario, + RequestListener, ConformanceCheck, CheckStatus, DRAFT_PROTOCOL_VERSION @@ -35,45 +35,21 @@ export const DECLARED_CHECK_IDS = [ 'sep-2575-client-retry-supported-version' ] as const; -export class RequestMetadataScenario implements Scenario { +export class RequestMetadataScenario extends HandlerScenario { name = 'request-metadata'; readonly source = { introducedIn: DRAFT_PROTOCOL_VERSION } as const; description = 'Per-request _meta and MCP-Protocol-Version header obligations (SEP-2575)'; - private server: http.Server | null = null; private checks: ConformanceCheck[] = []; private hasSimulatedRejection = false; private requestsObserved = 0; - async start(): Promise { + handler(_getBaseUrl: () => string): RequestListener { this.hasSimulatedRejection = false; this.checks = []; this.requestsObserved = 0; - return new Promise((resolve, reject) => { - this.server = http.createServer((req, res) => { - this.handleRequest(req, res); - }); - this.server.on('error', reject); - this.server.listen(0, () => { - const address = this.server!.address(); - if (address && typeof address === 'object') { - resolve({ serverUrl: `http://localhost:${address.port}` }); - } - }); - }); - } - - async stop(): Promise { - return new Promise((resolve) => { - if (this.server) { - this.server.close(() => { - resolve(); - }); - } else { - resolve(); - } - }); + return (req, res) => this.handleRequest(req, res); } getChecks(): ConformanceCheck[] { diff --git a/src/scenarios/client/sse-retry.ts b/src/scenarios/client/sse-retry.ts index b90bf40a..98ee2fa9 100644 --- a/src/scenarios/client/sse-retry.ts +++ b/src/scenarios/client/sse-retry.ts @@ -8,7 +8,12 @@ */ import http from 'http'; -import { Scenario, ScenarioUrls, ConformanceCheck } from '../../types.js'; +import { + Scenario, + ScenarioUrls, + ConformanceCheck, + RequestListener +} from '../../types.js'; export class SSERetryScenario implements Scenario { name = 'sse-retry'; @@ -38,14 +43,24 @@ export class SSERetryScenario implements Scenario { private readonly LATE_TOLERANCE = 200; // Allow 200ms late for network/event loop private readonly VERY_LATE_MULTIPLIER = 2; // If >2x retry value, client is likely ignoring it + handler(_getBaseUrl: () => string): RequestListener { + this.checks = []; + this.toolStreamCloseTime = null; + this.getReconnectionTime = null; + this.getConnectionCount = 0; + this.lastEventIds = []; + this.eventIdCounter = 0; + this.sessionId = `session-${Date.now()}`; + this.pendingToolCallId = null; + this.getResponseStream = null; + return (req, res) => this.handleRequest(req, res); + } + async start(): Promise { + const listener = this.handler(() => `http://localhost:${this.port}`); return new Promise((resolve, reject) => { - this.server = http.createServer((req, res) => { - this.handleRequest(req, res); - }); - + this.server = http.createServer(listener); this.server.on('error', reject); - this.server.listen(0, () => { const address = this.server!.address(); if (address && typeof address === 'object') { diff --git a/src/scenarios/client/tools_call.ts b/src/scenarios/client/tools_call.ts index 59470f37..0fec16e1 100644 --- a/src/scenarios/client/tools_call.ts +++ b/src/scenarios/client/tools_call.ts @@ -4,9 +4,9 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'; -import type { Scenario, ConformanceCheck } from '../../types'; +import type { ConformanceCheck, RequestListener } from '../../types'; +import { HandlerScenario } from '../../types'; import express, { Request, Response } from 'express'; -import { ScenarioUrls } from '../../types'; import { createRequestLogger } from '../request-logger'; function createMcpServer(checks: ConformanceCheck[]): Server { @@ -113,28 +113,16 @@ function createServerApp(checks: ConformanceCheck[]): express.Application { return app; } -export class ToolsCallScenario implements Scenario { +export class ToolsCallScenario extends HandlerScenario { name = 'tools_call'; readonly source = { introducedIn: '2025-06-18' } as const; description = 'Tests calling tools with various parameter types'; - private app: express.Application | null = null; - private httpServer: any = null; + mcpPath = '/mcp'; private checks: ConformanceCheck[] = []; - async start(): Promise { + handler(_getBaseUrl: () => string): RequestListener { this.checks = []; - this.app = createServerApp(this.checks); - this.httpServer = this.app.listen(0); - const port = this.httpServer.address().port; - return { serverUrl: `http://localhost:${port}/mcp` }; - } - - async stop() { - if (this.httpServer) { - await new Promise((resolve) => this.httpServer.close(resolve)); - this.httpServer = null; - } - this.app = null; + return createServerApp(this.checks); } getChecks(): ConformanceCheck[] { diff --git a/src/types.ts b/src/types.ts index 8052eb1e..f467733a 100644 --- a/src/types.ts +++ b/src/types.ts @@ -91,6 +91,12 @@ export interface ScenarioUrls { context?: Record; } +/** A Node-style request handler — what `http.createServer` accepts. */ +export type RequestListener = ( + req: import('http').IncomingMessage, + res: import('http').ServerResponse +) => void; + export interface Scenario { name: string; description: string; @@ -100,11 +106,77 @@ export interface Scenario { * Use this for scenarios where the client is expected to error (e.g., rejecting invalid auth). */ allowClientError?: boolean; + /** + * Sub-path of the MCP endpoint relative to the handler root. The CLI runner + * appends this to the listen URL; the hosted runner appends it to the + * mounted prefix. Default: '' (handler root is the MCP endpoint). + */ + mcpPath?: string; + /** + * Return the request handler without binding a port. The hosted runner + * mounts this directly under a path prefix so scenarios can run on + * serverless hosts that don't allow loopback listeners. + * + * `getBaseUrl` returns the public URL this handler is reachable at (no + * trailing slash) — use it for scenarios that embed self-referential + * absolute URLs in responses. Called lazily so `start()` can resolve it + * after the OS assigns a port. + * + * Implementations should reset per-run state here, not in `start()`. + * If omitted, the scenario only runs via `start()`/`stop()` (e.g. auth + * scenarios that need a second origin). + */ + handler?(getBaseUrl: () => string): RequestListener; start(): Promise; stop(): Promise; getChecks(): ConformanceCheck[]; } +/** + * Convenience: implement `handler()` + `mcpPath` and get `start()`/`stop()` + * for free. Covers every scenario that just needs one HTTP origin. + */ +export abstract class HandlerScenario implements Scenario { + abstract name: string; + abstract description: string; + abstract readonly source: ScenarioSource; + allowClientError?: boolean; + mcpPath = ''; + + private _server: import('http').Server | null = null; + private _baseUrl = ''; + + abstract handler(getBaseUrl: () => string): RequestListener; + abstract getChecks(): ConformanceCheck[]; + + async start(): Promise { + const http = await import('http'); + const listener = this.handler(() => this._baseUrl); + return new Promise((resolve, reject) => { + this._server = http.createServer(listener); + this._server.on('error', reject); + this._server.listen(0, () => { + const addr = this._server!.address(); + if (!addr || typeof addr !== 'object') { + return reject(new Error('Failed to get server address')); + } + this._baseUrl = `http://localhost:${addr.port}`; + resolve({ serverUrl: `${this._baseUrl}${this.mcpPath}` }); + }); + }); + } + + async stop(): Promise { + if (!this._server) return; + await new Promise((resolve) => { + // closeAllConnections so hung SSE streams don't keep the process alive + this._server!.closeAllConnections?.(); + this._server!.close(() => resolve()); + }); + this._server = null; + } +} + export interface ClientScenario { name: string; description: string; From 5efcfae42bc968cc77653ba1716a3cd4d227070b Mon Sep 17 00:00:00 2001 From: Paul Carleton Date: Fri, 29 May 2026 13:15:17 +0000 Subject: [PATCH 3/9] hosted: auth scenarios via second-origin relay MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Auth scenarios need ≥2 public origins because RFC 8414/9728 well-known paths and issuer validation are origin-rooted — they can't live under the /s/// prefix. This adds an AS-relay topology where a stateless second deployment forwards everything to the RS app's /__aux//* backchannel; all scenario state (closures, checks[]) stays in one process. - types: AuthHandlerScenario base — authHandlers(ctx)→{rs,aux} mirrors HandlerScenario; start()/stop() bind one localhost port per origin so the CLI runner path is unchanged. - scenarios: refactor basic-cimd, discovery-metadata×4, pre-registration to the new shape (rest are mechanical follow-up; still work via start()). - hosted/server: --as-origin/--as2-origin/--idp-origin enable auth/* mounts; /__aux//* dispatch (extracts /r/, strips it, hands to the run's aux handler) guarded by x-relay-secret + timingSafeEqual; root-level /.well-known/oauth-protected-resource/s/* dispatch for RFC 9728 discovery. - examples/hosted/valtown-relay.ts: ~40 LOC stateless relay (curated header forward, redirect:manual, shared secret). One val per role. - hosted-auth.test.ts: spins RS+relay on ephemeral ports and walks discovery → DCR → authorize → token → MCP → results end-to-end. Co-Authored-By: Claude Opus 4.8 --- examples/hosted/valtown-relay.ts | 95 +++++++ examples/hosted/valtown.ts | 13 +- src/hosted/README.md | 74 ++++- src/hosted/hosted-auth.test.ts | 247 ++++++++++++++++ src/hosted/index.ts | 32 ++- src/hosted/server.ts | 202 ++++++++++--- src/hosted/session.ts | 81 +++++- src/index.ts | 25 +- src/scenarios/client/auth/basic-cimd.ts | 35 +-- .../client/auth/discovery-metadata.ts | 269 +++++++++--------- src/scenarios/client/auth/pre-registration.ts | 50 ++-- src/types.ts | 108 +++++++ 12 files changed, 993 insertions(+), 238 deletions(-) create mode 100644 examples/hosted/valtown-relay.ts create mode 100644 src/hosted/hosted-auth.test.ts diff --git a/examples/hosted/valtown-relay.ts b/examples/hosted/valtown-relay.ts new file mode 100644 index 00000000..315e0f19 --- /dev/null +++ b/examples/hosted/valtown-relay.ts @@ -0,0 +1,95 @@ +/** + * MCP conformance — auxiliary-origin relay (val.town). + * + * The hosted RS app owns all scenario state, but auth scenarios need a second + * public origin so OAuth `.well-known/*` discovery and issuer validation work + * (those are origin-rooted by RFC 8414/9728 — they can't live under the + * `/s///` prefix). This val IS that origin: it forwards + * every request to the RS app's `/__aux//*` backchannel and adds a + * shared secret so the backchannel can't be spoofed by hitting the RS + * directly. + * + * One val per role: deploy this once for `as`, and again for `as2` / `idp` + * if you need the three-origin scenarios (authorization-server-migration, + * enterprise-managed-authorization). + * + * val.town env (Project → Settings → Environment variables): + * CONFORMANCE_RS_ORIGIN https://.val.run + * CONFORMANCE_RELAY_SECRET + * CONFORMANCE_RELAY_ROLE as | as2 | idp (default: as) + * + * Deploy: create an HTTP val and paste: + * + * import handler from "https://esm.sh/@modelcontextprotocol/conformance/examples/hosted/valtown-relay.ts"; + * export default handler; + * + * No scenario logic lives here, so you only redeploy this when the relay + * contract changes — adding/editing scenarios only touches the RS val. + */ + +declare const process: { env: Record }; + +const RS_ORIGIN = process.env.CONFORMANCE_RS_ORIGIN; +const RELAY_SECRET = process.env.CONFORMANCE_RELAY_SECRET; +const ROLE = process.env.CONFORMANCE_RELAY_ROLE ?? 'as'; + +/** + * Headers we forward from the client. Everything else is dropped so a client + * can't smuggle x-relay-secret / x-forwarded-* through us, and so the + * upstream sees a stable shape regardless of what the edge added. + */ +const FORWARD_HEADERS = [ + 'accept', + 'authorization', + 'content-type', + 'content-length', + 'user-agent' +] as const; + +export default async function handler(req: Request): Promise { + if (!RS_ORIGIN || !RELAY_SECRET) { + return Response.json( + { + error: + 'relay misconfigured: set CONFORMANCE_RS_ORIGIN and CONFORMANCE_RELAY_SECRET' + }, + { status: 500 } + ); + } + + const url = new URL(req.url); + const target = `${RS_ORIGIN}/__aux/${ROLE}${url.pathname}${url.search}`; + + const headers = new Headers(); + for (const h of FORWARD_HEADERS) { + const v = req.headers.get(h); + if (v) headers.set(h, v); + } + headers.set('x-relay-secret', RELAY_SECRET); + // The aux handler reconstructs absolute URLs (issuer, endpoints) from + // getAuxBaseUrl() which the RS app already knows, so it doesn't strictly + // need this — but it's useful for logging/debugging on the RS side. + headers.set('x-relay-host', url.host); + + const upstream = await fetch(target, { + method: req.method, + headers, + body: + req.method === 'GET' || req.method === 'HEAD' + ? undefined + : await req.arrayBuffer(), + // /authorize 302s to the client's redirect_uri — pass it through, don't + // follow it ourselves. + redirect: 'manual' + }); + + // Strip hop-by-hop / origin-identifying headers; pass everything else. + const outHeaders = new Headers(upstream.headers); + for (const h of ['content-encoding', 'transfer-encoding', 'connection']) { + outHeaders.delete(h); + } + return new Response(upstream.body, { + status: upstream.status, + headers: outHeaders + }); +} diff --git a/examples/hosted/valtown.ts b/examples/hosted/valtown.ts index 51a3c340..ee0a8c80 100644 --- a/examples/hosted/valtown.ts +++ b/examples/hosted/valtown.ts @@ -26,7 +26,18 @@ import { createHostedApp } from '../../src/hosted/server'; const NOT_FETCH_SAFE = new Set(['sse-retry']); -const { app } = createHostedApp(); +// Auth scenarios need a second public origin (RFC 8414 well-known is +// origin-rooted). Deploy examples/hosted/valtown-relay.ts as a separate val +// and point CONFORMANCE_AS_ORIGIN at it; both vals share +// CONFORMANCE_RELAY_SECRET so /__aux can't be hit directly. +const { app } = createHostedApp({ + auxOrigins: { + as: process.env.CONFORMANCE_AS_ORIGIN, + as2: process.env.CONFORMANCE_AS2_ORIGIN, + idp: process.env.CONFORMANCE_IDP_ORIGIN + }, + relaySecret: process.env.CONFORMANCE_RELAY_SECRET +}); export default async function (request: Request): Promise { const url = new URL(request.url); diff --git a/src/hosted/README.md b/src/hosted/README.md index 915d6010..460ce80e 100644 --- a/src/hosted/README.md +++ b/src/hosted/README.md @@ -42,15 +42,70 @@ accumulate on that run. ### Coverage -Hostable = any scenario that implements `handler()`. Currently that's -everything **except** `auth/*` (need a second public origin for the -authorization server). `listHostableScenarios()` derives the list at runtime -from which scenarios expose `handler()`. +Hostable = any scenario that implements `handler()` (single origin) or +`authHandlers()` (multi-origin, see below). `listHostableScenarios()` derives +the list at runtime, gated by which aux origins are configured. `sse-retry` implements `handler()` and works under `conformance hosted`, but its connection-close-timing checks won't be meaningful through a buffered fetch bridge — see below. +## Auth scenarios — second-origin relay + +`auth/*` scenarios stand up two cross-referencing HTTP apps: a resource +server (the MCP endpoint + PRM) and an OAuth authorization server. The +`.well-known/*` discovery paths and RFC 8414 `issuer` validation are +**origin-rooted**, so the AS can't live under `/s///` — it +needs its own public origin. + +``` +client RS origin AS-relay origin + │ POST /s/auth/.../mcp │ │ + │──────────────────────────▶│ 401 + WWW-Authenticate │ + │ GET /.well-known/oauth-protected-resource/s/auth/... │ + │──────────────────────────▶│ {authorization_servers: │ + │ │ [/r/]} │ + │ GET /.well-known/oauth-authorization-server/r/ │ + │──────────────────────────────────────────────────────────▶│ + │ │◀── /__aux/as/.well-known/... │ + │ │ (x-relay-secret) │ +``` + +The AS relay (`examples/hosted/valtown-relay.ts`) is **stateless** — it just +forwards every request to `/__aux/` with a shared +secret. All scenario state (closures, checks) stays on the RS process; the +per-run AS issuer is `/r/` so the run-id is recoverable +from any path the client constructs from it. The RS app extracts that +`/r/` segment, strips it, and dispatches to the run's AS handler with the +path `createAuthServer()` registered. + +```bash +# CLI — also reads CONFORMANCE_RELAY_SECRET from env +npx @modelcontextprotocol/conformance hosted \ + --port 3000 \ + --as-origin https://conformance-as.example.com \ + --relay-secret "$(openssl rand -hex 32)" +``` + +Two extra routes appear when `--as-origin` is set: + +| Route | Purpose | +| --------------------------------------------------- | -------------------------------------------------------------------- | +| `GET /.well-known/oauth-protected-resource/s/<...>` | RFC 9728 root-level PRM dispatch — recovers run from the path suffix | +| `ALL /__aux//*` | Relay backchannel; 403 without `x-relay-secret` | + +The three-origin scenarios (`authorization-server-migration` needs `--as2-origin`, +`enterprise-managed-authorization` needs `--idp-origin`) are mounted only +when those flags are set; deploy one more relay per role with +`CONFORMANCE_RELAY_ROLE=as2|idp`. + +**Fidelity note:** the hosted AS issuer always carries a `/r/` path +component, so scenarios that locally test root-issuer discovery +(`auth/metadata-default`, `auth/metadata-var1`) become path-issuer tests when +hosted. The RFC 8414 mechanics are identical. +`auth/2025-03-26-endpoint-fallback` (no-metadata fallback to `/authorize` at +the MCP origin) is not hostable. + ## Serverless / val.town `examples/hosted/valtown.ts` wraps `createHostedApp()` in a @@ -67,6 +122,17 @@ The bridge buffers the response, so streaming-SSE scenarios (`sse-retry`) are returned as 501; everything else — including the SDK's `StreamableHTTPServerTransport` in stateless mode — works. +### Two-val auth setup + +| Val | File | Env | +| ---------------- | ---------------------------------- | ---------------------------------------------------------------------------------------- | +| `conformance` | `examples/hosted/valtown.ts` | `CONFORMANCE_AS_ORIGIN=https://-conformance-as.val.run`, `CONFORMANCE_RELAY_SECRET` | +| `conformance-as` | `examples/hosted/valtown-relay.ts` | `CONFORMANCE_RS_ORIGIN=https://-conformance.val.run`, `CONFORMANCE_RELAY_SECRET` | + +Same `CONFORMANCE_RELAY_SECRET` on both. Run state lives in the RS val's +process memory, so a run must complete within one warm isolate (~minutes on +val.town — fine for a conformance flow). + ## Example ```bash diff --git a/src/hosted/hosted-auth.test.ts b/src/hosted/hosted-auth.test.ts new file mode 100644 index 00000000..7aacfa2a --- /dev/null +++ b/src/hosted/hosted-auth.test.ts @@ -0,0 +1,247 @@ +/** + * Hosted auth scenarios — RS app + a local relay simulating the AS origin. + * + * Mirrors the production topology (RS val.town app + AS relay val) on two + * ephemeral localhost ports, then walks the OAuth discovery → DCR → + * authorize → token → MCP flow by hand to prove the path-rewrite and + * relay-secret guard work end to end. + */ + +import { describe, it, expect, beforeAll, afterAll } from 'vitest'; +import express from 'express'; +import type { Server } from 'http'; +import { createHostedApp } from './server'; +import { SessionManager, listHostableScenarios } from './session'; + +const RELAY_SECRET = 'test-relay-secret-do-not-use-in-prod'; + +describe('hosted auth scenarios (RS + AS relay)', () => { + let rsSrv: Server; + let relaySrv: Server; + let sessions: SessionManager; + let rs: string; // RS origin + let asOrigin: string; // relay origin + + beforeAll(async () => { + // Relay first so we know its origin before configuring the RS app. + const relay = express(); + relay.use(express.raw({ type: '*/*' })); + relay.all(/.*/, async (req, res) => { + const headers: Record = { + 'x-relay-secret': RELAY_SECRET, + 'x-relay-host': req.headers.host ?? '' + }; + for (const h of ['accept', 'authorization', 'content-type']) { + const v = req.headers[h]; + if (typeof v === 'string') headers[h] = v; + } + const search = req.url.includes('?') + ? req.url.slice(req.url.indexOf('?')) + : ''; + const body = ['GET', 'HEAD'].includes(req.method) + ? undefined + : new Uint8Array(req.body as Buffer); + const upstream = await fetch(`${rs}/__aux/as${req.path}${search}`, { + method: req.method, + headers, + body, + redirect: 'manual' + }); + res.status(upstream.status); + upstream.headers.forEach((v, k) => res.setHeader(k, v)); + res.send(Buffer.from(await upstream.arrayBuffer())); + }); + asOrigin = await listen(relay, (s) => (relaySrv = s)); + + const hosted = createHostedApp({ + auxOrigins: { as: asOrigin }, + relaySecret: RELAY_SECRET + }); + sessions = hosted.sessions; + rs = await listen(hosted.app, (s) => (rsSrv = s)); + }); + + afterAll(async () => { + await sessions.close(); + await Promise.all( + [rsSrv, relaySrv].map((s) => new Promise((r) => s.close(() => r()))) + ); + }); + + it('lists auth/* scenarios as hostable when as-origin is configured', () => { + const names = listHostableScenarios(['as']); + expect(names).toContain('auth/basic-cimd'); + expect(names).toContain('auth/metadata-default'); + expect(names).toContain('auth/pre-registration'); + // 3-origin scenarios still excluded with only [as] + expect(names).not.toContain('auth/authorization-server-migration'); + }); + + it('rejects /__aux/* without the relay secret', async () => { + const res = await fetch( + `${rs}/__aux/as/.well-known/oauth-authorization-server/r/nope` + ); + expect(res.status).toBe(403); + }); + + it('walks auth/metadata-default end-to-end through the relay', async () => { + const runId = 'authflow'; + const mcpUrl = `${rs}/s/auth/metadata-default/${runId}/mcp`; + + // 1. Unauthenticated MCP → 401 with WWW-Authenticate pointing at PRM + const r401 = await fetch(mcpUrl, { + method: 'POST', + headers: jsonHeaders(), + body: JSON.stringify(initBody()) + }); + expect(r401.status).toBe(401); + const www = r401.headers.get('www-authenticate') ?? ''; + expect(www).toContain('resource_metadata='); + + // 2. PRM via root well-known dispatch (RFC 9728 path-suffix derivation) + const prmUrl = `${rs}/.well-known/oauth-protected-resource/s/auth/metadata-default/${runId}/mcp`; + const prm = await fetch(prmUrl).then((r) => r.json()); + expect(prm.resource).toBe(mcpUrl); + expect(prm.authorization_servers).toEqual([`${asOrigin}/r/${runId}`]); + + // 3. AS metadata — client derives well-known from issuer per RFC 8414 → + // hits the relay origin → forwarded to /__aux/as/… → run resolved. + const asMeta = await fetch( + `${asOrigin}/.well-known/oauth-authorization-server/r/${runId}` + ).then((r) => r.json()); + expect(asMeta.issuer).toBe(`${asOrigin}/r/${runId}`); + expect(asMeta.authorization_endpoint).toBe( + `${asOrigin}/r/${runId}/authorize` + ); + expect(asMeta.token_endpoint).toBe(`${asOrigin}/r/${runId}/token`); + + // 4. DCR + const reg = await fetch(asMeta.registration_endpoint, { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ + client_name: 'vitest', + redirect_uris: ['http://localhost:0/cb'] + }) + }).then((r) => r.json()); + expect(reg.client_id).toBeTruthy(); + + // 5. /authorize → 302 to redirect_uri with code (relay passes redirect through) + const authz = await fetch( + `${asMeta.authorization_endpoint}?` + + new URLSearchParams({ + response_type: 'code', + client_id: reg.client_id, + redirect_uri: 'http://localhost:0/cb', + code_challenge: 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM', + code_challenge_method: 'S256', + resource: mcpUrl + }), + { redirect: 'manual' } + ); + expect(authz.status).toBe(302); + const loc = new URL(authz.headers.get('location')!); + const code = loc.searchParams.get('code'); + expect(code).toBeTruthy(); + // RFC 9207 iss parameter should be the per-run issuer + expect(loc.searchParams.get('iss')).toBe(`${asOrigin}/r/${runId}`); + + // 6. /token + const tok = await fetch(asMeta.token_endpoint, { + method: 'POST', + headers: { 'content-type': 'application/x-www-form-urlencoded' }, + body: new URLSearchParams({ + grant_type: 'authorization_code', + code: code!, + redirect_uri: 'http://localhost:0/cb', + client_id: reg.client_id, + code_verifier: + 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk' /* matches challenge */, + resource: mcpUrl + }) + }).then((r) => r.json()); + expect(tok.access_token).toBeTruthy(); + + // 7. Authenticated MCP initialize → 200 + const ok = await fetch(mcpUrl, { + method: 'POST', + headers: { + ...jsonHeaders(), + authorization: `Bearer ${tok.access_token}` + }, + body: JSON.stringify(initBody()) + }); + expect(ok.status).toBe(200); + + // 8. Results — checks from BOTH origins accumulated on the one run. + const results = await fetch(`${rs}/results/${runId}`).then((r) => r.json()); + const ids = results.checks.map((c: { id: string }) => c.id); + expect(ids).toContain('prm-pathbased-requested'); // RS-side + expect(ids).toContain('authorization-server-metadata'); // AS-side via relay + expect(ids).toContain('client-registration'); + expect(ids).toContain('authorization-request'); + expect(ids).toContain('token-request'); + }); + + it('exposes scenarioContext on the start_run response (pre-registration)', async () => { + const r = await fetch(`${rs}/s/auth/pre-registration`).then((r) => + r.json() + ); + expect(r.context).toEqual({ + client_id: 'pre-registered-client', + client_secret: 'pre-registered-secret' + }); + }); + + it('routes tenant-prefixed AS metadata (auth/metadata-var2) correctly', async () => { + const runId = 'tenant'; + // Touch RS to lazily create the run so the aux handler exists. + await fetch(`${rs}/s/auth/metadata-var2/${runId}/mcp`, { + method: 'POST', + headers: jsonHeaders(), + body: JSON.stringify(initBody()) + }); + // Issuer is /r//tenant1 → well-known at + // /.well-known/oauth-authorization-server/r//tenant1 + const meta = await fetch( + `${asOrigin}/.well-known/oauth-authorization-server/r/${runId}/tenant1` + ).then((r) => r.json()); + expect(meta.issuer).toBe(`${asOrigin}/r/${runId}/tenant1`); + expect(meta.authorization_endpoint).toBe( + `${asOrigin}/r/${runId}/tenant1/authorize` + ); + }); +}); + +function listen( + app: express.Application, + capture: (s: Server) => void +): Promise { + return new Promise((resolve) => { + const s = app.listen(0, () => { + const a = s.address(); + capture(s); + resolve(`http://localhost:${(a as { port: number }).port}`); + }); + }); +} + +function jsonHeaders() { + return { + 'content-type': 'application/json', + accept: 'application/json, text/event-stream' + }; +} + +function initBody() { + return { + jsonrpc: '2.0', + id: 1, + method: 'initialize', + params: { + protocolVersion: '2025-06-18', + clientInfo: { name: 'vitest', version: '0' }, + capabilities: {} + } + }; +} diff --git a/src/hosted/index.ts b/src/hosted/index.ts index 3d2937ea..3396152b 100644 --- a/src/hosted/index.ts +++ b/src/hosted/index.ts @@ -1,5 +1,6 @@ import { createHostedApp } from './server'; import { listHostableScenarios } from './session'; +import { AuxOriginRole } from '../types'; export { createHostedApp } from './server'; export { listHostableScenarios } from './session'; @@ -8,20 +9,47 @@ export interface HostedCliOptions { port: number; publicOrigin?: string; ttlMs?: number; + auxOrigins?: Partial>; + relaySecret?: string; } export async function runHostedServer(opts: HostedCliOptions): Promise { + const auxOrigins = opts.auxOrigins ?? {}; + const haveAux = (Object.keys(auxOrigins) as AuxOriginRole[]).filter( + (r) => auxOrigins[r] + ); + if (haveAux.length && !opts.relaySecret) { + console.error( + 'Refusing to start with --as-origin but no --relay-secret: the /__aux ' + + 'backchannel would be open to direct check-forgery. Set ' + + '--relay-secret (or CONFORMANCE_RELAY_SECRET) to the same value the ' + + 'relay sends.' + ); + process.exit(1); + } + const { app, sessions } = createHostedApp({ publicOrigin: opts.publicOrigin, - ttlMs: opts.ttlMs + ttlMs: opts.ttlMs, + auxOrigins, + relaySecret: opts.relaySecret }); const server = app.listen(opts.port, () => { const origin = opts.publicOrigin ?? `http://localhost:${opts.port}`; console.error(`MCP conformance hosted server listening on ${origin}`); console.error( - ` ${listHostableScenarios().length} scenarios mounted under ${origin}/s/` + ` ${listHostableScenarios(haveAux).length} scenarios mounted under ${origin}/s/` ); + if (haveAux.length) { + for (const r of haveAux) { + console.error(` aux[${r}] relay origin: ${auxOrigins[r]}`); + } + } else { + console.error( + ' (auth/* scenarios disabled — pass --as-origin to enable)' + ); + } console.error(` meta MCP server at ${origin}/mcp`); }); diff --git a/src/hosted/server.ts b/src/hosted/server.ts index 212e87ae..dc13fbef 100644 --- a/src/hosted/server.ts +++ b/src/hosted/server.ts @@ -20,7 +20,8 @@ * this works on serverless hosts. Each run gets a fresh Scenario instance. */ -import express, { Request } from 'express'; +import express, { Request, Response } from 'express'; +import { timingSafeEqual } from 'crypto'; import { Server } from '@modelcontextprotocol/sdk/server/index.js'; import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'; import { @@ -30,29 +31,46 @@ import { } from '@modelcontextprotocol/sdk/types.js'; import { SessionManager, + HostedRun, UnknownScenarioError, NotHostableError, listHostableScenarios } from './session'; import { renderLanding, renderResults } from './html'; import { getScenario } from '../scenarios'; -import { ConformanceCheck } from '../types'; +import { ConformanceCheck, AuxOriginRole } from '../types'; export interface HostedServerOptions { publicOrigin?: string; ttlMs?: number; + /** + * Public origins of the AS/IdP relay deployments. When set, scenarios that + * implement `authHandlers()` become hostable; their per-run AS issuer is + * `/r/`. See examples/hosted/valtown-relay.ts. + */ + auxOrigins?: Partial>; + /** + * Shared secret the relay sends in `x-relay-secret`. `/__aux/*` rejects + * requests without it so the aux backchannel can't be hit directly. Set + * the same value in the relay's env. + */ + relaySecret?: string; } /** Only allow run-ids that are safe in a single path segment. */ const RUN_ID_RE = /^[A-Za-z0-9_-]{1,64}$/; +const AUX_ROLES: readonly AuxOriginRole[] = ['as', 'as2', 'idp']; + export function createHostedApp(opts: HostedServerOptions = {}): { app: express.Application; sessions: SessionManager; } { - const sessions = new SessionManager({ ttlMs: opts.ttlMs }); + const auxOrigins = opts.auxOrigins ?? {}; + const haveAux = AUX_ROLES.filter((r) => auxOrigins[r]); + const sessions = new SessionManager({ ttlMs: opts.ttlMs, auxOrigins }); const app = express(); - const hostable = new Set(listHostableScenarios()); + const hostable = new Set(listHostableScenarios(haveAux)); function origin(req: Request): string { if (opts.publicOrigin) return opts.publicOrigin; @@ -65,6 +83,51 @@ export function createHostedApp(opts: HostedServerOptions = {}): { return `${origin(req)}/s/${scenario}/${runId}`; } + /** + * Resolve "//" against the hostable set. + * Scenario names may contain '/', so try progressively longer prefixes. + * Returns undefined if no hostable scenario matches the prefix. + */ + function resolveRun(rest: string): + | { + scenarioName: string; + runId: string | undefined; + suffix: string; + } + | undefined { + const segments = rest.split('/'); + for (let i = 1; i <= segments.length; i++) { + const candidate = segments.slice(0, i).join('/'); + if (hostable.has(candidate)) { + const runId = segments[i] || undefined; + const suffix = '/' + segments.slice(i + 1).join('/'); + return { scenarioName: candidate, runId, suffix }; + } + } + return undefined; + } + + /** + * Dispatch (req, res) to `listener` after rewriting `req.url` so the + * scenario sees the path it would have under start()/stop() — i.e. with + * the run-prefix stripped and (for well-known dispatch) the well-known + * prefix re-prepended. + */ + function dispatch( + run: HostedRun, + listener: (req: Request, res: Response) => void, + req: Request, + res: Response, + rewrittenUrl: string + ) { + res.setHeader( + 'link', + `<${origin(req)}/results/${run.id}>; rel="conformance-results"` + ); + req.url = rewrittenUrl; + listener(req, res); + } + // ---------- discovery ---------- app.get('/', (req, res) => { @@ -95,26 +158,14 @@ export function createHostedApp(opts: HostedServerOptions = {}): { app.all(/^\/s\/(.+)$/, (req, res, next) => { const rest = req.params[0]; // "//" - - // Scenario names can contain '/', so try progressively longer prefixes - // until one matches a known scenario. - const segments = rest.split('/'); - let nameLen = 0; - let scenarioName = ''; - for (let i = 1; i <= segments.length; i++) { - const candidate = segments.slice(0, i).join('/'); - if (hostable.has(candidate)) { - scenarioName = candidate; - nameLen = i; - break; - } - } - if (!scenarioName) { + const resolved = resolveRun(rest); + if (!resolved) { // Distinguish "exists but not hostable" from "unknown" + const segments = rest.split('/'); for (let i = 1; i <= segments.length; i++) { if (getScenario(segments.slice(0, i).join('/'))) { res.status(501).json({ - error: `scenario '${segments.slice(0, i).join('/')}' is not hostable (no handler())` + error: `scenario '${segments.slice(0, i).join('/')}' is not hostable here` }); return; } @@ -122,9 +173,7 @@ export function createHostedApp(opts: HostedServerOptions = {}): { res.status(404).json({ error: `unknown scenario '${segments[0]}'` }); return; } - - const runId = segments[nameLen]; - const suffix = '/' + segments.slice(nameLen + 1).join('/'); + const { scenarioName, runId, suffix } = resolved; // GET /s/ with no run-id → mint one and tell the caller where // to point their client. @@ -171,19 +220,108 @@ export function createHostedApp(opts: HostedServerOptions = {}): { throw e; } - // Advertise where results live so a client can discover them without - // out-of-band knowledge of the URL scheme. - res.setHeader( - 'link', - `<${origin(req)}/results/${run.id}>; rel="conformance-results"` - ); - // Rewrite to the path the scenario expects (it thinks it's at root). // The query string is preserved because we keep the express req object. - req.url = suffix === '/' ? run.mcpPath || '/' : suffix; - run.listener(req, res); + dispatch( + run, + run.listener, + req, + res, + suffix === '/' ? run.mcpPath || '/' : suffix + ); + }); + + // ---------- root well-known dispatch (RS side) ---------- + // + // RFC 9728: a client given MCP URL /s///mcp derives the PRM + // URL as /.well-known/oauth-protected-resource/s///mcp — + // i.e. at the *origin root*, not under the run prefix. We catch that here, + // recover (scenario, run-id) from the path suffix, and re-dispatch to the + // run's RS handler with the path it would have seen on its own origin. + // + // Requests that arrive *under* the run prefix (because the WWW-Authenticate + // header points there) already work via the /s/* mount above. + + app.get(/^\/\.well-known\/oauth-protected-resource\/s\/(.+)$/, (req, res) => { + const resolved = resolveRun(req.params[0]); + if (!resolved?.runId || !RUN_ID_RE.test(resolved.runId)) { + res.status(404).json({ error: 'no run for this resource path' }); + return; + } + const run = sessions.get(resolved.runId); + if (!run) { + res.status(404).json({ error: 'no run for this resource path' }); + return; + } + // Scenario expects e.g. '/.well-known/oauth-protected-resource/mcp' + const rewritten = + '/.well-known/oauth-protected-resource' + + (resolved.suffix === '/' ? '' : resolved.suffix); + dispatch(run, run.listener, req, res, rewritten); }); + // ---------- aux-origin backchannel (relay target) ---------- + // + // The AS relay (examples/hosted/valtown-relay.ts) forwards every request it + // receives to /__aux/. The per-run AS issuer is + // /r/, so every path the client hits — endpoints + // (/r//authorize) and RFC 8414 well-known + // (/.well-known/oauth-authorization-server/r/[/tenant]) — carries + // `/r/` somewhere in it. We extract the id, strip that segment, and + // dispatch to the run's aux handler so it sees exactly the path + // createAuthServer registered. + // + // Guarded by a shared secret so this internal mount can't be hit directly + // to forge checks into someone else's run. + + if (haveAux.length) { + const secret = opts.relaySecret ?? process.env.CONFORMANCE_RELAY_SECRET; + const guard = (req: Request, res: Response): boolean => { + const got = req.header('x-relay-secret') ?? ''; + // Constant-time compare; mismatch length → fast 403 is fine. + const ok = + !!secret && + got.length === secret.length && + timingSafeEqual(Buffer.from(got), Buffer.from(secret)); + if (!ok) { + res + .status(403) + .json({ error: 'forbidden: /__aux is the relay backchannel' }); + } + return ok; + }; + + app.all(/^\/__aux\/([a-z0-9]+)(\/.*)$/, (req, res) => { + if (!guard(req, res)) return; + const role = req.params[0] as AuxOriginRole; + const path = req.params[1]; + if (!AUX_ROLES.includes(role)) { + res.status(404).json({ error: `unknown aux role '${role}'` }); + return; + } + + // Find /r/ anywhere in the path and excise it. + const m = path.match(/^(.*?)\/r\/([A-Za-z0-9_-]{1,64})(\/.*)?$/); + if (!m) { + res + .status(404) + .json({ error: 'aux request path missing /r/ segment' }); + return; + } + const [, prefix, runId, suffix = ''] = m; + const run = sessions.get(runId); + const listener = run?.auxListeners?.[role]; + if (!run || !listener) { + res.status(404).json({ error: `no aux '${role}' handler for run` }); + return; + } + const search = req.url.includes('?') + ? req.url.slice(req.url.indexOf('?')) + : ''; + dispatch(run, listener, req, res, (prefix + suffix || '/') + search); + }); + } + // ---------- results ---------- app.get('/results/:id.html', (req, res) => { diff --git a/src/hosted/session.ts b/src/hosted/session.ts index c1d4586d..306d5b23 100644 --- a/src/hosted/session.ts +++ b/src/hosted/session.ts @@ -9,15 +9,23 @@ */ import { randomBytes } from 'crypto'; -import { Scenario, ConformanceCheck, RequestListener } from '../types'; +import { + Scenario, + ConformanceCheck, + RequestListener, + AuthHandlerScenario, + AuxOriginRole +} from '../types'; import { getScenario, scenarios } from '../scenarios'; export interface HostedRun { id: string; scenarioName: string; scenario: Scenario; - /** The mounted handler — invoke directly with (req, res). */ + /** The mounted RS handler — invoke directly with (req, res). */ listener: RequestListener; + /** Aux-origin handlers (AS, IdP, …) for auth scenarios. */ + auxListeners?: Partial>; /** Sub-path under the run prefix where the MCP endpoint lives. */ mcpPath: string; createdAt: number; @@ -29,15 +37,23 @@ export interface SessionManagerOptions { /** Idle ms after which a run is reaped. Default 5 minutes. */ ttlMs?: number; sweepIntervalMs?: number; + /** + * Public origins of the relay deployments, keyed by role. Required for any + * scenario that exposes `authHandlers()`. Each value is the relay's public + * URL (no trailing slash); per-run AS issuer becomes `/r/`. + */ + auxOrigins?: Partial>; } export class SessionManager { private runs = new Map(); private readonly ttlMs: number; + private readonly auxOrigins: Partial>; private sweeper: ReturnType; constructor(opts: SessionManagerOptions = {}) { this.ttlMs = opts.ttlMs ?? 5 * 60_000; + this.auxOrigins = opts.auxOrigins ?? {}; const sweepIntervalMs = opts.sweepIntervalMs ?? 30_000; this.sweeper = setInterval(() => this.sweep(), sweepIntervalMs); this.sweeper.unref?.(); @@ -64,21 +80,53 @@ export class SessionManager { const proto = getScenario(scenarioName); if (!proto) throw new UnknownScenarioError(scenarioName); - if (!proto.handler) throw new NotHostableError(scenarioName); const Ctor = proto.constructor as new () => Scenario; const scenario = new Ctor(); const runId = id ?? randomBytes(6).toString('base64url'); - const listener = scenario.handler!(() => baseUrlFor(runId)); + + let listener: RequestListener; + let auxListeners: HostedRun['auxListeners']; + let context: Record | undefined; + + if (scenario instanceof AuthHandlerScenario) { + // Multi-origin scenario: build RS + aux handlers from authHandlers(). + // Aux issuer is /r/ so the run-id is recoverable + // from any RFC 8414 well-known path the client constructs from it. + const missing = scenario.auxRoles.filter((r) => !this.auxOrigins[r]); + if (missing.length) { + throw new NotHostableError( + scenarioName, + `needs aux origin(s) [${missing.join(', ')}] — start with --as-origin` + ); + } + const handlers = scenario.authHandlers({ + getRsBaseUrl: () => baseUrlFor(runId), + getAuxBaseUrl: (role) => `${this.auxOrigins[role]}/r/${runId}` + }); + listener = handlers.rs; + auxListeners = handlers.aux; + context = ( + scenario as unknown as { + scenarioContext?: () => Record; + } + ).scenarioContext?.(); + } else if (scenario.handler) { + listener = scenario.handler(() => baseUrlFor(runId)); + } else { + throw new NotHostableError(scenarioName); + } const run: HostedRun = { id: runId, scenarioName, scenario, listener, + auxListeners, mcpPath: scenario.mcpPath ?? '', createdAt: Date.now(), - lastSeenAt: Date.now() + lastSeenAt: Date.now(), + context }; this.runs.set(runId, run); return run; @@ -135,17 +183,28 @@ export class UnknownScenarioError extends Error { } export class NotHostableError extends Error { - constructor(name: string) { + constructor(name: string, why?: string) { super( - `Scenario '${name}' does not implement handler() and cannot run hosted ` + - `(typically auth scenarios that need a second origin).` + `Scenario '${name}' cannot run hosted` + + (why + ? `: ${why}` + : ` (no handler() or authHandlers() — typically backcompat scenarios that need root-of-origin endpoints).`) ); } } -/** Scenarios that expose handler() and so can run without a loopback port. */ -export function listHostableScenarios(): string[] { +/** Scenarios that can run hosted, partitioned by what they need. */ +export function listHostableScenarios( + withAuxOrigins: readonly AuxOriginRole[] = [] +): string[] { + const have = new Set(withAuxOrigins); return Array.from(scenarios.entries()) - .filter(([, s]) => typeof s.handler === 'function') + .filter(([, s]) => { + if (typeof s.handler === 'function') return true; + if (s instanceof AuthHandlerScenario) { + return s.auxRoles.every((r) => have.has(r)); + } + return false; + }) .map(([name]) => name); } diff --git a/src/index.ts b/src/index.ts index 3eb75177..66ba985b 100644 --- a/src/index.ts +++ b/src/index.ts @@ -562,8 +562,10 @@ program.addCommand(createTraceabilityCommand()); program .command('hosted') .description( - 'Run a long-lived HTTP server that exposes every (non-auth) client ' + - 'scenario at /s/ and serves results at /results/.' + 'Run a long-lived HTTP server that exposes every client scenario at ' + + '/s/ and serves results at /results/. With ' + + '--as-origin, auth/* scenarios are also mounted; deploy ' + + 'examples/hosted/valtown-relay.ts at that origin.' ) .option('--port ', 'Port to listen on', '3000') .option( @@ -571,11 +573,28 @@ program 'Origin to use in generated links (default: derived from Host header)' ) .option('--ttl ', 'Idle session TTL in milliseconds', '300000') + .option( + '--as-origin ', + 'Public origin of the AS relay (enables auth/* scenarios)' + ) + .option('--as2-origin ', 'Second AS relay (for migration scenario)') + .option('--idp-origin ', 'IdP relay (for EMA scenario)') + .option( + '--relay-secret ', + 'Shared secret the relay sends in x-relay-secret. Required with --as-origin. ' + + 'Defaults to $CONFORMANCE_RELAY_SECRET.' + ) .action(async (options) => { await runHostedServer({ port: parseInt(options.port, 10), publicOrigin: options.publicOrigin, - ttlMs: parseInt(options.ttl, 10) + ttlMs: parseInt(options.ttl, 10), + auxOrigins: { + as: options.asOrigin, + as2: options.as2Origin, + idp: options.idpOrigin + }, + relaySecret: options.relaySecret ?? process.env.CONFORMANCE_RELAY_SECRET }); }); diff --git a/src/scenarios/client/auth/basic-cimd.ts b/src/scenarios/client/auth/basic-cimd.ts index a99b4e35..c91796f2 100644 --- a/src/scenarios/client/auth/basic-cimd.ts +++ b/src/scenarios/client/auth/basic-cimd.ts @@ -1,8 +1,11 @@ -import type { Scenario, ConformanceCheck } from '../../../types'; -import { ScenarioUrls } from '../../../types'; +import { + AuthHandlerScenario, + AuthHandlerContext, + AuthHandlers, + ConformanceCheck +} from '../../../types'; import { createAuthServer } from './helpers/createAuthServer'; import { createServer } from './helpers/createServer'; -import { ServerLifecycle } from './helpers/serverLifecycle'; import { SpecReferences } from './spec-references'; /** @@ -20,19 +23,18 @@ export const CIMD_CLIENT_METADATA_URL = * clients SHOULD use a URL as their client_id instead of using dynamic client * registration. */ -export class AuthBasicCIMDScenario implements Scenario { +export class AuthBasicCIMDScenario extends AuthHandlerScenario { name = 'auth/basic-cimd'; readonly source = { introducedIn: '2025-11-25' } as const; description = 'Tests OAuth flow with Client ID Metadata Documents (SEP-991/URL-based client IDs). Server advertises client_id_metadata_document_supported=true and client should use URL as client_id instead of DCR.'; - private authServer = new ServerLifecycle(); - private server = new ServerLifecycle(); private checks: ConformanceCheck[] = []; - async start(): Promise { + authHandlers(ctx: AuthHandlerContext): AuthHandlers { this.checks = []; + const getAsUrl = () => ctx.getAuxBaseUrl('as'); - const authApp = createAuthServer(this.checks, this.authServer.getUrl, { + const authApp = createAuthServer(this.checks, getAsUrl, { clientIdMetadataDocumentSupported: true, onAuthorizationRequest: (data) => { // Check if client used URL-based client ID @@ -57,22 +59,9 @@ export class AuthBasicCIMDScenario implements Scenario { } }); - await this.authServer.start(authApp); + const rsApp = createServer(this.checks, ctx.getRsBaseUrl, getAsUrl); - const app = createServer( - this.checks, - this.server.getUrl, - this.authServer.getUrl - ); - - await this.server.start(app); - - return { serverUrl: `${this.server.getUrl()}/mcp` }; - } - - async stop() { - await this.authServer.stop(); - await this.server.stop(); + return { rs: rsApp, aux: { as: authApp } }; } getChecks(): ConformanceCheck[] { diff --git a/src/scenarios/client/auth/discovery-metadata.ts b/src/scenarios/client/auth/discovery-metadata.ts index 7387ead4..eb916260 100644 --- a/src/scenarios/client/auth/discovery-metadata.ts +++ b/src/scenarios/client/auth/discovery-metadata.ts @@ -6,11 +6,14 @@ * generated from them. */ -import type { Scenario, ConformanceCheck } from '../../../types'; -import { ScenarioUrls } from '../../../types'; +import { + AuthHandlerScenario, + AuthHandlerContext, + AuthHandlers, + ConformanceCheck +} from '../../../types'; import { createAuthServer } from './helpers/createAuthServer'; import { createServer } from './helpers/createServer'; -import { ServerLifecycle } from './helpers/serverLifecycle'; import { SpecReferences } from './spec-references'; import { Request, Response } from 'express'; @@ -69,155 +72,157 @@ const SCENARIO_CONFIGS: MetadataScenarioConfig[] = [ ]; /** - * Creates a metadata discovery scenario from configuration. + * Base for the table-driven discovery scenarios. Each subclass binds a row + * of SCENARIO_CONFIGS; we use real classes (not factory-returned literals) + * so the hosted runner can do `new Ctor()` for a fresh instance per run. */ -function createMetadataScenario(config: MetadataScenarioConfig): Scenario { - const authServer = new ServerLifecycle(); - const server = new ServerLifecycle(); - let checks: ConformanceCheck[] = []; - - const routePrefix = config.authRoutePrefix || ''; - const isOpenIdConfiguration = config.oauthMetadataLocation.includes( - 'openid-configuration' - ); - - // Determine if PRM is at path-based location - const isPathBasedPrm = - config.prmLocation === '/.well-known/oauth-protected-resource/mcp'; - - return { - name: `auth/${config.name}`, - source: { introducedIn: '2025-11-25' }, - description: `Tests Basic OAuth metadata discovery flow. - -**PRM:** ${config.prmLocation}${config.inWwwAuth ? '' : ' (not in WWW-Authenticate)'} -**OAuth metadata:** ${config.oauthMetadataLocation} -`, - - async start(): Promise { - checks = []; - - const authApp = createAuthServer(checks, authServer.getUrl, { - metadataPath: config.oauthMetadataLocation, - isOpenIdConfiguration, - ...(routePrefix && { routePrefix }) +abstract class MetadataDiscoveryScenario extends AuthHandlerScenario { + protected abstract readonly config: MetadataScenarioConfig; + readonly source = { introducedIn: '2025-11-25' } as const; + private checks: ConformanceCheck[] = []; + + get name() { + return `auth/${this.config.name}`; + } + get description() { + return `Tests Basic OAuth metadata discovery flow. + +**PRM:** ${this.config.prmLocation}${this.config.inWwwAuth ? '' : ' (not in WWW-Authenticate)'} +**OAuth metadata:** ${this.config.oauthMetadataLocation} +`; + } + + authHandlers(ctx: AuthHandlerContext): AuthHandlers { + this.checks = []; + const config = this.config; + const routePrefix = config.authRoutePrefix || ''; + const isOpenIdConfiguration = config.oauthMetadataLocation.includes( + 'openid-configuration' + ); + const getAsUrl = () => ctx.getAuxBaseUrl('as'); + + const authApp = createAuthServer(this.checks, getAsUrl, { + metadataPath: config.oauthMetadataLocation, + isOpenIdConfiguration, + ...(routePrefix && { routePrefix }) + }); + + // If path-based OAuth metadata, trap root requests + if (routePrefix) { + authApp.get('/.well-known/oauth-authorization-server', (req, res) => { + this.checks.push({ + id: 'authorization-server-metadata-wrong-path', + name: 'AuthorizationServerMetadataWrongPath', + description: + 'Client requested authorization server at the root path when the AS URL has a path-based location', + status: 'FAILURE', + timestamp: new Date().toISOString(), + specReferences: [ + SpecReferences.RFC_AUTH_SERVER_METADATA_REQUEST, + SpecReferences.MCP_AUTH_DISCOVERY + ], + details: { + url: req.url + } + }); + res.status(404).send('Not Found'); }); + } - // If path-based OAuth metadata, trap root requests - if (routePrefix) { - authApp.get('/.well-known/oauth-authorization-server', (req, res) => { - checks.push({ - id: 'authorization-server-metadata-wrong-path', - name: 'AuthorizationServerMetadataWrongPath', + const getAuthServerUrl = routePrefix + ? () => `${getAsUrl()}${routePrefix}` + : getAsUrl; + + const rsApp = createServer( + this.checks, + ctx.getRsBaseUrl, + getAuthServerUrl, + { + prmPath: config.prmLocation, + includePrmInWwwAuth: config.inWwwAuth + } + ); + + // Add trap for root PRM requests if configured + if (config.trapRootPrm) { + rsApp.get( + '/.well-known/oauth-protected-resource', + (req: Request, res: Response) => { + this.checks.push({ + id: 'prm-priority-order', + name: 'PRM Priority Order', description: - 'Client requested authorization server at the root path when the AS URL has a path-based location', + 'Client requested PRM metadata at root location on a server with path-based PRM', status: 'FAILURE', timestamp: new Date().toISOString(), specReferences: [ - SpecReferences.RFC_AUTH_SERVER_METADATA_REQUEST, - SpecReferences.MCP_AUTH_DISCOVERY + SpecReferences.RFC_PRM_DISCOVERY, + SpecReferences.MCP_PRM_DISCOVERY ], details: { - url: req.url + url: req.url, + path: req.path } }); - res.status(404).send('Not Found'); - }); - } - - await authServer.start(authApp); - const getAuthServerUrl = routePrefix - ? () => `${authServer.getUrl()}${routePrefix}` - : authServer.getUrl; - - const app = createServer(checks, server.getUrl, getAuthServerUrl, { - prmPath: config.prmLocation, - includePrmInWwwAuth: config.inWwwAuth - }); - - // Add trap for root PRM requests if configured - if (config.trapRootPrm) { - app.get( - '/.well-known/oauth-protected-resource', - (req: Request, res: Response) => { - checks.push({ - id: 'prm-priority-order', - name: 'PRM Priority Order', - description: - 'Client requested PRM metadata at root location on a server with path-based PRM', - status: 'FAILURE', - timestamp: new Date().toISOString(), - specReferences: [ - SpecReferences.RFC_PRM_DISCOVERY, - SpecReferences.MCP_PRM_DISCOVERY - ], - details: { - url: req.url, - path: req.path - } - }); - - res.status(404).json({ - error: 'not_found', - error_description: 'PRM metadata not available at root location' - }); - } - ); - } - - await server.start(app); - - return { serverUrl: `${server.getUrl()}/mcp` }; - }, - - async stop() { - await authServer.stop(); - await server.stop(); - }, - - getChecks(): ConformanceCheck[] { - const expectedSlugs = [ - ...(isPathBasedPrm ? ['prm-pathbased-requested'] : []), - 'authorization-server-metadata', - 'client-registration', - 'authorization-request', - 'token-request' - ]; - - for (const slug of expectedSlugs) { - if (!checks.find((c) => c.id === slug)) { - checks.push({ - id: slug, - name: `Expected Check Missing: ${slug}`, - description: `Expected Check Missing: ${slug}`, - status: 'FAILURE', - timestamp: new Date().toISOString() + res.status(404).json({ + error: 'not_found', + error_description: 'PRM metadata not available at root location' }); } - } + ); + } + + return { rs: rsApp, aux: { as: authApp } }; + } - return checks; + getChecks(): ConformanceCheck[] { + const isPathBasedPrm = + this.config.prmLocation === '/.well-known/oauth-protected-resource/mcp'; + const expectedSlugs = [ + ...(isPathBasedPrm ? ['prm-pathbased-requested'] : []), + 'authorization-server-metadata', + 'client-registration', + 'authorization-request', + 'token-request' + ]; + + for (const slug of expectedSlugs) { + if (!this.checks.find((c) => c.id === slug)) { + this.checks.push({ + id: slug, + name: `Expected Check Missing: ${slug}`, + description: `Expected Check Missing: ${slug}`, + status: 'FAILURE', + timestamp: new Date().toISOString() + }); + } } - }; + + return this.checks; + } } -// Generate scenario instances from configurations -export const AuthMetadataDefaultScenario = createMetadataScenario( - SCENARIO_CONFIGS[0] -); -export const AuthMetadataVar1Scenario = createMetadataScenario( - SCENARIO_CONFIGS[1] -); -export const AuthMetadataVar2Scenario = createMetadataScenario( - SCENARIO_CONFIGS[2] -); -export const AuthMetadataVar3Scenario = createMetadataScenario( - SCENARIO_CONFIGS[3] -); +export class AuthMetadataDefaultScenario extends MetadataDiscoveryScenario { + protected readonly config = SCENARIO_CONFIGS[0]; +} +export class AuthMetadataVar1Scenario extends MetadataDiscoveryScenario { + protected readonly config = SCENARIO_CONFIGS[1]; +} +export class AuthMetadataVar2Scenario extends MetadataDiscoveryScenario { + protected readonly config = SCENARIO_CONFIGS[2]; +} +export class AuthMetadataVar3Scenario extends MetadataDiscoveryScenario { + protected readonly config = SCENARIO_CONFIGS[3]; +} // Export all scenarios as an array for convenience -export const metadataScenarios = SCENARIO_CONFIGS.map(createMetadataScenario); +export const metadataScenarios = [ + new AuthMetadataDefaultScenario(), + new AuthMetadataVar1Scenario(), + new AuthMetadataVar2Scenario(), + new AuthMetadataVar3Scenario() +]; // Export function to list metadata scenario names (for suite support) export function listMetadataScenarios(): string[] { diff --git a/src/scenarios/client/auth/pre-registration.ts b/src/scenarios/client/auth/pre-registration.ts index b482e4f3..7bd573c6 100644 --- a/src/scenarios/client/auth/pre-registration.ts +++ b/src/scenarios/client/auth/pre-registration.ts @@ -1,7 +1,11 @@ -import type { Scenario, ConformanceCheck, ScenarioUrls } from '../../../types'; +import { + AuthHandlerScenario, + AuthHandlerContext, + AuthHandlers, + ConformanceCheck +} from '../../../types'; import { createAuthServer } from './helpers/createAuthServer'; import { createServer } from './helpers/createServer'; -import { ServerLifecycle } from './helpers/serverLifecycle'; import { SpecReferences } from './spec-references'; import { MockTokenVerifier } from './helpers/mockTokenVerifier'; @@ -17,21 +21,20 @@ const PRE_REGISTERED_CLIENT_SECRET = 'pre-registered-secret'; * This tests the pre-registration approach described in the MCP spec: * https://modelcontextprotocol.io/specification/draft/basic/authorization#preregistration */ -export class PreRegistrationScenario implements Scenario { +export class PreRegistrationScenario extends AuthHandlerScenario { name = 'auth/pre-registration'; readonly source = { introducedIn: '2025-11-25' } as const; description = 'Tests OAuth flow with pre-registered client credentials. Server does not support DCR.'; - private authServer = new ServerLifecycle(); - private server = new ServerLifecycle(); private checks: ConformanceCheck[] = []; - async start(): Promise { + authHandlers(ctx: AuthHandlerContext): AuthHandlers { this.checks = []; + const getAsUrl = () => ctx.getAuxBaseUrl('as'); const tokenVerifier = new MockTokenVerifier(this.checks, []); - const authApp = createAuthServer(this.checks, this.authServer.getUrl, { + const authApp = createAuthServer(this.checks, getAsUrl, { tokenVerifier, disableDynamicRegistration: true, tokenEndpointAuthMethodsSupported: ['client_secret_basic'], @@ -102,35 +105,22 @@ export class PreRegistrationScenario implements Scenario { } }); - await this.authServer.start(authApp); - - const app = createServer( - this.checks, - this.server.getUrl, - this.authServer.getUrl, - { - prmPath: '/.well-known/oauth-protected-resource/mcp', - requiredScopes: [], - tokenVerifier - } - ); + const rsApp = createServer(this.checks, ctx.getRsBaseUrl, getAsUrl, { + prmPath: '/.well-known/oauth-protected-resource/mcp', + requiredScopes: [], + tokenVerifier + }); - await this.server.start(app); + return { rs: rsApp, aux: { as: authApp } }; + } + protected scenarioContext() { return { - serverUrl: `${this.server.getUrl()}/mcp`, - context: { - client_id: PRE_REGISTERED_CLIENT_ID, - client_secret: PRE_REGISTERED_CLIENT_SECRET - } + client_id: PRE_REGISTERED_CLIENT_ID, + client_secret: PRE_REGISTERED_CLIENT_SECRET }; } - async stop() { - await this.authServer.stop(); - await this.server.stop(); - } - getChecks(): ConformanceCheck[] { // Ensure we have the pre-registration check const hasPreRegCheck = this.checks.some( diff --git a/src/types.ts b/src/types.ts index f467733a..e4aa9c6b 100644 --- a/src/types.ts +++ b/src/types.ts @@ -177,6 +177,114 @@ export abstract class HandlerScenario implements Scenario { } } +/** + * Named extra origins a multi-origin scenario needs beyond the resource + * server. `as` is the OAuth authorization server; `as2`/`idp` cover the + * three-origin scenarios (authorization-server-migration, EMA). + */ +export type AuxOriginRole = 'as' | 'as2' | 'idp'; + +export interface AuthHandlerContext { + /** Public URL of the resource-server mount (no trailing slash). */ + getRsBaseUrl: () => string; + /** + * Public URL of an aux origin for this run (no trailing slash). When + * hosted, this is `/r/` so the run-id is recoverable + * from any path the client constructs from it (RFC 8414 well-known + * insertion, endpoint paths, etc.). + */ + getAuxBaseUrl: (role: AuxOriginRole) => string; +} + +export interface AuthHandlers { + /** Resource-server handler — serves /mcp and PRM. */ + rs: RequestListener; + /** Aux-origin handlers keyed by role. */ + aux: Partial>; +} + +/** + * Convenience: implement `authHandlers()` and get `start()`/`stop()` for + * free. `start()` binds one ephemeral localhost port per origin, exactly as + * the auth scenarios did with `ServerLifecycle` before; the hosted runner + * mounts the same handlers behind path prefixes + an AS relay instead. + */ +export abstract class AuthHandlerScenario implements Scenario { + abstract name: string; + abstract description: string; + abstract readonly source: ScenarioSource; + allowClientError?: boolean; + mcpPath = '/mcp'; + + /** Aux origins this scenario needs. Override for 3-origin scenarios. */ + readonly auxRoles: readonly AuxOriginRole[] = ['as']; + + private _servers: import('http').Server[] = []; + private _urls: { rs: string; aux: Partial> } = { + rs: '', + aux: {} + }; + + abstract authHandlers(ctx: AuthHandlerContext): AuthHandlers; + abstract getChecks(): ConformanceCheck[]; + + /** Optional context to pass to the client (credentials etc). */ + protected scenarioContext?(): Record; + + async start(): Promise { + const http = await import('http'); + const handlers = this.authHandlers({ + getRsBaseUrl: () => this._urls.rs, + getAuxBaseUrl: (role) => { + const u = this._urls.aux[role]; + if (!u) throw new Error(`aux role '${role}' not started`); + return u; + } + }); + + const listen = (h: RequestListener): Promise => + new Promise((resolve, reject) => { + const srv = http.createServer(h); + srv.on('error', reject); + srv.listen(0, () => { + const addr = srv.address(); + if (!addr || typeof addr !== 'object') { + return reject(new Error('Failed to get server address')); + } + this._servers.push(srv); + resolve(`http://localhost:${addr.port}`); + }); + }); + + // Aux origins must come up first — RS handlers reference their URLs. + for (const role of this.auxRoles) { + const h = handlers.aux[role]; + if (!h) throw new Error(`authHandlers() missing aux role '${role}'`); + this._urls.aux[role] = await listen(h); + } + this._urls.rs = await listen(handlers.rs); + + return { + serverUrl: `${this._urls.rs}${this.mcpPath}`, + ...(this.scenarioContext && { context: this.scenarioContext() }) + }; + } + + async stop(): Promise { + await Promise.all( + this._servers.map( + (s) => + new Promise((resolve) => { + s.closeAllConnections?.(); + s.close(() => resolve()); + }) + ) + ); + this._servers = []; + this._urls = { rs: '', aux: {} }; + } +} + export interface ClientScenario { name: string; description: string; From 071ce4e9ecda2171a3e59354c07647d360e78e81 Mon Sep 17 00:00:00 2001 From: Paul Carleton Date: Thu, 25 Jun 2026 14:08:46 +0100 Subject: [PATCH 4/9] experimental: stateless 2026-07-28 conformance checker + auth-chain checker MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Hosted MCP checker for the stateless draft protocol (2026-07-28): - src/scenarios/client/stateless-gauntlet.ts — single stateless server whose tools each validate one aspect of the request that carried it. Transport obligations (Accept, Content-Type, MCP-Protocol-Version, Mcp-Method/Mcp-Name, io.modelcontextprotocol/* _meta) checked on every POST. Results carry the required resultType, and discover/list carry ttlMs/cacheScope. - src/scenarios/client/auth-checker.ts — auth-chain checker scenario. - examples/hosted/valtown-checker.ts + valtown-auth-checker.ts — val.town entrypoints; each val IS the checker (origin-rooted, no /x/ path). - examples/hosted/deploy-valtown.ts — stages the import closure with Deno-style specifiers and pushes via the val.town v2 API. - examples/hosted/fetch-bridge.ts — adapts express RequestListener → fetch handler for serverless runtimes. - src/scenarios/client/auth/helpers/createAuthServer.ts — encode PKCE challenge + scopes into the auth code itself so the mock AS is stateless across serverless isolates. Builds on paulc/hosted-auth (second-origin relay) and paulc/hosted-server. --- .gitignore | 4 + .../clients/typescript/everything-client.ts | 233 ++++ examples/hosted/deploy-valtown.ts | 367 +++++ examples/hosted/fetch-bridge.ts | 104 ++ examples/hosted/local-relay.ts | 36 + examples/hosted/valtown-auth-checker.ts | 18 + examples/hosted/valtown-checker.ts | 29 + examples/hosted/valtown-manifest.json | 28 + examples/hosted/valtown.ts | 81 +- src/hosted/server.ts | 361 ++++- src/scenarios/client/auth-checker.ts | 571 ++++++++ .../client/auth/discovery-metadata.ts | 4 + .../client/auth/helpers/createAuthServer.ts | 58 +- src/scenarios/client/stateless-gauntlet.ts | 1200 +++++++++++++++++ src/scenarios/index.ts | 10 +- src/types.ts | 8 + 16 files changed, 3021 insertions(+), 91 deletions(-) create mode 100644 examples/hosted/deploy-valtown.ts create mode 100644 examples/hosted/fetch-bridge.ts create mode 100644 examples/hosted/local-relay.ts create mode 100644 examples/hosted/valtown-auth-checker.ts create mode 100644 examples/hosted/valtown-checker.ts create mode 100644 examples/hosted/valtown-manifest.json create mode 100644 src/scenarios/client/auth-checker.ts create mode 100644 src/scenarios/client/stateless-gauntlet.ts diff --git a/.gitignore b/.gitignore index 2fdd7d0a..89b4c6c9 100644 --- a/.gitignore +++ b/.gitignore @@ -5,4 +5,8 @@ dist/ .vscode/ .idea/ .claude/settings.local.json +.claude/worktrees .sdk-under-test/ +.valtown-stage/ +.serve-*.ts +.env diff --git a/examples/clients/typescript/everything-client.ts b/examples/clients/typescript/everything-client.ts index 63ca051b..0854a4f5 100644 --- a/examples/clients/typescript/everything-client.ts +++ b/examples/clients/typescript/everything-client.ts @@ -99,6 +99,239 @@ registerScenarios(['initialize', 'tools-call'], runBasicClient); // correct behavior here. registerScenario('json-schema-ref-no-deref', runBasicClient); +// ============================================================================ +// Stateless gauntlet — a hand-rolled DRAFT (SEP-2575) client. No initialize, +// no session: every request carries the protocol version, client identity, +// and capabilities itself, plus the Mcp-Method/Mcp-Name routing headers +// (SEP-2243). MRTR (SEP-2322) retries echo requestState unchanged. +// The server judges each request on its own content; any isError result or +// HTTP error carries an explanation of what the client got wrong. +// ============================================================================ + +const DRAFT_VERSION = '2026-07-28'; +const DRAFT_META = { + 'io.modelcontextprotocol/protocolVersion': DRAFT_VERSION, + 'io.modelcontextprotocol/clientInfo': { + name: 'everything-client', + version: '1.0.0' + }, + 'io.modelcontextprotocol/clientCapabilities': { elicitation: {} } +}; + +async function draftRpc( + serverUrl: string, + method: string, + params: Record = {} +): Promise> { + const headers: Record = { + 'content-type': 'application/json', + accept: 'application/json, text/event-stream', + 'mcp-protocol-version': DRAFT_VERSION, + 'mcp-method': method + }; + if (method === 'tools/call' && typeof params.name === 'string') { + headers['mcp-name'] = params.name; + } + const res = await fetch(serverUrl, { + method: 'POST', + headers, + body: JSON.stringify({ + jsonrpc: '2.0', + id: 1, + method, + params: { ...params, _meta: DRAFT_META } + }) + }); + if (!res.ok) { + throw new Error(`${method}: HTTP ${res.status}: ${await res.text()}`); + } + const json = (await res.json()) as { + result?: Record; + error?: { code: number; message: string }; + }; + if (json.error) { + throw new Error( + `${method}: JSON-RPC ${json.error.code}: ${json.error.message}` + ); + } + return json.result ?? {}; +} + +const GAUNTLET_ARGS: Record> = { + validate_arguments: { + message: 'hello from everything-client', + count: 42, + payload: { kind: 'solid' } + }, + mrtr_confirm: {}, + // Listed only when a client does NOT declare elicitation; harmless to call. + elicitation_missing: {} +}; + +/** Answer an input_required result: accept every elicitation request. */ +function answerInputRequests( + inputRequests: Record +): Record { + return Object.fromEntries( + Object.entries(inputRequests).map(([key, request]) => { + if (request.method !== 'elicitation/create') { + throw new Error( + `unsupported input request method '${request.method}'` + ); + } + return [key, { action: 'accept', content: { confirmed: true } }]; + }) + ); +} + +async function runGauntletClient(serverUrl: string): Promise { + const discover = await draftRpc(serverUrl, 'server/discover'); + logger.debug( + `server/discover: supportedVersions=${JSON.stringify(discover.supportedVersions)}` + ); + + const { tools } = (await draftRpc(serverUrl, 'tools/list')) as { + tools: { name: string }[]; + }; + logger.debug(`Gauntlet lists ${tools.length} tools`); + + const failures: string[] = []; + for (const tool of tools) { + const args = GAUNTLET_ARGS[tool.name]; + if (!args) { + failures.push(`no argument template for tool '${tool.name}'`); + continue; + } + let result = await draftRpc(serverUrl, 'tools/call', { + name: tool.name, + arguments: args + }); + // MRTR: answer the input requests and retry with the state echoed. + if (result.resultType === 'input_required') { + result = await draftRpc(serverUrl, 'tools/call', { + name: tool.name, + inputResponses: answerInputRequests( + result.inputRequests as Record + ), + ...(result.requestState !== undefined + ? { requestState: result.requestState } + : {}) + }); + } + const content = result.content as + | { type: string; text?: string }[] + | undefined; + const text = content?.[0]?.text ?? JSON.stringify(result); + if (result.isError) { + failures.push(`${tool.name}: ${text}`); + } else { + logger.debug(`${tool.name}: ${text}`); + } + } + + if (failures.length > 0) { + throw new Error(`gauntlet failures:\n ${failures.join('\n ')}`); + } +} + +registerScenario('checker-2026-07-28', runGauntletClient); + +// ============================================================================ +// Auth-chain checker — walk the re-auth rungs in order. Each advance tool +// answers with an OAuth challenge (401 with a different resource_metadata, +// then 403 insufficient_scope); the SDK's withOAuthRetry should absorb each +// challenge, re-authorize under the new configuration, and retry. +// ============================================================================ + +async function runAuthChainClient(serverUrl: string): Promise { + const client = new Client( + { name: 'test-auth-client', version: '1.0.0' }, + { capabilities: {} } + ); + const oauthFetch = withOAuthRetry( + 'test-auth-client', + new URL(serverUrl), + handle401, + CIMD_CLIENT_METADATA_URL + )(fetch); + const transport = new StreamableHTTPClientTransport(new URL(serverUrl), { + fetch: oauthFetch + }); + await client.connect(transport); + + for (const name of [ + 'auth_status', + 'advance_to_scoped', + 'auth_status', + 'advance_to_stepup', + 'auth_complete' + ]) { + const result = await client.callTool({ name, arguments: {} }); + const text = + Array.isArray(result.content) && result.content[0]?.type === 'text' + ? result.content[0].text + : JSON.stringify(result.content); + logger.debug(`${name}: ${text}`); + if (result.isError) { + throw new Error(`${name} failed: ${text}`); + } + } + + await transport.close(); +} + +registerScenario('checker-auth', runAuthChainClient); + +// The iss trap probe: calling check_iss_validation forces a re-auth whose +// authorization response carries a WRONG iss. The expected outcome is a +// client-side refusal — the call must FAIL with an iss complaint, not +// complete. Completing means the client exchanged the code anyway and the +// server's poisoned-token explanation comes back instead. +async function runAuthIssTrapProbe(serverUrl: string): Promise { + const client = new Client( + { name: 'test-auth-client', version: '1.0.0' }, + { capabilities: {} } + ); + const oauthFetch = withOAuthRetry( + 'test-auth-client', + new URL(serverUrl), + handle401, + CIMD_CLIENT_METADATA_URL + )(fetch); + const transport = new StreamableHTTPClientTransport(new URL(serverUrl), { + fetch: oauthFetch + }); + await client.connect(transport); + + // Two ways to learn the verdict, depending on whether the client validates + // iss. PASS: the client aborts mid-OAuth (validates iss), so callTool + // rejects locally with an iss complaint and never reaches the server. + // FAIL: the client exchanges the wrong-iss code, so the call completes with + // an in-band isError tool result carrying the FAIL verdict. + try { + const result = await client.callTool({ + name: 'check_iss_validation', + arguments: {} + }); + const text = + Array.isArray(result.content) && result.content[0]?.type === 'text' + ? result.content[0].text + : JSON.stringify(result.content); + if (result.isError && text.includes('FAIL [check_iss_validation]')) { + throw new Error(`CAUGHT BY THE TRAP (client ignored iss): ${text}`); + } + throw new Error(`unexpected non-error result from the iss trap: ${text}`); + } catch (e) { + const msg = e instanceof Error ? e.message : String(e); + if (msg.includes('CAUGHT BY THE TRAP')) throw e; + logger.debug(`iss trap outcome — client-side refusal (PASS): ${msg}`); + } finally { + await transport.close().catch(() => {}); + } +} + +registerScenario('checker-auth-iss', runAuthIssTrapProbe); + // ============================================================================ // request-metadata scenario (SEP-2575) // ============================================================================ diff --git a/examples/hosted/deploy-valtown.ts b/examples/hosted/deploy-valtown.ts new file mode 100644 index 00000000..8832387b --- /dev/null +++ b/examples/hosted/deploy-valtown.ts @@ -0,0 +1,367 @@ +/** + * Deploy the hosted conformance server to val.town as readable source. + * + * val.town's runtime (Deno) needs import specifiers the repo's Node toolchain + * doesn't use: `npm:` prefixes for packages, `node:` prefixes for builtins, + * and explicit `.ts` extensions on relative imports. Rather than fork the + * source, this script stages a copy of the import closure of + * examples/hosted/valtown.ts with those specifiers rewritten, then uploads + * the files via the val.town v2 API (same approach as a plain + * "create val + upsert files" deploy script). + * + * Two vals are deployed: + * rs — the conformance resource server (entry: examples/hosted/valtown.ts) + * relay — the second-origin auth relay (entry: examples/hosted/valtown-relay.ts) + * + * Usage: + * npx tsx examples/hosted/deploy-valtown.ts # stage only (.valtown-stage/) + * npx tsx examples/hosted/deploy-valtown.ts --push # stage + upload both vals + * npx tsx examples/hosted/deploy-valtown.ts --push rs # upload a single val + * + * Token: VAL_TOWN_TOKEN env var (or a .env file next to this script / repo root). + * Val ids are persisted to examples/hosted/valtown-manifest.json on first push. + * + * After the first push, set env vars on the vals (val.town UI → val → Environment): + * rs val: CONFORMANCE_AS_ORIGIN=, CONFORMANCE_RELAY_SECRET= + * relay val: CONFORMANCE_RS_ORIGIN=, CONFORMANCE_RELAY_SECRET=, + * CONFORMANCE_RELAY_ROLE=as + */ + +import { + existsSync, + mkdirSync, + readFileSync, + rmSync, + statSync, + writeFileSync +} from 'node:fs'; +import { dirname, join, relative, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import ts from 'typescript'; + +const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url)); +const REPO_ROOT = resolve(SCRIPT_DIR, '../..'); +const STAGE_ROOT = join(REPO_ROOT, '.valtown-stage'); +const MANIFEST_PATH = join(SCRIPT_DIR, 'valtown-manifest.json'); +const API = 'https://api.val.town/v2'; + +const NODE_BUILTINS = new Set([ + 'assert', + 'async_hooks', + 'buffer', + 'child_process', + 'crypto', + 'dns', + 'events', + 'fs', + 'http', + 'https', + 'net', + 'os', + 'path', + 'process', + 'querystring', + 'stream', + 'string_decoder', + 'timers', + 'tls', + 'url', + 'util', + 'zlib' +]); + +interface ValInfo { + id?: string; + name: string; + entry: string; + privacy: 'public' | 'unlisted' | 'private'; +} +interface Manifest { + vals: Record; +} + +const pkg = JSON.parse(readFileSync(join(REPO_ROOT, 'package.json'), 'utf8')); +const versions: Record = { + ...pkg.devDependencies, + ...pkg.dependencies +}; + +// --------------------------------------------------------------------------- +// Specifier rewriting +// --------------------------------------------------------------------------- + +/** Resolve a relative specifier from `fromFile` to an existing repo file. */ +function resolveRelative(fromFile: string, spec: string): string { + const base = resolve(dirname(fromFile), spec); + const candidates = [ + base, + `${base}.ts`, + `${base}.tsx`, + base.replace(/\.js$/, '.ts'), + join(base, 'index.ts') + ]; + for (const c of candidates) { + if (existsSync(c) && statSync(c).isFile()) return c; + } + throw new Error( + `cannot resolve '${spec}' from ${relative(REPO_ROOT, fromFile)}` + ); +} + +/** Rewrite one specifier to a val.town/Deno-compatible form. */ +function rewriteSpec( + fromFile: string, + spec: string, + discovered: Set +): string { + if ( + spec.startsWith('node:') || + spec.startsWith('npm:') || + spec.startsWith('http://') || + spec.startsWith('https://') + ) { + return spec; + } + if (spec.startsWith('.')) { + const target = resolveRelative(fromFile, spec); + discovered.add(target); + let rel = relative(dirname(fromFile), target).replace(/\\/g, '/'); + if (!rel.startsWith('.')) rel = `./${rel}`; + return rel; + } + if (NODE_BUILTINS.has(spec.split('/')[0])) return `node:${spec}`; + // npm package (possibly scoped, possibly with a subpath) + const parts = spec.split('/'); + const name = spec.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0]; + const subpath = spec.slice(name.length); // '' or '/server/index.js' + const version = versions[name]; + if (!version) + throw new Error( + `no version for '${name}' in package.json (imported by ${relative(REPO_ROOT, fromFile)})` + ); + return `npm:${name}@${version}${subpath}`; +} + +/** Collect the string-literal module specifiers of a source file via the TS AST. */ +function collectSpecifiers(sourceFile: ts.SourceFile): ts.StringLiteral[] { + const specs: ts.StringLiteral[] = []; + const visit = (node: ts.Node) => { + if ( + (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && + node.moduleSpecifier && + ts.isStringLiteral(node.moduleSpecifier) + ) { + specs.push(node.moduleSpecifier); + } else if ( + ts.isCallExpression(node) && + node.expression.kind === ts.SyntaxKind.ImportKeyword && + node.arguments.length > 0 && + ts.isStringLiteral(node.arguments[0]) + ) { + specs.push(node.arguments[0]); + } + ts.forEachChild(node, visit); + }; + visit(sourceFile); + return specs; +} + +/** Rewrite all import/export specifiers in a file; returns new source. */ +function rewriteFile(file: string, discovered: Set): string { + const src = readFileSync(file, 'utf8'); + const sourceFile = ts.createSourceFile( + file, + src, + ts.ScriptTarget.Latest, + true, + ts.ScriptKind.TS + ); + // Replace back-to-front so earlier positions stay valid. + const specs = collectSpecifiers(sourceFile).sort( + (a, b) => b.getStart(sourceFile) - a.getStart(sourceFile) + ); + let out = src; + for (const lit of specs) { + const rewritten = rewriteSpec(file, lit.text, discovered); + if (rewritten === lit.text) continue; + // getStart()/getEnd() include the quotes; keep them as-is. + const start = lit.getStart(sourceFile) + 1; + const end = lit.getEnd() - 1; + out = out.slice(0, start) + rewritten + out.slice(end); + } + return out; +} + +/** Crawl the import closure of `entry`, rewriting as we go. */ +function stageVal(key: string, entry: string): Map { + const staged = new Map(); // repo-relative path -> content + const queue = [resolve(REPO_ROOT, entry)]; + const seen = new Set(queue); + + while (queue.length > 0) { + const file = queue.shift()!; + const discovered = new Set(); + const content = rewriteFile(file, discovered); + staged.set(relative(REPO_ROOT, file).replace(/\\/g, '/'), content); + for (const dep of discovered) { + if (!seen.has(dep)) { + seen.add(dep); + queue.push(dep); + } + } + } + + // Entry point: val.town serves the root http.ts as the HTTP handler. + staged.set('http.ts', `export { default } from './${entry}';\n`); + + // Write the staging dir for inspection / local Deno testing. + const dir = join(STAGE_ROOT, key); + rmSync(dir, { recursive: true, force: true }); + for (const [path, content] of staged) { + const out = join(dir, path); + mkdirSync(dirname(out), { recursive: true }); + writeFileSync(out, content); + } + console.log( + `staged ${key}: ${staged.size} files → ${relative(REPO_ROOT, dir)}/` + ); + return staged; +} + +// --------------------------------------------------------------------------- +// val.town v2 API +// --------------------------------------------------------------------------- + +function getToken(): string { + if (process.env.VAL_TOWN_TOKEN) return process.env.VAL_TOWN_TOKEN; + for (const envPath of [join(SCRIPT_DIR, '.env'), join(REPO_ROOT, '.env')]) { + if (existsSync(envPath)) { + const m = readFileSync(envPath, 'utf8').match(/VAL_TOWN_TOKEN=(.+)/); + if (m) return m[1].trim(); + } + } + throw new Error('VAL_TOWN_TOKEN not set (env var or .env file)'); +} + +async function api( + token: string, + method: string, + path: string, + body?: unknown +): Promise { + return fetch(`${API}${path}`, { + method, + headers: { + Authorization: `Bearer ${token}`, + 'Content-Type': 'application/json' + }, + body: body ? JSON.stringify(body) : undefined + }); +} + +async function createVal(token: string, info: ValInfo): Promise { + const res = await api(token, 'POST', '/vals', { + name: info.name, + privacy: info.privacy + }); + if (!res.ok) { + throw new Error( + `create ${info.name}: HTTP ${res.status} ${await res.text()}` + ); + } + const { id } = (await res.json()) as { id: string }; + return id; +} + +async function upsertFile( + token: string, + valId: string, + path: string, + content: string, + type: 'http' | 'script' +): Promise { + const q = `/vals/${valId}/files?path=${encodeURIComponent(path)}`; + let res = await api(token, 'PUT', q, { content, type }); + if (res.status === 404) { + res = await api(token, 'POST', q, { content, type }); + } + if (!res.ok) { + throw new Error(`upsert ${path}: HTTP ${res.status} ${await res.text()}`); + } +} + +async function pushVal( + token: string, + key: string, + info: ValInfo, + staged: Map +): Promise { + console.log(`\n── ${key} (${info.name}) ──`); + let created = false; + if (!info.id) { + info.id = await createVal(token, info); + created = true; + console.log(` created: ${info.id}`); + } + for (const [path, content] of staged) { + const type = path === 'http.ts' ? 'http' : 'script'; + await upsertFile(token, info.id, path, content, type); + console.log(` ↑ ${path} (${content.length} bytes)`); + } + return created; +} + +// --------------------------------------------------------------------------- +// main +// --------------------------------------------------------------------------- + +async function main() { + const args = process.argv.slice(2); + const push = args.includes('--push'); + const targets = args.filter((a) => !a.startsWith('--')); + + const manifest: Manifest = JSON.parse(readFileSync(MANIFEST_PATH, 'utf8')); + const keys = targets.length > 0 ? targets : Object.keys(manifest.vals); + + const stagedByKey = new Map>(); + for (const key of keys) { + const info = manifest.vals[key]; + if (!info) + throw new Error( + `unknown val '${key}' (manifest has: ${Object.keys(manifest.vals).join(', ')})` + ); + stagedByKey.set(key, stageVal(key, info.entry)); + } + + if (!push) { + console.log('\nstage only (pass --push to upload). Local check, e.g.:'); + console.log( + ' deno serve --port 3203 --allow-net --allow-env .valtown-stage/rs/http.ts' + ); + return; + } + + const token = getToken(); + let dirty = false; + for (const key of keys) { + const created = await pushVal( + token, + key, + manifest.vals[key], + stagedByKey.get(key)! + ); + dirty = dirty || created; + } + if (dirty) { + writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + '\n'); + console.log('\nvaltown-manifest.json updated with new val ids'); + } + console.log( + '\n✓ done — remember the env vars (see header comment) if this was the first push.' + ); +} + +main().catch((e: unknown) => { + console.error(e instanceof Error ? e.message : e); + process.exit(1); +}); diff --git a/examples/hosted/fetch-bridge.ts b/examples/hosted/fetch-bridge.ts new file mode 100644 index 00000000..4ee18790 --- /dev/null +++ b/examples/hosted/fetch-bridge.ts @@ -0,0 +1,104 @@ +/** + * Web fetch ↔ Node bridge: adapt a Node RequestListener (express app) to a + * fetch-style handler for serverless runtimes (val.town, Deno Deploy, Bun). + * + * Intercepts the user-facing write surface (writeHead/setHeader/write/end) + * so we never touch ServerResponse's socket-coupled internals — the approach + * serverless-http and light-my-request take. + */ + +import { IncomingMessage, ServerResponse } from 'node:http'; +import { Socket } from 'node:net'; + +type NodeListener = (req: IncomingMessage, res: ServerResponse) => void; + +export function toFetchHandler( + listener: NodeListener +): (request: Request) => Promise { + return async (request: Request): Promise => { + const url = new URL(request.url); + + // --- web Request → Node IncomingMessage --- + const body = request.body + ? Buffer.from(await request.arrayBuffer()) + : undefined; + // Express's req.protocol/req.ip read socket.encrypted/.remoteAddress, + // and IncomingMessage._destroy calls socket.destroy(), so a real + // (unconnected) Socket with the encrypted flag patched on is the path + // of least surprise. + const socket = Object.assign(new Socket(), { encrypted: false }); + const nodeReq = new IncomingMessage(socket); + nodeReq.method = request.method; + nodeReq.url = url.pathname + url.search; + nodeReq.httpVersion = '1.1'; + nodeReq.httpVersionMajor = 1; + nodeReq.httpVersionMinor = 1; + nodeReq.headers = Object.fromEntries(request.headers); + nodeReq.headers.host ??= url.host; + if (body?.length) nodeReq.headers['content-length'] = String(body.length); + // The SDK's StreamableHTTPServerTransport converts Node→Web via + // @hono/node-server, which reads rawHeaders (the [k,v,k,v,...] array), + // not the parsed headers object. Deno's node:http compat exposes + // rawHeaders as a getter-only accessor, so shadow it with an own + // property instead of assigning. + Object.defineProperty(nodeReq, 'rawHeaders', { + value: Object.entries(nodeReq.headers).flat() as string[], + writable: true, + configurable: true + }); + if (body?.length) nodeReq.push(body); + nodeReq.push(null); + + // --- Node ServerResponse → web Response --- + const nodeRes = new ServerResponse(nodeReq); + const chunks: Buffer[] = []; + let status = 200; + const headers = new Headers(); + + const captureHeaders = ( + h?: Record + ) => { + for (const [k, v] of Object.entries(h ?? {})) { + headers.set(k, Array.isArray(v) ? v.join(', ') : String(v)); + } + }; + nodeRes.setHeader = ((k: string, v: string | string[] | number) => { + headers.set(k, Array.isArray(v) ? v.join(', ') : String(v)); + return nodeRes; + }) as ServerResponse['setHeader']; + nodeRes.getHeader = (k: string) => + headers.get(k.toLowerCase()) ?? undefined; + nodeRes.removeHeader = (k: string) => headers.delete(k); + nodeRes.writeHead = ((code: number, h?: Record) => { + status = code; + captureHeaders(h); + return nodeRes; + }) as ServerResponse['writeHead']; + nodeRes.write = ((c: string | Buffer, enc?: BufferEncoding) => { + if (c) chunks.push(typeof c === 'string' ? Buffer.from(c, enc) : c); + return true; + }) as ServerResponse['write']; + nodeRes.flushHeaders = () => {}; + Object.defineProperty(nodeRes, 'statusCode', { + get: () => status, + set: (v: number) => { + status = v; + } + }); + + return new Promise((resolve) => { + nodeRes.end = ((c?: string | Buffer, enc?: BufferEncoding) => { + if (c) chunks.push(typeof c === 'string' ? Buffer.from(c, enc) : c); + resolve( + new Response(chunks.length ? Buffer.concat(chunks) : null, { + status, + headers + }) + ); + return nodeRes; + }) as ServerResponse['end']; + + listener(nodeReq, nodeRes); + }); + }; +} diff --git a/examples/hosted/local-relay.ts b/examples/hosted/local-relay.ts new file mode 100644 index 00000000..1195cfd6 --- /dev/null +++ b/examples/hosted/local-relay.ts @@ -0,0 +1,36 @@ +#!/usr/bin/env -S npx tsx +/** + * Run the val.town relay locally for end-to-end testing without deploying. + * Thin Node http.Server → fetch-handler bridge around valtown-relay.ts. + * + * CONFORMANCE_RS_ORIGIN=http://localhost:3000 \ + * CONFORMANCE_RELAY_SECRET=dev \ + * npx tsx examples/hosted/local-relay.ts 3001 + */ +import http from 'node:http'; +import handler from './valtown-relay'; + +const port = Number(process.argv[2] ?? 3001); + +http + .createServer(async (req, res) => { + const chunks: Buffer[] = []; + for await (const c of req) chunks.push(c as Buffer); + const body = chunks.length ? Buffer.concat(chunks) : undefined; + const url = `http://${req.headers.host}${req.url}`; + const out = await handler( + new Request(url, { + method: req.method, + headers: req.headers as Record, + body: body ? new Uint8Array(body) : undefined + }) + ); + res.writeHead(out.status, Object.fromEntries(out.headers)); + res.end(Buffer.from(await out.arrayBuffer())); + }) + .listen(port, () => { + console.error( + `relay[${process.env.CONFORMANCE_RELAY_ROLE ?? 'as'}] ` + + `listening on http://localhost:${port} → ${process.env.CONFORMANCE_RS_ORIGIN}/__aux` + ); + }); diff --git a/examples/hosted/valtown-auth-checker.ts b/examples/hosted/valtown-auth-checker.ts new file mode 100644 index 00000000..8ce5722b --- /dev/null +++ b/examples/hosted/valtown-auth-checker.ts @@ -0,0 +1,18 @@ +/** + * MCP Checker — Auth Chain — dedicated val.town entry, mounted at the + * origin root (the val URL is the MCP endpoint; well-knowns are + * origin-rooted). See src/scenarios/client/auth-checker.ts. + */ + +import { AuthCheckerScenario } from '../../src/scenarios/client/auth-checker'; +import { toFetchHandler } from './fetch-bridge'; + +let origin = 'https://invalid.example'; + +const scenario = new AuthCheckerScenario(); +const bridge = toFetchHandler(scenario.handler(() => origin)); + +export default function (request: Request): Promise { + origin = new URL(request.url).origin; + return bridge(request); +} diff --git a/examples/hosted/valtown-checker.ts b/examples/hosted/valtown-checker.ts new file mode 100644 index 00000000..8e3dd229 --- /dev/null +++ b/examples/hosted/valtown-checker.ts @@ -0,0 +1,29 @@ +/** + * MCP Checker — 2026-07-28 (stateless draft) — dedicated val.town entry. + * + * This val IS the checker: the gauntlet scenario is mounted at the ORIGIN + * ROOT, so the val URL is the MCP endpoint itself (no /x/ path), + * the RFC 9728/8414 well-knowns are origin-rooted, and client configuration + * is just the val URL. One val = one spec version; other versions get their + * own checker vals. + * + * POST / the MCP endpoint (strict: stateless draft only) + * POST /lenient advisory mode — classic flows complete, gaps reported + * GET / HTML explainer (browsers) / JSON hint (everyone else) + * /oauth/* the initialize consent gate's mini-AS + */ + +import { StatelessGauntletScenario } from '../../src/scenarios/client/stateless-gauntlet'; +import { toFetchHandler } from './fetch-bridge'; + +// The base URL is the request origin; handler() reads it lazily per request, +// and it is constant for a deployed val, so a module-level cell is safe. +let origin = 'https://invalid.example'; + +const scenario = new StatelessGauntletScenario(); +const bridge = toFetchHandler(scenario.handler(() => origin)); + +export default function (request: Request): Promise { + origin = new URL(request.url).origin; + return bridge(request); +} diff --git a/examples/hosted/valtown-manifest.json b/examples/hosted/valtown-manifest.json new file mode 100644 index 00000000..46d2608d --- /dev/null +++ b/examples/hosted/valtown-manifest.json @@ -0,0 +1,28 @@ +{ + "vals": { + "rs": { + "name": "mcp-conformance", + "entry": "examples/hosted/valtown.ts", + "privacy": "public", + "id": "b6283b42-5b64-11f1-a2b2-ee650bb23af1" + }, + "relay": { + "name": "mcp-conformance-as", + "entry": "examples/hosted/valtown-relay.ts", + "privacy": "public", + "id": "c3e769ce-5b64-11f1-ad2f-ee650bb23af1" + }, + "checker": { + "name": "mcp-checker-2026-07-28", + "entry": "examples/hosted/valtown-checker.ts", + "privacy": "public", + "id": "44515dfc-51ef-4efc-8148-80dd309b42e0" + }, + "auth-checker": { + "name": "mcp-checker-auth", + "entry": "examples/hosted/valtown-auth-checker.ts", + "privacy": "public", + "id": "53e9c5a5-9ad2-49d4-8b60-3a683d1de202" + } + } +} diff --git a/examples/hosted/valtown.ts b/examples/hosted/valtown.ts index ee0a8c80..16be5fa2 100644 --- a/examples/hosted/valtown.ts +++ b/examples/hosted/valtown.ts @@ -20,9 +20,8 @@ * Request→Response bridge. They're filtered out below. */ -import { IncomingMessage, ServerResponse } from 'node:http'; -import { Socket } from 'node:net'; import { createHostedApp } from '../../src/hosted/server'; +import { toFetchHandler } from './fetch-bridge'; const NOT_FETCH_SAFE = new Set(['sse-retry']); @@ -39,6 +38,8 @@ const { app } = createHostedApp({ relaySecret: process.env.CONFORMANCE_RELAY_SECRET }); +const bridge = toFetchHandler(app); + export default async function (request: Request): Promise { const url = new URL(request.url); @@ -53,79 +54,5 @@ export default async function (request: Request): Promise { ); } - // --- web Request → Node IncomingMessage --- - const body = request.body - ? Buffer.from(await request.arrayBuffer()) - : undefined; - // Express's req.protocol/req.ip read socket.encrypted/.remoteAddress, and - // IncomingMessage._destroy calls socket.destroy(), so a real (unconnected) - // Socket with the encrypted flag patched on is the path of least surprise. - const socket = Object.assign(new Socket(), { encrypted: false }); - const nodeReq = new IncomingMessage(socket); - nodeReq.method = request.method; - nodeReq.url = url.pathname + url.search; - nodeReq.httpVersion = '1.1'; - nodeReq.httpVersionMajor = 1; - nodeReq.httpVersionMinor = 1; - nodeReq.headers = Object.fromEntries(request.headers); - nodeReq.headers.host ??= url.host; - if (body?.length) nodeReq.headers['content-length'] = String(body.length); - // The SDK's StreamableHTTPServerTransport converts Node→Web via - // @hono/node-server, which reads rawHeaders (the [k,v,k,v,...] array), - // not the parsed headers object. - nodeReq.rawHeaders = Object.entries(nodeReq.headers).flat() as string[]; - if (body?.length) nodeReq.push(body); - nodeReq.push(null); - - // --- Node ServerResponse → web Response --- - // Intercept the user-facing write surface (writeHead/setHeader/write/end) - // so we never touch ServerResponse's socket-coupled internals. This is the - // approach serverless-http and light-my-request take. - const nodeRes = new ServerResponse(nodeReq); - const chunks: Buffer[] = []; - let status = 200; - const headers = new Headers(); - - const captureHeaders = (h?: Record) => { - for (const [k, v] of Object.entries(h ?? {})) { - headers.set(k, Array.isArray(v) ? v.join(', ') : String(v)); - } - }; - nodeRes.setHeader = ((k: string, v: string | string[] | number) => { - headers.set(k, Array.isArray(v) ? v.join(', ') : String(v)); - return nodeRes; - }) as ServerResponse['setHeader']; - nodeRes.getHeader = (k: string) => headers.get(k.toLowerCase()) ?? undefined; - nodeRes.removeHeader = (k: string) => headers.delete(k); - nodeRes.writeHead = ((code: number, h?: Record) => { - status = code; - captureHeaders(h); - return nodeRes; - }) as ServerResponse['writeHead']; - nodeRes.write = ((c: string | Buffer, enc?: BufferEncoding) => { - if (c) chunks.push(typeof c === 'string' ? Buffer.from(c, enc) : c); - return true; - }) as ServerResponse['write']; - nodeRes.flushHeaders = () => {}; - Object.defineProperty(nodeRes, 'statusCode', { - get: () => status, - set: (v: number) => { - status = v; - } - }); - - return new Promise((resolve) => { - nodeRes.end = ((c?: string | Buffer, enc?: BufferEncoding) => { - if (c) chunks.push(typeof c === 'string' ? Buffer.from(c, enc) : c); - resolve( - new Response(chunks.length ? Buffer.concat(chunks) : null, { - status, - headers - }) - ); - return nodeRes; - }) as ServerResponse['end']; - - app(nodeReq, nodeRes); - }); + return bridge(request); } diff --git a/src/hosted/server.ts b/src/hosted/server.ts index dc13fbef..70ff6a53 100644 --- a/src/hosted/server.ts +++ b/src/hosted/server.ts @@ -21,6 +21,7 @@ */ import express, { Request, Response } from 'express'; +import { ServerResponse } from 'http'; import { timingSafeEqual } from 'crypto'; import { Server } from '@modelcontextprotocol/sdk/server/index.js'; import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'; @@ -38,7 +39,13 @@ import { } from './session'; import { renderLanding, renderResults } from './html'; import { getScenario } from '../scenarios'; -import { ConformanceCheck, AuxOriginRole } from '../types'; +import { + ConformanceCheck, + AuxOriginRole, + AuthHandlerScenario, + RequestListener, + Scenario +} from '../types'; export interface HostedServerOptions { publicOrigin?: string; @@ -62,6 +69,105 @@ const RUN_ID_RE = /^[A-Za-z0-9_-]{1,64}$/; const AUX_ROLES: readonly AuxOriginRole[] = ['as', 'as2', 'idp']; +// --------------------------------------------------------------------------- +// Stateless ("/x") mounting support. +// +// /x/ mounts a scenario with NO run-id and NO results polling: a +// fresh scenario instance judges each request on its own content, and if the +// request itself violates a conformance requirement the response is replaced +// with a 400 explaining which checks failed. This only behaves sensibly for +// scenarios whose checks are per-request (no cross-request memory) — which +// is also exactly what serverless hosts with multiple isolates can support. +// --------------------------------------------------------------------------- + +/** Scenarios whose checks need cross-request or timing state — excluded. */ +const NOT_STATELESS = new Set(['sse-retry']); + +/** + * The aux relay correlates flows by a /r/ in the path. In stateless + * mode that segment encodes the scenario name instead of a run-id + * ('auth/metadata-default' → 'x--auth--metadata-default'); run-ids can't + * collide with it because '--' never appears in minted ids and the prefix is + * reserved. + */ +const STATELESS_SLUG_PREFIX = 'x--'; +function statelessSlug(scenarioName: string): string { + return STATELESS_SLUG_PREFIX + scenarioName.split('/').join('--'); +} +function decodeStatelessSlug(segment: string): string | undefined { + if (!segment.startsWith(STATELESS_SLUG_PREFIX)) return undefined; + return segment.slice(STATELESS_SLUG_PREFIX.length).split('--').join('/'); +} + +interface CapturedResponse { + status: number; + headers: Record; + body: Buffer; +} + +/** + * Run a scenario listener against a buffered response so the outcome can be + * judged (and replaced) after the handler finishes. Same interception + * surface the valtown bridge uses: writeHead/setHeader/write/end and the + * statusCode property — everything express and the SDK transport touch. + */ +function runCaptured( + listener: RequestListener, + req: Request, + rewrittenUrl: string +): Promise { + return new Promise((resolve, reject) => { + const headers: Record = {}; + const chunks: Buffer[] = []; + let status = 200; + + const fake = new ServerResponse(req) as ServerResponse; + const captureHeaders = ( + h?: Record + ): void => { + for (const [k, v] of Object.entries(h ?? {})) { + headers[k.toLowerCase()] = Array.isArray(v) ? v : String(v); + } + }; + fake.setHeader = ((k: string, v: string | string[] | number) => { + headers[k.toLowerCase()] = Array.isArray(v) ? v : String(v); + return fake; + }) as ServerResponse['setHeader']; + fake.getHeader = (k: string) => headers[k.toLowerCase()]; + fake.removeHeader = (k: string) => { + delete headers[k.toLowerCase()]; + }; + fake.writeHead = ((code: number, h?: Record) => { + status = code; + captureHeaders(h); + return fake; + }) as ServerResponse['writeHead']; + fake.write = ((c: string | Buffer, enc?: BufferEncoding) => { + if (c) chunks.push(typeof c === 'string' ? Buffer.from(c, enc) : c); + return true; + }) as ServerResponse['write']; + fake.flushHeaders = () => {}; + Object.defineProperty(fake, 'statusCode', { + get: () => status, + set: (v: number) => { + status = v; + } + }); + fake.end = ((c?: string | Buffer, enc?: BufferEncoding) => { + if (c) chunks.push(typeof c === 'string' ? Buffer.from(c, enc) : c); + resolve({ status, headers, body: Buffer.concat(chunks) }); + return fake; + }) as ServerResponse['end']; + + req.url = rewrittenUrl; + try { + listener(req, fake); + } catch (e) { + reject(e instanceof Error ? e : new Error(String(e))); + } + }); +} + export function createHostedApp(opts: HostedServerOptions = {}): { app: express.Application; sessions: SessionManager; @@ -231,6 +337,219 @@ export function createHostedApp(opts: HostedServerOptions = {}): { ); }); + // ---------- stateless mounting (no run-id, fail-fast) ---------- + // + // /x/[/] judges every request on its own content with a + // fresh scenario instance. A request that records a FAILURE check gets a + // 400 explaining what went wrong instead of the scenario's response — the + // client-under-test finds out immediately, no results polling, no mint. + + interface StatelessInstance { + scenario: Scenario; + listener: RequestListener; + auxListeners?: Partial>; + mcpPath: string; + } + + function instantiateStateless( + scenarioName: string, + baseUrl: string + ): StatelessInstance { + const proto = getScenario(scenarioName); + if (!proto) throw new UnknownScenarioError(scenarioName); + const Ctor = proto.constructor as new () => Scenario; + const scenario = new Ctor(); + + if (scenario instanceof AuthHandlerScenario) { + const missing = scenario.auxRoles.filter((r) => !auxOrigins[r]); + if (missing.length) { + throw new NotHostableError( + scenarioName, + `needs aux origin(s) [${missing.join(', ')}] — start with --as-origin` + ); + } + const handlers = scenario.authHandlers({ + getRsBaseUrl: () => baseUrl, + getAuxBaseUrl: (role) => + `${auxOrigins[role]}/r/${statelessSlug(scenarioName)}` + }); + return { + scenario, + listener: handlers.rs, + auxListeners: handlers.aux, + mcpPath: scenario.mcpPath ?? '' + }; + } + if (scenario.handler) { + return { + scenario, + listener: scenario.handler(() => baseUrl), + mcpPath: scenario.mcpPath ?? '' + }; + } + throw new NotHostableError(scenarioName); + } + + /** + * Resolve "/" (no run-id segment) against the + * hostable set, longest scenario-name prefix first. + */ + function resolveStateless( + rest: string + ): { scenarioName: string; suffix: string } | undefined { + const segments = rest.split('/'); + for (let i = segments.length; i >= 1; i--) { + const candidate = segments.slice(0, i).join('/'); + if (hostable.has(candidate) && !NOT_STATELESS.has(candidate)) { + return { + scenarioName: candidate, + suffix: '/' + segments.slice(i).join('/') + }; + } + } + return undefined; + } + + /** Emit the captured response, or replace it with a 400 on FAILUREs. */ + function finishStateless( + res: Response, + scenario: Scenario, + captured: CapturedResponse, + scenarioName: string + ): void { + const checks = scenario.rawChecks?.() ?? scenario.getChecks(); + const failures = checks.filter((c) => c.status === 'FAILURE'); + if (failures.length > 0) { + res.status(400).json({ + error: 'conformance failure', + scenario: scenarioName, + failures: failures.map(({ id, description, details }) => ({ + id, + description, + details + })) + }); + return; + } + for (const [k, v] of Object.entries(captured.headers)) { + res.setHeader(k, v); + } + res.setHeader( + 'mcp-conformance', + `pass; checks=${checks.filter((c) => c.status === 'SUCCESS').length}` + ); + res.status(captured.status); + res.end(captured.body.length ? captured.body : undefined); + } + + app.all(/^\/x\/(.+)$/, async (req, res) => { + const rest = req.params[0]; + const resolved = resolveStateless(rest); + if (!resolved) { + const segments = rest.split('/'); + for (let i = 1; i <= segments.length; i++) { + const candidate = segments.slice(0, i).join('/'); + if (NOT_STATELESS.has(candidate)) { + res.status(501).json({ + error: `scenario '${candidate}' needs cross-request state and cannot run stateless — use /s/${candidate}/` + }); + return; + } + if (getScenario(candidate)) { + res.status(501).json({ + error: `scenario '${candidate}' is not hostable here` + }); + return; + } + } + res.status(404).json({ error: `unknown scenario '${segments[0]}'` }); + return; + } + const { scenarioName, suffix } = resolved; + + let inst: StatelessInstance; + try { + inst = instantiateStateless( + scenarioName, + `${origin(req)}/x/${scenarioName}` + ); + } catch (e) { + if (e instanceof UnknownScenarioError || e instanceof NotHostableError) { + res.status(400).json({ error: e.message }); + return; + } + throw e; + } + + const search = req.url.includes('?') + ? req.url.slice(req.url.indexOf('?')) + : ''; + const captured = await runCaptured( + inst.listener, + req, + (suffix === '/' ? inst.mcpPath || '/' : suffix) + search + ); + finishStateless(res, inst.scenario, captured, scenarioName); + }); + + // RFC 8414 root well-known for stateless mounts that embed their own AS + // (path-based issuer /x//): metadata lives at + // /.well-known//x//. + app.get( + /^\/\.well-known\/(oauth-authorization-server|openid-configuration)\/x\/(.+)$/, + async (req, res) => { + const doc = req.params[0]; + const resolved = resolveStateless(req.params[1]); + if (!resolved) { + res.status(404).json({ error: 'no scenario for this issuer path' }); + return; + } + let inst: StatelessInstance; + try { + inst = instantiateStateless( + resolved.scenarioName, + `${origin(req)}/x/${resolved.scenarioName}` + ); + } catch { + res.status(404).json({ error: 'no scenario for this issuer path' }); + return; + } + const rewritten = + `/.well-known/${doc}` + + (resolved.suffix === '/' ? '' : resolved.suffix); + const captured = await runCaptured(inst.listener, req, rewritten); + finishStateless(res, inst.scenario, captured, resolved.scenarioName); + } + ); + + // RFC 9728 root well-known for stateless mounts: PRM URL for MCP URL + // /x//mcp is /.well-known/oauth-protected-resource/x//mcp. + app.get( + /^\/\.well-known\/oauth-protected-resource\/x\/(.+)$/, + async (req, res) => { + const resolved = resolveStateless(req.params[0]); + if (!resolved) { + res.status(404).json({ error: 'no scenario for this resource path' }); + return; + } + let inst: StatelessInstance; + try { + inst = instantiateStateless( + resolved.scenarioName, + `${origin(req)}/x/${resolved.scenarioName}` + ); + } catch { + res.status(404).json({ error: 'no scenario for this resource path' }); + return; + } + const rewritten = + '/.well-known/oauth-protected-resource' + + (resolved.suffix === '/' ? '' : resolved.suffix); + const captured = await runCaptured(inst.listener, req, rewritten); + finishStateless(res, inst.scenario, captured, resolved.scenarioName); + } + ); + // ---------- root well-known dispatch (RS side) ---------- // // RFC 9728: a client given MCP URL /s///mcp derives the PRM @@ -291,7 +610,7 @@ export function createHostedApp(opts: HostedServerOptions = {}): { return ok; }; - app.all(/^\/__aux\/([a-z0-9]+)(\/.*)$/, (req, res) => { + app.all(/^\/__aux\/([a-z0-9]+)(\/.*)$/, async (req, res) => { if (!guard(req, res)) return; const role = req.params[0] as AuxOriginRole; const path = req.params[1]; @@ -309,15 +628,47 @@ export function createHostedApp(opts: HostedServerOptions = {}): { return; } const [, prefix, runId, suffix = ''] = m; + const search = req.url.includes('?') + ? req.url.slice(req.url.indexOf('?')) + : ''; + + // Stateless flows encode the scenario name (not a run-id) in the /r/ + // segment; per-flow OAuth state rides inside the artifacts themselves + // (auth code, token), so a fresh instance per request is enough. + const slugScenario = decodeStatelessSlug(runId); + if (slugScenario !== undefined) { + let inst: StatelessInstance; + try { + inst = instantiateStateless( + slugScenario, + `${origin(req)}/x/${slugScenario}` + ); + } catch { + res + .status(404) + .json({ error: `no stateless scenario '${slugScenario}'` }); + return; + } + const listener = inst.auxListeners?.[role]; + if (!listener) { + res.status(404).json({ error: `no aux '${role}' handler` }); + return; + } + const captured = await runCaptured( + listener, + req, + (prefix + suffix || '/') + search + ); + finishStateless(res, inst.scenario, captured, slugScenario); + return; + } + const run = sessions.get(runId); const listener = run?.auxListeners?.[role]; if (!run || !listener) { res.status(404).json({ error: `no aux '${role}' handler for run` }); return; } - const search = req.url.includes('?') - ? req.url.slice(req.url.indexOf('?')) - : ''; dispatch(run, listener, req, res, (prefix + suffix || '/') + search); }); } diff --git a/src/scenarios/client/auth-checker.ts b/src/scenarios/client/auth-checker.ts new file mode 100644 index 00000000..f7849591 --- /dev/null +++ b/src/scenarios/client/auth-checker.ts @@ -0,0 +1,571 @@ +/** + * Auth checker — a stateless re-auth chain. + * + * One MCP server, three auth rungs. Each rung is reached by forcing the + * client back through authorization under a DIFFERENT configuration, using + * only the spec's own signals: + * + * rung 1 "basic" 401 challenge → PRM #1 → AS #1: PKCE S256 + DCR + + * RFC 8707 resource indicator. + * rung 2 "scoped" calling advance_to_scoped with a basic token → 401 + * whose WWW-Authenticate points at PRM #2 (different AS, + * SEP-835: scope must be taken from scopes_supported). + * rung 3 "step-up" calling advance_to_stepup with only conformance:read → + * 403 insufficient_scope, scope="… conformance:write" + * (RFC 6750 step-up at the same AS). + * + * The access token IS the progress report: `ac.`, so + * possession of a token with cfg=scoped and conformance:write proves the + * client handled discovery, a challenge-driven AS switch, SEP-835 scope + * selection, and 403 step-up — with zero server-side state. The final + * auth_complete tool spells that out. + * + * Like the consent gate in checker-2026-07-28, the embedded ASs are + * deliverers of specific challenge shapes, not auth conformance tests in + * themselves — but unlike the consent gate they auto-redirect, so the whole + * chain is automatable. + */ + +import { Server } from '@modelcontextprotocol/sdk/server/index.js'; +import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'; +import { + CallToolRequestSchema, + CallToolResult, + ListToolsRequestSchema +} from '@modelcontextprotocol/sdk/types.js'; +import express, { Request, Response } from 'express'; +import { createHash } from 'crypto'; +import type { ConformanceCheck } from '../../types'; +import { HandlerScenario } from '../../types'; + +const SERVER_INFO = { name: 'mcp-checker-auth', version: '1.0.0' }; + +const SCOPE_READ = 'conformance:read'; +const SCOPE_WRITE = 'conformance:write'; + +type Cfg = 'basic' | 'scoped' | 'isstrap'; + +interface TokenClaims { + cfg: Cfg; + scope: string; + /** Set on tokens minted through the iss-mismatch trap — see rung 4. */ + trap?: string; +} + +function mintToken(claims: TokenClaims): string { + return `ac.${Buffer.from(JSON.stringify(claims)).toString('base64url')}`; +} + +function parseToken(authorization: string | undefined): TokenClaims | undefined { + const m = /^Bearer ac\.([A-Za-z0-9_-]+)$/.exec(authorization ?? ''); + if (!m) return undefined; + try { + const claims = JSON.parse(Buffer.from(m[1], 'base64url').toString()); + if (!['basic', 'scoped', 'isstrap'].includes(claims.cfg)) return undefined; + return { + cfg: claims.cfg, + scope: String(claims.scope ?? ''), + ...(claims.trap ? { trap: String(claims.trap) } : {}) + }; + } catch { + return undefined; + } +} + +const hasScope = (t: TokenClaims, scope: string) => + t.scope.split(' ').includes(scope); + +/** What each successfully-reached rung proves about the client. */ +const RUNG_PROOF: Record = { + auth_status: 'you completed at least one full authorization flow', + advance_to_scoped: + 'your client handled a mid-session 401 whose WWW-Authenticate pointed ' + + 'at a DIFFERENT resource_metadata, re-discovered, re-registered at the ' + + 'second AS, and requested the scope advertised in scopes_supported ' + + '(SEP-835)', + advance_to_stepup: + 'your client handled a 403 insufficient_scope challenge by ' + + 're-authorizing with the broader scope from the challenge (RFC 6750 ' + + 'step-up) while staying at the same AS', + auth_complete: + 'ALL AUTH RUNGS PASSED: initial discovery + PKCE S256 + DCR + RFC 8707 ' + + 'resource indicator (rung 1), challenge-driven AS switch + SEP-835 ' + + 'scope selection (rung 2), 403 insufficient_scope step-up (rung 3)' +}; + +const TOOLS = [ + { + name: 'auth_status', + description: + 'Reports which auth rung your current access token proves. Call this ' + + 'first and after each advance.' + }, + { + name: 'advance_to_scoped', + description: + 'Rung 2 gate. With a rung-1 (basic) token this returns HTTP 401 whose ' + + 'WWW-Authenticate names a different resource_metadata — re-authorize ' + + 'through it (note its scopes_supported) and retry.' + }, + { + name: 'advance_to_stepup', + description: + `Rung 3 gate. Requires ${SCOPE_WRITE}; with only ${SCOPE_READ} this ` + + 'returns HTTP 403 insufficient_scope naming the scope to add — ' + + 're-authorize with it and retry.' + }, + { + name: 'auth_complete', + description: + 'The finish line. Succeeds only with a token proving every rung; the ' + + 'result is the full report.' + }, + { + name: 'check_iss_validation', + description: + 'OPTIONAL TRAP (RFC 9207 / SEP-2468). Calling this returns a 401 ' + + 'pointing at an AS that advertises ' + + 'authorization_response_iss_parameter_supported: true but sends a ' + + 'WRONG iss in the authorization response. This tool can NEVER return ' + + 'success: a conformant client refuses to exchange the code (your own ' + + "client errors about the iss mismatch — that error IS the pass). A " + + 'client that exchanges the code anyway receives a poisoned token, and ' + + 'every request made with it fails with an explanation. Run this last; ' + + 'it ends the session either way.' + } +].map((t) => ({ ...t, inputSchema: { type: 'object', properties: {} } })); + +export class AuthCheckerScenario extends HandlerScenario { + name = 'checker-auth'; + description = + 'Stateless auth re-auth chain: each tool rung forces re-authorization ' + + 'under a different configuration (401 with a different ' + + 'resource_metadata, then 403 insufficient_scope step-up). The access ' + + 'token encodes progress; auth_complete succeeds only after every rung.'; + readonly source = { introducedIn: '2025-06-18' } as const; + mcpPath = ''; + + private checks: ConformanceCheck[] = []; + + handler(getBaseUrl: () => string): express.Application { + const app = express(); + app.use(express.json()); + app.use(express.urlencoded({ extended: false })); + + const base = () => new URL(getBaseUrl()); + const basePath = () => (base().pathname === '/' ? '' : base().pathname); + const prmUrl = (cfg: Cfg) => + `${base().origin}/.well-known/oauth-protected-resource${basePath()}${cfg === 'basic' ? '' : `/cfg/${cfg}`}`; + const issuer = (cfg: Cfg) => `${getBaseUrl()}/as/${cfg}`; + /** The deliberately-wrong iss value the trap AS puts in its redirects. */ + const wrongIss = () => `${getBaseUrl()}/as/mixup-attacker`; + + const record = ( + id: string, + ok: boolean, + description: string, + details?: Record + ) => { + this.checks.push({ + id, + name: id, + description, + status: ok ? 'SUCCESS' : 'WARNING', + timestamp: new Date().toISOString(), + specReferences: [ + { + id: 'MCP-Auth', + url: 'https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization' + } + ], + details + }); + }; + + // ---------------- protected resource metadata (three variants) -------- + const prmDoc = (cfg: Cfg) => ({ + resource: getBaseUrl(), + authorization_servers: [issuer(cfg)], + bearer_methods_supported: ['header'], + // SEP-835: rung 2's PRM advertises the scope the client must request. + // Deliberately ONLY the read scope — the write scope must be learned + // from the rung-3 403 challenge, otherwise an SDK that requests all of + // scopes_supported up front would never exercise the step-up path. + ...(cfg === 'scoped' ? { scopes_supported: [SCOPE_READ] } : {}) + }); + app.get('/.well-known/oauth-protected-resource', (_req, res) => { + res.json(prmDoc('basic')); + }); + app.get('/.well-known/oauth-protected-resource/cfg/scoped', (_req, res) => { + res.json(prmDoc('scoped')); + }); + app.get('/.well-known/oauth-protected-resource/cfg/isstrap', (_req, res) => { + res.json(prmDoc('isstrap')); + }); + + // ---------------- the two ASs (path-based issuers, stateless) --------- + const asMetadata = (cfg: Cfg) => (_req: Request, res: Response) => { + res.json({ + issuer: issuer(cfg), + authorization_endpoint: `${issuer(cfg)}/authorize`, + token_endpoint: `${issuer(cfg)}/token`, + registration_endpoint: `${issuer(cfg)}/register`, + response_types_supported: ['code'], + grant_types_supported: ['authorization_code'], + code_challenge_methods_supported: ['S256'], + token_endpoint_auth_methods_supported: ['none'], + ...(cfg === 'scoped' ? { scopes_supported: [SCOPE_READ, SCOPE_WRITE] } : {}), + // RFC 9207: the trap AS PROMISES iss in authorization responses — + // which obliges the client to validate it. The redirect then carries + // a wrong one. + ...(cfg === 'isstrap' + ? { authorization_response_iss_parameter_supported: true } + : {}) + }); + }; + for (const cfg of ['basic', 'scoped', 'isstrap'] as const) { + app.get(`/.well-known/oauth-authorization-server/as/${cfg}`, asMetadata(cfg)); + app.get(`/.well-known/openid-configuration/as/${cfg}`, asMetadata(cfg)); + + app.post(`/as/${cfg}/register`, (req, res) => { + res.status(201).json({ + ...req.body, + client_id: `checker-auth-${cfg}-client`, + token_endpoint_auth_method: 'none' + }); + }); + + app.get(`/as/${cfg}/authorize`, (req, res) => { + const q = req.query as Record; + const fail = (error: string, description: string) => { + if (!q.redirect_uri) { + res.status(400).json({ error, error_description: description }); + return; + } + const r = new URL(q.redirect_uri); + r.searchParams.set('error', error); + r.searchParams.set('error_description', description); + if (q.state !== undefined) r.searchParams.set('state', q.state); + res.redirect(r.toString()); + }; + if (q.code_challenge === undefined || q.code_challenge_method !== 'S256') { + fail('invalid_request', 'PKCE with S256 is required'); + return; + } + if (cfg === 'basic' && q.resource === undefined) { + fail( + 'invalid_target', + 'RFC 8707: include the resource parameter naming the MCP server' + ); + return; + } + const requested = (q.scope ?? '').split(' ').filter(Boolean); + if (cfg === 'scoped' && !requested.includes(SCOPE_READ)) { + fail( + 'invalid_scope', + `SEP-835: request the scopes advertised in the PRM scopes_supported (at least ${SCOPE_READ}); got '${q.scope ?? ''}'` + ); + return; + } + record( + `auth-checker-authorize-${cfg}`, + true, + `Conformant authorization request at the '${cfg}' AS`, + { scope: q.scope } + ); + if (!q.redirect_uri) { + res.status(400).json({ error: 'invalid_request', error_description: 'redirect_uri required' }); + return; + } + const r = new URL(q.redirect_uri); + r.searchParams.set( + 'code', + Buffer.from( + JSON.stringify({ + cfg, + challenge: q.code_challenge, + scope: requested.join(' ') + }) + ).toString('base64url') + ); + if (q.state !== undefined) r.searchParams.set('state', q.state); + // The trap: metadata promised iss, the response lies about it. A + // conformant client compares this against the issuer it authorized + // at and refuses to exchange the code (RFC 9207 §2.4). + if (cfg === 'isstrap') r.searchParams.set('iss', wrongIss()); + res.redirect(r.toString()); + }); + + app.post(`/as/${cfg}/token`, (req, res) => { + const grant = req.body as Record; + let code: { cfg?: string; challenge?: string; scope?: string }; + try { + code = JSON.parse( + Buffer.from(String(grant.code ?? ''), 'base64url').toString() + ); + } catch { + code = {}; + } + if (grant.grant_type !== 'authorization_code' || code.cfg !== cfg) { + res.status(400).json({ error: 'invalid_grant' }); + return; + } + const expected = createHash('sha256') + .update(String(grant.code_verifier ?? '')) + .digest('base64url'); + if (expected !== code.challenge) { + res.status(400).json({ + error: 'invalid_grant', + error_description: 'PKCE verification failed' + }); + return; + } + const scope = code.scope ?? ''; + // Exchanging a trap code means the client ignored the iss mismatch — + // the token records the offense and incriminates every later request. + res.json({ + access_token: mintToken({ + cfg, + scope, + ...(cfg === 'isstrap' + ? { trap: 'exchanged-code-despite-iss-mismatch' } + : {}) + }), + token_type: 'Bearer', + expires_in: 3600, + ...(scope ? { scope } : {}) + }); + }); + } + + // ---------------- landing ------------------------------------------- + app.get('/', (req, res) => { + if (!String(req.headers.accept ?? '').includes('text/html')) { + res.status(405).json({ + error: 'POST JSON-RPC to this URL (auth required)', + docs: 'open this URL in a browser for a full explanation' + }); + return; + } + res.type('html').send(` +MCP Checker — Auth Chain + + +

MCP Checker — Auth Chain

+

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

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

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

+`); + }); + + // ---------------- the MCP endpoint, gated per rung ------------------- + // HTTP header values must be Latin-1; keep the rich text in the body. + const headerSafe = (s: string) => s.replace(/[^\x20-\x7e]/g, '-'); + const challenge401 = ( + res: Response, + cfg: Cfg, + description: string + ) => { + res + .status(401) + .set( + 'WWW-Authenticate', + `Bearer error="invalid_token", error_description="${headerSafe(description)}", resource_metadata="${prmUrl(cfg)}"` + ) + .json({ error: 'invalid_token', error_description: description }); + }; + + app.post('/', async (req: Request, res: Response) => { + const token = parseToken(req.headers.authorization); + const body = + req.body && !Array.isArray(req.body) + ? (req.body as { method?: string; params?: { name?: string } }) + : {}; + + if (!token) { + challenge401( + res, + 'basic', + 'Rung 1: authorize via the resource_metadata in this challenge' + ); + return; + } + + // NOTE: a poisoned token (minted by exchanging a wrong-iss code) is + // NOT rejected at the HTTP layer. Doing so delivered the verdict on the + // SDK's reconnect/initialize POST — a layer the agent never sees, so + // the failure surfaced as an opaque "reconnect failed: HTTP 400". We + // accept the token (the session stays alive) and instead fail the + // check_iss_validation TOOL CALL in-band below, matching every other + // rung's verdict style. Safe: the harness controls both ASs. + + // Gate the advance tools at the HTTP layer so the failures are real + // OAuth challenges, not tool errors — that is the whole trick. + const toolName = + body.method === 'tools/call' ? body.params?.name : undefined; + + // The iss trap. A non-poisoned token gets challenged toward the trap AS + // (a conformant client refuses mid-OAuth and never comes back — that + // out-of-band refusal is the PASS). A poisoned token means the client + // exchanged the wrong-iss code: fall through to the SDK dispatch, which + // returns the FAIL verdict as an in-band tool result. + if (toolName === 'check_iss_validation' && !token.trap) { + record('auth-checker-iss-trap-armed', true, 'iss trap challenge issued'); + challenge401( + res, + 'isstrap', + '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' + ); + return; + } + if (toolName === 'advance_to_scoped' && token.cfg !== 'scoped') { + record('auth-checker-rung2-challenged', true, 'Rung 2 challenge issued'); + challenge401( + res, + 'scoped', + 'Rung 2: this rung requires the second AS configuration — re-authorize via the resource_metadata in this challenge and note its scopes_supported' + ); + return; + } + if ( + (toolName === 'advance_to_stepup' || toolName === 'auth_complete') && + !(token.cfg === 'scoped' && hasScope(token, SCOPE_WRITE)) + ) { + if (token.cfg !== 'scoped') { + challenge401(res, 'scoped', 'Complete rung 2 before rung 3'); + return; + } + record('auth-checker-rung3-challenged', true, 'Rung 3 step-up issued'); + res + .status(403) + .set( + 'WWW-Authenticate', + `Bearer error="insufficient_scope", scope="${SCOPE_READ} ${SCOPE_WRITE}", resource_metadata="${prmUrl('scoped')}"` + ) + .json({ + error: 'insufficient_scope', + error_description: `Rung 3: re-authorize with '${SCOPE_WRITE}' (RFC 6750 step-up)` + }); + return; + } + + // Gate passed — serve via the SDK (per-request, stateless). + const server = new Server(SERVER_INFO, { + capabilities: { tools: {} }, + instructions: + 'Auth-chain checker. Call auth_status, then advance_to_scoped, ' + + 'then advance_to_stepup, then auth_complete. Each advance forces ' + + 'a re-authorization under a different configuration; an HTTP ' + + '401/403 along the way is the next challenge, not a failure.' + }); + server.setRequestHandler(ListToolsRequestSchema, async () => ({ + tools: TOOLS + })); + server.setRequestHandler( + CallToolRequestSchema, + async (request): Promise => { + // iss trap, fail path: reached only with a poisoned token, i.e. + // the client exchanged a code whose response carried a wrong iss. + // Deliver the verdict in-band so it surfaces as a tool result, not + // a swallowed transport error — and keep the session alive. + if (request.params.name === 'check_iss_validation') { + record( + 'auth-checker-iss-trap-caught', + false, + 'Client exchanged an authorization code despite an iss mismatch', + { iss: wrongIss(), expected: issuer('isstrap') } + ); + return { + content: [ + { + type: 'text', + text: + 'FAIL [check_iss_validation]: client exchanged an ' + + `authorization code whose response carried iss='${wrongIss()}', ` + + `expected '${issuer('isstrap')}' (RFC 9207 / SEP-2468). The ` + + 'trap AS advertised ' + + 'authorization_response_iss_parameter_supported: true, so a ' + + 'conformant client MUST compare iss against the issuer it ' + + 'authorized at and abort BEFORE the token exchange. ' + + 'Reaching this tool result means your client did not — ' + + 'leaving it open to authorization-server mix-up attacks.' + } + ], + isError: true + }; + } + const proof = RUNG_PROOF[request.params.name]; + if (!proof) { + return { + content: [ + { + type: 'text', + text: `unknown tool '${request.params.name}'` + } + ], + isError: true + }; + } + record(`auth-checker-${request.params.name}`, true, proof, { + cfg: token.cfg, + scope: token.scope + }); + const status = + request.params.name === 'auth_status' + ? `Token: cfg=${token.cfg}, scope='${token.scope}' — ${ + token.cfg === 'basic' + ? 'rung 1 done; call advance_to_scoped next.' + : hasScope(token, SCOPE_WRITE) + ? 'all rungs done; call auth_complete.' + : 'rung 2 done; call advance_to_stepup next.' + }` + : proof; + return { + content: [ + { + type: 'text', + text: `CONFORMANCE OK [${request.params.name}]: ${status}` + } + ] + }; + } + ); + const transport = new StreamableHTTPServerTransport({ + sessionIdGenerator: undefined + }); + await server.connect(transport); + await transport.handleRequest(req, res, req.body); + res.on('close', () => { + void transport.close(); + void server.close(); + }); + }); + + return app; + } + + getChecks(): ConformanceCheck[] { + return this.checks; + } +} diff --git a/src/scenarios/client/auth/discovery-metadata.ts b/src/scenarios/client/auth/discovery-metadata.ts index eb916260..39c504c9 100644 --- a/src/scenarios/client/auth/discovery-metadata.ts +++ b/src/scenarios/client/auth/discovery-metadata.ts @@ -176,6 +176,10 @@ abstract class MetadataDiscoveryScenario extends AuthHandlerScenario { return { rs: rsApp, aux: { as: authApp } }; } + rawChecks(): ConformanceCheck[] { + return this.checks; + } + getChecks(): ConformanceCheck[] { const isPathBasedPrm = this.config.prmLocation === '/.well-known/oauth-protected-resource/mcp'; diff --git a/src/scenarios/client/auth/helpers/createAuthServer.ts b/src/scenarios/client/auth/helpers/createAuthServer.ts index d4acb7fa..0a687387 100644 --- a/src/scenarios/client/auth/helpers/createAuthServer.ts +++ b/src/scenarios/client/auth/helpers/createAuthServer.ts @@ -5,6 +5,36 @@ import { createRequestLogger } from '../../../request-logger'; import { SpecReferences } from '../spec-references'; import { MockTokenVerifier } from './mockTokenVerifier'; +/** + * The authorization code is opaque to the client, so we use it to carry the + * per-flow state (PKCE challenge, requested scopes) from /authorize to + * /token. This keeps the AS stateless across processes — on serverless hosts + * (val.town) the two requests can land on different isolates, where closure + * state from /authorize doesn't exist. The closure variables remain as a + * fallback for flows that don't round-trip our code (e.g. hand-rolled tests). + */ +interface AuthCodeState { + challenge?: string; + scopes?: string[]; +} + +const AUTH_CODE_PREFIX = 'test-auth-code'; + +function encodeAuthCode(state: AuthCodeState): string { + return `${AUTH_CODE_PREFIX}.${Buffer.from(JSON.stringify(state)).toString('base64url')}`; +} + +function decodeAuthCode(code: string | undefined): AuthCodeState | undefined { + if (!code?.startsWith(`${AUTH_CODE_PREFIX}.`)) return undefined; + try { + return JSON.parse( + Buffer.from(code.slice(AUTH_CODE_PREFIX.length + 1), 'base64url').toString() + ) as AuthCodeState; + } catch { + return undefined; + } +} + /** * Compute S256 code challenge from a code verifier. * BASE64URL(SHA256(code_verifier)) @@ -261,7 +291,13 @@ export function createAuthServer( const redirectUri = req.query.redirect_uri as string; const state = req.query.state as string; const redirectUrl = new URL(redirectUri); - redirectUrl.searchParams.set('code', 'test-auth-code'); + redirectUrl.searchParams.set( + 'code', + encodeAuthCode({ + challenge: codeChallenge, + scopes: lastAuthorizationScopes + }) + ); if (state) { redirectUrl.searchParams.set('state', state); } @@ -286,6 +322,13 @@ export function createAuthServer( const requestedScope = req.body.scope; const grantType = req.body.grant_type; + // Recover per-flow state from the code itself (survives process changes + // on serverless hosts); fall back to closure state for codes we didn't + // mint via encodeAuthCode. + const codeState = decodeAuthCode(req.body.code as string | undefined); + const flowChallenge = codeState?.challenge ?? storedCodeChallenge; + const flowScopes = codeState?.scopes ?? lastAuthorizationScopes; + checks.push({ id: 'token-request', name: 'TokenRequest', @@ -316,18 +359,17 @@ export function createAuthServer( // PKCE: Validate code_verifier matches code_challenge (S256) // Fail if either is missing const computedChallenge = - codeVerifier && storedCodeChallenge + codeVerifier && flowChallenge ? computeS256Challenge(codeVerifier) : undefined; const matches = - computedChallenge !== undefined && - computedChallenge === storedCodeChallenge; + computedChallenge !== undefined && computedChallenge === flowChallenge; let description: string; - if (!storedCodeChallenge && !codeVerifier) { + if (!flowChallenge && !codeVerifier) { description = 'Neither code_challenge nor code_verifier were sent - PKCE is required'; - } else if (!storedCodeChallenge) { + } else if (!flowChallenge) { description = 'code_challenge was not sent in authorization request - PKCE is required'; } else if (!codeVerifier) { @@ -348,14 +390,14 @@ export function createAuthServer( specReferences: [SpecReferences.MCP_PKCE], details: { matches, - storedChallenge: storedCodeChallenge || 'not sent', + storedChallenge: flowChallenge || 'not sent', computedChallenge: computedChallenge || 'not computed' } }); } let token = `test-token-${Date.now()}`; - let scopes: string[] = lastAuthorizationScopes; + let scopes: string[] = flowScopes; if (onTokenRequest) { const result = await onTokenRequest({ diff --git a/src/scenarios/client/stateless-gauntlet.ts b/src/scenarios/client/stateless-gauntlet.ts new file mode 100644 index 00000000..7d2ca421 --- /dev/null +++ b/src/scenarios/client/stateless-gauntlet.ts @@ -0,0 +1,1200 @@ +/** + * Stateless conformance gauntlet — one MCP server, many validating tools. + * + * Unlike the per-aspect scenarios, this is a single stateless server a client + * connects to once. Every tool validates some aspect of the request that + * carried it; transport-level obligations (Accept header, content type, + * MCP-Protocol-Version) are validated on every POST before dispatch. The + * conformance contract is self-evident: + * + * list tools, call each one with valid arguments — if nothing errors, + * the client passed everything this server can observe per-request. + * + * There is intentionally NO cross-request state: each request is judged on + * its own content, so the server can run on serverless hosts (val.town) + * where consecutive requests may land on different isolates, and no run-id + * or results polling is needed. Checks are still recorded for the runner / + * hosted results view, but a misbehaving client finds out immediately + * because its own request fails with an explanation. + */ + +import { Server } from '@modelcontextprotocol/sdk/server/index.js'; +import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'; +import { + CallToolRequestSchema, + CallToolResult, + ListToolsRequestSchema +} from '@modelcontextprotocol/sdk/types.js'; +import express, { Request, Response } from 'express'; +import { createHash } from 'crypto'; +import type { ConformanceCheck } from '../../types'; +import { HandlerScenario, DRAFT_PROTOCOL_VERSION } from '../../types'; + +const SPEC_HTTP = { + id: 'MCP-Streamable-HTTP', + url: 'https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http' +}; +const SPEC_TOOLS = { + id: 'MCP-Tools', + url: 'https://modelcontextprotocol.io/specification/2025-06-18/server/tools#calling-tools' +}; + +/** + * The draft wire string and its planned release date are treated as the same + * version: clients built against the dated release string must pass against + * a server that predates the rename (and vice versa). + */ +const DRAFT_VERSION_ALIASES = [DRAFT_PROTOCOL_VERSION, '2026-07-28']; + +const CLASSIC_PROTOCOL_VERSIONS = ['2025-03-26', '2025-06-18', '2025-11-25']; + +const KNOWN_PROTOCOL_VERSIONS = [ + ...CLASSIC_PROTOCOL_VERSIONS, + ...DRAFT_VERSION_ALIASES +]; + +function isDraftVersion(v: unknown): boolean { + return DRAFT_VERSION_ALIASES.includes(String(v)); +} + +/** Versions compare equal across the draft/release-date alias. */ +function sameVersion(a: unknown, b: unknown): boolean { + return ( + String(a) === String(b) || (isDraftVersion(a) && isDraftVersion(b)) + ); +} + +const META_NS = 'io.modelcontextprotocol/'; + +/** + * The bearer token minted by the consent interstitial. The token IS the + * message: every subsequent request from the consented client carries + * `Authorization: Bearer this-client-led-with-initialize`, so request logs, + * proxies, and the readiness report can all state the fact directly. + */ +const CONSENT_TOKEN = 'this-client-led-with-initialize'; + +/** What clients see in serverInfo — one val, one spec version. */ +const SERVER_INFO = { name: 'mcp-checker-2026-07-28', version: '1.0.0' }; + +// --------------------------------------------------------------------------- +// MRTR (SEP-2322) — multi-round-trip tool, draft mode only. +// +// Listed only for clients whose per-request `_meta` clientCapabilities +// declare elicitation support: a client that can't answer elicitation +// requests simply never sees the tool, so "call every listed tool" stays the +// whole contract. The requestState is self-contained (no server memory), so +// the retry can land on any isolate. +// --------------------------------------------------------------------------- + +const MRTR_TOOL = { + name: 'mrtr_confirm', + description: + 'Multi-round-trip tool (SEP-2322): the first call returns an ' + + 'input_required result with an elicitation request and a requestState. ' + + 'Re-call this tool with inputResponses.confirm set to the elicitation ' + + 'result and requestState echoed back unchanged.', + inputSchema: { type: 'object', properties: {} } +}; + +/** + * Listed in place of mrtr_confirm when the client does NOT declare the + * elicitation capability — so the absence is discoverable instead of silent. + * Calling it is not an error (not implementing elicitation is conformant); + * the result explains what declaring the capability unlocks. + */ +const ELICITATION_MISSING_TOOL = { + name: 'elicitation_missing', + description: + 'You are seeing this tool because your client did not declare the ' + + "'elicitation' capability in _meta " + + `${META_NS}clientCapabilities. Clients that declare it ` + + '({"elicitation": {}}) see the full tool list, including the ' + + 'multi-round-trip (MRTR, SEP-2322) tool mrtr_confirm. Calling this ' + + 'tool is not an error — it returns this explanation.', + inputSchema: { type: 'object', properties: {} } +}; + +function declaresElicitation(meta: Record): boolean { + const caps = meta[`${META_NS}clientCapabilities`]; + return ( + typeof caps === 'object' && + caps !== null && + (caps as Record).elicitation !== undefined + ); +} + +function encodeMrtrState(): string { + return Buffer.from( + JSON.stringify({ tool: MRTR_TOOL.name, nonce: 'gauntlet-mrtr-v1' }) + ).toString('base64url'); +} + +function decodeMrtrState(state: string): boolean { + try { + const parsed = JSON.parse(Buffer.from(state, 'base64url').toString()); + return parsed.tool === MRTR_TOOL.name && parsed.nonce === 'gauntlet-mrtr-v1'; + } catch { + return false; + } +} + +interface ToolOutcome { + ok: boolean; + /** What was validated (on success) or what the client got wrong. */ + detail: string; +} + +/** + * Tool registry. Transport conformance (headers, _meta, version) is enforced + * on every request before any tool runs, so tools only need to cover what a + * request body can get wrong: constructing arguments that honor the + * inputSchema. One tool with a string, a number, and a same-document $ref + * field covers every argument kind in a single call; failures itemize + * per-field problems so nothing diagnostic is lost by the consolidation. + */ +const GAUNTLET_TOOLS: { + name: string; + description: string; + inputSchema: Record; + validate: (args: Record, req: Request) => ToolOutcome; +}[] = [ + { + name: 'validate_arguments', + description: + 'Echoes back its arguments. Validates that the client constructs ' + + 'arguments honoring the inputSchema: a required string, a required ' + + 'JSON number (not a stringified number), and a field defined via a ' + + 'same-document $ref (#/$defs/payload) — local refs are safe to ' + + 'resolve (SEP-2106). Failures list every non-conforming field.', + inputSchema: { + type: 'object', + properties: { + message: { type: 'string', description: 'Any string to echo' }, + count: { type: 'number', description: 'Any JSON number' }, + payload: { $ref: '#/$defs/payload' } + }, + required: ['message', 'count', 'payload'], + $defs: { + payload: { + type: 'object', + properties: { kind: { type: 'string', enum: ['solid', 'liquid'] } }, + required: ['kind'] + } + } + }, + validate: (args) => { + const problems: string[] = []; + if (typeof args.message !== 'string') { + problems.push( + `'message' must be a string; got ${JSON.stringify(args.message)} (${typeof args.message})` + ); + } + if (typeof args.count !== 'number') { + problems.push( + `'count' must be a JSON number, not a stringified number; got ${JSON.stringify(args.count)} (${typeof args.count})` + ); + } + const payload = args.payload as { kind?: unknown } | undefined; + if ( + !payload || + typeof payload !== 'object' || + (payload.kind !== 'solid' && payload.kind !== 'liquid') + ) { + problems.push( + `'payload' must match #/$defs/payload ({kind: "solid"|"liquid"}); got ${JSON.stringify(args.payload)}` + ); + } + if (problems.length > 0) { + return { ok: false, detail: problems.join('; ') }; + } + return { + ok: true, + detail: `message=${args.message}, count=${String(args.count)}, payload.kind=${String(payload?.kind)}` + }; + } + } +]; + +/** Transport-level problems with the request, empty when conformant. */ +function headerProblems(req: Request): string[] { + const problems: string[] = []; + const accept = String(req.headers.accept ?? ''); + if ( + !accept.includes('application/json') || + !accept.includes('text/event-stream') + ) { + problems.push( + `Accept header MUST list both application/json and text/event-stream; got '${accept || '(missing)'}'` + ); + } + const contentType = String(req.headers['content-type'] ?? ''); + if (!contentType.includes('application/json')) { + problems.push( + `Content-Type MUST be application/json; got '${contentType || '(missing)'}'` + ); + } + return problems; +} + +/** + * Draft-2026 (SEP-2575/SEP-2243) per-request obligations. There is no + * initialization in the stateless draft protocol, so everything a classic + * handshake established must be carried by every request: the version header, + * the io.modelcontextprotocol/* `_meta` fields, and the Mcp-Method/Mcp-Name + * routing headers. + */ +function draftProblems( + req: Request, + body: { method?: string; params?: Record } +): string[] { + const problems: string[] = []; + const headerVersion = req.headers['mcp-protocol-version']; + const meta = (body.params?._meta ?? {}) as Record; + const metaVersion = meta[`${META_NS}protocolVersion`]; + + if (!headerVersion) { + problems.push( + 'MCP-Protocol-Version header MUST be sent on every request (SEP-2575; there is no initialize handshake to negotiate it)' + ); + } else if (!KNOWN_PROTOCOL_VERSIONS.includes(String(headerVersion))) { + problems.push( + `MCP-Protocol-Version '${String(headerVersion)}' is not a known protocol version (${KNOWN_PROTOCOL_VERSIONS.join(', ')})` + ); + } + for (const field of ['protocolVersion', 'clientInfo', 'clientCapabilities']) { + if (meta[`${META_NS}${field}`] === undefined) { + problems.push( + `_meta MUST carry ${META_NS}${field} on every request (SEP-2575)` + ); + } + } + if ( + headerVersion !== undefined && + metaVersion !== undefined && + !sameVersion(headerVersion, metaVersion) + ) { + problems.push( + `MCP-Protocol-Version header ('${String(headerVersion)}') MUST match _meta ${META_NS}protocolVersion ('${String(metaVersion)}')` + ); + } + const mcpMethod = req.headers['mcp-method']; + if (!mcpMethod) { + problems.push( + 'Mcp-Method header MUST mirror the JSON-RPC method on every POST (SEP-2243)' + ); + } else if (body.method && String(mcpMethod) !== body.method) { + problems.push( + `Mcp-Method header ('${String(mcpMethod)}') MUST equal the body method ('${body.method}') (SEP-2243)` + ); + } + if (body.method === 'tools/call') { + const mcpName = req.headers['mcp-name']; + const toolName = (body.params as { name?: string } | undefined)?.name; + if (!mcpName) { + problems.push( + 'Mcp-Name header MUST mirror params.name on tools/call (SEP-2243)' + ); + } else if (toolName && String(mcpName) !== toolName) { + problems.push( + `Mcp-Name header ('${String(mcpName)}') MUST equal params.name ('${toolName}') (SEP-2243)` + ); + } + } + return problems; +} + +function check( + checks: ConformanceCheck[], + id: string, + name: string, + ok: boolean, + description: string, + details?: Record, + failStatus: 'FAILURE' | 'WARNING' = 'FAILURE' +): void { + checks.push({ + id, + name, + description, + status: ok ? 'SUCCESS' : failStatus, + timestamp: new Date().toISOString(), + specReferences: [SPEC_HTTP], + details + }); +} + +interface ToolCallResult { + content: { type: 'text'; text: string }[]; + isError?: boolean; + [key: string]: unknown; +} + +/** + * Execute a gauntlet tool call. In lenient mode failures stay isError tool + * results (recorded as WARNING checks) instead of escalating to HTTP 400 — + * an old client keeps its flow and reads the feedback from the result. + */ +function runTool( + checks: ConformanceCheck[], + name: string, + args: Record, + req: Request, + lenient = false +): ToolCallResult { + const tool = GAUNTLET_TOOLS.find((t) => t.name === name); + if (!tool) { + return { + content: [ + { + type: 'text', + text: + `CONFORMANCE FAIL: unknown tool '${name}'. ` + + `Available: ${GAUNTLET_TOOLS.map((t) => t.name).join(', ')}` + } + ], + isError: true + }; + } + const outcome = tool.validate(args, req); + check( + checks, + `gauntlet-${tool.name}`, + `Gauntlet: ${tool.name}`, + outcome.ok, + outcome.ok + ? `Client called ${tool.name} conformantly` + : `Client call to ${tool.name} was not conformant`, + { detail: outcome.detail }, + lenient ? 'WARNING' : 'FAILURE' + ); + if (!outcome.ok) { + return { + content: [ + { + type: 'text', + text: `CONFORMANCE FAIL [${tool.name}]: ${outcome.detail}` + } + ], + isError: true + }; + } + return { + content: [ + { type: 'text', text: `CONFORMANCE OK [${tool.name}]: ${outcome.detail}` } + ] + }; +} + +// --------------------------------------------------------------------------- +// Lenient mode ("/lenient" sub-path) — serve old clients, report the gaps. +// +// Classic flows complete normally (initialize handshake via the SDK) so an +// old client can actually run; the draft gap report is delivered where the +// client will see it: the initialize result's `instructions`, and the +// draft_readiness tool whose result itemizes what the request that carried +// it was missing relative to the stateless draft. +// --------------------------------------------------------------------------- + +const DRAFT_READINESS_TOOL = { + name: 'draft_readiness', + description: + 'Reports how draft-ready (stateless 2026-07-28, SEP-2575) your client ' + + 'is, judged from the request that carries this call: protocol version ' + + 'declaration, _meta fields, and Mcp-* routing headers. Never errors — ' + + 'the result is the report.', + inputSchema: { type: 'object', properties: {} } +}; + +/** + * Behavioral changes the draft brings that a per-request gap list cannot + * detect — appended to every readiness report so old clients learn about + * them even though their requests can't "miss" them yet. + */ +const MRTR_NOTE = + 'Also note: the stateless draft replaces server-initiated requests with ' + + 'multi-round-trip tool results (MRTR, SEP-2322). If your client supports ' + + 'elicitation, it must declare it in _meta ' + + `${META_NS}clientCapabilities ({"elicitation": {}}) and handle ` + + "resultType:'input_required' tool results — answer the inputRequests and " + + 'retry the call with requestState echoed back unchanged. Declaring the ' + + "capability makes this gauntlet list the mrtr_confirm tool so you can " + + 'exercise that flow.'; + +/** Itemized draft gaps of one request, framed as an advisory report. */ +function readinessReport( + req: Request, + body: { method?: string; params?: Record } +): string { + const headerVersion = req.headers['mcp-protocol-version']; + const meta = (body.params?._meta ?? {}) as Record; + const gaps = draftProblems(req, body); + // The consent token spells it out: this client led with initialize. + if (req.headers.authorization === `Bearer ${CONSENT_TOKEN}`) { + gaps.unshift( + 'Do not lead with initialize — the stateless draft has no handshake. ' + + 'This client presented the consent token (literally ' + + `'${CONSENT_TOKEN}') minted at the initialize gate, so it opened ` + + 'this session with initialize. Draft clients start with ' + + 'server/discover or any request directly.' + ); + } else if (body.method === 'initialize') { + gaps.unshift( + 'Do not lead with initialize — the stateless draft has no handshake. ' + + 'This request IS an initialize. Draft clients start with ' + + 'server/discover or any request directly.' + ); + } + if (gaps.length === 0) { + return ( + 'DRAFT-READY: this request carries everything the stateless draft ' + + 'protocol requires. Run the strict gauntlet at the parent URL ' + + '(without /lenient) to confirm end to end.' + + (declaresElicitation(meta) ? '' : `\n\n${MRTR_NOTE}`) + ); + } + const intro = + body.method === 'initialize' + ? 'Your client spoke the classic handshake protocol' + + ' — the stateless draft (2026-07-28) has no initialize step.' + : `Your client declared protocol version '${String(headerVersion ?? '(none)')}'.`; + return ( + `DRAFT GAPS (${gaps.length}): ${intro} To be draft-ready it must also fix:\n` + + gaps.map((g, i) => `${i + 1}. ${g}`).join('\n') + + `\n\n${MRTR_NOTE}` + ); +} + +/** Classic SDK server for lenient mode, carrying the gap report. */ +function createLenientClassicServer( + checks: ConformanceCheck[], + req: Request, + body: { method?: string; params?: Record } +): Server { + const server = new Server( + SERVER_INFO, + { + capabilities: { tools: {} }, + instructions: + 'Lenient conformance gauntlet. Call every listed tool with valid ' + + 'arguments; call draft_readiness for an itemized report of what ' + + 'this client must change for the stateless draft protocol.\n\n' + + readinessReport(req, body) + } + ); + + server.setRequestHandler(ListToolsRequestSchema, async () => ({ + // Classic requests carry no per-request capabilities, so MRTR can't be + // capability-gated here the way it is in draft mode — list the + // placeholder unconditionally so the old client discovers the gap. + tools: [ + ...GAUNTLET_TOOLS.map(({ name, description, inputSchema }) => ({ + name, + description, + inputSchema + })), + DRAFT_READINESS_TOOL, + ELICITATION_MISSING_TOOL + ] + })); + + server.setRequestHandler( + CallToolRequestSchema, + async (request): Promise => { + if (request.params.name === DRAFT_READINESS_TOOL.name) { + return { + content: [ + { type: 'text' as const, text: readinessReport(req, body) } + ] + }; + } + if (request.params.name === ELICITATION_MISSING_TOOL.name) { + return { + content: [ + { + type: 'text' as const, + text: `CONFORMANCE NOTE [elicitation_missing]: ${MRTR_NOTE}` + } + ] + }; + } + return runTool( + checks, + request.params.name, + (request.params.arguments ?? {}) as Record, + req, + true + ); + } + ); + + return server; +} + +export class StatelessGauntletScenario extends HandlerScenario { + name = 'checker-2026-07-28'; + description = + 'Single stateless MCP server with validating tools, draft protocol ' + + '(SEP-2575) ONLY. List tools, call each once with valid arguments; any ' + + 'error response tells you what the client got wrong. No run-id and no ' + + 'results polling — every request is judged on its own content. Clients ' + + 'that fall back to a classic version (initialize, or a 2025-* version ' + + 'header) fail with an itemized list of what a draft request carries ' + + 'that theirs did not.'; + readonly source = { introducedIn: '2025-06-18' } as const; + mcpPath = ''; + + private checks: ConformanceCheck[] = []; + + handler(getBaseUrl: () => string): express.Application { + const app = express(); + app.use(express.json()); + app.use(express.urlencoded({ extended: false })); + + // ----------------------------------------------------------------------- + // Consent gate for `initialize` (and only initialize — nothing else is + // auth-gated). An old client leading with initialize gets a 401; its + // OAuth flow lands a human on an HTML page explaining that initialize + // does not exist in the stateless draft. Continuing mints a consent + // token, and a consented classic client is served leniently — so "I + // understand, test anyway" is exactly what the token encodes. This + // mini-AS is a consent-delivery vehicle, NOT an auth conformance test + // (the auth/* scenarios cover that). + // ----------------------------------------------------------------------- + const issuer = () => `${getBaseUrl()}/oauth`; + // PRM URL per RFC 9728, derived from wherever this app is mounted: + // root mount (dedicated checker val) → origin-rooted well-known; + // /x/ mount (hosted runner) → path-suffixed well-known. + const prmUrl = () => { + const base = new URL(getBaseUrl()); + return `${base.origin}/.well-known/oauth-protected-resource${base.pathname === '/' ? '' : base.pathname}`; + }; + + app.get('/.well-known/oauth-protected-resource', (_req, res) => { + res.json({ + resource: getBaseUrl(), + authorization_servers: [issuer()], + bearer_methods_supported: ['header'] + }); + }); + + const asMetadata = (_req: Request, res: Response) => { + res.json({ + issuer: issuer(), + authorization_endpoint: `${issuer()}/authorize`, + token_endpoint: `${issuer()}/token`, + registration_endpoint: `${issuer()}/register`, + response_types_supported: ['code'], + grant_types_supported: ['authorization_code'], + code_challenge_methods_supported: ['S256'], + token_endpoint_auth_methods_supported: ['none'] + }); + }; + app.get('/.well-known/oauth-authorization-server/oauth', asMetadata); + // OIDC-style discovery fallback for clients that only try this form. + app.get('/.well-known/openid-configuration/oauth', asMetadata); + + app.post('/oauth/register', (req, res) => { + res.status(201).json({ + ...req.body, + client_id: 'gauntlet-consent-client', + token_endpoint_auth_method: 'none' + }); + }); + + app.get('/oauth/authorize', (req, res) => { + const query = new URLSearchParams( + req.query as Record + ).toString(); + const continueUrl = `${issuer()}/authorize/continue?${query}`; + res + .status(200) + .type('html') + .send(` +Hold on — initialize? + + +

Hold on — this client led with initialize

+

The client you are testing started its session with an +initialize request. That is invalid in the new +stateless protocol (2026-07-28 / SEP-2575) — there is no handshake; +every request carries the protocol version, client info, and capabilities +itself.

+

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

+

I understand — continue with the test

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

MCP Checker — 2026-07-28

+

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

+ +

How it works

+

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

+
POST ${base}            strict — stateless draft only
+POST ${base}/lenient    advisory — classic clients complete, gaps reported
+ +

What is checked

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

Old clients

+

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

+ +

Try it

+
curl -X POST ${base} \\
+  -H 'content-type: application/json' \\
+  -H 'accept: application/json, text/event-stream' \\
+  -H 'mcp-protocol-version: 2026-07-28' \\
+  -H 'mcp-method: tools/list' \\
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{
+    "io.modelcontextprotocol/protocolVersion":"2026-07-28",
+    "io.modelcontextprotocol/clientInfo":{"name":"my-client","version":"1.0"},
+    "io.modelcontextprotocol/clientCapabilities":{}}}}'
+`); + }); + + return app; + } + + /** + * Draft-2026 dispatch: no lifecycle, plain JSON responses, every request + * self-contained. Transport/draft obligations were already enforced. + */ + private handleDraft( + req: Request, + res: Response, + body: { method?: string; id?: unknown; params?: Record }, + lenient = false + ): void { + const reply = (result: object) => { + // 2026-07-28 makes resultType REQUIRED on every Result; default it here so + // every path is covered, and let callers override (e.g. 'input_required'). + res.json({ + jsonrpc: '2.0', + id: body.id ?? null, + result: { resultType: 'complete', ...result } + }); + }; + + switch (body.method) { + case 'server/discover': + reply({ + ttlMs: 0, + cacheScope: 'public', + supportedVersions: DRAFT_VERSION_ALIASES, + capabilities: { tools: {} }, + serverInfo: SERVER_INFO, + instructions: + 'Call every tool once with valid arguments. Each tool validates ' + + 'the request that carried it; any error explains what your ' + + 'client got wrong.' + }); + return; + + case 'tools/list': { + const meta = (body.params?._meta ?? {}) as Record; + const tools = GAUNTLET_TOOLS.map( + ({ name, description, inputSchema }) => ({ + name, + description, + inputSchema + }) + ); + // MRTR is only part of the contract for clients that can answer + // elicitation requests — gate the listing on the declared capability + // each request carries. Clients without it get a placeholder that + // makes the gap (and how to close it) discoverable. + tools.push( + declaresElicitation(meta) ? MRTR_TOOL : ELICITATION_MISSING_TOOL + ); + if (lenient) tools.push(DRAFT_READINESS_TOOL); + reply({ ttlMs: 0, cacheScope: 'public', tools }); + return; + } + + case 'tools/call': { + const params = (body.params ?? {}) as { + name?: string; + arguments?: Record; + inputResponses?: Record; + requestState?: string; + _meta?: Record; + }; + + if (params.name === DRAFT_READINESS_TOOL.name && lenient) { + reply({ + content: [ + { type: 'text', text: readinessReport(req, body) } + ] + }); + return; + } + + if (params.name === MRTR_TOOL.name) { + reply(this.runMrtr(params, lenient)); + return; + } + + if (params.name === ELICITATION_MISSING_TOOL.name) { + const declared = declaresElicitation( + (params._meta ?? {}) as Record + ); + this.checks.push({ + id: 'gauntlet-elicitation-missing', + name: 'Gauntlet: elicitation capability not declared', + description: + 'Client called the elicitation_missing placeholder tool', + status: 'INFO', + timestamp: new Date().toISOString(), + specReferences: [SPEC_TOOLS], + details: { declared } + }); + reply({ + content: [ + { + type: 'text', + text: declared + ? 'CONFORMANCE NOTE [elicitation_missing]: this request DOES declare the elicitation capability — list tools again and you will see mrtr_confirm instead of this placeholder.' + : '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 ' + + `${META_NS}clientCapabilities as {"elicitation": {}}; the full tool list will then appear.` + } + ] + }); + return; + } + + // MRTR plumbing must not leak onto unrelated calls (SEP-2322). + if ( + params.inputResponses !== undefined || + params.requestState !== undefined + ) { + const detail = + 'inputResponses/requestState MUST only be sent when retrying the ' + + 'tool that returned input_required; they leaked onto ' + + `'${params.name ?? '(none)'}'`; + check( + this.checks, + 'gauntlet-mrtr-leak', + 'Gauntlet: MRTR state leak', + false, + 'MRTR retry fields leaked onto an unrelated tool call', + { detail } + ); + reply({ + content: [ + { type: 'text', text: `CONFORMANCE FAIL [${params.name}]: ${detail}` } + ], + isError: true + }); + return; + } + + reply( + runTool(this.checks, params.name ?? '', params.arguments ?? {}, req) + ); + return; + } + + case 'initialize': + case 'ping': + case 'logging/setLevel': + // Removed from the stateless draft protocol entirely. + res.status(404).json({ + jsonrpc: '2.0', + id: body.id ?? null, + error: { + code: -32601, + message: `Method not found: '${body.method}' does not exist in the stateless draft protocol (use server/discover, not initialize)` + } + }); + return; + + default: + res.status(404).json({ + jsonrpc: '2.0', + id: body.id ?? null, + error: { + code: -32601, + message: `Method not found: '${body.method ?? '(none)'}'. Supported: server/discover, tools/list, tools/call` + } + }); + } + } + + /** + * Two-phase MRTR tool. First call → input_required with a self-contained + * requestState. Retry → validate the echoed state and the elicitation + * response shape, then complete. + */ + private runMrtr( + params: { + inputResponses?: Record; + requestState?: string; + }, + lenient = false + ): object { + if (params.inputResponses === undefined) { + // Round 1: ask for confirmation via elicitation. + return { + resultType: 'input_required', + inputRequests: { + confirm: { + method: 'elicitation/create', + params: { + message: 'Confirm the MRTR round-trip by answering this.', + requestedSchema: { + type: 'object', + properties: { confirmed: { type: 'boolean' } }, + required: ['confirmed'] + } + } + } + }, + requestState: encodeMrtrState() + }; + } + + // Round 2: judge the retry on its own content. + const problems: string[] = []; + if (params.requestState === undefined) { + problems.push( + 'requestState MUST be echoed back unchanged on the retry (SEP-2322)' + ); + } else if (!decodeMrtrState(params.requestState)) { + problems.push( + `requestState was altered — it MUST be echoed back byte-exact; got '${params.requestState.slice(0, 60)}'` + ); + } + const confirm = params.inputResponses.confirm as + | { action?: unknown; content?: { confirmed?: unknown } } + | undefined; + if (!confirm || typeof confirm !== 'object') { + problems.push( + "inputResponses MUST be keyed by the inputRequests key ('confirm')" + ); + } else { + if (confirm.action !== 'accept' && confirm.action !== 'decline' && confirm.action !== 'cancel') { + problems.push( + `elicitation response action MUST be accept/decline/cancel; got ${JSON.stringify(confirm.action)}` + ); + } + if ( + confirm.action === 'accept' && + typeof confirm.content?.confirmed !== 'boolean' + ) { + problems.push( + `accepted elicitation content MUST match requestedSchema ({confirmed: boolean}); got ${JSON.stringify(confirm.content)}` + ); + } + } + + const ok = problems.length === 0; + const detail = ok + ? `requestState echoed intact; elicitation response valid (action=${String((params.inputResponses.confirm as { action?: unknown })?.action)})` + : problems.join('; '); + check( + this.checks, + 'gauntlet-mrtr_confirm', + 'Gauntlet: mrtr_confirm', + ok, + ok + ? 'Client completed the MRTR round-trip conformantly' + : 'Client MRTR retry was not conformant', + { detail }, + lenient ? 'WARNING' : 'FAILURE' + ); + if (!ok) { + return { + content: [ + { type: 'text', text: `CONFORMANCE FAIL [mrtr_confirm]: ${detail}` } + ], + isError: true + }; + } + return { + content: [ + { type: 'text', text: `CONFORMANCE OK [mrtr_confirm]: ${detail}` } + ] + }; + } + + getChecks(): ConformanceCheck[] { + return this.checks; + } +} diff --git a/src/scenarios/index.ts b/src/scenarios/index.ts index 1422c90e..0c96d9d6 100644 --- a/src/scenarios/index.ts +++ b/src/scenarios/index.ts @@ -11,6 +11,8 @@ import { } from '../types'; import { InitializeScenario } from './client/initialize'; import { ToolsCallScenario } from './client/tools_call'; +import { StatelessGauntletScenario } from './client/stateless-gauntlet'; +import { AuthCheckerScenario } from './client/auth-checker'; import { ElicitationClientDefaultsScenario } from './client/elicitation-defaults'; import { SSERetryScenario } from './client/sse-retry'; import { RequestMetadataScenario } from './client/request-metadata'; @@ -269,7 +271,13 @@ const scenariosList: Scenario[] = [ new HttpInvalidToolHeadersScenario(), // JSON Schema network $ref dereferencing (SEP-2106) - new JsonSchemaRefDerefScenario() + new JsonSchemaRefDerefScenario(), + + // Stateless gauntlet — single server, validating tools, no run-id needed + new StatelessGauntletScenario(), + + // Auth re-auth chain checker — token encodes progress through the rungs + new AuthCheckerScenario() ]; // Core scenarios (tier 1 requirements) diff --git a/src/types.ts b/src/types.ts index e4aa9c6b..6b13e883 100644 --- a/src/types.ts +++ b/src/types.ts @@ -130,6 +130,14 @@ export interface Scenario { start(): Promise; stop(): Promise; getChecks(): ConformanceCheck[]; + /** + * Checks recorded so far WITHOUT end-of-flow finalization. Some scenarios' + * `getChecks()` appends aggregate failures for flow steps never observed + * ("expected check missing"); those judgments are only meaningful when one + * instance saw the whole flow. Stateless mounting (`/x/...`) judges each + * request on its own content, so it reads this view when present. + */ + rawChecks?(): ConformanceCheck[]; } /** From 7f9adaf06fe486589a445bd81ad0694a4a071de6 Mon Sep 17 00:00:00 2001 From: Paul Carleton Date: Mon, 7 Sep 2026 12:10:01 +0000 Subject: [PATCH 5/9] hosted: persist runs across serverless isolates (RunStore) + val.town SQLite store val.town load-balances one run's requests across short-lived isolates, so GET /results on the in-memory server flapped between "unknown run", an empty check list and the real one depending on which isolate answered. - src/hosted/store.ts: RunStore interface (+ MemoryRunStore). Each process writes its raw check log through after every request, keyed by (run, writer) and replaced wholesale so concurrent writers never clobber; run metadata is persisted so a cold process can rebuild handlers. - SessionManager: optional store, ensure() (used by the /__aux relay backchannel), persist()/flush(), and results() that merges every writer's log and re-judges it once with a fresh scenario instance (finalizeChecks) instead of trusting one process's getChecks(). - server.ts: results routes and meta get_results go through the merged view; RS-side PRM well-known uses getOrCreate; dispatch writes through on res.end when a store is configured; minted context carries the scenario name so it can be passed verbatim as MCP_CONFORMANCE_CONTEXT. - examples/hosted/valtown-store.ts: SqliteRunStore on the account SQLite API (6h retention, swept on run creation). valtown.ts wires it up and awaits sessions.flush() before returning each response so the last request's write isn't abandoned when the isolate idles. - json-schema-ref-no-deref: keep observed state in the raw log as _state/* INFO events (+ rawChecks()) so it is multi-process safe. - everything-client: tools_call alias and actually call the tool. - valtown-manifest: client-rs / client-relay vals. --- .../clients/typescript/everything-client.ts | 14 +- examples/hosted/valtown-manifest.json | 12 ++ examples/hosted/valtown-store.ts | 150 ++++++++++++++++++ examples/hosted/valtown.ts | 15 +- src/hosted/hosted-auth.test.ts | 1 + src/hosted/server.ts | 89 ++++++++--- src/hosted/session.ts | 149 ++++++++++++++++- src/hosted/store.ts | 67 ++++++++ src/scenarios/client/json-schema-ref-deref.ts | 46 ++++-- 9 files changed, 498 insertions(+), 45 deletions(-) create mode 100644 examples/hosted/valtown-store.ts create mode 100644 src/hosted/store.ts diff --git a/examples/clients/typescript/everything-client.ts b/examples/clients/typescript/everything-client.ts index 0854a4f5..3f2bdb12 100644 --- a/examples/clients/typescript/everything-client.ts +++ b/examples/clients/typescript/everything-client.ts @@ -84,14 +84,20 @@ async function runBasicClient(serverUrl: string): Promise { await client.connect(transport); logger.debug('Successfully connected to MCP server'); - await client.listTools(); + const list = await client.listTools(); logger.debug('Successfully listed tools'); + const tool = list.tools[0]; + if (tool) { + await client.callTool({ name: tool.name, arguments: { a: 2, b: 3 } }); + logger.debug('Successfully called tool'); + } + await transport.close(); logger.debug('Connection closed successfully'); } -registerScenarios(['initialize', 'tools-call'], runBasicClient); +registerScenarios(['initialize', 'tools_call', 'tools-call'], runBasicClient); // SEP-2106: json-schema-ref-no-deref advertises a tool whose inputSchema // contains a network-URI $ref. A conformant client lists tools normally and @@ -175,9 +181,7 @@ function answerInputRequests( return Object.fromEntries( Object.entries(inputRequests).map(([key, request]) => { if (request.method !== 'elicitation/create') { - throw new Error( - `unsupported input request method '${request.method}'` - ); + throw new Error(`unsupported input request method '${request.method}'`); } return [key, { action: 'accept', content: { confirmed: true } }]; }) diff --git a/examples/hosted/valtown-manifest.json b/examples/hosted/valtown-manifest.json index 46d2608d..141861ea 100644 --- a/examples/hosted/valtown-manifest.json +++ b/examples/hosted/valtown-manifest.json @@ -23,6 +23,18 @@ "entry": "examples/hosted/valtown-auth-checker.ts", "privacy": "public", "id": "53e9c5a5-9ad2-49d4-8b60-3a683d1de202" + }, + "client-rs": { + "name": "mcp-client-conformance", + "entry": "examples/hosted/valtown.ts", + "privacy": "unlisted", + "id": "92c705de-6b43-49f6-bcb4-a55337aa0cb7" + }, + "client-relay": { + "name": "mcp-client-conformance-as", + "entry": "examples/hosted/valtown-relay.ts", + "privacy": "unlisted", + "id": "81046d9c-cff3-4abf-bb0d-9e454f8f5316" } } } diff --git a/examples/hosted/valtown-store.ts b/examples/hosted/valtown-store.ts new file mode 100644 index 00000000..2743394d --- /dev/null +++ b/examples/hosted/valtown-store.ts @@ -0,0 +1,150 @@ +/** + * RunStore backed by val.town's per-account SQLite (REST API). + * + * val.town injects an API token into every val as the `valtown` env var; the + * SQLite API is `POST /v1/sqlite/execute {statement:{sql,args}}`. Two tables, + * created lazily once per isolate. Old runs are swept on new-run creation, + * throttled per isolate, so the database stays bounded without a cron. + */ + +import type { ConformanceCheck } from '../../src/types'; +import type { RunStore } from '../../src/hosted/store'; + +const API = 'https://api.val.town/v1/sqlite/execute'; + +export interface SqliteRunStoreOptions { + token?: string; + /** Runs older than this are swept. Default 6h. */ + retentionMs?: number; + /** Cap on checks persisted per (run, writer). Default 1000. */ + maxChecks?: number; +} + +type Row = unknown[]; + +export class SqliteRunStore implements RunStore { + private readonly token: string; + private readonly retentionMs: number; + private readonly maxChecks: number; + private ready: Promise | undefined; + private lastSweep = 0; + + constructor(opts: SqliteRunStoreOptions = {}) { + const token = opts.token ?? process.env.valtown; + if (!token) + throw new Error('SqliteRunStore: no val.town token (env valtown)'); + this.token = token; + this.retentionMs = + opts.retentionMs ?? + Number(process.env.CONFORMANCE_RUN_RETENTION_MS ?? 6 * 3600_000); + this.maxChecks = opts.maxChecks ?? 1000; + } + + private async exec(sql: string, args: unknown[] = []): Promise { + const res = await fetch(API, { + method: 'POST', + headers: { + Authorization: `Bearer ${this.token}`, + 'Content-Type': 'application/json' + }, + body: JSON.stringify({ statement: { sql, args } }) + }); + if (!res.ok) { + throw new Error( + `sqlite ${res.status}: ${(await res.text()).slice(0, 200)}` + ); + } + const body = (await res.json()) as { rows?: Row[] }; + return body.rows ?? []; + } + + private init(): Promise { + this.ready ??= (async () => { + await this.exec( + `CREATE TABLE IF NOT EXISTS hosted_runs_v2 ( + id TEXT PRIMARY KEY, scenario TEXT NOT NULL, created_at INTEGER NOT NULL)` + ); + await this.exec( + `CREATE TABLE IF NOT EXISTS hosted_checks_v2 ( + run_id TEXT NOT NULL, writer TEXT NOT NULL, checks TEXT NOT NULL, + updated_at INTEGER NOT NULL, PRIMARY KEY (run_id, writer))` + ); + })().catch((e) => { + this.ready = undefined; + throw e; + }); + return this.ready; + } + + async saveRun(id: string, scenarioName: string): Promise { + await this.init(); + await this.exec( + `INSERT INTO hosted_runs_v2 (id, scenario, created_at) VALUES (?, ?, ?) + ON CONFLICT(id) DO UPDATE SET scenario = excluded.scenario`, + [id, scenarioName, Date.now()] + ); + void this.sweep().catch(() => {}); + } + + async loadRun(id: string): Promise { + await this.init(); + const rows = await this.exec( + `SELECT scenario FROM hosted_runs_v2 WHERE id = ?`, + [id] + ); + return rows[0]?.[0] as string | undefined; + } + + async saveChecks( + id: string, + writer: string, + checks: ConformanceCheck[] + ): Promise { + await this.init(); + await this.exec( + `INSERT INTO hosted_checks_v2 (run_id, writer, checks, updated_at) + VALUES (?, ?, ?, ?) + ON CONFLICT(run_id, writer) DO UPDATE + SET checks = excluded.checks, updated_at = excluded.updated_at`, + [id, writer, JSON.stringify(checks.slice(-this.maxChecks)), Date.now()] + ); + } + + async loadChecks(id: string): Promise> { + await this.init(); + const rows = await this.exec( + `SELECT writer, checks FROM hosted_checks_v2 WHERE run_id = ?`, + [id] + ); + const out = new Map(); + for (const [writer, checks] of rows) { + try { + out.set(writer as string, JSON.parse(checks as string)); + } catch { + // corrupt row — ignore + } + } + return out; + } + + async deleteRun(id: string): Promise { + await this.init(); + await this.exec(`DELETE FROM hosted_checks_v2 WHERE run_id = ?`, [id]); + await this.exec(`DELETE FROM hosted_runs_v2 WHERE id = ?`, [id]); + } + + private async sweep(): Promise { + const now = Date.now(); + if (now - this.lastSweep < 5 * 60_000) return; + this.lastSweep = now; + const cutoff = now - this.retentionMs; + await this.exec( + `DELETE FROM hosted_checks_v2 WHERE run_id IN + (SELECT id FROM hosted_runs_v2 WHERE created_at < ?)`, + [cutoff] + ); + await this.exec(`DELETE FROM hosted_runs_v2 WHERE created_at < ?`, [ + cutoff + ]); + } +} diff --git a/examples/hosted/valtown.ts b/examples/hosted/valtown.ts index 16be5fa2..7efc26da 100644 --- a/examples/hosted/valtown.ts +++ b/examples/hosted/valtown.ts @@ -22,6 +22,7 @@ import { createHostedApp } from '../../src/hosted/server'; import { toFetchHandler } from './fetch-bridge'; +import { SqliteRunStore } from './valtown-store'; const NOT_FETCH_SAFE = new Set(['sse-retry']); @@ -29,13 +30,16 @@ const NOT_FETCH_SAFE = new Set(['sse-retry']); // origin-rooted). Deploy examples/hosted/valtown-relay.ts as a separate val // and point CONFORMANCE_AS_ORIGIN at it; both vals share // CONFORMANCE_RELAY_SECRET so /__aux can't be hit directly. -const { app } = createHostedApp({ +const { app, sessions } = createHostedApp({ auxOrigins: { as: process.env.CONFORMANCE_AS_ORIGIN, as2: process.env.CONFORMANCE_AS2_ORIGIN, idp: process.env.CONFORMANCE_IDP_ORIGIN }, - relaySecret: process.env.CONFORMANCE_RELAY_SECRET + relaySecret: process.env.CONFORMANCE_RELAY_SECRET, + // val.town spreads one run's requests over several isolates; persist to + // the account's SQLite so /results is the union of what they all saw. + store: process.env.valtown ? new SqliteRunStore() : undefined }); const bridge = toFetchHandler(app); @@ -54,5 +58,10 @@ export default async function (request: Request): Promise { ); } - return bridge(request); + const response = await bridge(request); + // The bridge buffers until end(), by which point the scenario has recorded + // its checks and the write-through has started; finish it before the + // isolate is allowed to go idle. + await sessions.flush(); + return response; } diff --git a/src/hosted/hosted-auth.test.ts b/src/hosted/hosted-auth.test.ts index 7aacfa2a..1461fd02 100644 --- a/src/hosted/hosted-auth.test.ts +++ b/src/hosted/hosted-auth.test.ts @@ -188,6 +188,7 @@ describe('hosted auth scenarios (RS + AS relay)', () => { r.json() ); expect(r.context).toEqual({ + name: 'auth/pre-registration', client_id: 'pre-registered-client', client_secret: 'pre-registered-secret' }); diff --git a/src/hosted/server.ts b/src/hosted/server.ts index 70ff6a53..a8cb19fc 100644 --- a/src/hosted/server.ts +++ b/src/hosted/server.ts @@ -38,6 +38,7 @@ import { listHostableScenarios } from './session'; import { renderLanding, renderResults } from './html'; +import type { RunStore } from './store'; import { getScenario } from '../scenarios'; import { ConformanceCheck, @@ -62,6 +63,12 @@ export interface HostedServerOptions { * the same value in the relay's env. */ relaySecret?: string; + /** + * Persist runs so a deployment that load-balances one run's requests + * across processes (serverless isolates) still serves complete results. + * See ./store.ts. Omit for a single long-lived process. + */ + store?: RunStore; } /** Only allow run-ids that are safe in a single path segment. */ @@ -174,7 +181,11 @@ export function createHostedApp(opts: HostedServerOptions = {}): { } { const auxOrigins = opts.auxOrigins ?? {}; const haveAux = AUX_ROLES.filter((r) => auxOrigins[r]); - const sessions = new SessionManager({ ttlMs: opts.ttlMs, auxOrigins }); + const sessions = new SessionManager({ + ttlMs: opts.ttlMs, + auxOrigins, + store: opts.store + }); const app = express(); const hostable = new Set(listHostableScenarios(haveAux)); @@ -231,6 +242,18 @@ export function createHostedApp(opts: HostedServerOptions = {}): { `<${origin(req)}/results/${run.id}>; rel="conformance-results"` ); req.url = rewrittenUrl; + if (sessions.store) { + // Write this process's view through once the scenario has answered + // (hosted scenarios record their checks before calling end()). + // Serverless entry points should await sessions.flush() before + // returning the response so this write isn't abandoned. + const end = res.end; + res.end = function (this: Response, ...args: unknown[]) { + const out = (end as (...a: unknown[]) => Response).apply(this, args); + void sessions.persist(run); + return out; + } as Response['end']; + } listener(req, res); } @@ -300,7 +323,7 @@ export function createHostedApp(opts: HostedServerOptions = {}): { mcpUrl: `${runBaseUrl(req, scenarioName, run.id)}${run.mcpPath}`, resultsUrl: `${origin(req)}/results/${run.id}`, resultsHtmlUrl: `${origin(req)}/results/${run.id}.html`, - context: run.context + context: contextFor(run) }); } catch (e) { next(e); @@ -567,8 +590,14 @@ export function createHostedApp(opts: HostedServerOptions = {}): { res.status(404).json({ error: 'no run for this resource path' }); return; } - const run = sessions.get(resolved.runId); - if (!run) { + // getOrCreate, not get: on a multi-process host this may be the first + // request this process sees for the run. + let run; + try { + run = sessions.getOrCreate(resolved.scenarioName, resolved.runId, (id) => + runBaseUrl(req, resolved.scenarioName, id) + ); + } catch { res.status(404).json({ error: 'no run for this resource path' }); return; } @@ -663,7 +692,9 @@ export function createHostedApp(opts: HostedServerOptions = {}): { return; } - const run = sessions.get(runId); + const run = await sessions.ensure(runId, (s, id) => + runBaseUrl(req, s, id) + ); const listener = run?.auxListeners?.[role]; if (!run || !listener) { res.status(404).json({ error: `no aux '${role}' handler for run` }); @@ -675,27 +706,27 @@ export function createHostedApp(opts: HostedServerOptions = {}): { // ---------- results ---------- - app.get('/results/:id.html', (req, res) => { - const run = sessions.get(req.params.id); - const checks = sessions.results(req.params.id); - if (!run || !checks) { + app.get('/results/:id.html', async (req, res) => { + const r = await sessions.results(req.params.id); + if (!r) { res .status(404) .type('html') - .send(`

No run ${req.params.id}

`); + .send(`

No run ${escapeId(req.params.id)}

`); return; } - res.type('html').send(renderResults(run.scenarioName, run.id, checks)); + res + .type('html') + .send(renderResults(r.scenarioName, req.params.id, r.checks)); }); - app.get('/results/:id', (req, res) => { - const run = sessions.get(req.params.id); - const checks = sessions.results(req.params.id); - if (!run || !checks) { + app.get('/results/:id', async (req, res) => { + const r = await sessions.results(req.params.id); + if (!r) { res.status(404).json({ error: 'unknown run' }); return; } - res.json(summarise(run.scenarioName, run.id, checks)); + res.json(summarise(r.scenarioName, req.params.id, r.checks)); }); app.delete('/results/:id', async (req, res) => { @@ -828,7 +859,7 @@ function createMetaMcpServer( mcpUrl: `${runBaseUrl(run.scenarioName, run.id)}${run.mcpPath}`, resultsUrl: `${publicOrigin}/results/${run.id}`, resultsHtmlUrl: `${publicOrigin}/results/${run.id}.html`, - context: run.context + context: contextFor(run) }, null, 2 @@ -846,11 +877,14 @@ function createMetaMcpServer( } case 'get_results': { - const run = sessions.get(args.run_id); - const checks = sessions.results(args.run_id); - if (!run || !checks) return errorText(`no run '${args.run_id}'`); + const r = await sessions.results(args.run_id); + if (!r) return errorText(`no run '${args.run_id}'`); return text( - JSON.stringify(summarise(run.scenarioName, run.id, checks), null, 2) + JSON.stringify( + summarise(r.scenarioName, args.run_id, r.checks), + null, + 2 + ) ); } @@ -863,6 +897,19 @@ function createMetaMcpServer( return server; } +/** + * The context blob a client-under-test needs (pre-registered credentials + * etc.), tagged with the scenario name the way the CLI runner's + * MCP_CONFORMANCE_CONTEXT is, so it can be passed through verbatim. + */ +function contextFor(run: HostedRun): Record | undefined { + return run.context ? { name: run.scenarioName, ...run.context } : undefined; +} + +function escapeId(id: string): string { + return id.replace(/[^A-Za-z0-9_-]/g, ''); +} + function text(t: string): CallToolResult { return { content: [{ type: 'text', text: t }] }; } diff --git a/src/hosted/session.ts b/src/hosted/session.ts index 306d5b23..02b362cc 100644 --- a/src/hosted/session.ts +++ b/src/hosted/session.ts @@ -17,6 +17,7 @@ import { AuxOriginRole } from '../types'; import { getScenario, scenarios } from '../scenarios'; +import type { RunStore } from './store'; export interface HostedRun { id: string; @@ -43,6 +44,55 @@ export interface SessionManagerOptions { * URL (no trailing slash); per-run AS issuer becomes `/r/`. */ auxOrigins?: Partial>; + /** + * Optional persistence so runs survive being load-balanced across + * processes (serverless isolates). Omit for a single long-lived process. + */ + store?: RunStore; +} + +/** Results view: the scenario a run belongs to plus its judged checks. */ +export interface RunResults { + scenarioName: string; + checks: ConformanceCheck[]; +} + +/** + * The scenario's raw event log — what it actually observed — as opposed to + * getChecks(), which for most client scenarios also appends "expected X, + * never saw it" FAILUREs (and mutates). Persisting the raw log per process + * and judging the merged log once is what makes multi-process hosting work. + */ +export function rawChecksOf(scenario: Scenario): ConformanceCheck[] { + if (scenario.rawChecks) return scenario.rawChecks(); + const bag = (scenario as unknown as { checks?: unknown }).checks; + if (Array.isArray(bag)) return bag as ConformanceCheck[]; + return scenario.getChecks(); +} + +/** + * Judge a merged raw log with the scenario's own end-of-run logic by loading + * it into a fresh instance. Falls back to the raw log for scenarios that + * don't keep a plain `checks` array. + */ +export function finalizeChecks( + scenarioName: string, + merged: ConformanceCheck[] +): ConformanceCheck[] { + const proto = getScenario(scenarioName); + if (!proto) return merged; + try { + const Ctor = proto.constructor as new () => Scenario; + const fresh = new Ctor() as unknown as { + checks?: unknown; + getChecks(): ConformanceCheck[]; + }; + if (!Array.isArray(fresh.checks)) return merged; + fresh.checks = merged.map((c) => ({ ...c })); + return fresh.getChecks(); + } catch { + return merged; + } } export class SessionManager { @@ -50,10 +100,15 @@ export class SessionManager { private readonly ttlMs: number; private readonly auxOrigins: Partial>; private sweeper: ReturnType; + readonly store: RunStore | undefined; + private pending = new Set>(); + /** Identifies this process's rows in the store. */ + readonly writerId = randomBytes(4).toString('hex'); constructor(opts: SessionManagerOptions = {}) { this.ttlMs = opts.ttlMs ?? 5 * 60_000; this.auxOrigins = opts.auxOrigins ?? {}; + this.store = opts.store; const sweepIntervalMs = opts.sweepIntervalMs ?? 30_000; this.sweeper = setInterval(() => this.sweep(), sweepIntervalMs); this.sweeper.unref?.(); @@ -129,6 +184,7 @@ export class SessionManager { context }; this.runs.set(runId, run); + void this.store?.saveRun(runId, scenarioName).catch(logStoreError); return run; } @@ -138,16 +194,94 @@ export class SessionManager { return r; } - results(id: string): ConformanceCheck[] | undefined { - return this.runs.get(id)?.scenario.getChecks(); + /** + * Like get(), but if this process has never seen the run and a store is + * configured, rebuild it from persisted metadata. This is how an aux-origin + * request or a results page lands correctly on a cold process. + */ + async ensure( + id: string, + baseUrlFor: (scenarioName: string, runId: string) => string + ): Promise { + const local = this.get(id); + if (local || !this.store) return local; + let scenarioName: string | undefined; + try { + scenarioName = await this.store.loadRun(id); + } catch (e) { + logStoreError(e); + } + if (!scenarioName) return undefined; + return this.getOrCreate(scenarioName, id, (rid) => + baseUrlFor(scenarioName, rid) + ); + } + + /** Write this process's view of a run's checks through to the store. */ + persist(run: HostedRun): Promise { + if (!this.store) return Promise.resolve(); + const p = this.store + .saveChecks( + run.id, + this.writerId, + rawChecksOf(run.scenario).map((c) => ({ ...c })) + ) + .catch(logStoreError) + .finally(() => this.pending.delete(p)); + this.pending.add(p); + return p; + } + + /** + * Resolve once every in-flight persist() has settled. Serverless entry + * points await this before handing back the response so the write isn't + * abandoned when the isolate is frozen after responding. + */ + async flush(): Promise { + while (this.pending.size) await Promise.all(Array.from(this.pending)); + } + + /** + * Judged checks for a run. Without a store this is the scenario's own + * getChecks(). With a store it is every process's raw log merged (this + * process's live log wins over its own persisted row) and re-judged once. + */ + async results(id: string): Promise { + const run = this.runs.get(id); + if (!this.store) { + return run + ? { scenarioName: run.scenarioName, checks: run.scenario.getChecks() } + : undefined; + } + let byWriter = new Map(); + try { + byWriter = await this.store.loadChecks(id); + } catch (e) { + logStoreError(e); + } + if (run) byWriter.set(this.writerId, rawChecksOf(run.scenario)); + let scenarioName = run?.scenarioName; + if (!scenarioName) { + try { + scenarioName = await this.store.loadRun(id); + } catch (e) { + logStoreError(e); + } + } + if (!scenarioName) return undefined; + const merged = Array.from(byWriter.values()) + .flat() + .sort((a, b) => (a.timestamp ?? '').localeCompare(b.timestamp ?? '')); + return { scenarioName, checks: finalizeChecks(scenarioName, merged) }; } list(): HostedRun[] { return Array.from(this.runs.values()); } - async destroy(id: string): Promise { + async destroy(id: string, fromStore = true): Promise { const r = this.runs.get(id); + if (fromStore) void this.store?.deleteRun(id).catch(logStoreError); if (!r) return; this.runs.delete(id); // handler() never started a server, but some scenarios hold timers/streams @@ -162,18 +296,23 @@ export class SessionManager { async close(): Promise { clearInterval(this.sweeper); await Promise.all( - Array.from(this.runs.keys()).map((id) => this.destroy(id)) + Array.from(this.runs.keys()).map((id) => this.destroy(id, false)) ); } private sweep(): void { const now = Date.now(); for (const [id, r] of this.runs) { - if (now - r.lastSeenAt > this.ttlMs) void this.destroy(id); + // Local eviction only — the store has its own retention. + if (now - r.lastSeenAt > this.ttlMs) void this.destroy(id, false); } } } +function logStoreError(e: unknown): void { + console.error('[hosted] run store:', e instanceof Error ? e.message : e); +} + export class UnknownScenarioError extends Error { constructor(name: string) { super( diff --git a/src/hosted/store.ts b/src/hosted/store.ts new file mode 100644 index 00000000..51ba4f9f --- /dev/null +++ b/src/hosted/store.ts @@ -0,0 +1,67 @@ +/** + * Run persistence for the hosted conformance server. + * + * A long-lived Node process keeps every run in memory and needs none of this. + * Serverless hosts (val.town, Deno Deploy, …) load-balance one run's requests + * across short-lived isolates, so the isolate that answers GET /results is + * often not the one that saw the MCP traffic. A RunStore lets each isolate + * write through what it observed and lets any isolate serve a merged view: + * + * - run metadata (id → scenario) so an isolate that never saw the run can + * still rebuild its handlers (aux-origin requests, results pages); + * - checks, keyed by (run, writer): each isolate owns its own row and + * replaces it wholesale after every request, so concurrent writers never + * clobber each other and no append ordering is needed. + * + * The merged log is re-judged at results time by a fresh scenario instance + * (see SessionManager.results), which is what turns "isolate B never saw a + * tools/call" from a false FAILURE into the union of what A and B saw. + */ + +import type { ConformanceCheck } from '../types'; + +export interface RunStore { + saveRun(id: string, scenarioName: string): Promise; + /** Scenario name for a run id, or undefined if no isolate ever saw it. */ + loadRun(id: string): Promise; + saveChecks( + id: string, + writer: string, + checks: ConformanceCheck[] + ): Promise; + /** All writers' check lists for a run, keyed by writer id. */ + loadChecks(id: string): Promise>; + deleteRun(id: string): Promise; +} + +/** In-process store — used by tests to exercise the merge path. */ +export class MemoryRunStore implements RunStore { + private runs = new Map(); + private checks = new Map>(); + + async saveRun(id: string, scenarioName: string): Promise { + if (!this.runs.has(id)) this.runs.set(id, scenarioName); + } + async loadRun(id: string): Promise { + return this.runs.get(id); + } + async saveChecks( + id: string, + writer: string, + checks: ConformanceCheck[] + ): Promise { + let byWriter = this.checks.get(id); + if (!byWriter) this.checks.set(id, (byWriter = new Map())); + byWriter.set( + writer, + checks.map((c) => ({ ...c })) + ); + } + async loadChecks(id: string): Promise> { + return new Map(this.checks.get(id) ?? []); + } + async deleteRun(id: string): Promise { + this.runs.delete(id); + this.checks.delete(id); + } +} diff --git a/src/scenarios/client/json-schema-ref-deref.ts b/src/scenarios/client/json-schema-ref-deref.ts index 13f5b773..bdb3d9f8 100644 --- a/src/scenarios/client/json-schema-ref-deref.ts +++ b/src/scenarios/client/json-schema-ref-deref.ts @@ -25,6 +25,8 @@ import { HandlerScenario, DRAFT_PROTOCOL_VERSION } from '../../types'; const TOOL_NAME = 'lookup_user'; const CANARY_PATH = '/canary/profile-schema.json'; +const TOOLS_LISTED_EVENT = '_state/tools-listed'; +const CANARY_EVENT = '_state/canary-fetched'; const CHECK_ID = 'sep-2106-no-network-ref-deref'; const SPEC_REFERENCES = [ @@ -78,12 +80,30 @@ export class JsonSchemaRefDerefScenario extends HandlerScenario { The 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.`; mcpPath = '/mcp'; - private canaryRequests: Array<{ method: string; userAgent?: string }> = []; - private toolsListed = false; + /** + * Raw event log. What the scenario observed is kept as INFO events here + * (rather than in private fields) so a host that spreads one run over + * several processes can merge the logs and judge once — see rawChecks(). + */ + checks: ConformanceCheck[] = []; + + private record(id: string, details?: Record): void { + this.checks.push({ + id, + name: id, + description: id, + status: 'INFO', + timestamp: new Date().toISOString(), + details + }); + } + + rawChecks(): ConformanceCheck[] { + return this.checks; + } handler(getBaseUrl: () => string): RequestListener { - this.canaryRequests = []; - this.toolsListed = false; + this.checks = []; const app = express(); app.use(express.json()); @@ -92,7 +112,7 @@ The scenario advertises a tool whose inputSchema contains a \`$ref\` pointing at // network $ref. Return a valid schema so a dereferencing client gets a // realistic response rather than an error it might silently swallow. app.all(CANARY_PATH, (req: Request, res: Response) => { - this.canaryRequests.push({ + this.record(CANARY_EVENT, { method: req.method, userAgent: req.headers['user-agent'] }); @@ -108,7 +128,7 @@ The scenario advertises a tool whose inputSchema contains a \`$ref\` pointing at // Stateless: fresh server and transport per request const canaryUrl = `${getBaseUrl()}${CANARY_PATH}`; const server = createMcpServer(canaryUrl, () => { - this.toolsListed = true; + this.record(TOOLS_LISTED_EVENT); }); const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined @@ -136,9 +156,13 @@ The scenario advertises a tool whose inputSchema contains a \`$ref\` pointing at // Built fresh on every call so getChecks() is idempotent — the runner may // call it more than once and we must not accumulate duplicates. const timestamp = new Date().toISOString(); - const fetched = this.canaryRequests.length > 0; + const canaryRequests = this.checks + .filter((c) => c.id === CANARY_EVENT) + .map((c) => c.details ?? {}); + const toolsListed = this.checks.some((c) => c.id === TOOLS_LISTED_EVENT); + const fetched = canaryRequests.length > 0; - if (!this.toolsListed) { + if (!toolsListed) { return [ { id: CHECK_ID, @@ -165,13 +189,13 @@ The scenario advertises a tool whose inputSchema contains a \`$ref\` pointing at status: fetched ? 'FAILURE' : 'SUCCESS', timestamp, errorMessage: fetched - ? `Canary URL ${CANARY_PATH} was fetched ${this.canaryRequests.length} time(s)` + ? `Canary URL ${CANARY_PATH} was fetched ${canaryRequests.length} time(s)` : undefined, specReferences: SPEC_REFERENCES, details: { toolsListed: true, - canaryRequestCount: this.canaryRequests.length, - canaryRequests: this.canaryRequests + canaryRequestCount: canaryRequests.length, + canaryRequests } } ]; From 4cbb1caba95996071c6f4ef3b1db13e60e47e635 Mon Sep 17 00:00:00 2001 From: Paul Carleton Date: Mon, 7 Sep 2026 12:13:16 +0000 Subject: [PATCH 6/9] steps: declarative client steering for plumbing-only scenarios First slice of "generic steering" for client conformance: a scenario may declare the client-side choreography it needs as data, the runner ships it in MCP_CONFORMANCE_CONTEXT as `steps`, and a client with no bespoke handler for the scenario name interprets it. Checks stay in the scenario; only the instructions to the client under test become data. - src/steps: closed op set (tools/list, tools/call, wait, disconnect) as a zod schema, one `$from` capture form, resolveFrom/resolveArguments. - Scenario.steps (types.ts); declared on initialize, tools_call, json-schema-ref-no-deref and elicitation-sep1034-client-defaults. - runner/client.ts merges steps into the context blob; the hosted server does the same for minted runs and lists steps on / and /scenarios. - everything-client: fallback interpreter (standing defaults: connect first, accept elicitation with schema defaults, disconnect last). Named handlers still win; MCP_CONFORMANCE_FORCE_STEPS=1 forces the generic path so it can be exercised against scenarios that also have handlers. --- .../clients/typescript/everything-client.ts | 78 ++++++++++++- src/hosted/html.ts | 27 ++++- src/hosted/server.ts | 13 ++- src/hosted/session.ts | 3 + src/runner/client.ts | 12 +- src/scenarios/client/elicitation-defaults.ts | 13 +++ src/scenarios/client/initialize.ts | 3 + src/scenarios/client/json-schema-ref-deref.ts | 2 + src/scenarios/client/tools_call.ts | 5 + src/steps/index.test.ts | 61 +++++++++++ src/steps/index.ts | 103 ++++++++++++++++++ src/types.ts | 8 ++ 12 files changed, 317 insertions(+), 11 deletions(-) create mode 100644 src/steps/index.test.ts create mode 100644 src/steps/index.ts diff --git a/examples/clients/typescript/everything-client.ts b/examples/clients/typescript/everything-client.ts index 3f2bdb12..849dbc17 100644 --- a/examples/clients/typescript/everything-client.ts +++ b/examples/clients/typescript/everything-client.ts @@ -21,6 +21,12 @@ import { } from '@modelcontextprotocol/sdk/client/auth-extensions.js'; import { ElicitRequestSchema } from '@modelcontextprotocol/sdk/types.js'; import { ClientConformanceContextSchema } from '../../../src/schemas/context.js'; +import { + StepsSchema, + resolveArguments, + type Captures, + type Step +} from '../../../src/steps/index.js'; import { auth, extractWWWAuthenticateParams @@ -1123,6 +1129,68 @@ registerScenario('sep-2322-client-request-state', runMRTRClient); // Main entry point // ============================================================================ +// ============================================================================ +// Generic steering: fallback interpreter for scenarios that ship `steps` +// ============================================================================ +// +// A scenario with no bespoke handler here can still be driven if the runner +// put `steps` in MCP_CONFORMANCE_CONTEXT (see src/steps). The op set is +// closed; standing defaults: connect first, accept elicitation with schema +// defaults, disconnect at the end. + +function stepsFromContext(): Step[] | undefined { + const raw = process.env.MCP_CONFORMANCE_CONTEXT; + if (!raw) return undefined; + try { + const parsed = StepsSchema.safeParse(JSON.parse(raw).steps); + return parsed.success ? parsed.data : undefined; + } catch { + return undefined; + } +} + +async function runSteps(serverUrl: string, steps: Step[]): Promise { + const client = new Client( + { name: 'conformance-generic-client', version: '1.0.0' }, + { capabilities: { elicitation: { applyDefaults: true } } } + ); + // Standing default: if the server asks, accept with schema defaults. + client.setRequestHandler(ElicitRequestSchema, async () => ({ + action: 'accept' as const, + content: {} + })); + + const transport = new StreamableHTTPClientTransport(new URL(serverUrl)); + await client.connect(transport); + logger.debug(`steps: connected, running ${steps.length} step(s)`); + + const captures: Captures = {}; + let connected = true; + for (const step of steps) { + logger.debug('step:', JSON.stringify(step)); + switch (step.op) { + case 'tools/list': + captures['tools/list'] = await client.listTools(); + break; + case 'tools/call': + captures['tools/call'] = await client.callTool({ + name: step.name, + arguments: resolveArguments(captures, step.arguments) + }); + break; + case 'wait': + await new Promise((r) => setTimeout(r, step.ms)); + break; + case 'disconnect': + await transport.close(); + connected = false; + break; + } + } + if (connected) await transport.close(); + logger.debug('steps: done'); +} + async function main(): Promise { const scenarioName = process.env.MCP_CONFORMANCE_SCENARIO; const serverUrl = process.argv[2]; @@ -1141,7 +1209,15 @@ async function main(): Promise { process.exit(1); } - const handler = scenarioHandlers[scenarioName]; + // Named handlers win; steps are the fallback for names this client has + // never heard of. MCP_CONFORMANCE_FORCE_STEPS=1 inverts that so the + // generic path can be exercised against scenarios that also have handlers. + const steps = stepsFromContext(); + const named = scenarioHandlers[scenarioName]; + const handler = + steps && (!named || process.env.MCP_CONFORMANCE_FORCE_STEPS === '1') + ? (url: string) => runSteps(url, steps) + : named; if (!handler) { console.error(`Unknown scenario: ${scenarioName}`); console.error('\nAvailable scenarios:'); diff --git a/src/hosted/html.ts b/src/hosted/html.ts index cbab3cfe..244b0250 100644 --- a/src/hosted/html.ts +++ b/src/hosted/html.ts @@ -31,14 +31,25 @@ function esc(s: string): string { ); } -export function renderLanding(origin: string, scenarios: string[]): string { +export function renderLanding( + origin: string, + scenarios: string[], + stepsFor: (name: string) => readonly unknown[] | undefined = () => undefined +): string { const rows = scenarios - .map( - (n) => + .map((n) => { + const steps = stepsFor(n); + const steer = steps + ? `
steps (${steps.length})` + + `
${esc(JSON.stringify(steps, null, 1))}
` + : 'bespoke'; + return ( `${esc(n)}` + `${esc(origin)}/s/${esc(n)}/<run-id>` + + `${steer}` + `mint` - ) + ); + }) .join(''); return ` MCP Conformance — hosted @@ -54,8 +65,14 @@ returns {mcpUrl, resultsUrl}.

This server is also an MCP server at ${esc(origin)}/mcp with list_scenarios / start_run / get_results tools.

+

Generic steering: scenarios with a steps column need no +scenario-specific client code — the mint response (and /scenarios) +carries context.steps, a closed op list +(tools/list, tools/call, wait, +disconnect) that a dumb client can interpret. Pass the +context object verbatim as MCP_CONFORMANCE_CONTEXT.

Scenarios (${scenarios.length})

-${rows}
nameMCP URL pattern
+${rows}
nameMCP URL patternclient

Example

$ npx @modelcontextprotocol/inspector ${esc(origin)}/s/initialize/demo
 $ curl ${esc(origin)}/results/demo | jq .summary
`; diff --git a/src/hosted/server.ts b/src/hosted/server.ts index a8cb19fc..929bb85e 100644 --- a/src/hosted/server.ts +++ b/src/hosted/server.ts @@ -260,7 +260,15 @@ export function createHostedApp(opts: HostedServerOptions = {}): { // ---------- discovery ---------- app.get('/', (req, res) => { - res.type('html').send(renderLanding(origin(req), Array.from(hostable))); + res + .type('html') + .send( + renderLanding( + origin(req), + Array.from(hostable), + (name) => getScenario(name)?.steps + ) + ); }); app.get('/scenarios', (_req, res) => { @@ -271,7 +279,8 @@ export function createHostedApp(opts: HostedServerOptions = {}): { name, description: s.description, source: s.source, - mcpPath: s.mcpPath ?? '' + mcpPath: s.mcpPath ?? '', + ...(s.steps && { steps: s.steps }) }; }) ); diff --git a/src/hosted/session.ts b/src/hosted/session.ts index 02b362cc..5d5a0b87 100644 --- a/src/hosted/session.ts +++ b/src/hosted/session.ts @@ -172,6 +172,9 @@ export class SessionManager { throw new NotHostableError(scenarioName); } + const steps = (scenario as Scenario).steps; + if (steps) context = { ...context, steps }; + const run: HostedRun = { id: runId, scenarioName, diff --git a/src/runner/client.ts b/src/runner/client.ts index 1bf8c9f6..346f5990 100644 --- a/src/runner/client.ts +++ b/src/runner/client.ts @@ -117,9 +117,15 @@ export async function runConformanceTest( console.error(`Starting scenario: ${scenarioName}`); const urls = await scenario.start(); + // Steering steps ride in the same context blob as credentials etc. + const context: Record | undefined = + scenario.steps || urls.context + ? { ...urls.context, ...(scenario.steps && { steps: scenario.steps }) } + : undefined; + console.error(`Executing client: ${clientCommand} ${urls.serverUrl}`); - if (urls.context) { - console.error(`With context: ${JSON.stringify(urls.context)}`); + if (context) { + console.error(`With context: ${JSON.stringify(context)}`); } try { @@ -128,7 +134,7 @@ export async function runConformanceTest( scenarioName, urls.serverUrl, timeout, - urls.context, + context, specVersion ); diff --git a/src/scenarios/client/elicitation-defaults.ts b/src/scenarios/client/elicitation-defaults.ts index 4d73c81e..93496c6a 100644 --- a/src/scenarios/client/elicitation-defaults.ts +++ b/src/scenarios/client/elicitation-defaults.ts @@ -494,6 +494,19 @@ export class ElicitationClientDefaultsScenario extends HandlerScenario { await super.stop(); } + /** + * The tool call triggers elicitation/create; the interpreter's standing + * default (accept with schema defaults) is exactly the behaviour under test. + */ + readonly steps = [ + { op: 'tools/list' }, + { + op: 'tools/call', + name: 'test_client_elicitation_defaults', + arguments: {} + } + ] as const; + getChecks(): ConformanceCheck[] { const expectedSlugs = [ 'client-elicitation-sep1034-string-default', diff --git a/src/scenarios/client/initialize.ts b/src/scenarios/client/initialize.ts index d693be75..f29e2ff4 100644 --- a/src/scenarios/client/initialize.ts +++ b/src/scenarios/client/initialize.ts @@ -20,6 +20,9 @@ export class InitializeScenario extends HandlerScenario { return (req, res) => this.handleRequest(req, res); } + /** Plumbing only: connect (implicit) and make one ordinary request. */ + readonly steps = [{ op: 'tools/list' }] as const; + getChecks(): ConformanceCheck[] { return this.checks; } diff --git a/src/scenarios/client/json-schema-ref-deref.ts b/src/scenarios/client/json-schema-ref-deref.ts index bdb3d9f8..c55e8936 100644 --- a/src/scenarios/client/json-schema-ref-deref.ts +++ b/src/scenarios/client/json-schema-ref-deref.ts @@ -79,6 +79,8 @@ export class JsonSchemaRefDerefScenario extends HandlerScenario { The 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.`; mcpPath = '/mcp'; + /** List only — the point is what the client does NOT fetch afterwards. */ + readonly steps = [{ op: 'tools/list' }] as const; /** * Raw event log. What the scenario observed is kept as INFO events here diff --git a/src/scenarios/client/tools_call.ts b/src/scenarios/client/tools_call.ts index 0fec16e1..13009ea6 100644 --- a/src/scenarios/client/tools_call.ts +++ b/src/scenarios/client/tools_call.ts @@ -125,6 +125,11 @@ export class ToolsCallScenario extends HandlerScenario { return createServerApp(this.checks); } + readonly steps = [ + { op: 'tools/list' }, + { op: 'tools/call', name: 'add_numbers', arguments: { a: 5, b: 3 } } + ] as const; + getChecks(): ConformanceCheck[] { const expectedSlugs = ['tool-add-numbers']; // add a failure if not in there already diff --git a/src/steps/index.test.ts b/src/steps/index.test.ts new file mode 100644 index 00000000..5fbf9a96 --- /dev/null +++ b/src/steps/index.test.ts @@ -0,0 +1,61 @@ +import { describe, it, expect } from 'vitest'; +import { StepsSchema, resolveFrom, resolveArguments } from './index'; +import { getScenario } from '../scenarios'; + +describe('steps', () => { + it('validates the closed op set', () => { + expect( + StepsSchema.safeParse([ + { op: 'tools/list' }, + { op: 'tools/call', name: 'x', arguments: { a: 1 } }, + { op: 'wait', ms: 10 }, + { op: 'disconnect' } + ]).success + ).toBe(true); + expect(StepsSchema.safeParse([{ op: 'resources/nuke' }]).success).toBe( + false + ); + }); + + it('resolves $from paths with key, index and filter segments', () => { + const captures = { + 'tools/list': { + tools: [ + { name: 'a', inputSchema: { type: 'object', title: 'A' } }, + { name: 'b', inputSchema: { type: 'object', title: 'B' } } + ] + } + }; + expect( + resolveFrom(captures, { + $from: 'tools/list', + path: 'tools[name=b].inputSchema.title' + }) + ).toBe('B'); + expect( + resolveFrom(captures, { $from: 'tools/list', path: 'tools[0].name' }) + ).toBe('a'); + expect( + resolveFrom(captures, { $from: 'tools/list', path: 'tools[name=z].x' }) + ).toBeUndefined(); + expect( + resolveArguments(captures, { + lit: 1, + schema: { $from: 'tools/list', path: 'tools[1].inputSchema' } + }) + ).toEqual({ lit: 1, schema: { type: 'object', title: 'B' } }); + }); + + it('every scenario that declares steps declares valid ones', () => { + for (const name of [ + 'initialize', + 'tools_call', + 'json-schema-ref-no-deref', + 'elicitation-sep1034-client-defaults' + ]) { + const s = getScenario(name); + expect(s?.steps, name).toBeDefined(); + expect(StepsSchema.safeParse(s!.steps).success, name).toBe(true); + } + }); +}); diff --git a/src/steps/index.ts b/src/steps/index.ts new file mode 100644 index 00000000..2390d48b --- /dev/null +++ b/src/steps/index.ts @@ -0,0 +1,103 @@ +/** + * Client steering steps ("generic steering"). + * + * Most client scenarios only need plumbing from the client under test: + * connect, list tools, call a tool, hang around, disconnect. Instead of every + * SDK's everything-client carrying a per-scenario dispatch table for that + * choreography, a scenario can declare it as data. The runner ships the + * steps to the client in MCP_CONFORMANCE_CONTEXT (`context.steps`); a client + * with no bespoke handler for the scenario name runs a small interpreter over + * them. Checks stay in the scenario — only the *instructions* become data. + * + * The op set is deliberately closed. Anything that needs judgement on the + * client side (credential modes, MRTR) keeps a named handler. + * + * Standing defaults an interpreter should apply without being told: + * - `initialize` is implicit (connect before the first step); + * - if the server sends elicitation/create, accept with schema defaults + * (empty content + `elicitation.applyDefaults` capability); + * - disconnect after the last step unless a `disconnect` step says when. + */ + +import { z } from 'zod'; + +/** + * `{ "$from": "tools/list", "path": "tools[name=echo].inputSchema" }` — a + * value captured from the most recent result of a previous op. The only + * dataflow form; two scenarios need it ("call B with the schema you got for + * A"), nothing needs more. + */ +export const FromRefSchema = z.object({ + $from: z.enum(['tools/list', 'tools/call']), + path: z.string() +}); +export type FromRef = z.infer; + +export const StepSchema = z.discriminatedUnion('op', [ + z.object({ op: z.literal('tools/list') }), + z.object({ + op: z.literal('tools/call'), + name: z.string(), + /** Argument values may be literals or `$from` captures. */ + arguments: z.record(z.string(), z.unknown()).optional() + }), + z.object({ op: z.literal('wait'), ms: z.number().int().nonnegative() }), + z.object({ op: z.literal('disconnect') }) +]); +export type Step = z.infer; + +export const StepsSchema = z.array(StepSchema); + +/** Results an interpreter has captured so far, keyed by op. */ +export type Captures = Partial>; + +export function isFromRef(v: unknown): v is FromRef { + return ( + typeof v === 'object' && + v !== null && + '$from' in v && + FromRefSchema.safeParse(v).success + ); +} + +/** + * Resolve a `$from` path against a captured result. Path grammar: + * dot-separated segments, each either a key (`inputSchema`), an index + * (`tools[0]`) or a filter on an array of objects (`tools[name=echo]`, + * first match). Returns undefined when anything along the way is missing — + * the interpreter should pass that through and let the scenario judge. + */ +export function resolveFrom(captures: Captures, ref: FromRef): unknown { + let cur: unknown = captures[ref.$from]; + for (const seg of ref.path.split('.').filter(Boolean)) { + const m = seg.match(/^([^[\]]*)(?:\[(?:(\d+)|([^=\]]+)=([^\]]*))\])?$/); + if (!m) return undefined; + const [, key, index, fkey, fval] = m; + if (key) cur = (cur as Record | undefined)?.[key]; + if (index !== undefined) cur = (cur as unknown[] | undefined)?.[+index]; + else if (fkey !== undefined) { + cur = Array.isArray(cur) + ? cur.find( + (x) => + typeof x === 'object' && + x !== null && + String((x as Record)[fkey]) === fval + ) + : undefined; + } + if (cur === undefined) return undefined; + } + return cur; +} + +/** Resolve every `$from` capture in a tools/call arguments object (shallow). */ +export function resolveArguments( + captures: Captures, + args: Record | undefined +): Record { + const out: Record = {}; + for (const [k, v] of Object.entries(args ?? {})) { + out[k] = isFromRef(v) ? resolveFrom(captures, v) : v; + } + return out; +} diff --git a/src/types.ts b/src/types.ts index 6b13e883..35288164 100644 --- a/src/types.ts +++ b/src/types.ts @@ -1,3 +1,5 @@ +import type { Step } from './steps'; + export type CheckStatus = | 'SUCCESS' | 'FAILURE' @@ -138,6 +140,12 @@ export interface Scenario { * request on its own content, so it reads this view when present. */ rawChecks?(): ConformanceCheck[]; + /** + * Client-side choreography as data (see src/steps). When present the + * runner includes it in MCP_CONFORMANCE_CONTEXT as `steps`, so a client + * with no bespoke handler for this scenario can still drive it. + */ + readonly steps?: readonly Step[]; } /** From 53422de95dc3cd07de5c5bd354b4f8b74bac9f24 Mon Sep 17 00:00:00 2001 From: Paul Carleton Date: Mon, 7 Sep 2026 14:20:02 +0000 Subject: [PATCH 7/9] Apply prettier/eslint --fix to hosted and experimental scenario files :house: Remote-Dev: homespace --- examples/hosted/fetch-bridge.ts | 4 +- src/scenarios/client/auth-checker.ts | 52 +++++++++---- .../client/auth/helpers/createAuthServer.ts | 5 +- src/scenarios/client/stateless-gauntlet.ts | 74 +++++++++---------- 4 files changed, 74 insertions(+), 61 deletions(-) diff --git a/examples/hosted/fetch-bridge.ts b/examples/hosted/fetch-bridge.ts index 4ee18790..1f3cb664 100644 --- a/examples/hosted/fetch-bridge.ts +++ b/examples/hosted/fetch-bridge.ts @@ -55,9 +55,7 @@ export function toFetchHandler( let status = 200; const headers = new Headers(); - const captureHeaders = ( - h?: Record - ) => { + const captureHeaders = (h?: Record) => { for (const [k, v] of Object.entries(h ?? {})) { headers.set(k, Array.isArray(v) ? v.join(', ') : String(v)); } diff --git a/src/scenarios/client/auth-checker.ts b/src/scenarios/client/auth-checker.ts index f7849591..2ba8f2de 100644 --- a/src/scenarios/client/auth-checker.ts +++ b/src/scenarios/client/auth-checker.ts @@ -56,7 +56,9 @@ function mintToken(claims: TokenClaims): string { return `ac.${Buffer.from(JSON.stringify(claims)).toString('base64url')}`; } -function parseToken(authorization: string | undefined): TokenClaims | undefined { +function parseToken( + authorization: string | undefined +): TokenClaims | undefined { const m = /^Bearer ac\.([A-Za-z0-9_-]+)$/.exec(authorization ?? ''); if (!m) return undefined; try { @@ -128,7 +130,7 @@ const TOOLS = [ 'authorization_response_iss_parameter_supported: true but sends a ' + 'WRONG iss in the authorization response. This tool can NEVER return ' + 'success: a conformant client refuses to exchange the code (your own ' + - "client errors about the iss mismatch — that error IS the pass). A " + + 'client errors about the iss mismatch — that error IS the pass). A ' + 'client that exchanges the code anyway receives a poisoned token, and ' + 'every request made with it fails with an explanation. Run this last; ' + 'it ends the session either way.' @@ -199,9 +201,12 @@ export class AuthCheckerScenario extends HandlerScenario { app.get('/.well-known/oauth-protected-resource/cfg/scoped', (_req, res) => { res.json(prmDoc('scoped')); }); - app.get('/.well-known/oauth-protected-resource/cfg/isstrap', (_req, res) => { - res.json(prmDoc('isstrap')); - }); + app.get( + '/.well-known/oauth-protected-resource/cfg/isstrap', + (_req, res) => { + res.json(prmDoc('isstrap')); + } + ); // ---------------- the two ASs (path-based issuers, stateless) --------- const asMetadata = (cfg: Cfg) => (_req: Request, res: Response) => { @@ -214,7 +219,9 @@ export class AuthCheckerScenario extends HandlerScenario { grant_types_supported: ['authorization_code'], code_challenge_methods_supported: ['S256'], token_endpoint_auth_methods_supported: ['none'], - ...(cfg === 'scoped' ? { scopes_supported: [SCOPE_READ, SCOPE_WRITE] } : {}), + ...(cfg === 'scoped' + ? { scopes_supported: [SCOPE_READ, SCOPE_WRITE] } + : {}), // RFC 9207: the trap AS PROMISES iss in authorization responses — // which obliges the client to validate it. The redirect then carries // a wrong one. @@ -224,7 +231,10 @@ export class AuthCheckerScenario extends HandlerScenario { }); }; for (const cfg of ['basic', 'scoped', 'isstrap'] as const) { - app.get(`/.well-known/oauth-authorization-server/as/${cfg}`, asMetadata(cfg)); + app.get( + `/.well-known/oauth-authorization-server/as/${cfg}`, + asMetadata(cfg) + ); app.get(`/.well-known/openid-configuration/as/${cfg}`, asMetadata(cfg)); app.post(`/as/${cfg}/register`, (req, res) => { @@ -248,7 +258,10 @@ export class AuthCheckerScenario extends HandlerScenario { if (q.state !== undefined) r.searchParams.set('state', q.state); res.redirect(r.toString()); }; - if (q.code_challenge === undefined || q.code_challenge_method !== 'S256') { + if ( + q.code_challenge === undefined || + q.code_challenge_method !== 'S256' + ) { fail('invalid_request', 'PKCE with S256 is required'); return; } @@ -274,7 +287,10 @@ export class AuthCheckerScenario extends HandlerScenario { { scope: q.scope } ); if (!q.redirect_uri) { - res.status(400).json({ error: 'invalid_request', error_description: 'redirect_uri required' }); + res.status(400).json({ + error: 'invalid_request', + error_description: 'redirect_uri required' + }); return; } const r = new URL(q.redirect_uri); @@ -382,11 +398,7 @@ see what your client has proven.

// ---------------- the MCP endpoint, gated per rung ------------------- // HTTP header values must be Latin-1; keep the rich text in the body. const headerSafe = (s: string) => s.replace(/[^\x20-\x7e]/g, '-'); - const challenge401 = ( - res: Response, - cfg: Cfg, - description: string - ) => { + const challenge401 = (res: Response, cfg: Cfg, description: string) => { res .status(401) .set( @@ -431,7 +443,11 @@ see what your client has proven.

// exchanged the wrong-iss code: fall through to the SDK dispatch, which // returns the FAIL verdict as an in-band tool result. if (toolName === 'check_iss_validation' && !token.trap) { - record('auth-checker-iss-trap-armed', true, 'iss trap challenge issued'); + record( + 'auth-checker-iss-trap-armed', + true, + 'iss trap challenge issued' + ); challenge401( res, 'isstrap', @@ -440,7 +456,11 @@ see what your client has proven.

return; } if (toolName === 'advance_to_scoped' && token.cfg !== 'scoped') { - record('auth-checker-rung2-challenged', true, 'Rung 2 challenge issued'); + record( + 'auth-checker-rung2-challenged', + true, + 'Rung 2 challenge issued' + ); challenge401( res, 'scoped', diff --git a/src/scenarios/client/auth/helpers/createAuthServer.ts b/src/scenarios/client/auth/helpers/createAuthServer.ts index 0a687387..ae008b52 100644 --- a/src/scenarios/client/auth/helpers/createAuthServer.ts +++ b/src/scenarios/client/auth/helpers/createAuthServer.ts @@ -28,7 +28,10 @@ function decodeAuthCode(code: string | undefined): AuthCodeState | undefined { if (!code?.startsWith(`${AUTH_CODE_PREFIX}.`)) return undefined; try { return JSON.parse( - Buffer.from(code.slice(AUTH_CODE_PREFIX.length + 1), 'base64url').toString() + Buffer.from( + code.slice(AUTH_CODE_PREFIX.length + 1), + 'base64url' + ).toString() ) as AuthCodeState; } catch { return undefined; diff --git a/src/scenarios/client/stateless-gauntlet.ts b/src/scenarios/client/stateless-gauntlet.ts index 7d2ca421..2e135903 100644 --- a/src/scenarios/client/stateless-gauntlet.ts +++ b/src/scenarios/client/stateless-gauntlet.ts @@ -59,9 +59,7 @@ function isDraftVersion(v: unknown): boolean { /** Versions compare equal across the draft/release-date alias. */ function sameVersion(a: unknown, b: unknown): boolean { - return ( - String(a) === String(b) || (isDraftVersion(a) && isDraftVersion(b)) - ); + return String(a) === String(b) || (isDraftVersion(a) && isDraftVersion(b)); } const META_NS = 'io.modelcontextprotocol/'; @@ -133,7 +131,9 @@ function encodeMrtrState(): string { function decodeMrtrState(state: string): boolean { try { const parsed = JSON.parse(Buffer.from(state, 'base64url').toString()); - return parsed.tool === MRTR_TOOL.name && parsed.nonce === 'gauntlet-mrtr-v1'; + return ( + parsed.tool === MRTR_TOOL.name && parsed.nonce === 'gauntlet-mrtr-v1' + ); } catch { return false; } @@ -418,7 +418,7 @@ const MRTR_NOTE = `${META_NS}clientCapabilities ({"elicitation": {}}) and handle ` + "resultType:'input_required' tool results — answer the inputRequests and " + 'retry the call with requestState echoed back unchanged. Declaring the ' + - "capability makes this gauntlet list the mrtr_confirm tool so you can " + + 'capability makes this gauntlet list the mrtr_confirm tool so you can ' + 'exercise that flow.'; /** Itemized draft gaps of one request, framed as an advisory report. */ @@ -471,17 +471,14 @@ function createLenientClassicServer( req: Request, body: { method?: string; params?: Record } ): Server { - const server = new Server( - SERVER_INFO, - { - capabilities: { tools: {} }, - instructions: - 'Lenient conformance gauntlet. Call every listed tool with valid ' + - 'arguments; call draft_readiness for an itemized report of what ' + - 'this client must change for the stateless draft protocol.\n\n' + - readinessReport(req, body) - } - ); + const server = new Server(SERVER_INFO, { + capabilities: { tools: {} }, + instructions: + 'Lenient conformance gauntlet. Call every listed tool with valid ' + + 'arguments; call draft_readiness for an itemized report of what ' + + 'this client must change for the stateless draft protocol.\n\n' + + readinessReport(req, body) + }); server.setRequestHandler(ListToolsRequestSchema, async () => ({ // Classic requests carry no per-request capabilities, so MRTR can't be @@ -503,9 +500,7 @@ function createLenientClassicServer( async (request): Promise => { if (request.params.name === DRAFT_READINESS_TOOL.name) { return { - content: [ - { type: 'text' as const, text: readinessReport(req, body) } - ] + content: [{ type: 'text' as const, text: readinessReport(req, body) }] }; } if (request.params.name === ELICITATION_MISSING_TOOL.name) { @@ -607,10 +602,7 @@ export class StatelessGauntletScenario extends HandlerScenario { req.query as Record ).toString(); const continueUrl = `${issuer()}/authorize/continue?${query}`; - res - .status(200) - .type('html') - .send(` + res.status(200).type('html').send(` Hold on — initialize? +${esc(scenario)} — ${esc(sessionId)}

${esc(scenario)}

session ${esc(sessionId)} — ${passed} passed, ${failed} failed, ${checks.length} total

${items}`; diff --git a/src/hosted/server.ts b/src/hosted/server.ts index 23d35532..e09a64ba 100644 --- a/src/hosted/server.ts +++ b/src/hosted/server.ts @@ -662,15 +662,27 @@ export function createHostedApp(opts: HostedServerOptions = {}): { return; } - // Find /r/ anywhere in the path and excise it. - const m = path.match(/^(.*?)\/r\/([A-Za-z0-9_-]{1,64})(\/.*)?$/); - if (!m) { + // Find the first /r/ segment pair anywhere in the path and + // excise it. Plain segment splitting: a regex over the whole path would + // backtrack polynomially on adversarial input. + const segments = path.split('/'); // path starts with '/', so [0] === '' + let rIdx = -1; + for (let i = 1; i < segments.length - 1; i++) { + if (segments[i] === 'r' && RUN_ID_RE.test(segments[i + 1])) { + rIdx = i; + break; + } + } + if (rIdx < 0) { res .status(404) .json({ error: 'aux request path missing /r/ segment' }); return; } - const [, prefix, runId, suffix = ''] = m; + const prefix = segments.slice(0, rIdx).join('/'); + const runId = segments[rIdx + 1]; + const rest = segments.slice(rIdx + 2); + const suffix = rest.length ? '/' + rest.join('/') : ''; const search = req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : ''; diff --git a/src/scenarios/client/stateless-gauntlet.ts b/src/scenarios/client/stateless-gauntlet.ts index 2e135903..55375558 100644 --- a/src/scenarios/client/stateless-gauntlet.ts +++ b/src/scenarios/client/stateless-gauntlet.ts @@ -75,6 +75,17 @@ const CONSENT_TOKEN = 'this-client-led-with-initialize'; /** What clients see in serverInfo — one val, one spec version. */ const SERVER_INFO = { name: 'mcp-checker-2026-07-28', version: '1.0.0' }; +/** Escape a string for interpolation into HTML text or a quoted attribute. */ +function escapeHtml(s: string): string { + return s.replace( + /[&<>"']/g, + (c) => + ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' })[ + c + ]! + ); +} + // --------------------------------------------------------------------------- // MRTR (SEP-2322) — multi-round-trip tool, draft mode only. // @@ -619,7 +630,7 @@ client's classic flow and report what it is missing (see the draft_readiness tool and the initialize result's instructions). But know that leading with initialize will not work against stateless draft servers.

-

I understand — continue with the test

+

I understand — continue with the test

`); }); @@ -877,8 +888,8 @@ poll: every request is judged on its own content. If your client gets something wrong, the request itself fails with an explanation of what and why. If you can list the tools and call each one successfully, your client is conformant for everything this server can observe.

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

What is checked

    @@ -901,10 +912,10 @@ endpoint gates it behind an OAuth consent screen: your client's auth flow lands page explaining the situation, with a continue button. Continuing mints the bearer token ${CONSENT_TOKEN} — the token is the message — and the classic flow is then served with advisory feedback. No other request requires auth. Prefer zero friction? Use -${base}/lenient.

    +${escapeHtml(base)}/lenient.

    Try it

    -
    curl -X POST ${base} \\
+
    curl -X POST ${escapeHtml(base)} \\
   -H 'content-type: application/json' \\
   -H 'accept: application/json, text/event-stream' \\
   -H 'mcp-protocol-version: 2026-07-28' \\

From 8bf9546fbaf1422009adf1b616986a89f1df6f73 Mon Sep 17 00:00:00 2001
From: Claude 
Date: Thu, 10 Sep 2026 13:12:51 +0000
Subject: [PATCH 9/9] auth helpers: rename the flow-code envelope helpers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CodeQL (js/missing-rate-limiting) flagged the /authorize and /token route
handlers in createAuthServer.ts as "performing authorization without rate
limiting". The only change this branch made to those handlers is calling
encodeAuthCode()/decodeAuthCode(), and CodeQL's heuristic treats any callee
whose name looks authorization-related as a credential check. These
helpers only pack/unpack a base64url JSON envelope carrying per-flow PKCE
state — no secret, no signature, no verification — so rename them to
packFlowCode()/unpackFlowCode() (and AuthCodeState to FlowCodeState) and
document that in the doc comment. No behaviour change; the mock AS is a
test fixture, not a production authorization server.

Co-Authored-By: Claude Fable 5.1 
Claude-Session: https://claude.ai/code/session_01FXWixCiyW8eEfwFeZcADEK
---
 .../client/auth/helpers/createAuthServer.ts    | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)

diff --git a/src/scenarios/client/auth/helpers/createAuthServer.ts b/src/scenarios/client/auth/helpers/createAuthServer.ts
index 75cf7591..9197b569 100644
--- a/src/scenarios/client/auth/helpers/createAuthServer.ts
+++ b/src/scenarios/client/auth/helpers/createAuthServer.ts
@@ -20,19 +20,23 @@ import {
  * (val.town) the two requests can land on different isolates, where closure
  * state from /authorize doesn't exist. The closure variables remain as a
  * fallback for flows that don't round-trip our code (e.g. hand-rolled tests).
+ *
+ * The code is a plain base64url JSON envelope — no secret, no signature, no
+ * verification: it is a state carrier for a test fixture, not a credential
+ * check, and the helper names say so (they perform no authorization).
  */
-interface AuthCodeState {
+interface FlowCodeState {
   challenge?: string;
   scopes?: string[];
 }
 
 const AUTH_CODE_PREFIX = 'test-auth-code';
 
-function encodeAuthCode(state: AuthCodeState): string {
+function packFlowCode(state: FlowCodeState): string {
   return `${AUTH_CODE_PREFIX}.${Buffer.from(JSON.stringify(state)).toString('base64url')}`;
 }
 
-function decodeAuthCode(code: string | undefined): AuthCodeState | undefined {
+function unpackFlowCode(code: string | undefined): FlowCodeState | undefined {
   if (!code?.startsWith(`${AUTH_CODE_PREFIX}.`)) return undefined;
   try {
     return JSON.parse(
@@ -40,7 +44,7 @@ function decodeAuthCode(code: string | undefined): AuthCodeState | undefined {
         code.slice(AUTH_CODE_PREFIX.length + 1),
         'base64url'
       ).toString()
-    ) as AuthCodeState;
+    ) as FlowCodeState;
   } catch {
     return undefined;
   }
@@ -506,7 +510,7 @@ export function createAuthServer(
     const redirectUrl = new URL(redirectUri);
     redirectUrl.searchParams.set(
       'code',
-      encodeAuthCode({
+      packFlowCode({
         challenge: codeChallenge,
         scopes: lastAuthorizationScopes
       })
@@ -540,8 +544,8 @@ export function createAuthServer(
 
     // Recover per-flow state from the code itself (survives process changes
     // on serverless hosts); fall back to closure state for codes we didn't
-    // mint via encodeAuthCode.
-    const codeState = decodeAuthCode(req.body.code as string | undefined);
+    // mint via packFlowCode.
+    const codeState = unpackFlowCode(req.body.code as string | undefined);
     const flowChallenge = codeState?.challenge ?? storedCodeChallenge;
     const flowScopes = codeState?.scopes ?? lastAuthorizationScopes;