@procedures/mcp-server 0.0.0-stage → 0.1.0

package/src/transport/mcp-transport.ts

@@ -0,0 +1,418 @@
+/**
+ * MCP Server Transport
+ *
+ * Implements ServerTransport interface for MCP protocol.
+ * Maps PROCEDURE_REGISTRY to MCP tools.
+ */
+
+import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  type ServerNotification,
+} from "@modelcontextprotocol/sdk/types.js";
+import type { Transport as SdkTransport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { ServerTransport, Server, ProcedureRegistry } from "@procedures/client";
+import { PROCEDURE_REGISTRY, pathToMethod } from "@procedures/client";
+import {
+  proceduresToMcpTools,
+  toToolDefinition,
+  decodePath,
+  type McpTool,
+} from "@procedures/mcp";
+import type { McpServerTransportOptions, McpServerTransportState } from "../types.js";
+import { createStdioTransport } from "./stdio.js";
+import { createSseTransport } from "./sse.js";
+
+/**
+ * Generate a unique request ID.
+ */
+/** The most text blocks of a stream result: the last items of a long stream. */
+const MAX_STREAM_BLOCKS = 100;
+
+function toText(value: unknown): string {
+  return typeof value === "string" ? value : (JSON.stringify(value, null, 2) ?? String(value));
+}
+
+/**
+ * The structured content of a result: the result as JSON, when it is an object. JSON drops
+ * what JSON cannot show (a function, `undefined`) and turns a class instance into its JSON form
+ * (an ObjectId into its hex text), as the text block does.
+ */
+function structuredContentOf(value: unknown): Record<string, unknown> | undefined {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+  try {
+    const json = JSON.parse(JSON.stringify(value)) as unknown;
+    return json !== null && typeof json === "object" && !Array.isArray(json) ? (json as Record<string, unknown>) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function generateRequestId(): string {
+  return `mcp-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+
+/**
+ * MCP Server Transport
+ *
+ * Implements the ServerTransport interface for MCP (Model Context Protocol).
+ * Maps procedures from PROCEDURE_REGISTRY to MCP tools, handling:
+ * - ListToolsRequest: Returns all registered procedures as tools
+ * - CallToolRequest: Executes the corresponding procedure
+ *
+ * @example
+ * ```typescript
+ * const server = new ProcedureServer({ autoRegister: true });
+ * const mcpTransport = new McpServerTransport(server, {
+ *   transport: "stdio",
+ *   serverInfo: { name: "my-server", version: "1.0.0" }
+ * });
+ * server.addTransport(mcpTransport);
+ * await server.start();
+ * ```
+ */
+export class McpServerTransport implements ServerTransport {
+  readonly name = "mcp";
+
+  private mcpServer: McpServer;
+  private server: Server;
+  private registry: ProcedureRegistry;
+  private options: Required<Pick<McpServerTransportOptions, "transport" | "serverInfo">> &
+    McpServerTransportOptions;
+  private running = false;
+  private tools: Map<string, McpTool> = new Map();
+  private registerListener: ((procedure: unknown) => void) | undefined;
+  private unregisterListener: ((procedure: unknown) => void) | undefined;
+  /** A pending list_changed notification: a burst of registrations sends one */
+  private listChangedTimer: ReturnType<typeof setTimeout> | undefined;
+
+  constructor(server: Server, options: McpServerTransportOptions = {}) {
+    this.server = server;
+    this.options = {
+      transport: options.transport ?? "stdio",
+      serverInfo: options.serverInfo ?? {
+        name: "procedure-server",
+        version: "1.0.0",
+      },
+      ...options,
+    };
+    // 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 =
+      options.registry ??
+      (server as { getRegistry?: () => ProcedureRegistry }).getRegistry?.() ??
+      PROCEDURE_REGISTRY;
+
+    // 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, {
+      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)
+  }
+
+  /**
+   * Setup MCP request handlers.
+   */
+  private setupHandlers(): void {
+    // ListToolsRequestSchema -> List all procedures as tools
+    this.mcpServer.setRequestHandler(ListToolsRequestSchema, async () => {
+      this.log("ListToolsRequest received");
+
+      const tools = Array.from(this.tools.values()).map(toToolDefinition);
+
+      this.log(`Returning ${tools.length} tools`);
+
+      return { tools };
+    });
+
+    // CallToolRequestSchema -> Execute procedure
+    this.mcpServer.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+      const { name, arguments: args } = request.params;
+
+      this.log(`CallToolRequest: ${name}`);
+
+      // Find tool
+      const tool = this.tools.get(name);
+      if (!tool) {
+        this.log(`Tool not found: ${name}`);
+        return {
+          content: [{ type: "text" as const, text: `Tool not found: ${name}` }],
+          isError: true,
+        };
+      }
+
+      // Decode path from tool name. The method is the core mapping of every host (deep dive
+      // architecture review 3.3)
+      const path = decodePath(name);
+
+      // Build ServerRequest
+      const serverRequest = {
+        id: generateRequestId(),
+        method: pathToMethod(path),
+        payload: args ?? {},
+        metadata: {
+          transport: "mcp" as const,
+          mcpRequestId: generateRequestId(),
+        },
+        // A cancelled tool call (notifications/cancelled) aborts the procedure
+        signal: extra.signal,
+      };
+
+      try {
+        // Process through universal server
+        const response = await this.server.handle(serverRequest);
+
+        this.log(`Tool ${name} completed: ${response.status.type}`);
+
+        // Convert to MCP result
+        if (response.status.type === "success" && response.stream) {
+          return await this.streamResult(response.stream, extra);
+        }
+        if (response.status.type === "success") {
+          const structured = tool.outputSchema ? structuredContentOf(response.payload) : undefined;
+          return {
+            content: [{ type: "text" as const, text: toText(response.payload) }],
+            // MCP structured output: the result as an object, for a tool with an output schema.
+            // The text block stays, for clients that do not read structured content.
+            ...(structured ? { structuredContent: structured } : {}),
+          };
+        } else {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: response.status.message ?? "Unknown error",
+              },
+            ],
+            isError: true,
+          };
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        this.log(`Tool ${name} error: ${message}`);
+
+        return {
+          content: [{ type: "text" as const, text: message }],
+          isError: true,
+        };
+      }
+    });
+  }
+
+  /**
+   * Setup registry event listeners for dynamic tool updates.
+   */
+  /**
+   * The result of a streaming procedure. An MCP tool result is one message, so the transport
+   * reads the whole stream. Each item becomes a text block (the last MAX_STREAM_BLOCKS items),
+   * and a progress notification when the caller sent a progress token, so a client can show
+   * the items while the stream runs.
+   */
+  private async streamResult(
+    stream: AsyncIterable<unknown>,
+    extra: {
+      _meta?: { progressToken?: string | number | undefined } | undefined;
+      sendNotification: (notification: ServerNotification) => Promise<void>;
+    }
+  ): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
+    const progressToken = extra._meta?.progressToken;
+    const blocks: Array<{ type: "text"; text: string }> = [];
+    let count = 0;
+    try {
+      for await (const item of stream) {
+        count++;
+        const text = toText(item);
+        blocks.push({ type: "text", text });
+        if (blocks.length > MAX_STREAM_BLOCKS) blocks.shift();
+        if (progressToken !== undefined) {
+          await extra
+            .sendNotification({
+              method: "notifications/progress",
+              params: { progressToken, progress: count, message: text.slice(0, 1000) },
+            })
+            .catch(() => undefined);
+        }
+      }
+    } catch (error) {
+      blocks.push({ type: "text", text: error instanceof Error ? error.message : String(error) });
+      return { content: blocks, isError: true };
+    }
+    if (count > MAX_STREAM_BLOCKS) {
+      blocks.unshift({ type: "text", text: `(${count} items: the first ${count - MAX_STREAM_BLOCKS} are not shown)` });
+    }
+    if (count === 0) blocks.push({ type: "text", text: "(no items)" });
+    return { content: blocks };
+  }
+
+  private setupRegistryListeners(): void {
+    // Create listener functions that we can later remove
+    this.registerListener = () => {
+      this.log("Procedure registered, refreshing tools");
+      this.refreshTools();
+    };
+
+    this.unregisterListener = () => {
+      this.log("Procedure unregistered, refreshing tools");
+      this.refreshTools();
+    };
+
+    // Refresh tools when procedures are registered/unregistered
+    this.registry.on("register", this.registerListener);
+    this.registry.on("unregister", this.unregisterListener);
+  }
+
+  /**
+   * Remove the registry event listeners, if attached.
+   */
+  private removeRegistryListeners(): void {
+    if (this.registerListener) {
+      this.registry.off("register", this.registerListener);
+      this.registerListener = undefined;
+    }
+    if (this.unregisterListener) {
+      this.registry.off("unregister", this.unregisterListener);
+      this.unregisterListener = undefined;
+    }
+  }
+
+  /**
+   * Refresh the tool list from the registry.
+   */
+  private refreshTools(): void {
+    const procedures = this.registry.getAll();
+    const mcpTools = proceduresToMcpTools(procedures, this.options.toolFilter);
+    const before = this.toolSignature();
+
+    this.tools.clear();
+    for (const tool of mcpTools) {
+      this.tools.set(tool.name, tool);
+    }
+
+    this.log(`Refreshed tools: ${this.tools.size} available`);
+    if (this.running && this.toolSignature() !== before) this.scheduleListChanged();
+  }
+
+  /** The tool names and descriptions: a change of this text is a change of the tool list. */
+  private toolSignature(): string {
+    const entries = Array.from(this.tools.values(), (tool) => [tool.name, tool.description ?? ""]);
+    return JSON.stringify(entries.sort((a, b) => (a[0]! < b[0]! ? -1 : a[0]! > b[0]! ? 1 : 0)));
+  }
+
+  /** Send one notifications/tools/list_changed for a burst of registry events. */
+  private scheduleListChanged(): void {
+    if (this.listChangedTimer) return;
+    this.listChangedTimer = setTimeout(() => {
+      this.listChangedTimer = undefined;
+      if (!this.running) return;
+      this.mcpServer.sendToolListChanged().catch((error: unknown) => {
+        this.log(`list_changed failed: ${error instanceof Error ? error.message : String(error)}`);
+      });
+    }, 0);
+    this.listChangedTimer.unref?.();
+  }
+
+  /**
+   * Log a debug message if debug mode is enabled.
+   */
+  private log(message: string): void {
+    if (this.options.debug) {
+      // MUST be stderr: the stdio MCP transport uses stdout for JSON-RPC framing, so any
+      // stdout write here corrupts the protocol stream. See documentation/BUGS-2026-07.md (M39/Bug4).
+      console.error(`[${this.name}] ${message}`);
+    }
+  }
+
+  /**
+   * Start the MCP transport.
+   */
+  async start(): Promise<void> {
+    if (this.running) {
+      this.log("Already running");
+      return;
+    }
+
+    // Refresh tools before starting, and keep them current while running
+    this.refreshTools();
+    this.setupRegistryListeners();
+
+    try {
+      // Create appropriate transport
+      let transport: SdkTransport;
+      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 === "sse") {
+        transport = createSseTransport(this.options.sseOptions);
+        this.log(`Using SSE transport on ${this.options.sseOptions?.path ?? "/mcp/sse"}`);
+      } else {
+        throw new Error(`Unknown MCP transport: ${this.options.transport}`);
+      }
+
+      // Connect MCP server to transport
+      await this.mcpServer.connect(transport);
+    } catch (error) {
+      this.removeRegistryListeners();
+      throw error;
+    }
+
+    this.running = true;
+    this.log(`MCP server started (${this.options.transport}), ${this.tools.size} tools available`);
+  }
+
+  /**
+   * Stop the MCP transport.
+   */
+  async stop(): Promise<void> {
+    if (!this.running) {
+      return;
+    }
+
+    // Cleanup registry listeners
+    this.removeRegistryListeners();
+    if (this.listChangedTimer) {
+      clearTimeout(this.listChangedTimer);
+      this.listChangedTimer = undefined;
+    }
+
+    await this.mcpServer.close();
+    this.running = false;
+    this.log("MCP server stopped");
+  }
+
+  /**
+   * Check if the transport is running.
+   */
+  isRunning(): boolean {
+    return this.running;
+  }
+
+  /**
+   * Get current transport state.
+   */
+  getState(): McpServerTransportState {
+    return {
+      running: this.running,
+      toolCount: this.tools.size,
+      transport: this.options.transport,
+    };
+  }
+
+  /**
+   * Get the list of available tools.
+   */
+  getTools(): McpTool[] {
+    return Array.from(this.tools.values());
+  }
+}

package/src/transport/sse.ts

@@ -0,0 +1,29 @@
+/**
+ * SSE Transport Wrapper
+ *
+ * Creates an MCP SSE (Server-Sent Events) transport for HTTP streaming.
+ * NOTE: SSE transport requires HTTP server integration - use with Express or similar.
+ */
+
+import type { SseTransportOptions } from "../types.js";
+
+/**
+ * SSE transport is not yet implemented as a standalone transport.
+ *
+ * SSE requires HTTP server integration with:
+ * - GET endpoint for SSE connection
+ * - POST endpoint for messages
+ *
+ * For now, use stdio transport or implement SSE with your HTTP framework directly.
+ *
+ * @throws Error - SSE transport requires HTTP server integration
+ */
+export function createSseTransport(
+  _options?: SseTransportOptions
+): never {
+  throw new Error(
+    "SSE transport requires HTTP server integration. " +
+    "Use stdio transport for standalone MCP server, or integrate SSE " +
+    "with your HTTP framework (Express, etc.) using SSEServerTransport directly."
+  );
+}

package/src/transport/stdio.ts

@@ -0,0 +1,19 @@
+/**
+ * Stdio Transport Wrapper
+ *
+ * Creates an MCP stdio transport for CLI usage.
+ */
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+/**
+ * Create a stdio transport for MCP server.
+ *
+ * Stdio transport uses standard input/output for communication,
+ * suitable for CLI tools and desktop app integrations.
+ *
+ * @returns MCP stdio transport instance
+ */
+export function createStdioTransport(): StdioServerTransport {
+  return new StdioServerTransport();
+}

package/src/types.ts

@@ -0,0 +1,64 @@
+/**
+ * MCP Transport Types
+ *
+ * Configuration options for the MCP server transport.
+ */
+
+import type { Transport as SdkTransport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { ProcedureRegistry } from "@procedures/client";
+import type { McpServerInfo, McpToolFilter } from "@procedures/mcp";
+
+/**
+ * SSE transport configuration options.
+ */
+export interface SseTransportOptions {
+  /** Port to listen on (default: 3002) */
+  port?: number;
+  /** Host to bind to (default: "0.0.0.0") */
+  host?: string;
+  /** Path for SSE endpoint (default: "/mcp/sse") */
+  path?: string;
+  /** Enable CORS (default: true) */
+  cors?: boolean;
+}
+
+/**
+ * MCP Server Transport configuration options.
+ */
+export interface McpServerTransportOptions {
+  /** Transport type: stdio or sse (default: "stdio") */
+  transport?: "stdio" | "sse";
+
+  /** Procedure registry to use (defaults to PROCEDURE_REGISTRY) */
+  registry?: ProcedureRegistry;
+
+  /** Server info for MCP protocol */
+  serverInfo?: McpServerInfo;
+
+  /** Tool filtering options */
+  toolFilter?: McpToolFilter;
+
+  /** SSE-specific options (when transport is "sse") */
+  sseOptions?: SseTransportOptions;
+
+  /**
+   * An MCP SDK transport to connect, in place of `transport`. Use it to embed the server in
+   * another process, or in a test (the SDK's `InMemoryTransport`).
+   */
+  sdkTransport?: SdkTransport;
+
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+/**
+ * MCP Server Transport state.
+ */
+export interface McpServerTransportState {
+  /** Whether the transport is running */
+  running: boolean;
+  /** Number of registered tools */
+  toolCount: number;
+  /** Transport type in use */
+  transport: "stdio" | "sse";
+}