@procedures/mcp-server 0.2.3 → 0.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/mcp-server",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Model Context Protocol server transport: serve typed procedures as MCP tools to Claude and other MCP clients, with streaming progress, list_changed and an expose policy.",
   "keywords": [
     "mcp",
@@ -60,17 +60,17 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@procedures/mcp": "0.2.3"
+    "@procedures/mcp": "0.3.0"
   },
   "peerDependencies": {
-    "@procedures/client": "^0.2.3"
+    "@procedures/client": "^0.3.0"
   },
   "devDependencies": {
     "typescript": "^7.0.2",
     "@types/node": "^22.0.0",
     "@mark1russell7/cue": "^1.0.0",
     "vitest": "^5.0.3",
-    "@procedures/client": "0.2.3",
+    "@procedures/client": "0.3.0",
     "zod": "^4.6.5"
   },
   "scripts": {

package/src/procedures/mcp/list-tools.ts

@@ -67,7 +67,8 @@ export const mcpListToolsProcedure: AnyProcedure = defineProcedure({
     }
 
     // The registry of the caller: a host with its own registry lists its own tools
-    const procedures = (ctx?.registry ?? PROCEDURE_REGISTRY).getAll();
+    // Only the procedures that the host exposes (roadmap R17)
+    const procedures = (ctx?.registry ?? PROCEDURE_REGISTRY).getAll().filter((procedure) => !ctx?.expose || ctx.expose(procedure.path));
     const mcpTools = proceduresToMcpTools(procedures, filter);
 
     const tools: McpToolInfo[] = mcpTools.map((tool) => ({

package/src/procedures/mcp/serve.ts

@@ -25,6 +25,7 @@ import {
 import { McpServerTransport } from "../../transport/mcp-transport.js";
 import type { McpServerTransportOptions } from "../../types.js";
 import { exposeRule, importBundles, mergeSurfaces } from "../../surface.js";
+import { ms } from "@procedures/client";
 
 /** The default bundle of the tool surface. */
 export const DEFAULT_SERVE_BUNDLE = "@procedures/bundle-mcp";
@@ -129,7 +130,7 @@ export async function prepareServe(
     registry,
     expose,
     strictCalls: input.strictCalls ?? true,
-    interceptors: [timeoutInterceptor({ ms: input.toolTimeoutMs ?? 600_000 })],
+    interceptors: [timeoutInterceptor({ limit: ms(input.toolTimeoutMs ?? 600_000) })],
   });
   return warning === undefined ? { server, expose } : { server, expose, warning };
 }

package/src/transport/http.ts

@@ -0,0 +1,129 @@
+/**
+ * The MCP transport over Streamable HTTP (roadmap R26), the HTTP transport of the current MCP
+ * specification. Before, this package had only stdio, and its SSE transport only threw.
+ *
+ * Each client gets a session: its `initialize` request makes a transport and an MCP server of its
+ * own, and the later requests of the client carry the `mcp-session-id` header of that session.
+ * A session gets the progress of a tool call and the `list_changed` notifications. The checks of
+ * a local server apply: the server listens on loopback by default, it refuses a web page of
+ * another host or origin (DNS rebinding, cross-site requests), and with a token it refuses a
+ * request without the token.
+ */
+
+import { randomUUID } from "node:crypto";
+import { createServer, type IncomingMessage, type Server as HttpServer, type ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { bearerOf, checkBrowserRequest, tokenMatches } from "@procedures/client";
+import type { HttpTransportOptions } from "../types.js";
+
+/** The HTTP endpoint of an MCP server, with a session for each client. */
+export interface McpHttpTransport {
+  /** This function starts to listen, when the endpoint has a server of its own. It gives the URL. */
+  listen(): Promise<string>;
+  /** The number of open sessions. */
+  readonly sessions: number;
+  /** This function closes each session, and the server when the endpoint made one. */
+  close(): Promise<void>;
+}
+
+/**
+ * This function makes the Streamable HTTP endpoint of an MCP server. `connect` connects the
+ * transport of a new session to an MCP server of its own.
+ */
+export function createHttpTransport(
+  options: HttpTransportOptions,
+  connect: (transport: StreamableHTTPServerTransport) => Promise<void>,
+): McpHttpTransport {
+  const path = options.path ?? "/mcp";
+  const host = options.host ?? "127.0.0.1";
+  const owned = options.server === undefined;
+  const server: HttpServer = options.server ?? createServer();
+  const sessions = new Map<string, StreamableHTTPServerTransport>();
+
+  const refuse = (res: ServerResponse, status: number, code: string, message: string): void => {
+    res.statusCode = status;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32001, message, data: { code } }, id: null }));
+  };
+
+  /** The transport of a request: the one of its session, or a new one for an `initialize`. */
+  const transportOf = async (req: IncomingMessage): Promise<StreamableHTTPServerTransport | undefined> => {
+    const sessionId = req.headers["mcp-session-id"];
+    if (typeof sessionId === "string") return sessions.get(sessionId);
+    if (req.method !== "POST") return undefined;
+    const transport: StreamableHTTPServerTransport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+      onsessioninitialized: (id) => {
+        sessions.set(id, transport);
+      },
+    });
+    transport.onclose = () => {
+      if (transport.sessionId) sessions.delete(transport.sessionId);
+    };
+    await connect(transport);
+    return transport;
+  };
+
+  const onRequest = (req: IncomingMessage, res: ServerResponse): void => {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    if (url.pathname !== path) {
+      if (owned) refuse(res, 404, "NOT_FOUND", `No MCP endpoint at ${url.pathname}`);
+      return;
+    }
+    // A web page must not reach the tools: the host and the origin of the request
+    const guard = checkBrowserRequest(req, { ...(options.allowedOrigins ? { allowedOrigins: options.allowedOrigins } : {}) });
+    if (!guard.ok) {
+      refuse(res, guard.status, guard.code, guard.message);
+      return;
+    }
+    if (options.token !== undefined && !tokenMatches(options.token, bearerOf(req.headers["authorization"]))) {
+      refuse(res, 401, "UNAUTHORIZED", "Unauthorized: this server requires its token");
+      return;
+    }
+    void transportOf(req)
+      .then((transport) => {
+        if (!transport) {
+          refuse(res, 404, "SESSION_NOT_FOUND", "No session: start one with an initialize request");
+          return;
+        }
+        return transport.handleRequest(req, res);
+      })
+      .catch((error: unknown) => {
+        if (!res.headersSent) refuse(res, 500, "INTERNAL_ERROR", error instanceof Error ? error.message : String(error));
+      });
+  };
+  server.on("request", onRequest);
+
+  return {
+    listen: async () => {
+      if (owned && !server.listening) {
+        await new Promise<void>((resolve, reject) => {
+          server.once("error", reject);
+          server.listen(options.port ?? 3003, host, () => {
+            server.off("error", reject);
+            resolve();
+          });
+        });
+      }
+      const address = server.address() as AddressInfo | null;
+      const shown = host === "0.0.0.0" ? "localhost" : host;
+      return `http://${shown}:${address?.port ?? options.port ?? 3003}${path}`;
+    },
+    get sessions() {
+      return sessions.size;
+    },
+    close: async () => {
+      server.off("request", onRequest);
+      const open = [...sessions.values()];
+      sessions.clear();
+      await Promise.all(open.map((transport) => transport.close().catch(() => undefined)));
+      if (owned && server.listening) {
+        await new Promise<void>((resolve) => {
+          server.close(() => resolve());
+          server.closeAllConnections();
+        });
+      }
+    },
+  };
+}

