@procedures/mcp-server 0.10.0 → 0.12.0

package/src/face.ts

@@ -0,0 +1,96 @@
+/**
+ * The MCP face of a procedures host (CLI-7): Streamable HTTP at a path of a listener of the host.
+ *
+ * `mcpFace(options)` gives a face factory for `createProcedureHost({ faces: { mcp: mcpFace() } })`
+ * of `@procedures/peer`. The face mounts on the mount list of the listener, so the MCP endpoint
+ * shares the port of the other faces. Each tool call goes through the handler of the face, thus
+ * through the request tracking of the service of the host.
+ *
+ * - The tools are the procedures of the registry of the host that its policy exposes.
+ * - Without a token of its own, the face takes the token of the policy. Without origins of its
+ *   own, it takes the permitted origins of the policy.
+ * - The types are structural: this package does not depend on `@procedures/peer`.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { HostPolicy, ProcedureRegistry, RequestHandler } from "@procedures/client";
+import type { McpToolFilter } from "@procedures/mcp";
+import { McpServerTransport } from "./transport/mcp-transport.js";
+import type { McpServerTransportOptions } from "./types.js";
+
+/** The options of `mcpFace()`: the options of an MCP transport, with the path of its endpoint. */
+export interface McpFaceOptions extends Omit<McpServerTransportOptions, "transport" | "httpOptions" | "sdkTransport" | "stdio" | "sseOptions" | "registry"> {
+  /** The path of the endpoint. The default is `/mcp`. */
+  readonly path?: string | undefined;
+  /** The token that each request sends as `Authorization: Bearer <token>`. The default is the token of the policy. */
+  readonly token?: string | undefined;
+  /** The browser origins that can call the endpoint, besides loopback origins. The default is the list of the policy. */
+  readonly allowedOrigins?: string[] | undefined;
+}
+
+/** What the MCP face needs of its host: the handler of its calls, the registry and the policy. */
+export interface McpFaceContext {
+  readonly handler: RequestHandler;
+  readonly registry: ProcedureRegistry;
+  readonly policy: HostPolicy;
+}
+
+/** The MCP face: its request handler, its stop parts, its endpoint and its transport. */
+export interface McpFace {
+  readonly handler: (req: IncomingMessage, res: ServerResponse) => boolean;
+  readonly parts: {
+    start(): Promise<void>;
+    stopIntake(): void;
+    drain(): Promise<void>;
+    inFlight(): number;
+    close(): Promise<void>;
+  };
+  readonly endpoint: { readonly type: string; readonly scheme: "http"; readonly path: string };
+  readonly transport: McpServerTransport;
+}
+
+/**
+ * This function gives the MCP face of a procedures host. The host calls the factory one time.
+ *
+ * @example
+ * ```typescript
+ * const host = createProcedureHost({ registry, policy, faces: { http: true, mcp: mcpFace({ serverInfo }) }, listen });
+ * ```
+ */
+export function mcpFace(options: McpFaceOptions = {}): (context: McpFaceContext) => McpFace {
+  return (context) => {
+    const { path: givenPath, token: givenToken, allowedOrigins: givenOrigins, ...common } = options;
+    const path = givenPath ?? "/mcp";
+    const token = givenToken ?? context.policy.token;
+    const policyOrigins = context.policy.browser.allowedOrigins;
+    const allowedOrigins = givenOrigins ?? (Array.isArray(policyOrigins) ? [...policyOrigins] : undefined);
+    const toolFilter: McpToolFilter = { ...common.toolFilter, ...(context.policy.expose ? { include: context.policy.expose } : {}) };
+    const transport = new McpServerTransport(context.handler, {
+      ...common,
+      registry: context.registry,
+      toolFilter,
+      transport: "http",
+      httpOptions: {
+        mount: true,
+        path,
+        ...(token !== undefined ? { token } : {}),
+        ...(allowedOrigins ? { allowedOrigins } : {}),
+        ...(context.handler.ambientCredentials ? { ambientCredentials: context.handler.ambientCredentials } : {}),
+      },
+    });
+    return {
+      handler: (req, res) => transport.handleHttp(req, res),
+      // The tool calls go through the request tracking of the host: the face counts no work of its own.
+      // An open stream of a session ends at the close of the face.
+      parts: {
+        start: () => transport.start(),
+        stopIntake: () => undefined,
+        drain: async () => undefined,
+        inFlight: () => 0,
+        close: () => transport.stop(),
+      },
+      endpoint: { type: "mcp", scheme: "http", path },
+      transport,
+    };
+  };
+}

package/src/index.ts

@@ -20,6 +20,10 @@ export { createMcpHost, mcpExposeRule, redirectConsoleToStderr } from "./host.js
 export type { McpHost, McpHostOptions, McpHostFaces, McpStdioFace, McpHostServerOptions, McpHostParts, McpHostState } from "./host.js";
 export { DEFAULT_ELICIT_TIMEOUT_MS } from "./transport/mcp-transport.js";
 
+// The MCP face of a procedures host (CLI-7): Streamable HTTP on a listener of the host
+export { mcpFace } from "./face.js";
+export type { McpFace, McpFaceContext, McpFaceOptions } from "./face.js";
+
 // The envelopes of the text from outside the host (CLI-10)
 export { createUntrustedEnvelopes, defaultUntrustedNotice, DEFAULT_UNTRUSTED_TAG } from "./untrusted.js";
 export type { UntrustedContentOptions, UntrustedWrapContext, UntrustedEnvelopes } from "./untrusted.js";

package/src/transport/http.ts

