@specific.dev/spectest 0.55.0 → 0.56.1

package/dist/mcp-transport.js

@@ -0,0 +1,337 @@
+// Streamable-HTTP transport for the MCP client (`mcp.ts`).
+//
+// This is a hand-written JSON-RPC client for the MCP streamable-HTTP
+// transport. We do not depend on `@modelcontextprotocol/sdk`, because that
+// package pulls in ~90 transitive packages (express, hono, cors, ajv, zod)
+// and ~25 MB, for its SERVER half. The SDK here ships into every project's
+// VM and is installed on every cold start, so a dependency of that size is
+// paid by projects that never test an MCP server. The client half of the
+// protocol is small, and this file is all of it.
+//
+// What it implements (MCP revision 2025-06-18, backward compatible with
+// 2025-03-26):
+//   - POST of one JSON-RPC message, with a reply that is either
+//     `application/json` or an `text/event-stream` (SSE) stream.
+//   - The `initialize` handshake, the `Mcp-Session-Id` header the server
+//     may issue, and the `MCP-Protocol-Version` header that every later
+//     request must carry.
+//   - Server-to-client requests (sampling, roots) that arrive
+//     on the SSE stream of the request that caused them. The answer goes
+//     back on its own POST, as the spec requires.
+//   - `DELETE` to end the session.
+//
+// What it does NOT implement, deliberately: the standalone GET stream, and
+// resumption by `Last-Event-ID`. Both matter to a long-lived desktop
+// client that must survive a dropped connection. A test makes one request
+// at a time and its VM is snapshotted, not disconnected. Add them when a
+// project needs them, not before.
+//
+// It also does not implement the DEPRECATED HTTP+SSE transport
+// (2024-11-05): a long-lived `GET` stream plus a separate POST endpoint
+// named by its first `endpoint` event. A server that speaks only that one
+// answers our `initialize` POST with a `4xx` and this client gives up
+// there. Adding it is a self-contained change — the fallback trigger is
+// that same `4xx` — but nothing needs it yet.
+//
+// Recording lives one layer up. This file is transport only, so `mcp.ts`
+// can record one step per logical operation instead of one per HTTP call.
+import { rawFetch } from "./harness/raw-fetch.js";
+/** An HTTP-level failure from the MCP endpoint. A `401` carries the
+ *  parsed {@link McpChallenge}, which is what makes "the server rejected
+ *  this call" assertable in a test. */
+export class McpHttpError extends Error {
+    status;
+    challenge;
+    body;
+    constructor(status, message, challenge, body) {
+        super(message);
+        this.name = "McpHttpError";
+        this.status = status;
+        this.challenge = challenge;
+        this.body = body;
+    }
+}
+/** A JSON-RPC error result. The request reached the server and the server
+ *  answered with an error object. */
+export class McpRpcError extends Error {
+    code;
+    data;
+    constructor(error) {
+        super(error.message);
+        this.name = "McpRpcError";
+        this.code = error.code;
+        this.data = error.data;
+    }
+}
+/** Parse a `WWW-Authenticate` header. Returns `undefined` when there is
+ *  no header, so a bare `401` still reports a status with no challenge. */
+export function parseChallenge(header, status) {
+    if (!header)
+        return undefined;
+    const scheme = header.split(/[\s,]/, 1)[0] ?? "Bearer";
+    const params = {};
+    // `name="value"` pairs, or `name=value` for the unquoted form some
+    // servers emit. Values may hold commas, so match on the quotes first.
+    const re = /([A-Za-z_-]+)\s*=\s*(?:"([^"]*)"|([^\s,]+))/g;
+    for (let m = re.exec(header); m !== null; m = re.exec(header)) {
+        params[m[1].toLowerCase()] = m[2] ?? m[3] ?? "";
+    }
+    return {
+        status,
+        scheme,
+        resourceMetadataUrl: params["resource_metadata"],
+        scope: params["scope"],
+        error: params["error"],
+        raw: header,
+    };
+}
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** The revision we speak. A server that wants an older one negotiates it
+ *  in the `initialize` result and we echo whatever it chose. */
+export const PROTOCOL_VERSION = "2025-06-18";
+export class McpTransport {
+    url;
+    /** Issued by the server on `initialize`, echoed on every later request.
+     *  Absent for a stateless server, which is legal. */
+    sessionId;
+    /** Negotiated on `initialize`. Sent on every request after that. */
+    protocolVersion;
+    nextId = 1;
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+        this.url = opts.url;
+    }
+    /** Send a request and resolve with its result. Throws
+     *  {@link McpHttpError} for a transport failure and {@link McpRpcError}
+     *  for a JSON-RPC error result. */
+    async request(method, params, opts) {
+        const id = this.nextId++;
+        const message = { jsonrpc: "2.0", id, method, params };
+        const res = await this.post(message, opts?.timeoutMs);
+        const response = await this.readResponse(res, id);
+        if (response.error)
+            throw new McpRpcError(response.error);
+        return response.result;
+    }
+    /** Send a notification. Nothing comes back. */
+    async notify(method, params, opts) {
+        const message = { jsonrpc: "2.0", method, params };
+        const res = await this.post(message, opts?.timeoutMs);
+        // A notification gets `202 Accepted` with no body. Drain anything the
+        // server sent anyway so the connection can be reused.
+        await res.text().catch(() => "");
+    }
+    /** End the session. Best-effort: a server that does not support
+     *  `DELETE` answers 405, which is not an error for us. */
+    async close() {
+        if (!this.sessionId)
+            return;
+        try {
+            const res = await rawFetch(this.url, { method: "DELETE", headers: this.headers() });
+            await res.text().catch(() => "");
+        }
+        catch {
+            // The peer is gone. Nothing to end.
+        }
+        this.sessionId = undefined;
+    }
+    headers(extra) {
+        const h = {
+            accept: "application/json, text/event-stream",
+            ...this.opts.headers,
+            ...extra,
+        };
+        const token = this.opts.token?.();
+        if (token)
+            h["authorization"] = `Bearer ${token}`;
+        if (this.sessionId)
+            h["mcp-session-id"] = this.sessionId;
+        if (this.protocolVersion)
+            h["mcp-protocol-version"] = this.protocolVersion;
+        return h;
+    }
+    async post(message, timeoutMs) {
+        const started = Date.now();
+        const budget = timeoutMs ?? this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), budget);
+        let res;
+        try {
+            res = await rawFetch(this.url, {
+                method: "POST",
+                headers: this.headers({ "content-type": "application/json" }),
+                body: JSON.stringify(message),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            clearTimeout(timer);
+            const method = "method" in message ? message.method : "response";
+            if (controller.signal.aborted) {
+                throw new Error(`MCP request ${method} to ${this.url} timed out after ${budget} ms`);
+            }
+            throw err;
+        }
+        clearTimeout(timer);
+        // The session id is issued on `initialize` and must be echoed from
+        // then on. Read it off every reply: a server may rotate it.
+        const issued = res.headers.get("mcp-session-id");
+        if (issued)
+            this.sessionId = issued;
+        this.opts.onExchange?.({
+            method: "POST",
+            url: this.url,
+            status: res.status,
+            durationMs: Date.now() - started,
+            sessionId: this.sessionId,
+            streamed: (res.headers.get("content-type") ?? "").includes("text/event-stream"),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            const challenge = parseChallenge(res.headers.get("www-authenticate"), res.status);
+            const method = "method" in message ? message.method : "response";
+            throw new McpHttpError(res.status, `MCP ${method} failed: HTTP ${res.status}${body ? ` — ${truncate(body)}` : ""}`, challenge, body);
+        }
+        return res;
+    }
+    /** Read the reply to request `id`. The body is either one JSON-RPC
+     *  response, or an SSE stream that carries it — possibly after
+     *  server-to-client traffic that belongs to the same request. */
+    async readResponse(res, id) {
+        const contentType = res.headers.get("content-type") ?? "";
+        if (!contentType.includes("text/event-stream")) {
+            const text = await res.text();
+            const parsed = JSON.parse(text);
+            const messages = Array.isArray(parsed) ? parsed : [parsed];
+            for (const m of messages) {
+                if (isResponse(m) && m.id === id)
+                    return m;
+            }
+            throw new Error(`MCP reply carried no response for request ${id}`);
+        }
+        if (!res.body)
+            throw new Error("MCP reply announced an SSE stream but carried no body");
+        for await (const event of readSse(res.body)) {
+            let message;
+            try {
+                message = JSON.parse(event);
+            }
+            catch {
+                // A comment or a keep-alive frame. Not ours to interpret.
+                continue;
+            }
+            if (isResponse(message)) {
+                if (message.id === id)
+                    return message;
+                continue;
+            }
+            if (isRequest(message)) {
+                // Answer on a separate POST, and keep reading. Awaiting the
+                // handler here would stall the stream that carries our own reply.
+                void this.answer(message);
+                continue;
+            }
+            this.opts.onNotification?.(message);
+        }
+        throw new Error(`MCP stream ended before the response to request ${id} arrived`);
+    }
+    /** Handle one server-to-client request and post the answer back. */
+    async answer(request) {
+        let response;
+        try {
+            if (!this.opts.onRequest) {
+                // The server asked for something this client never advertised.
+                response = {
+                    jsonrpc: "2.0",
+                    id: request.id,
+                    error: { code: -32601, message: `Method not found: ${request.method}` },
+                };
+            }
+            else {
+                response = { jsonrpc: "2.0", id: request.id, result: await this.opts.onRequest(request) };
+            }
+        }
+        catch (err) {
+            response = {
+                jsonrpc: "2.0",
+                id: request.id,
+                error: { code: -32603, message: err?.message ?? String(err) },
+            };
+        }
+        try {
+            const res = await this.post(response);
+            await res.text().catch(() => "");
+        }
+        catch {
+            // The server gave up on the request, or the stream is closed. There
+            // is nowhere left to report this.
+        }
+    }
+}
+function isResponse(m) {
+    return "id" in m && !("method" in m);
+}
+function isRequest(m) {
+    return "id" in m && "method" in m;
+}
+function truncate(s, max = 300) {
+    return s.length <= max ? s : `${s.slice(0, max)}…`;
+}
+/**
+ * Yield the `data` payload of each SSE event on a byte stream.
+ *
+ * Frames are separated by a blank line and a frame's data may span
+ * several `data:` lines, which are joined with a newline (WHATWG EventSource).
+ * `event:` and `id:` are read and dropped: MCP puts the whole JSON-RPC
+ * message in `data`, and we do not resume streams.
+ */
+async function* readSse(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            // Accept both LF and CRLF frame separators.
+            for (;;) {
+                const match = /\r?\n\r?\n/.exec(buffer);
+                if (!match)
+                    break;
+                const frame = buffer.slice(0, match.index);
+                buffer = buffer.slice(match.index + match[0].length);
+                const data = sseData(frame);
+                if (data !== undefined)
+                    yield data;
+            }
+        }
+        const tail = sseData(buffer);
+        if (tail !== undefined)
+            yield tail;
+    }
+    finally {
+        reader.cancel().catch(() => { });
+    }
+}
+/** The `data` of one SSE frame, or `undefined` when it carries none.
+ *  Exported for tests. */
+export function sseData(frame) {
+    const lines = frame.split(/\r?\n/);
+    const data = [];
+    for (const line of lines) {
+        if (line.startsWith(":"))
+            continue;
+        const colon = line.indexOf(":");
+        const field = colon === -1 ? line : line.slice(0, colon);
+        if (field !== "data")
+            continue;
+        let value = colon === -1 ? "" : line.slice(colon + 1);
+        if (value.startsWith(" "))
+            value = value.slice(1);
+        data.push(value);
+    }
+    return data.length > 0 ? data.join("\n") : undefined;
+}