package/src/transport/mcp-transport.ts

@@ -23,6 +23,8 @@ import {
 import type { McpServerTransportOptions, McpServerTransportState } from "../types.js";
 import { createStdioTransport } from "./stdio.js";
 import { createSseTransport } from "./sse.js";
+import { createHttpTransport, type McpHttpTransport } from "./http.js";
+import { optionalMs } from "@procedures/client";
 
 /**
  * Generate a unique request ID.
@@ -84,8 +86,15 @@ export class McpServerTransport implements ServerTransport {
   private tools: Map<string, McpTool> = new Map();
   private registerListener: ((procedure: unknown) => void) | undefined;
   private unregisterListener: ((procedure: unknown) => void) | undefined;
+  /** The Streamable HTTP transport and its URL, when the transport is "http" (R26) */
+  private http: McpHttpTransport | undefined;
+  /** The MCP servers of the sessions of the Streamable HTTP transport */
+  private readonly sessionServers = new Set<McpServer>();
+  private httpUrl: string | undefined;
   /** A pending list_changed notification: a burst of registrations sends one */
   private listChangedTimer: ReturnType<typeof setTimeout> | undefined;
+  /** The limits of a stream that can run without an end, the time in milliseconds (R15) */
+  private readonly streamLimits: { items: number; timeMs: number };
 
   constructor(server: Server, options: McpServerTransportOptions = {}) {
     this.server = server;
@@ -97,6 +106,10 @@ export class McpServerTransport implements ServerTransport {
       },
       ...options,
     };
+    this.streamLimits = {
+      items: Math.max(1, options.streamLimits?.items ?? 100),
+      timeMs: optionalMs(options.streamLimits?.time, "streamLimits.time") ?? 30_000,
+    };
     // The registry of the server, when it has one (a ProcedureServer with an explicit registry):
     // before, the tools came from the global registry, also when the server served another one
     this.registry =
@@ -106,25 +119,32 @@ export class McpServerTransport implements ServerTransport {
 
     // Create MCP server with capabilities. The tool list follows the registry: when it changes,
     // the server sends notifications/tools/list_changed (deep dive roadmap 0.4)
-    this.mcpServer = new McpServer(this.options.serverInfo, {
+    this.mcpServer = this.createSdkServer();
+
+    // The registry listeners are attached in start() and removed in stop(): attaching them here
+    // leaked them for a transport that never started or failed to start (BUGS-2026-07 L28)
+  }
+
+  /**
+   * An MCP server of the SDK with the handlers of this transport. The stdio transport has one, and
+   * each session of the Streamable HTTP transport has one of its own (roadmap R26).
+   */
+  private createSdkServer(): McpServer {
+    const server = new McpServer(this.options.serverInfo, {
       capabilities: {
         tools: { listChanged: true },
       },
     });
-
-    // Setup request handlers
-    this.setupHandlers();
-
-    // The registry listeners are attached in start() and removed in stop(): attaching them here
-    // leaked them for a transport that never started or failed to start (BUGS-2026-07 L28)
+    this.setupHandlers(server);
+    return server;
   }
 
   /**
    * Setup MCP request handlers.
    */
-  private setupHandlers(): void {
+  private setupHandlers(server: McpServer): void {
     // ListToolsRequestSchema -> List all procedures as tools
-    this.mcpServer.setRequestHandler(ListToolsRequestSchema, async () => {
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
       this.log("ListToolsRequest received");
 
       const tools = Array.from(this.tools.values()).map(toToolDefinition);
@@ -135,7 +155,7 @@ export class McpServerTransport implements ServerTransport {
     });
 
     // CallToolRequestSchema -> Execute procedure
-    this.mcpServer.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
       const { name, arguments: args } = request.params;
 
       this.log(`CallToolRequest: ${name}`);
@@ -175,7 +195,8 @@ export class McpServerTransport implements ServerTransport {
 
         // Convert to MCP result
         if (response.status.type === "success" && response.stream) {
-          return await this.streamResult(response.stream, extra);
+          const unbounded = response.metadata?.["stream"] === "unbounded";
+          return await this.streamResult(response.stream, extra, unbounded);
         }
         if (response.status.type === "success") {
           const structured = tool.outputSchema ? structuredContentOf(response.payload) : undefined;
@@ -186,14 +207,17 @@ export class McpServerTransport implements ServerTransport {
             ...(structured ? { structuredContent: structured } : {}),
           };
         } else {
+          // The code and the reason of the error travel on each face (roadmap R25)
+          const reason = typeof response.metadata?.["reason"] === "string" ? response.metadata["reason"] : undefined;
           return {
             content: [
               {
                 type: "text" as const,
-                text: response.status.message ?? "Unknown error",
+                text: `${response.status.message ?? "Unknown error"}${reason ? ` (reason: ${reason})` : ""}`,
               },
             ],
             isError: true,
+            _meta: { code: response.status.code, ...(reason ? { reason } : {}) },
           };
         }
       } catch (error) {
@@ -222,14 +246,25 @@ export class McpServerTransport implements ServerTransport {
     extra: {
       _meta?: { progressToken?: string | number | undefined } | undefined;
       sendNotification: (notification: ServerNotification) => Promise<void>;
-    }
+    },
+    unbounded = false
   ): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
     const progressToken = extra._meta?.progressToken;
     const blocks: Array<{ type: "text"; text: string }> = [];
     let count = 0;
+    // A stream that can run without an end stops at the first limit (roadmap R15: before, a
+    // docker.logs with follow ended only at the time limit of the tool call)
+    const limits = this.streamLimits;
+    const started = Date.now();
+    let stoppedBy: string | undefined;
     try {
       for await (const item of stream) {
         count++;
+        if (unbounded && (count > limits.items || Date.now() - started > limits.timeMs)) {
+          stoppedBy = count > limits.items ? `${limits.items} items` : `${Math.round(limits.timeMs / 1000)} seconds`;
+          count--;
+          break;
+        }
         const text = toText(item);
         blocks.push({ type: "text", text });
         if (blocks.length > MAX_STREAM_BLOCKS) blocks.shift();
@@ -249,6 +284,9 @@ export class McpServerTransport implements ServerTransport {
     if (count > MAX_STREAM_BLOCKS) {
       blocks.unshift({ type: "text", text: `(${count} items: the first ${count - MAX_STREAM_BLOCKS} are not shown)` });
     }
+    if (stoppedBy) {
+      blocks.push({ type: "text", text: `(The stream can run without an end, so the tool stopped it after ${stoppedBy}.)` });
+    }
     if (count === 0) blocks.push({ type: "text", text: "(no items)" });
     return { content: blocks };
   }
@@ -313,6 +351,7 @@ export class McpServerTransport implements ServerTransport {
     this.listChangedTimer = setTimeout(() => {
       this.listChangedTimer = undefined;
       if (!this.running) return;
+      for (const sessionServer of this.sessionServers) sessionServer.sendToolListChanged().catch(() => undefined);
       this.mcpServer.sendToolListChanged().catch((error: unknown) => {
         this.log(`list_changed failed: ${error instanceof Error ? error.message : String(error)}`);
       });
@@ -346,13 +385,22 @@ export class McpServerTransport implements ServerTransport {
 
     try {
       // Create appropriate transport
-      let transport: SdkTransport;
+      let transport: SdkTransport | undefined;
       if (this.options.sdkTransport) {
         transport = this.options.sdkTransport;
         this.log("Using the given transport");
       } else if (this.options.transport === "stdio") {
         transport = createStdioTransport();
         this.log("Using stdio transport");
+      } else if (this.options.transport === "http") {
+        // Streamable HTTP (roadmap R26): an MCP server of its own for each session
+        this.http = createHttpTransport(this.options.httpOptions ?? {}, async (sessionTransport) => {
+          const sessionServer = this.createSdkServer();
+          this.sessionServers.add(sessionServer);
+          sessionServer.onclose = () => this.sessionServers.delete(sessionServer);
+          await sessionServer.connect(sessionTransport as unknown as SdkTransport);
+        });
+        transport = undefined;
       } else if (this.options.transport === "sse") {
         transport = createSseTransport(this.options.sseOptions);
         this.log(`Using SSE transport on ${this.options.sseOptions?.path ?? "/mcp/sse"}`);
@@ -361,9 +409,15 @@ export class McpServerTransport implements ServerTransport {
       }
 
       // Connect MCP server to transport
-      await this.mcpServer.connect(transport);
+      if (transport) await this.mcpServer.connect(transport);
+      if (this.http) {
+        this.httpUrl = await this.http.listen();
+        this.log(`Using Streamable HTTP at ${this.httpUrl}`);
+      }
     } catch (error) {
       this.removeRegistryListeners();
+      await this.http?.close().catch(() => undefined);
+      this.http = undefined;
       throw error;
     }
 
@@ -387,6 +441,11 @@ export class McpServerTransport implements ServerTransport {
     }
 
     await this.mcpServer.close();
+    await this.http?.close();
+    for (const sessionServer of this.sessionServers) await sessionServer.close().catch(() => undefined);
+    this.sessionServers.clear();
+    this.http = undefined;
+    this.httpUrl = undefined;
     this.running = false;
     this.log("MCP server stopped");
   }
@@ -406,6 +465,7 @@ export class McpServerTransport implements ServerTransport {
       running: this.running,
       toolCount: this.tools.size,
       transport: this.options.transport,
+      ...(this.httpUrl ? { url: this.httpUrl } : {}),
     };
   }
 

package/src/types.ts

@@ -7,10 +7,27 @@
 import type { Transport as SdkTransport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import type { ProcedureRegistry } from "@procedures/client";
 import type { McpServerInfo, McpToolFilter } from "@procedures/mcp";
+import type { Duration } from "@procedures/client";
 
 /**
  * SSE transport configuration options.
  */
+/** The options of the Streamable HTTP transport (roadmap R26). */
+export interface HttpTransportOptions {
+  /** Port to listen on (default: 3003) */
+  port?: number | undefined;
+  /** Host to bind to (default: "127.0.0.1": only this computer can reach the tools) */
+  host?: string | undefined;
+  /** The path of the MCP endpoint (default: "/mcp") */
+  path?: string | undefined;
+  /** A secret that each request must send as `Authorization: Bearer <token>` */
+  token?: string | undefined;
+  /** Browser origins that can call the server, besides loopback origins */
+  allowedOrigins?: string[] | undefined;
+  /** An HTTP server to answer on, in place of a server of the transport (it does not listen then) */
+  server?: import("node:http").Server | undefined;
+}
+
 export interface SseTransportOptions {
   /** Port to listen on (default: 3002) */
   port?: number;
@@ -26,8 +43,14 @@ export interface SseTransportOptions {
  * MCP Server Transport configuration options.
  */
 export interface McpServerTransportOptions {
-  /** Transport type: stdio or sse (default: "stdio") */
-  transport?: "stdio" | "sse";
+  /**
+   * Transport type (default: "stdio"). "http" is Streamable HTTP, the HTTP transport of the
+   * current MCP specification (roadmap R26). "sse" is not implemented.
+   */
+  transport?: "stdio" | "sse" | "http";
+
+  /** The options of the Streamable HTTP transport. */
+  httpOptions?: HttpTransportOptions | undefined;
 
   /** Procedure registry to use (defaults to PROCEDURE_REGISTRY) */
   registry?: ProcedureRegistry;
@@ -49,6 +72,13 @@ export interface McpServerTransportOptions {
 
   /** Enable debug logging */
   debug?: boolean;
+
+  /**
+   * The limits of a stream that can run without an end (`stream: { unbounded: true }` of its
+   * procedure): the tool stops it at the first one and gives the items that it has (roadmap R15).
+   * @default { items: 100, time: seconds(30) }
+   */
+  streamLimits?: { items?: number; time?: Duration } | undefined;
 }
 
 /**
@@ -60,5 +90,7 @@ export interface McpServerTransportState {
   /** Number of registered tools */
   toolCount: number;
   /** Transport type in use */
-  transport: "stdio" | "sse";
+  transport: "stdio" | "sse" | "http";
+  /** The URL of the Streamable HTTP endpoint, when the transport is "http" */
+  url?: string;
 }