@specific.dev/spectest 0.55.0 → 0.56.0

package/src/mcp-transport.ts

@@ -0,0 +1,427 @@
+// 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.
+//
+// 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";
+
+/** A JSON-RPC id. The client only ever mints numbers. */
+export type JsonRpcId = number | string;
+
+export interface JsonRpcRequest {
+  jsonrpc: "2.0";
+  id: JsonRpcId;
+  method: string;
+  params?: unknown;
+}
+
+export interface JsonRpcNotification {
+  jsonrpc: "2.0";
+  method: string;
+  params?: unknown;
+}
+
+export interface JsonRpcError {
+  code: number;
+  message: string;
+  data?: unknown;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  id: JsonRpcId;
+  result?: unknown;
+  error?: JsonRpcError;
+}
+
+type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
+
+/**
+ * The `WWW-Authenticate` challenge an MCP server sends with a `401`.
+ *
+ * `resourceMetadataUrl` is the entry point of the whole OAuth flow
+ * (RFC 9728). A server that omits it forces the client to guess the
+ * metadata location from its own URL, which `mcp-auth.ts` does.
+ */
+export interface McpChallenge {
+  /** The HTTP status that carried the challenge. */
+  status: number;
+  /** Almost always `Bearer`. */
+  scheme: string;
+  /** `resource_metadata` parameter — where the protected-resource
+   *  metadata lives. */
+  resourceMetadataUrl?: string;
+  /** `scope` parameter, when the server names what it wants. */
+  scope?: string;
+  /** `error` parameter, e.g. `invalid_token` for an expired token. */
+  error?: string;
+  /** The header, verbatim. Recorded so a test can assert on it. */
+  raw: string;
+}
+
+/** 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 {
+  readonly status: number;
+  readonly challenge?: McpChallenge;
+  readonly body?: string;
+
+  constructor(status: number, message: string, challenge?: McpChallenge, body?: string) {
+    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 {
+  readonly code: number;
+  readonly data?: unknown;
+
+  constructor(error: JsonRpcError) {
+    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: string | null, status: number): McpChallenge | undefined {
+  if (!header) return undefined;
+  const scheme = header.split(/[\s,]/, 1)[0] ?? "Bearer";
+  const params: Record<string, string> = {};
+  // `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,
+  };
+}
+
+/** One HTTP exchange, for the step detail panel. Bodies are the parsed
+ *  JSON-RPC messages, not raw text. */
+export interface HttpExchange {
+  method: string;
+  url: string;
+  status: number;
+  durationMs: number;
+  sessionId?: string;
+  /** Set when the reply was an SSE stream rather than a JSON body. */
+  streamed?: boolean;
+}
+
+export interface McpTransportOptions {
+  url: string;
+  /** Extra headers on every request (a static API key, a tenant id). */
+  headers?: Record<string, string>;
+  /** Read at call time, so a token minted mid-session applies at once. */
+  token?: () => string | undefined;
+  /** Default per-request budget. */
+  timeoutMs?: number;
+  /** Called for every server notification. */
+  onNotification?: (n: JsonRpcNotification) => void;
+  /** Called for every server-to-client request. Resolve with the result,
+   *  or throw to answer with a JSON-RPC error. */
+  onRequest?: (r: JsonRpcRequest) => Promise<unknown>;
+  /** Called after every HTTP exchange, for the recorder. */
+  onExchange?: (x: HttpExchange) => void;
+}
+
+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 {
+  readonly url: string;
+  /** Issued by the server on `initialize`, echoed on every later request.
+   *  Absent for a stateless server, which is legal. */
+  sessionId?: string;
+  /** Negotiated on `initialize`. Sent on every request after that. */
+  protocolVersion?: string;
+
+  private nextId = 1;
+  private readonly opts: McpTransportOptions;
+
+  constructor(opts: McpTransportOptions) {
+    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<T = unknown>(
+    method: string,
+    params?: unknown,
+    opts?: { timeoutMs?: number },
+  ): Promise<T> {
+    const id = this.nextId++;
+    const message: JsonRpcRequest = { 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 as T;
+  }
+
+  /** Send a notification. Nothing comes back. */
+  async notify(method: string, params?: unknown, opts?: { timeoutMs?: number }): Promise<void> {
+    const message: JsonRpcNotification = { 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(): Promise<void> {
+    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;
+  }
+
+  private headers(extra?: Record<string, string>): Record<string, string> {
+    const h: Record<string, string> = {
+      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;
+  }
+
+  private async post(message: JsonRpcMessage, timeoutMs?: number): Promise<Response> {
+    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: Response;
+    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. */
+  private async readResponse(res: Response, id: JsonRpcId): Promise<JsonRpcResponse> {
+    const contentType = res.headers.get("content-type") ?? "";
+    if (!contentType.includes("text/event-stream")) {
+      const text = await res.text();
+      const parsed = JSON.parse(text) as JsonRpcMessage | JsonRpcMessage[];
+      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: JsonRpcMessage;
+      try {
+        message = JSON.parse(event) as JsonRpcMessage;
+      } 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. */
+  private async answer(request: JsonRpcRequest): Promise<void> {
+    let response: JsonRpcResponse;
+    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 as Error)?.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: JsonRpcMessage): m is JsonRpcResponse {
+  return "id" in m && !("method" in m);
+}
+
+function isRequest(m: JsonRpcMessage): m is JsonRpcRequest {
+  return "id" in m && "method" in m;
+}
+
+function truncate(s: string, max = 300): string {
+  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: ReadableStream<Uint8Array>): AsyncGenerator<string> {
+  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: string): string | undefined {
+  const lines = frame.split(/\r?\n/);
+  const data: string[] = [];
+  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/src/mcp.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+
+import { parseChallenge, sseData } from "./mcp-transport.js";
+import { base64url, canonicalResource, wellKnownUrls } from "./mcp-auth.js";
+
+describe("parseChallenge", () => {
+  test("reads the resource metadata URL", () => {
+    const challenge = parseChallenge(
+      'Bearer resource_metadata="https://api.test/.well-known/oauth-protected-resource"',
+      401,
+    );
+    expect(challenge?.scheme).toBe("Bearer");
+    expect(challenge?.resourceMetadataUrl).toBe(
+      "https://api.test/.well-known/oauth-protected-resource",
+    );
+    expect(challenge?.status).toBe(401);
+  });
+
+  test("reads every parameter, quoted or not", () => {
+    const challenge = parseChallenge(
+      'Bearer realm="mcp", error=invalid_token, scope="a b", resource_metadata="https://x/y"',
+      401,
+    );
+    expect(challenge?.error).toBe("invalid_token");
+    expect(challenge?.scope).toBe("a b");
+    expect(challenge?.resourceMetadataUrl).toBe("https://x/y");
+  });
+
+  test("a bare 401 has no challenge", () => {
+    expect(parseChallenge(null, 401)).toBeUndefined();
+  });
+});
+
+describe("wellKnownUrls", () => {
+  test("an issuer with no path has one spelling", () => {
+    expect(wellKnownUrls("https://api.test", "oauth-authorization-server")).toEqual([
+      "https://api.test/.well-known/oauth-authorization-server",
+    ]);
+  });
+
+  test("a path-carrying issuer inserts the segment first (RFC 8414)", () => {
+    // The order matters: RFC 8414 inserts, OpenID Connect appends, and
+    // servers differ on which they serve. Supabase serves the inserted
+    // form only.
+    expect(wellKnownUrls("https://api.test/auth/v1", "oauth-authorization-server")).toEqual([
+      "https://api.test/.well-known/oauth-authorization-server/auth/v1",
+      "https://api.test/auth/v1/.well-known/oauth-authorization-server",
+      "https://api.test/.well-known/oauth-authorization-server",
+    ]);
+  });
+
+  test("a trailing slash is not a path", () => {
+    expect(wellKnownUrls("https://api.test/", "oauth-protected-resource")).toEqual([
+      "https://api.test/.well-known/oauth-protected-resource",
+    ]);
+  });
+});
+
+describe("canonicalResource", () => {
+  test("drops the fragment and lowercases the host", () => {
+    expect(canonicalResource("https://API.Test/mcp#x")).toBe("https://api.test/mcp");
+  });
+});
+
+describe("sseData", () => {
+  test("reads one data line", () => {
+    expect(sseData('data: {"jsonrpc":"2.0"}')).toBe('{"jsonrpc":"2.0"}');
+  });
+
+  test("joins several data lines with a newline", () => {
+    expect(sseData("data: a\ndata: b")).toBe("a\nb");
+  });
+
+  test("ignores the other fields and comments", () => {
+    expect(sseData("event: message\nid: 7\n: keep-alive\ndata: x")).toBe("x");
+  });
+
+  test("a frame with no data yields nothing", () => {
+    expect(sseData("event: ping")).toBeUndefined();
+  });
+
+  test("only the first space after the colon is stripped", () => {
+    expect(sseData("data:  padded")).toBe(" padded");
+  });
+});
+
+describe("base64url", () => {
+  test("has no padding and no unsafe characters", () => {
+    const encoded = base64url(new Uint8Array([251, 255, 190, 1]));
+    expect(encoded).not.toContain("=");
+    expect(encoded).not.toContain("+");
+    expect(encoded).not.toContain("/");
+  });
+});