package/dist/mcp.d.ts

@@ -0,0 +1,246 @@
+import { type Wrapped } from "./inspect.js";
+import { type McpChallenge } from "./mcp-transport.js";
+import { type AuthorizationServerInfo, type AuthorizeOptions, type McpIdentity } from "./mcp-auth.js";
+export { McpHttpError, McpRpcError, type McpChallenge } from "./mcp-transport.js";
+export { McpAuthDeniedError, type AuthorizeOptions, type AuthorizationServerInfo, type McpIdentity, } from "./mcp-auth.js";
+/** One part of a tool result or a resource read. The open member keeps a
+ *  content type this SDK predates from being dropped. */
+export type McpContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+} | {
+    type: "audio";
+    data: string;
+    mimeType: string;
+} | {
+    type: "resource";
+    resource: McpResourceContents;
+} | {
+    type: "resource_link";
+    uri: string;
+    name?: string;
+    mimeType?: string;
+} | {
+    type: string;
+    [key: string]: unknown;
+};
+export interface McpResourceContents {
+    uri: string;
+    mimeType?: string;
+    /** Text resources carry `text`; binary ones carry base64 `blob`. */
+    text?: string;
+    blob?: string;
+}
+export interface McpToolInfo {
+    name: string;
+    title?: string;
+    description?: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+}
+export interface McpResourceInfo {
+    uri: string;
+    name?: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+}
+export interface McpPromptInfo {
+    name: string;
+    title?: string;
+    description?: string;
+    arguments?: {
+        name: string;
+        description?: string;
+        required?: boolean;
+    }[];
+}
+export interface McpPromptResult {
+    description?: string;
+    messages: {
+        role: string;
+        content: McpContent;
+    }[];
+}
+/**
+ * What a tool call returned.
+ *
+ * Every field is provenance-wrapped, like a `ctx.fetch` response, so an
+ * assertion on it nests under the call in the timeline. That also means a
+ * field is a HANDLE, not the value: `expect(res.isError).toBe(true)` is
+ * the way to check it, and code that must branch calls
+ * `res.isError.unwrap()`. A bare `if (res.isError)` is always true,
+ * because a handle is an object — the same rule `res.ok` follows on a
+ * wrapped `fetch` response.
+ */
+export interface McpToolResult<T = unknown> {
+    /** True when the TOOL failed — an error the model is meant to read. A
+     *  protocol or transport failure throws instead. */
+    isError: Wrapped<boolean>;
+    /** Every content part, in order. */
+    content: Wrapped<McpContent[]>;
+    /** The text parts, joined with a newline. The usual thing to assert on. */
+    text: Wrapped<string>;
+    /** `structuredContent`, when the tool declares an output schema. */
+    structured?: Wrapped<T>;
+    /** `structuredContent` if the tool returned it, else the text parsed as
+     *  JSON. Throws when the text is not JSON. */
+    json<U = T>(): Wrapped<U>;
+    /** The whole result, with no provenance wrappers. */
+    unwrap(): {
+        isError: boolean;
+        content: McpContent[];
+        structuredContent?: T;
+    };
+}
+/** A notification the server sent, with the moment it arrived. */
+export interface McpNotification {
+    method: string;
+    params?: unknown;
+    /** Milliseconds since this client was created. */
+    atMs: number;
+}
+/** A server-to-client sampling request (`sampling/createMessage`): the
+ *  server is asking the client's model to generate something. */
+export interface McpSamplingRequest {
+    messages: {
+        role: string;
+        content: McpContent;
+    }[];
+    systemPrompt?: string;
+    maxTokens?: number;
+    [key: string]: unknown;
+}
+/** What a test answers a sampling request with. Return a string for the
+ *  common "the model said this" case. */
+export type McpSamplingResult = string | {
+    text?: string;
+    content?: McpContent;
+    model?: string;
+    stopReason?: string;
+    role?: string;
+};
+export interface McpOptions {
+    /** A static bearer token. For a server that issues API keys rather than
+     *  running an OAuth flow. */
+    bearer?: string;
+    /** Extra headers on every request (an API key, a tenant id). */
+    headers?: Record<string, string>;
+    /** Per-request budget. Default 30 s. */
+    timeoutMs?: number;
+    /**
+     * Prefix for this client's step titles. Display only — it keys nothing.
+     * Worth setting when one test drives two clients; otherwise leave it
+     * out and the steps read as the tool names they are.
+     */
+    label?: string;
+    /** What this client calls itself in the `initialize` handshake. */
+    clientInfo?: {
+        name: string;
+        version: string;
+    };
+    /** Roots to advertise, as URIs or `{ uri, name }`. */
+    roots?: (string | {
+        uri: string;
+        name?: string;
+    })[];
+    /** Answer `sampling/createMessage`. Declaring it advertises the
+     *  capability, so a server that asks gets a deterministic reply instead
+     *  of a "method not found". */
+    sampling?: (req: McpSamplingRequest) => McpSamplingResult | Promise<McpSamplingResult>;
+}
+/** The in-progress authorization a test drives with its own browser. */
+export interface McpAuthorization {
+    /**
+     * Send the browser here.
+     *
+     * This and the other inputs below are raw strings, not wrapped handles:
+     * they are arguments to `page.goto(...)` and to your own code, and a
+     * handle would break at the call. What the flow FOUND — {@link server},
+     * and the {@link McpIdentity} that {@link complete} returns — is wrapped
+     * and is what a test asserts on.
+     */
+    readonly url: string;
+    readonly redirectUri: string;
+    readonly state: string;
+    readonly clientId: string;
+    /** What discovery found, wrapped against the `authorize` step. */
+    readonly server: Wrapped<AuthorizationServerInfo>;
+    readonly scopes: string[];
+    readonly resource?: string;
+    /**
+     * Wait for the redirect, exchange the code, and connect the client.
+     *
+     * Nothing to pass with the default loopback redirect. Pass `url` when
+     * the flow used a custom `redirectUri` that this daemon does not serve:
+     * hand back where the browser landed (`page.url()`).
+     */
+    complete(opts?: {
+        url?: string;
+        timeoutMs?: number;
+    }): Promise<Wrapped<McpIdentity>>;
+    /** Give up and release the loopback port. */
+    cancel(): void;
+}
+/** How a server names itself in the handshake. */
+export interface McpServerInfo {
+    name: string;
+    version: string;
+    title?: string;
+}
+export interface Mcp {
+    readonly url: string;
+    /** `serverInfo` from the handshake. Absent until the client connects.
+     *  Wrapped against the handshake step, so an assertion on it nests
+     *  there. */
+    readonly serverInfo?: Wrapped<McpServerInfo>;
+    /** What the server said it can do. */
+    readonly capabilities?: Wrapped<Record<string, unknown>>;
+    /** The negotiated protocol revision. */
+    readonly protocolVersion?: Wrapped<string>;
+    /** The server's `Mcp-Session-Id`, when it issues one. */
+    readonly sessionId?: Wrapped<string>;
+    /** True once a handshake has succeeded. A plain boolean: this is the
+     *  client's own state, not something a server op produced. */
+    readonly connected: boolean;
+    /** The last `401` challenge this client saw, parsed. Wrapped against
+     *  the step that was refused. */
+    readonly challenge?: Wrapped<McpChallenge>;
+    /** The grant, once an authorization completed. */
+    readonly identity?: Wrapped<McpIdentity>;
+    /** Instructions the server offers a client, when it does. */
+    readonly instructions?: Wrapped<string>;
+    /** Begin an OAuth flow. Does discovery, registration and PKCE, and
+     *  returns the URL to send a browser to. */
+    authorize(opts?: AuthorizeOptions): Promise<McpAuthorization>;
+    tools(): Promise<Wrapped<McpToolInfo[]>>;
+    call<T = unknown>(name: string, args?: Record<string, unknown>, opts?: {
+        timeoutMs?: number;
+    }): Promise<McpToolResult<T>>;
+    resources(): Promise<Wrapped<McpResourceInfo[]>>;
+    read(uri: string): Promise<Wrapped<McpResourceContents[]>>;
+    prompts(): Promise<Wrapped<McpPromptInfo[]>>;
+    prompt(name: string, args?: Record<string, string>): Promise<Wrapped<McpPromptResult>>;
+    /**
+     * Everything the server has pushed so far, oldest first.
+     *
+     * Each one is wrapped against its own step, so an assertion on a
+     * notification's params nests under the notification that carried them.
+     * The array itself is plain, so `.length` is a number.
+     */
+    notifications(filter?: string | RegExp): Wrapped<McpNotification>[];
+    /** End the session (`DELETE`). Tests do not need to call this. */
+    close(): Promise<void>;
+}
+/**
+ * Connect to an MCP server over streamable HTTP.
+ *
+ * Does not throw when the server answers the handshake with `401`: that
+ * response is the documented start of the OAuth flow, and it is kept on
+ * the client as {@link Mcp.challenge}. Any other failure throws.
+ */
+export declare function openMcp(url: string, opts?: McpOptions): Promise<Mcp>;