@corbits/mcp 0.1.0 → 0.3.0

package/README.md

@@ -1,81 +1,188 @@
 # @corbits/mcp
 
-An MCP client for Interchange: streamable HTTP transport (2025-03-26 spec),
-one `@intx/agent` tool per remote tool, and no gate of its own -- native
-per-tool grants check the whole surface.
-
-## Shape
-
-Discovery and calling are split, because a deployed agent's tool factories
-are evaluated synchronously when the agent is constructed and the agent must
-never hold a server's bearer.
-
-1. **The deployer discovers the catalog once**, server-side, through the hub
-   route this package mounts. The browser never holds an MCP token, so this
-   is the only way an OAuth-protected server's `tools/list` can be read.
-2. **The catalog is stored** with the rest of the agent's deploy config.
-3. **`mcpServers` turns it into tools.** It is synchronous and does no
-   network work at construction: the names and the `ask` marks come from the
-   stored catalog.
-4. **At run time the agent only ever sees a mediated handle.** Each server's
-   credential resolves to an `http` handle -- a fetch pinned to that server's
-   origin that injects the bearer per request -- so the token never reaches
-   agent code, and a relative path is all the bundle ever asks for.
-
-### Hub
+A Corbits tool pack for the Interchange sidecar that turns each tool on a remote Model Context Protocol server into its own `@intx/agent` tool, over streamable HTTP (2025-03-26 spec). It also ships a hub route for catalog discovery and OAuth discovery helpers, and the client works standalone.
+
+## Why @corbits/mcp?
+
+1. **One agent tool per remote tool.** `linear.list_issues` and `linear.delete_issue` are separate tools, so Interchange grants (per-principal permission records) allow, ask or deny each one.
+2. **The agent never holds the server's token.** Calls go through a mediated credential: a fetch pinned to the server's origin that adds the bearer per request.
+3. **Destructive tools stay behind approval.** Every generated tool starts `ask`-marked, and a tool the server flags `destructiveHint: true` cannot be lowered to `allow`.
+
+It supports `initialize`, `tools/list` and `tools/call` only, against stateless and stateful (`Mcp-Session-Id`) servers.
+
+## Install
+
+```bash
+bun add @corbits/mcp @intx/agent @intx/harness
+```
+
+Runs on Node.js 24+ and Bun 1.2+.
+
+For the `@corbits/mcp/hub` routes, also install:
+
+```bash
+bun add @corbits/credential-http @intx/authz @intx/crypto @intx/db @intx/hub-api drizzle-orm hono
+```
+
+## Quickstart
+
+Lists the tools on a public MCP server:
+
+```ts
+import { mcpInitialize, mcpListTools } from "@corbits/mcp";
+
+const url = "https://mcp.deepwiki.com/mcp";
+const session = await mcpInitialize(url);
+for (const tool of await mcpListTools(url, { session })) {
+  console.log(`${tool.name}: ${tool.description ?? ""}`);
+}
+```
+
+Every client call takes `{ fetch, timeoutMs, signal, session }` as its last argument, for example a fetch that adds an `Authorization` header. `timeoutMs` covers the request and reading its body, and `signal` cancels both. `mcpTools` and `mcpServers` take a `timeoutMs` option, 60 seconds by default, and pass each tool call's abort signal through, so a stalling server fails that call instead of hanging it. A response body or event-stream frame over 4 MiB is refused and the stream cancelled.
+
+## Where it fits
+
+[Interchange](https://github.com/faremeter/interchange) runs AI agents as principals: accounts with their own identity, permissions and credentials. Its hub is the multi-tenant control plane that holds tenants, grants and credentials; its sidecar is the agent runtime.
+
+- **Hub:** `@corbits/mcp/hub` mounts a discovery route on an [`@intx/hub-api`](https://github.com/faremeter/interchange/tree/main/packages/hub-api) app and reads tenant credentials from [`@intx/db`](https://github.com/faremeter/interchange/tree/main/packages/db).
+- **Sidecar:** `@corbits/mcp/sidecar-bundle` builds [`@intx/agent`](https://github.com/faremeter/interchange/tree/main/packages/agent) tools from a stored catalog.
+- **Pairs with:** [`@corbits/oauth-core`](https://github.com/corbitsdev/corbits-oauth-core) for the login flow and [`@corbits/credential-http`](https://github.com/corbitsdev/credential-http) for the origin-pinned credential provider.
+
+## Reference
+
+| Export                                            | Entry                         | Purpose                                                                                                           |
+| ------------------------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `mcpInitialize(url, opts?)`                       | `@corbits/mcp`                | Send `initialize` and `notifications/initialized`; returns the `McpSession` to pass to later calls.               |
+| `mcpListTools(url, opts?)`                        | `@corbits/mcp`                | Send `tools/list`; returns `McpTool[]`.                                                                           |
+| `mcpCallTool(url, name, args, opts?)`             | `@corbits/mcp`                | Send `tools/call`; returns `McpToolResult`.                                                                       |
+| `mcpTools(options, env?)`                         | `@corbits/mcp`                | Discover each server live, then build tools. For hosts that can await; servers use `name` and `credentialHandle`. |
+| `qualifiedName`, `toolDescription`, `isAskExempt` | `@corbits/mcp`                | Naming and `ask`-floor rules the tool builders use.                                                               |
+| `discoverMcpLoginEntry({ resourceUrl })`          | `@corbits/mcp`                | Resolve the authorization server (RFC 9728, then RFC 8414).                                                       |
+| `registerMcpClient(opts)`                         | `@corbits/mcp`                | Register a loopback public client (RFC 7591).                                                                     |
+| `mcpClientConfig(entry, opts)`                    | `@corbits/mcp`                | Build the `OAuthClientConfig` oauth-core's login helpers take.                                                    |
+| `selectMcpScopes(opts)`                           | `@corbits/mcp`                | Pick scopes in the MCP spec's selection order.                                                                    |
+| `mcpServers(config)`                              | `@corbits/mcp/sidecar-bundle` | Build tools from stored catalogs over mediated credentials.                                                       |
+| `shapeMcpContent(content)`, `SIDECAR_BUNDLE_ID`   | `@corbits/mcp/sidecar-bundle` | Result shaping and the bundle's tool id.                                                                          |
+| `mountMcpDiscovery(app, opts)`                    | `@corbits/mcp/hub`            | Mount `POST /mcp/discover`.                                                                                       |
+| `discoverMcpServer(args)`, `readCredential(opts)` | `@corbits/mcp/hub`            | The discovery and credential reads the route uses.                                                                |
+
+`McpToolSchema` validates a catalog entry (`McpTool`). Transport and protocol failures throw `McpError`. OAuth discovery failures throw `OAuthDiscoveryError` from `@corbits/oauth-core`.
+
+### Grants
+
+Every call is checked as resource `tool:<name>`. The most specific match wins, and `deny` beats `ask` beats `allow`. `tool:<handle>.<tool>` grants one remote tool and `tool:<handle>.*` covers a whole server. A handle or server name may not contain `.`, and a catalog may not list a tool name twice, so no tool falls under another server's grant.
+
+List `"<handle>.<tool>"` in `allowWithoutAsk` to let an `allow` grant run that tool without approval. The list is ignored for tools flagged `destructiveHint: true`.
+
+## Using with Interchange
+
+The deployer discovers a server's catalog once through the hub route and stores it with the agent's deploy config. The sidecar bundle turns the catalog into tools that call through a mediated credential.
+
+### Mount the hub route
 
 ```ts
 import { mountMcpDiscovery } from "@corbits/mcp/hub";
+import { timeWindowEvaluator } from "@intx/authz";
+import { createEnvKeyCredentialCipher } from "@intx/crypto";
+import { createDB, createGrantStore } from "@intx/db";
+import { createRequireGrant, type TenantEnv } from "@intx/hub-api";
+import { Hono } from "hono";
+
+const { db } = createDB({
+  host: "localhost",
+  port: 5432,
+  user: "postgres",
+  password: "postgres",
+  database: "interchange",
+});
+const requireGrant = createRequireGrant({
+  grantStore: createGrantStore(db),
+  conditionRegistry: { time_window: timeWindowEvaluator },
+});
 
-const api = new Hono<TenantEnv>();
-mountMcpDiscovery(api, { db, cipher, requireGrant });
-app.route("/api/tenants/:tenantId", api);
+export const mcpRoutes = new Hono<TenantEnv>();
+mountMcpDiscovery(mcpRoutes, {
+  db,
+  cipher: createEnvKeyCredentialCipher(
+    Buffer.from(String(process.env["CREDENTIAL_ENCRYPTION_KEY"]), "hex"),
+  ),
+  requireGrant: requireGrant("credential:*", "read"),
+});
 ```
 
-`POST /api/tenants/:tenantId/mcp/discover` with `{ url, credentialId? }`
-answers `{ data: { serverInfo, tools } }`. `url` must be https (http only on
-loopback); `credentialId` names a tenant credential whose secret is sent as a
-bearer, and the keyless sentinel sends no `authorization` header at all. The
-outbound fetch is origin-pinned and refuses a 3xx, so the secret never leaves
-the server's own origin.
+Mount `mcpRoutes` on the hub app under `/api/tenants/:tenantId`, behind the hub's auth and tenant middleware.
+
+`POST /api/tenants/:tenantId/mcp/discover` with `{ url, credentialId? }` returns `{ data: { serverInfo, tools } }`. `url` must be https; plain-http loopback is refused unless the host sets `allowLoopback: true` for local development. `credentialId` names a tenant credential whose secret is sent as a bearer; the credential's type must be `api_key` or `oauth_token`, and any other type reads as not found. An `oauth_token` credential's secret is its current access token, which [`@corbits/oauth-core`](https://github.com/corbitsdev/corbits-oauth-core)'s refresher renews in place, so nothing here refreshes it, and one past its `expiresAt` or marked `error` reads as not found until it is renewed or the user signs in again; a credential holding `MCP_NO_TOKEN_SENTINEL` from `@corbits/credential-http` sends no `authorization` header. Errors: 400 for a bad body or URL, 404 for an unknown credential or one that is not active or has expired, 422 when the server fails discovery, the secret is not a valid header value, or the request would leave the credential's origin. A 422 carries only this package's own messages and never the upstream HTTP status; any other failure reads as a generic handshake error, so no response or `onError` text quotes the secret. `requireGrant` is the host's own grant middleware for this route.
 
-### Sidecar bundle
+When a secret is sent, the fetch is pinned to the origin of the credential's provider `apiBaseUrl`; with no credential or a keyless one, to the URL's origin. Redirects are always refused, so the secret never leaves that origin. Each discovery request times out after 30 seconds.
+
+#### Extra origins
+
+Some servers serve MCP on a different origin from the one their credential is issued for. Nothing is allowed off the pinned origin by default. The host lists extra origins per pinned origin in `extraOrigins`, which is passed through to `@corbits/credential-http`:
 
 ```ts
+mountMcpDiscovery(mcpRoutes, {
+  db,
+  cipher,
+  requireGrant: requireGrant("credential:*", "read"),
+  extraOrigins: {
+    "https://api.example.com": ["https://mcp.example.net"],
+  },
+});
+```
+
+| Option         | Type                                          | Default |
+| -------------- | --------------------------------------------- | ------- |
+| `extraOrigins` | `Readonly<Record<string, readonly string[]>>` | `{}`    |
+
+A credential pinned to `https://api.example.com` may then be sent to `https://mcp.example.net`; no other credential can.
+
+`extraOrigins` is host-wide, not per tenant: an entry applies to every tenant's credential pinned to that origin, so list only origins you trust with all of them. `discoverMcpServer` takes the same option. For the sidecar bundle, configure the same allowance on the credential provider the host registers.
+
+### Load the sidecar bundle
+
+```ts
+import { mcpListTools } from "@corbits/mcp";
 import { mcpServers } from "@corbits/mcp/sidecar-bundle";
 
+const url = "https://mcp.deepwiki.com/mcp";
+
 export const tools = mcpServers({
   servers: [
     {
-      handle: "linear",
-      url: "https://mcp.linear.app/mcp",
-      tools: storedCatalog,
-      allowWithoutAsk: ["linear.list_issues"],
+      handle: "deepwiki",
+      url,
+      tools: await mcpListTools(url),
+      allowWithoutAsk: ["deepwiki.read_wiki_structure"],
     },
   ],
 });
 ```
 
-Each catalog entry becomes a tool named `<handle>.<tool>`, with the remote
-`inputSchema` passed through verbatim and its call proxied to `tools/call`. A
-result's text content comes back as text and anything else as JSON; `isError`
-passes through. A handle that will not resolve, or a server that fails
-`initialize`, fails only that server's calls.
+Each catalog entry becomes a tool named `<handle>.<tool>`, with the remote `inputSchema` passed through and the call proxied to `tools/call`. Text content comes back as text and anything else as JSON; `isError` passes through. A handle that does not resolve, or a server that fails `initialize`, fails only that server's calls.
+
+`handle` is the credential handle the host binds this server's token to. The bundle resolves it from the runtime `credentials` capability and expects an `http` credential, such as the one `@corbits/credential-http`'s MCP provider returns. The package manifest declares the `mcp-server` credential for this.
+
+#### OAuth servers
+
+A host records how a server authenticates in the credential's `metadata.mcp.auth`: `"none"` (the keyless sentinel), `"token"` (a pasted `api_key`) or `"oauth"` (an `oauth_token` login through `@corbits/oauth-core`, using `discoverMcpLoginEntry` and `mcpClientConfig` above). This package does not read the value; it reads the credential's type, so pass the `oauth_token` credential's id as `credentialId`. At run time the credential's provider shapes the handle from the credential's current secret, so a refreshed token reaches running agents without any change to the bundle.
 
-`mcpTools` (the root export) is the author-time equivalent, for code that can
-await discovery itself.
+### Grant access
 
-## Grants
+Grant the agent's principal `tool:deepwiki.*` for the whole server, or `tool:deepwiki.<tool>` per tool, with `allow`, `ask` or `deny`.
 
-Every call is checked as resource `tool:<name>`, most specific match wins,
-`deny` beats `ask` beats `allow`. Because each remote tool is its own agent
-tool, `tool:<handle>.<tool>` is grantable individually and `tool:<handle>.*`
-covers a whole server.
+## Upgrading from 0.1
 
-Every generated tool starts `ask`-marked. Listing `"<handle>.<tool>"` in
-`allowWithoutAsk` is the only way to lower that mark, and it is ignored for
-any remote tool the server flags `destructiveHint: true`.
+- Existing server configs, stored catalogs and the `mcp-server` credential keep working unchanged.
+- `@intx/harness` is a required peer. Import `FetchLike` from it; `@corbits/mcp` no longer exports that type.
+- `@intx/db`, `@intx/hub-api`, `drizzle-orm`, `hono` and `@corbits/credential-http` are optional peers. Install them if you use `@corbits/mcp/hub`. `@corbits/credential-http` replaces `@corbits/credential-mcp`.
+- Discovery with a credential pins to the credential's provider `apiBaseUrl` origin, not to the requested URL's origin. A credential with a secret whose provider has no `apiBaseUrl` is refused, and a URL on another origin needs `extraOrigins`. No origin is allowed by default.
+- `readCredentialSecret` is now `readCredential`, which returns `{ secret, origin? }`. `discoverMcpServer` takes `credential: { secret, origin? }` instead of `secret`.
+- `mcpInitialize` returns an `McpSession` (`protocolVersion`, `sessionId?`, `serverInfo?`) and sends `notifications/initialized`. Pass it as `{ session }` to `mcpListTools` and `mcpCallTool`; a stateful server needs it.
+- The discovery route refuses plain-http loopback URLs unless `allowLoopback` is set. Handles and server names containing `.`, and catalogs repeating a tool name, are refused. `mcpTools` refuses an empty or repeated server name, and a non-https URL, before any request.
+- `@intx/agent` and `@intx/harness` peers are `^0.4.0`.
+- Discovery rejects authorization-server metadata whose `issuer` differs from the one the protected resource names.
 
 ## License
 
-LGPL-2.1-only.
+[LGPL-2.1-only](https://github.com/corbitsdev/corbits-mcp/blob/main/LICENSE)

package/dist/client.d.ts

@@ -1,3 +1,4 @@
+import type { FetchLike } from "@intx/harness";
 export declare const McpToolSchema: import("arktype/internal/variants/object.ts").ObjectType<{
     name: string;
     inputSchema: Record<string, unknown>;
@@ -14,13 +15,22 @@ export interface McpToolResult {
     content: unknown;
     isError?: boolean;
 }
-export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 export interface McpClientOptions {
     /** Injectable `fetch` for tests and mediated-credential handles. */
     fetch?: FetchLike;
+    /** Abort the request, including reading its body, after this long. */
+    timeoutMs?: number;
+    /** Abort the request when this fires, e.g. a cancelled tool call. */
+    signal?: AbortSignal;
+    /** The session `mcpInitialize` opened; required by stateful servers. */
+    session?: McpSession;
 }
+/** The run-time `tools/call` and `initialize` bound when a caller sets none. */
+export declare const DEFAULT_TIMEOUT_MS = 60000;
 export declare class McpError extends Error {
-    constructor(message: string);
+    /** The HTTP status, when the server answered with a non-2xx one. */
+    readonly status: number | undefined;
+    constructor(message: string, status?: number);
 }
 declare const InitializeResult: import("arktype/internal/variants/object.ts").ObjectType<{
     protocolVersion?: string;
@@ -30,9 +40,17 @@ declare const InitializeResult: import("arktype/internal/variants/object.ts").Ob
     };
 }, {}>;
 export type McpServerInfo = typeof InitializeResult.infer;
-/** `initialize` handshake. The server's own identification is returned for a
- * caller that shows it; nothing here depends on it. */
-export declare function mcpInitialize(url: string, opts?: McpClientOptions): Promise<McpServerInfo>;
+export type McpSession = {
+    /** The negotiated version, sent as `MCP-Protocol-Version`. */
+    readonly protocolVersion: string;
+    /** The `Mcp-Session-Id` a stateful server assigned, if any. */
+    readonly sessionId?: string;
+    /** The server's own identification, for a caller that shows it. */
+    readonly serverInfo?: NonNullable<McpServerInfo["serverInfo"]>;
+};
+/** `initialize` handshake followed by `notifications/initialized`. Pass the
+ * returned session to every later call on this server. */
+export declare function mcpInitialize(url: string, opts?: McpClientOptions): Promise<McpSession>;
 /** `tools/list`: the remote server's tool catalog. */
 export declare function mcpListTools(url: string, opts?: McpClientOptions): Promise<McpTool[]>;
 export declare function mcpCallTool(url: string, name: string, toolArguments: Record<string, unknown>, opts?: McpClientOptions): Promise<McpToolResult>;

package/dist/client.js

@@ -1,6 +1,7 @@
-// MCP streamable-HTTP transport client (2025-03-26 spec): no session id or
-// resumption because this client only ever sends one request and awaits
-// its one reply, which is all initialize/tools-list/tools-call need.
+// MCP streamable-HTTP transport client (2025-03-26 spec). Each call sends one
+// request and awaits its one reply, which is all initialize/tools-list/
+// tools-call need; the session `initialize` opens is carried in `session`.
+// No resumption.
 import { type } from "arktype";
 export const McpToolSchema = type({
     name: "string",
@@ -13,6 +14,11 @@ export const McpToolSchema = type({
         "openWorldHint?": "boolean",
     },
 });
+/** The run-time `tools/call` and `initialize` bound when a caller sets none. */
+export const DEFAULT_TIMEOUT_MS = 60_000;
+const PROTOCOL_VERSION = "2025-03-26";
+/** Largest response body or SSE frame read before the stream is cancelled. */
+const MAX_MESSAGE_BYTES = 4 * 1024 * 1024;
 const JsonRpcResponse = type({
     jsonrpc: "'2.0'",
     id: "string | number",
@@ -20,12 +26,36 @@ const JsonRpcResponse = type({
     "error?": { code: "number", message: "string", "data?": "unknown" },
 });
 export class McpError extends Error {
-    constructor(message) {
+    /** The HTTP status, when the server answered with a non-2xx one. */
+    status;
+    constructor(message, status) {
         super(message);
         this.name = "McpError";
+        this.status = status;
     }
 }
 let nextId = 1;
+/** A reply to request `id`: a message carrying `result` or `error` and no
+ * `method`, which would make it a server request reusing the id. */
+function isResponseTo(message, id) {
+    return (typeof message === "object" &&
+        message !== null &&
+        message.id === id &&
+        !("method" in message) &&
+        ("result" in message || "error" in message));
+}
+function headersFor(session) {
+    return {
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream",
+        ...(session === undefined
+            ? {}
+            : { "mcp-protocol-version": session.protocolVersion }),
+        ...(session?.sessionId === undefined
+            ? {}
+            : { "mcp-session-id": session.sessionId }),
+    };
+}
 /**
  * Send one JSON-RPC request over streamable HTTP and return its `result`.
  * Handles both response shapes the spec allows: a direct `application/json`
@@ -35,71 +65,153 @@ let nextId = 1;
 async function sendRequest(url, method, params, opts) {
     const fetchImpl = opts.fetch ?? fetch;
     const id = nextId++;
-    const response = await fetchImpl(url, {
-        method: "POST",
-        headers: {
-            "content-type": "application/json",
-            accept: "application/json, text/event-stream",
-        },
-        body: JSON.stringify({
-            jsonrpc: "2.0",
-            id,
-            method,
-            ...(params !== undefined ? { params } : {}),
-        }),
-    });
-    if (!response.ok) {
-        throw new McpError(`MCP server ${url} responded ${response.status} to ${method}`);
+    const timeout = opts.timeoutMs === undefined
+        ? undefined
+        : AbortSignal.timeout(opts.timeoutMs);
+    const signals = [timeout, opts.signal].filter((s) => s !== undefined);
+    const signal = signals.length > 0 ? AbortSignal.any(signals) : undefined;
+    let message;
+    let sessionId;
+    try {
+        const response = await fetchImpl(url, {
+            method: "POST",
+            headers: headersFor(opts.session),
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id,
+                method,
+                ...(params !== undefined ? { params } : {}),
+            }),
+            ...(signal !== undefined ? { signal } : {}),
+        });
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new McpError(`MCP server ${url} responded ${response.status} to ${method}`, response.status);
+        }
+        sessionId = response.headers.get("mcp-session-id") ?? undefined;
+        const contentType = response.headers.get("content-type") ?? "";
+        message = contentType.includes("text/event-stream")
+            ? await readSseJsonRpc(response, id, signal)
+            : parseJson(await readCapped(response, signal));
+    }
+    catch (cause) {
+        if (opts.signal?.aborted === true) {
+            throw new McpError(`${method} to MCP server ${url} was cancelled`);
+        }
+        if (timeout?.aborted === true) {
+            throw new McpError(`MCP server ${url} did not answer ${method} within ${String(opts.timeoutMs)}ms`);
+        }
+        throw cause;
     }
-    const contentType = response.headers.get("content-type") ?? "";
-    const message = contentType.includes("text/event-stream")
-        ? await readSseJsonRpc(response, id)
-        : await response.json();
     const parsed = JsonRpcResponse(message);
-    if (parsed instanceof type.errors) {
-        throw new McpError(`MCP server ${url} sent a malformed response to ${method}: ${parsed.summary}`);
+    if (parsed instanceof type.errors || !isResponseTo(message, id)) {
+        throw new McpError(`MCP server ${url} sent a malformed response to ${method}${parsed instanceof type.errors ? `: ${parsed.summary}` : ""}`);
     }
     if (parsed.error !== undefined) {
         throw new McpError(`MCP server ${url} rejected ${method}: ${parsed.error.message}`);
     }
-    return parsed.result;
+    return { result: parsed.result, sessionId };
 }
-/** Read an SSE body and return the first JSON-RPC message whose id matches. */
-async function readSseJsonRpc(response, id) {
+/** Send a JSON-RPC notification; the server answers 202 with no body. */
+async function sendNotification(url, method, opts) {
+    const fetchImpl = opts.fetch ?? fetch;
+    const timeout = opts.timeoutMs === undefined
+        ? undefined
+        : AbortSignal.timeout(opts.timeoutMs);
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: "POST",
+            headers: headersFor(opts.session),
+            body: JSON.stringify({ jsonrpc: "2.0", method }),
+            ...(timeout !== undefined ? { signal: timeout } : {}),
+        });
+    }
+    catch (cause) {
+        if (timeout?.aborted === true) {
+            throw new McpError(`MCP server ${url} did not answer ${method} within ${String(opts.timeoutMs)}ms`);
+        }
+        throw cause;
+    }
+    await response.body?.cancel();
+    if (!response.ok) {
+        throw new McpError(`MCP server ${url} responded ${response.status} to ${method}`, response.status);
+    }
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new McpError("MCP server sent a body that is not JSON");
+    }
+}
+function overflow() {
+    return new McpError(`MCP server sent a message larger than ${String(MAX_MESSAGE_BYTES)} bytes`);
+}
+/** Read a body's chunks, cancelling the stream when the signal aborts. */
+async function* chunks(response, signal) {
     const body = response.body;
     if (body === null) {
-        throw new McpError("MCP server sent an event-stream response with no body");
+        throw new McpError("MCP server sent a response with no body");
     }
     const reader = body.getReader();
-    const decoder = new TextDecoder();
-    let buffer = "";
+    const abort = () => void reader.cancel().catch(() => undefined);
+    signal?.addEventListener("abort", abort, { once: true });
     try {
         for (;;) {
             const { done, value } = await reader.read();
             if (done)
-                break;
-            buffer += decoder.decode(value, { stream: true });
-            const frames = buffer.split("\n\n");
-            buffer = frames.pop() ?? "";
-            for (const frame of frames) {
-                const dataLines = frame
-                    .split("\n")
-                    .filter((line) => line.startsWith("data:"))
-                    .map((line) => line.slice(5).trim());
-                if (dataLines.length === 0)
-                    continue;
-                const candidate = JSON.parse(dataLines.join("\n"));
-                if (typeof candidate === "object" &&
-                    candidate !== null &&
-                    "id" in candidate &&
-                    candidate.id === id) {
-                    return candidate;
-                }
-            }
+                return;
+            yield value;
         }
     }
     finally {
-        reader.releaseLock();
+        signal?.removeEventListener("abort", abort);
+        await reader.cancel().catch(() => undefined);
+    }
+}
+async function readCapped(response, signal) {
+    const decoder = new TextDecoder();
+    let text = "";
+    let bytes = 0;
+    for await (const chunk of chunks(response, signal)) {
+        bytes += chunk.byteLength;
+        if (bytes > MAX_MESSAGE_BYTES)
+            throw overflow();
+        text += decoder.decode(chunk, { stream: true });
+    }
+    return text + decoder.decode();
+}
+/** Read an SSE body and return the first JSON-RPC message whose id matches. */
+async function readSseJsonRpc(response, id, signal) {
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for await (const chunk of chunks(response, signal)) {
+        buffer += decoder.decode(chunk, { stream: true });
+        const frames = buffer.split(/\r\n\r\n|\n\n|\r\r/);
+        buffer = frames.pop() ?? "";
+        if (buffer.length > MAX_MESSAGE_BYTES)
+            throw overflow();
+        for (const frame of frames) {
+            if (frame.length > MAX_MESSAGE_BYTES)
+                throw overflow();
+            const dataLines = frame
+                .split(/\r\n|\r|\n/)
+                .filter((line) => line.startsWith("data:"))
+                .map((line) => line.slice(5).trim());
+            if (dataLines.length === 0)
+                continue;
+            let candidate;
+            try {
+                candidate = JSON.parse(dataLines.join("\n"));
+            }
+            catch {
+                continue;
+            }
+            if (isResponseTo(candidate, id))
+                return candidate;
+        }
     }
     throw new McpError("MCP server closed the event stream without a matching response");
 }
@@ -107,25 +219,48 @@ const InitializeResult = type({
     "protocolVersion?": "string",
     "serverInfo?": { name: "string", "version?": "string" },
 });
-/** `initialize` handshake. The server's own identification is returned for a
- * caller that shows it; nothing here depends on it. */
+/** `initialize` handshake followed by `notifications/initialized`. Pass the
+ * returned session to every later call on this server. */
 export async function mcpInitialize(url, opts = {}) {
-    const result = await sendRequest(url, "initialize", {
-        protocolVersion: "2025-03-26",
+    const { result, sessionId } = await sendRequest(url, "initialize", {
+        protocolVersion: PROTOCOL_VERSION,
         capabilities: {},
-        clientInfo: { name: "@corbits/mcp", version: "0.1.0" },
-    }, opts);
+        clientInfo: { name: "@corbits/mcp", version: "0.2.0" },
+    }, {
+        ...(opts.fetch !== undefined ? { fetch: opts.fetch } : {}),
+        ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+        ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+    });
     const parsed = InitializeResult(result);
-    return parsed instanceof type.errors ? {} : parsed;
+    const info = parsed instanceof type.errors ? {} : parsed;
+    // Echoed into the MCP-Protocol-Version header, so printable ASCII only.
+    if (info.protocolVersion !== undefined &&
+        !/^[\x20-\x7e]+$/.test(info.protocolVersion)) {
+        throw new McpError(`MCP server ${url} sent a protocolVersion that is not printable ASCII`);
+    }
+    const session = {
+        protocolVersion: info.protocolVersion ?? PROTOCOL_VERSION,
+        ...(sessionId !== undefined ? { sessionId } : {}),
+        ...(info.serverInfo !== undefined ? { serverInfo: info.serverInfo } : {}),
+    };
+    await sendNotification(url, "notifications/initialized", {
+        ...opts,
+        session,
+    });
+    return session;
 }
 const ToolsListResult = type({ tools: McpToolSchema.array() });
 /** `tools/list`: the remote server's tool catalog. */
 export async function mcpListTools(url, opts = {}) {
-    const result = await sendRequest(url, "tools/list", undefined, opts);
+    const { result } = await sendRequest(url, "tools/list", undefined, opts);
     const parsed = ToolsListResult(result);
     if (parsed instanceof type.errors) {
         throw new McpError(`MCP server ${url} sent a malformed tools/list result: ${parsed.summary}`);
     }
+    const names = new Set(parsed.tools.map((tool) => tool.name));
+    if (names.size !== parsed.tools.length) {
+        throw new McpError(`MCP server ${url} sent a tools/list result with duplicate tool names`);
+    }
     return parsed.tools;
 }
 /** `tools/call`: invoke a remote tool by name with JSON arguments. */
@@ -134,7 +269,7 @@ const ToolCallResult = type({
     "isError?": "boolean",
 });
 export async function mcpCallTool(url, name, toolArguments, opts = {}) {
-    const result = await sendRequest(url, "tools/call", { name, arguments: toolArguments }, opts);
+    const { result } = await sendRequest(url, "tools/call", { name, arguments: toolArguments }, opts);
     const parsed = ToolCallResult(result);
     if (parsed instanceof type.errors) {
         throw new McpError(`MCP server ${url} sent a malformed tools/call result for ${name}: ${parsed.summary}`);