@@ -23,8 +23,13 @@ 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. */
+  /** This function starts to listen, when the endpoint has a server of its own. It gives the URL, or the path of a mounted endpoint. */
   listen(): Promise<string>;
+  /**
+   * This function answers a request of the path of the endpoint and gives true. It gives false for
+   * another path, when the endpoint does not own its server.
+   */
+  handle(req: IncomingMessage, res: ServerResponse): boolean;
   /** The number of open sessions. */
   readonly sessions: number;
   /** This function closes each session, and the server when the endpoint made one. */
@@ -41,8 +46,9 @@ export function createHttpTransport(
 ): 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 mounted = options.mount === true;
+  const owned = !mounted && options.server === undefined;
+  const server: HttpServer | undefined = mounted ? undefined : (options.server ?? createServer());
   const sessions = new Map<string, StreamableHTTPServerTransport>();
 
   const refuse = (res: ServerResponse, status: number, code: string, message: string): void => {
@@ -69,11 +75,12 @@ export function createHttpTransport(
     return transport;
   };
 
-  const onRequest = (req: IncomingMessage, res: ServerResponse): void => {
+  const handle = (req: IncomingMessage, res: ServerResponse): boolean => {
     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;
+      if (!owned) return false;
+      refuse(res, 404, "NOT_FOUND", `No MCP endpoint at ${url.pathname}`);
+      return true;
     }
     // A web page must not reach the tools: the host and the origin of the request. A server that
     // reads cookies trusts a request with ambient credentials only from a named origin (CSRF)
@@ -81,11 +88,11 @@ export function createHttpTransport(
     const guard = checkBrowserRequest(req, { ...(options.allowedOrigins ? { allowedOrigins: options.allowedOrigins } : {}) }, false, ambient);
     if (!guard.ok) {
       refuse(res, guard.status, guard.code, guard.message);
-      return;
+      return true;
     }
     if (options.token !== undefined && !tokenMatches(options.token, bearerOf(req.headers["authorization"]))) {
       refuse(res, 401, "UNAUTHORIZED", "Unauthorized: this server requires its token");
-      return;
+      return true;
     }
     void transportOf(req)
       .then((transport) => {
@@ -98,11 +105,17 @@ export function createHttpTransport(
       .catch((error: unknown) => {
         if (!res.headersSent) refuse(res, 500, "INTERNAL_ERROR", error instanceof Error ? error.message : String(error));
       });
+    return true;
+  };
+  const onRequest = (req: IncomingMessage, res: ServerResponse): void => {
+    handle(req, res);
   };
-  server.on("request", onRequest);
+  server?.on("request", onRequest);
 
   return {
+    handle,
     listen: async () => {
+      if (!server) return path;
       if (owned && !server.listening) {
         await new Promise<void>((resolve, reject) => {
           server.once("error", reject);
@@ -120,11 +133,11 @@ export function createHttpTransport(
       return sessions.size;
     },
     close: async () => {
-      server.off("request", onRequest);
+      server?.off("request", onRequest);
       const open = [...sessions.values()];
       sessions.clear();
       await Promise.all(open.map((transport) => transport.close().catch(() => undefined)));
-      if (owned && server.listening) {
+      if (owned && server?.listening) {
         await new Promise<void>((resolve) => {
           server.close(() => resolve());
           server.closeAllConnections();

package/src/transport/mcp-transport.ts

@@ -12,9 +12,9 @@ import {
   type ServerNotification,
 } from "@modelcontextprotocol/sdk/types.js";
 import type { Transport as SdkTransport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { IncomingMessage, ServerResponse } from "node:http";
 import type {
   ServerTransport,
-  Server,
   ProcedureRegistry,
   RequestHandler,
   Credentials,
@@ -156,7 +156,8 @@ export class McpServerTransport implements ServerTransport {
   readonly name = "mcp";
 
   private mcpServer: McpServer;
-  private server: Server;
+  /** The handler of the calls: a server, or the handler of a face of a procedures host (CLI-7). */
+  private server: RequestHandler;
   private registry: ProcedureRegistry;
   private options: Required<Pick<McpServerTransportOptions, "transport" | "serverInfo">> &
     McpServerTransportOptions;
@@ -176,7 +177,7 @@ export class McpServerTransport implements ServerTransport {
   /** This function removes the listener of the end of the stdio input */
   private stdinEnd: (() => void) | undefined;
 
-  constructor(server: Server, options: McpServerTransportOptions = {}) {
+  constructor(server: RequestHandler, options: McpServerTransportOptions = {}) {
     this.server = server;
     this.options = {
       transport: options.transport ?? "stdio",
@@ -671,6 +672,14 @@ export class McpServerTransport implements ServerTransport {
     this.log("MCP server stopped");
   }
 
+  /**
+   * This method answers a request of the Streamable HTTP endpoint on a listener that another part
+   * owns (`httpOptions.mount`, CLI-7). It gives false for another path, and before `start()`.
+   */
+  handleHttp(req: IncomingMessage, res: ServerResponse): boolean {
+    return this.http?.handle(req, res) ?? false;
+  }
+
   /**
    * Check if the transport is running.
    */

package/src/types.ts

@@ -65,6 +65,11 @@ export interface HttpTransportOptions {
   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;
+  /**
+   * True: the endpoint has no server and attaches to none. The owner of a listener mounts its
+   * request handler (`McpServerTransport.handleHttp`), for example the procedures host (CLI-7).
+   */
+  mount?: boolean | undefined;
   /**
    * How the procedure server reads cookies (`ambientCredentials` of `ProcedureServer`). The
    * transport sets it from its server. With a value, a request with a cookie needs a named origin.