@procedures/mcp-server 0.0.0-stage → 0.1.0

package/src/index.ts

@@ -0,0 +1,48 @@
+/**
+ * MCP Client Package
+ *
+ * MCP server transport for the procedure system.
+ * Maps PROCEDURE_REGISTRY to MCP tools for use with Claude Desktop
+ * and other MCP-compatible clients.
+ *
+ * @packageDocumentation
+ */
+
+// Importing the package registers its procedures, as in the other client packages (BUGS-2026-07 H18)
+import "./register.js";
+
+// Transport
+export { McpServerTransport } from "./transport/mcp-transport.js";
+export { createStdioTransport } from "./transport/stdio.js";
+export { createSseTransport } from "./transport/sse.js";
+
+// Types
+export type {
+  McpServerTransportOptions,
+  McpServerTransportState,
+  SseTransportOptions,
+} from "./types.js";
+
+// Procedures
+export { mcpServeProcedure, prepareServe, DEFAULT_SERVE_BUNDLE } from "./procedures/mcp/serve.js";
+export type { ServeOptions, ServeSetup } from "./procedures/mcp/serve.js";
+export { exposeRule, mergeSurfaces, importBundles, resolveBundleRegister } from "./surface.js";
+export type { ToolSurface, BundleSurfaceModule } from "./surface.js";
+export { mcpListToolsProcedure } from "./procedures/mcp/list-tools.js";
+
+// Re-export core MCP types for convenience
+export type {
+  McpTool,
+  McpToolDefinition,
+  McpToolFilter,
+  McpServerInfo,
+  McpTransportType,
+} from "@procedures/mcp";
+
+// Re-export mapping utilities
+export {
+  proceduresToMcpTools,
+  procedureToMcpTool,
+  encodePath,
+  decodePath,
+} from "@procedures/mcp";

package/src/module.ts

@@ -0,0 +1,18 @@
+/**
+ * Module (no side effects): the MCP procedures as data, for `createRegistry()`.
+ */
+
+import { defineModule, type AnyProcedure, type ProcedureModule } from "@procedures/client";
+import { mcpServeProcedure } from "./procedures/mcp/serve.js";
+import { mcpListToolsProcedure } from "./procedures/mcp/list-tools.js";
+
+/**
+ * The module of this package, for `createRegistry()`: its procedures as data. Importing this
+ * file registers nothing. (`register.ts` registers the same procedures in the global registry.)
+ */
+export const mcpModule: ProcedureModule = defineModule("@procedures/mcp-server", [
+  mcpServeProcedure as AnyProcedure,
+  mcpListToolsProcedure as AnyProcedure,
+]);
+
+export default mcpModule;

package/src/procedures/mcp/index.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP Procedures
+ */
+
+export { mcpServeProcedure } from "./serve.js";
+export { mcpListToolsProcedure } from "./list-tools.js";

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

@@ -0,0 +1,84 @@
+/**
+ * mcp.list-tools Procedure
+ *
+ * List available MCP tools from the procedure registry.
+ */
+
+import { z } from "zod";
+import { defineProcedure, PROCEDURE_REGISTRY, type AnyProcedure } from "@procedures/client";
+import { proceduresToMcpTools, type McpToolFilter } from "@procedures/mcp";
+
+const McpListToolsInputSchema = z.object({
+  /** Only include procedures with these tags */
+  includeTags: z.array(z.string()).optional().describe("Only include procedures with these tags"),
+  /** Exclude procedures with these tags */
+  excludeTags: z.array(z.string()).optional().describe("Exclude procedures with these tags"),
+  /** Exclude internal procedures (default: true) */
+  excludeInternal: z.boolean().default(true).describe("Exclude internal procedures (default: true)"),
+  /** Only include procedures under this path prefix */
+  pathPrefix: z.array(z.string()).optional().describe("Only include procedures under this path prefix"),
+});
+
+type McpListToolsInput = z.infer<typeof McpListToolsInputSchema>;
+
+interface McpToolInfo {
+  name: string;
+  description: string | undefined;
+  path: string[];
+  streaming: boolean | undefined;
+  tags: string[] | undefined;
+}
+
+interface McpListToolsOutput {
+  tools: McpToolInfo[];
+  count: number;
+}
+
+const McpListToolsOutputSchema: {
+  parse: (data: unknown) => McpListToolsOutput;
+  safeParse: (data: unknown) => { success: true; data: McpListToolsOutput };
+} = {
+  parse: (data: unknown) => data as McpListToolsOutput,
+  safeParse: (data: unknown) => ({ success: true as const, data: data as McpListToolsOutput }),
+};
+
+export const mcpListToolsProcedure: AnyProcedure = defineProcedure({
+  path: ["mcp", "list-tools"],
+  input: McpListToolsInputSchema,
+  output: McpListToolsOutputSchema,
+  metadata: {
+    description: "List available MCP tools from the procedure registry",
+    tags: ["mcp", "introspection"],
+  },
+  handler: async (input: McpListToolsInput): Promise<McpListToolsOutput> => {
+    // Build filter, only adding defined values
+    const filter: McpToolFilter = {
+      excludeInternal: input.excludeInternal,
+    };
+    if (input.includeTags !== undefined) {
+      filter.includeTags = input.includeTags;
+    }
+    if (input.excludeTags !== undefined) {
+      filter.excludeTags = input.excludeTags;
+    }
+    if (input.pathPrefix !== undefined) {
+      filter.pathPrefix = input.pathPrefix;
+    }
+
+    const procedures = PROCEDURE_REGISTRY.getAll();
+    const mcpTools = proceduresToMcpTools(procedures, filter);
+
+    const tools: McpToolInfo[] = mcpTools.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      path: tool.procedurePath,
+      streaming: tool.streaming,
+      tags: tool.tags,
+    }));
+
+    return {
+      tools,
+      count: tools.length,
+    };
+  },
+});

package/src/procedures/mcp/serve.ts

@@ -0,0 +1,170 @@
+/**
+ * mcp.serve Procedure
+ *
+ * Start MCP server to expose procedures as tools.
+ *
+ * Which procedures are tools is a security decision. Before, `mcp.serve` exposed every
+ * procedure of the registry, `shell.exec` too (deep dive, architecture review 3.2). Now the tools
+ * come from `namespaces`/`exclude`, or from the `mcpNamespaces`/`mcpExclude` of the bundles
+ * (default: `@procedures/bundle-mcp`, resolved from the current folder). Without a list,
+ * nothing is exposed. The nested calls follow the call policy (`strictCalls`), and each tool call
+ * has a time limit.
+ */
+
+import { z } from "zod";
+import {
+  defineProcedure,
+  ProcedureServer,
+  PROCEDURE_REGISTRY,
+  timeoutInterceptor,
+  type AnyProcedure,
+  type ProcedurePath,
+} from "@procedures/client";
+import { McpServerTransport } from "../../transport/mcp-transport.js";
+import type { McpServerTransportOptions } from "../../types.js";
+import { exposeRule, importBundles, mergeSurfaces } from "../../surface.js";
+
+/** The default bundle of the tool surface. */
+export const DEFAULT_SERVE_BUNDLE = "@procedures/bundle-mcp";
+
+const McpServeInputSchema = z.object({
+  /**
+   * Transport type (default: "stdio"). Only stdio is implemented: the SSE transport needs an
+   * HTTP server integration, and accepting "sse" here only led to an error (BUGS-2026-07 L28).
+   */
+  transport: z.enum(["stdio"]).default("stdio").describe("Transport type (default: \"stdio\"). Only stdio is implemented: the SSE transport needs an HTTP server integration, and accepting \"sse\" here only led to an error (BUGS-2026-07 L28)."),
+  /** Server name for MCP (default: "procedure-server") */
+  name: z.string().optional().describe("Server name for MCP (default: \"procedure-server\")"),
+  /** Server version for MCP (default: "1.0.0") */
+  version: z.string().optional().describe("Server version for MCP (default: \"1.0.0\")"),
+  /** Whether to auto-register all procedures (default: true) */
+  autoRegister: z.boolean().default(true).describe("Whether to auto-register all procedures (default: true)"),
+  /** Enable debug logging */
+  debug: z.boolean().default(false).describe("Enable debug logging"),
+  /** The namespaces (first path segments) of the tools. With this list, the bundles give no tools. */
+  namespaces: z.array(z.string()).optional().describe("The namespaces (first path segments) of the tools. With this list, the bundles give no tools."),
+  /** Procedure keys of the tool namespaces that are not tools. */
+  exclude: z.array(z.string()).optional().describe("Procedure keys of the tool namespaces that are not tools."),
+  /** The bundles whose mcpNamespaces and mcpExclude give the tools, when `namespaces` is not given. */
+  bundles: z.array(z.string()).optional().describe("The bundles whose mcpNamespaces and mcpExclude give the tools, when `namespaces` is not given."),
+  /** True (the default): a procedure of code without metadata.calls can call only tools. */
+  strictCalls: z.boolean().default(true).describe("True (the default): a procedure of code without metadata.calls can call only tools."),
+  /** The time limit of each tool call, in milliseconds (default: 600000). 0: no limit. */
+  toolTimeoutMs: z.number().int().min(0).default(600_000).describe("The time limit of each tool call, in milliseconds (default: 600000). 0: no limit."),
+});
+
+type McpServeInput = z.infer<typeof McpServeInputSchema>;
+
+interface McpServeOutput {
+  success: boolean;
+  transport: string;
+  toolCount: number;
+  serverName: string;
+  /** Why the server has no tools, when it has none. */
+  warning?: string;
+}
+
+const McpServeOutputSchema: {
+  parse: (data: unknown) => McpServeOutput;
+  safeParse: (data: unknown) => { success: true; data: McpServeOutput };
+} = {
+  parse: (data: unknown) => data as McpServeOutput,
+  safeParse: (data: unknown) => ({ success: true as const, data: data as McpServeOutput }),
+};
+
+/** The options of `prepareServe`: the tool surface and the rules of the server. */
+export interface ServeOptions {
+  autoRegister?: boolean | undefined;
+  namespaces?: readonly string[] | undefined;
+  exclude?: readonly string[] | undefined;
+  bundles?: readonly string[] | undefined;
+  strictCalls?: boolean | undefined;
+  toolTimeoutMs?: number | undefined;
+}
+
+/** The server of `mcp.serve`, before its transport starts. */
+export interface ServeSetup {
+  server: ProcedureServer;
+  expose: (path: ProcedurePath) => boolean;
+  /** Why the server has no tools, when it has none. */
+  warning?: string;
+}
+
+/**
+ * This function builds the procedure server of `mcp.serve`: its expose rule, its call policy and
+ * its interceptors. The bundles resolve from `from` (default: the current folder).
+ */
+export async function prepareServe(input: ServeOptions, from: string = process.cwd()): Promise<ServeSetup> {
+  let expose: (path: ProcedurePath) => boolean = () => false;
+  let warning: string | undefined;
+  if (input.namespaces) {
+    expose = exposeRule({ namespaces: input.namespaces, exclude: input.exclude });
+  } else {
+    const bundles = input.bundles ?? [DEFAULT_SERVE_BUNDLE];
+    try {
+      const surface = mergeSurfaces(await importBundles(bundles, from));
+      if (surface) {
+        expose = exposeRule({ namespaces: surface.namespaces, exclude: [...(surface.exclude ?? []), ...(input.exclude ?? [])] });
+      } else {
+        warning = `The bundles ${bundles.join(", ")} give no mcpNamespaces, so no procedure is a tool. Give namespaces.`;
+      }
+    } catch (error) {
+      warning =
+        `The bundles ${bundles.join(", ")} cannot be loaded from ${from} (${(error as Error).message}), ` +
+        `so no procedure is a tool. Give namespaces, or run in a project that has the bundles.`;
+    }
+  }
+
+  const server = new ProcedureServer({
+    autoRegister: input.autoRegister ?? true,
+    registry: PROCEDURE_REGISTRY,
+    expose,
+    strictCalls: input.strictCalls ?? true,
+    interceptors: [timeoutInterceptor({ ms: input.toolTimeoutMs ?? 600_000 })],
+  });
+  return warning === undefined ? { server, expose } : { server, expose, warning };
+}
+
+export const mcpServeProcedure: AnyProcedure = defineProcedure({
+  path: ["mcp", "serve"],
+  input: McpServeInputSchema,
+  output: McpServeOutputSchema,
+  metadata: {
+    description: "Start MCP server to expose procedures as tools",
+    tags: ["mcp", "server"],
+  },
+  handler: async (input: McpServeInput): Promise<McpServeOutput> => {
+    const serverName = input.name ?? "procedure-server";
+    const serverVersion = input.version ?? "1.0.0";
+    const { server, expose, warning } = await prepareServe(input);
+
+    // Build transport options
+    const options: McpServerTransportOptions = {
+      transport: input.transport,
+      serverInfo: {
+        name: serverName,
+        version: serverVersion,
+      },
+      debug: input.debug,
+      toolFilter: { include: expose },
+    };
+
+    // Create MCP transport
+    const mcpTransport = new McpServerTransport(server, options);
+
+    // Add transport and start
+    server.addTransport(mcpTransport);
+    await server.start();
+
+    const state = mcpTransport.getState();
+    if (warning) console.error(`[mcp.serve] ${warning}`);
+
+    return {
+      success: true,
+      transport: input.transport,
+      toolCount: state.toolCount,
+      serverName,
+      ...(warning ? { warning } : {}),
+    };
+  },
+});

package/src/register.ts

@@ -0,0 +1,24 @@
+/**
+ * Importing this file registers the MCP procedures in the global registry (DECISIONS-2026-10,
+ * "Every package root registers its procedures"). The procedures as data are in `module.ts`,
+ * which registers nothing: a host with its own registry uses that one.
+ */
+
+import { PROCEDURE_REGISTRY } from "@procedures/client";
+import { mcpModule } from "./module.js";
+
+export * from "./module.js";
+
+/**
+ * Register all MCP procedures.
+ */
+export function registerMcpProcedures(): void {
+  for (const proc of mcpModule.procedures) {
+    if (!PROCEDURE_REGISTRY.has(proc.path)) {
+      PROCEDURE_REGISTRY.register(proc);
+    }
+  }
+}
+
+// Auto-register when this module is imported
+registerMcpProcedures();

package/src/surface.ts

@@ -0,0 +1,85 @@
+/**
+ * The tool surface of an MCP server: which procedures are tools.
+ *
+ * A bundle (for example `@procedures/bundle-mcp`) registers procedures when it is imported.
+ * Its `register.js` exports `mcpNamespaces` (the first path segments of the tools) and
+ * `mcpExclude` (procedure keys of those namespaces that are not tools). The dev-tools server
+ * (`impl-mcp-dev`) and `mcp.serve` build their expose rule from these lists.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { surfaceRule, type ProcedurePath, type ToolSurface } from "@procedures/client";
+
+/** The tools of a server: the namespaces, less the excluded procedure keys (the core type). */
+export type { ToolSurface };
+
+/** The exports of a bundle's `register.js` that describe its tools. */
+export interface BundleSurfaceModule {
+  mcpNamespaces?: readonly string[];
+  mcpExclude?: readonly string[];
+}
+
+/** The expose rule of a tool surface: `surfaceRule()` of the core host policy (roadmap 2.3). */
+export function exposeRule(surface: ToolSurface): (path: ProcedurePath) => boolean {
+  return surfaceRule(surface);
+}
+
+/**
+ * The union of the surfaces of some bundles. Undefined when no bundle has `mcpNamespaces`: such
+ * bundles say nothing about their tools.
+ */
+export function mergeSurfaces(modules: readonly BundleSurfaceModule[]): ToolSurface | undefined {
+  let namespaces: Set<string> | undefined;
+  const exclude = new Set<string>();
+  for (const module of modules) {
+    if (Array.isArray(module.mcpNamespaces)) {
+      namespaces ??= new Set();
+      for (const namespace of module.mcpNamespaces) namespaces.add(namespace);
+    }
+    for (const key of module.mcpExclude ?? []) exclude.add(key);
+  }
+  return namespaces ? { namespaces: [...namespaces].sort(), exclude: [...exclude].sort() } : undefined;
+}
+
+/**
+ * The file URL of a bundle's `register.js`, found in the `node_modules` folders from `from`
+ * upward. The bundle's `exports` map gives the file. (`require.resolve` cannot do it: a bundle
+ * exports `register.js` for `import` only.)
+ */
+export function resolveBundleRegister(bundle: string, from: string): string {
+  let dir = resolve(from);
+  for (;;) {
+    const folder = join(dir, "node_modules", ...bundle.split("/"));
+    const manifestPath = join(folder, "package.json");
+    if (existsSync(manifestPath)) {
+      const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as { exports?: Record<string, unknown> };
+      const entry = manifest.exports?.["./register.js"];
+      const target =
+        typeof entry === "string"
+          ? entry
+          : ((entry as { import?: string; default?: string } | undefined)?.import ??
+            (entry as { default?: string } | undefined)?.default ??
+            "./dist/register.js");
+      return pathToFileURL(join(folder, target)).href;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) throw new Error(`Cannot find ${bundle} from ${from}`);
+    dir = parent;
+  }
+}
+
+/**
+ * This function imports the `register.js` of each bundle, which registers its procedures, and
+ * returns the modules. With `from`, a bundle resolves from that folder (a project), not from
+ * this package.
+ */
+export async function importBundles(bundles: readonly string[], from?: string): Promise<BundleSurfaceModule[]> {
+  const modules: BundleSurfaceModule[] = [];
+  for (const bundle of bundles) {
+    const target = from ? resolveBundleRegister(bundle, from) : `${bundle}/register.js`;
+    modules.push((await import(target)) as BundleSurfaceModule);
+  }
+  return modules;
+}

package/src/transport/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Transport exports.
+ */
+
+export { McpServerTransport } from "./mcp-transport.js";
+export { createStdioTransport } from "./stdio.js";
+export { createSseTransport } from "./sse.js";