@crewhaus/mcp-server 0.4.0

package/dist/build.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Tool registration + SDK-server construction for the MCP projection.
+ *
+ * `buildConfiguredServer` mints a fresh `McpServer` with the projected tools
+ * registered; the stdio path calls it once, the SSE path calls it per session.
+ * Every tool delegates to the injected `invoke`, which is the ONLY behavioural
+ * dependency — there is no compiler/runtime coupling here.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type CreateMcpServerOptions, type McpSubAgentDescriptor, type McpToolsMode } from "./types.js";
+/** Resolve the tools-mode default (`"chat"`), mirroring the IR lower step. */
+export declare function resolveToolsMode(mode: McpToolsMode | undefined): McpToolsMode;
+/**
+ * Reject a projection that cannot be built. The spec's cross-field check
+ * already guards `per-subagent` upstream, but this package must be safe when
+ * driven standalone (e.g. from a hand-built `invoke`).
+ */
+export declare function validateOptions(opts: CreateMcpServerOptions): void;
+interface ResolvedSubAgentTool {
+    /** The (sanitized, de-duplicated) MCP tool name. */
+    readonly toolName: string;
+    /** The ORIGINAL spec sub-agent name, threaded back through `McpInvokeContext`. */
+    readonly subAgent: string;
+    readonly description: string;
+}
+/**
+ * Map sub-agent descriptors to MCP tools, sanitizing names and de-duplicating
+ * against each other AND the reserved `chat` tool. The original sub-agent name
+ * is preserved on `subAgent` so `invoke` still routes by the real name even
+ * when the tool name was rewritten.
+ */
+export declare function resolveSubAgentTools(subAgents: readonly McpSubAgentDescriptor[]): readonly ResolvedSubAgentTool[];
+/** The tool names a projection will register, without building a server. */
+export declare function computeToolNames(opts: CreateMcpServerOptions): readonly string[];
+/** Register the projected tools onto `server`; returns their names in order. */
+export declare function registerAgentTools(server: McpServer, opts: CreateMcpServerOptions): readonly string[];
+/** Mint a fresh SDK server with the projected tools registered. */
+export declare function buildConfiguredServer(opts: CreateMcpServerOptions): {
+    readonly server: McpServer;
+    readonly toolNames: readonly string[];
+};
+export {};

package/dist/build.js

@@ -0,0 +1,114 @@
+/**
+ * Tool registration + SDK-server construction for the MCP projection.
+ *
+ * `buildConfiguredServer` mints a fresh `McpServer` with the projected tools
+ * registered; the stdio path calls it once, the SSE path calls it per session.
+ * Every tool delegates to the injected `invoke`, which is the ONLY behavioural
+ * dependency — there is no compiler/runtime coupling here.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { CHAT_TOOL_NAME, McpServerError, } from "./types.js";
+const DEFAULT_NAME = "crewhaus";
+const DEFAULT_VERSION = "0.0.0";
+/** Resolve the tools-mode default (`"chat"`), mirroring the IR lower step. */
+export function resolveToolsMode(mode) {
+    return mode ?? "chat";
+}
+/**
+ * Reject a projection that cannot be built. The spec's cross-field check
+ * already guards `per-subagent` upstream, but this package must be safe when
+ * driven standalone (e.g. from a hand-built `invoke`).
+ */
+export function validateOptions(opts) {
+    if (typeof opts.invoke !== "function") {
+        throw new McpServerError("createMcpServer requires an `invoke` function");
+    }
+    if (opts.transport !== "stdio" && opts.transport !== "sse") {
+        throw new McpServerError(`unsupported MCP transport ${JSON.stringify(opts.transport)} (expected "stdio" or "sse")`);
+    }
+    if (resolveToolsMode(opts.tools) === "per-subagent" &&
+        (opts.subAgents === undefined || opts.subAgents.length === 0)) {
+        throw new McpServerError('tools: "per-subagent" requires at least one sub-agent to project');
+    }
+}
+/** Fold a spec name into an MCP-safe tool name (`[A-Za-z0-9_-]`). */
+function sanitizeToolName(name) {
+    const cleaned = name.replace(/[^A-Za-z0-9_-]+/g, "_").replace(/^_+|_+$/g, "");
+    return cleaned.length > 0 ? cleaned : "subagent";
+}
+/** Make `base` unique against `used`, appending `_2`, `_3`, … on collision. */
+function uniqueName(base, used) {
+    if (!used.has(base)) {
+        used.add(base);
+        return base;
+    }
+    let n = 2;
+    while (used.has(`${base}_${n}`))
+        n += 1;
+    const candidate = `${base}_${n}`;
+    used.add(candidate);
+    return candidate;
+}
+/**
+ * Map sub-agent descriptors to MCP tools, sanitizing names and de-duplicating
+ * against each other AND the reserved `chat` tool. The original sub-agent name
+ * is preserved on `subAgent` so `invoke` still routes by the real name even
+ * when the tool name was rewritten.
+ */
+export function resolveSubAgentTools(subAgents) {
+    const used = new Set([CHAT_TOOL_NAME]);
+    return subAgents.map((sa) => ({
+        toolName: uniqueName(sanitizeToolName(sa.name), used),
+        subAgent: sa.name,
+        description: sa.description,
+    }));
+}
+/** The tool names a projection will register, without building a server. */
+export function computeToolNames(opts) {
+    if (resolveToolsMode(opts.tools) === "chat")
+        return [CHAT_TOOL_NAME];
+    return [CHAT_TOOL_NAME, ...resolveSubAgentTools(opts.subAgents ?? []).map((t) => t.toolName)];
+}
+/** Run `invoke`, mapping success/failure onto a `CallToolResult` (never throws). */
+async function runInvoke(invoke, message, context) {
+    try {
+        const text = await invoke(message, context);
+        return { content: [{ type: "text", text: typeof text === "string" ? text : String(text) }] };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { isError: true, content: [{ type: "text", text: `invoke failed: ${reason}` }] };
+    }
+}
+/** Register the projected tools onto `server`; returns their names in order. */
+export function registerAgentTools(server, opts) {
+    const agentName = opts.name ?? DEFAULT_NAME;
+    const names = [];
+    server.registerTool(CHAT_TOOL_NAME, {
+        title: `Chat with ${agentName}`,
+        description: opts.chatToolDescription ??
+            `Send a message to the ${agentName} agent and receive its final response.`,
+        inputSchema: { message: z.string().describe("The message to send to the agent.") },
+    }, ({ message }) => runInvoke(opts.invoke, message, { toolName: CHAT_TOOL_NAME }));
+    names.push(CHAT_TOOL_NAME);
+    if (resolveToolsMode(opts.tools) === "per-subagent") {
+        for (const tool of resolveSubAgentTools(opts.subAgents ?? [])) {
+            server.registerTool(tool.toolName, {
+                title: `Delegate to ${tool.subAgent}`,
+                description: tool.description,
+                inputSchema: {
+                    message: z.string().describe(`The message to route to the ${tool.subAgent} sub-agent.`),
+                },
+            }, ({ message }) => runInvoke(opts.invoke, message, { toolName: tool.toolName, subAgent: tool.subAgent }));
+            names.push(tool.toolName);
+        }
+    }
+    return names;
+}
+/** Mint a fresh SDK server with the projected tools registered. */
+export function buildConfiguredServer(opts) {
+    const server = new McpServer({ name: opts.name ?? DEFAULT_NAME, version: opts.version ?? DEFAULT_VERSION }, opts.instructions === undefined ? undefined : { instructions: opts.instructions });
+    const toolNames = registerAgentTools(server, opts);
+    return { server, toolNames };
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `@crewhaus/mcp-server` — project a compiled bundle's turn function as an MCP
+ * server (Loop-contract 0.4, Item 1 / G30). See `./types.ts` for the design
+ * rationale and the `IrExpose`/`IrExposeMcp` correspondence.
+ *
+ * `createMcpServer({ invoke, transport, tools, subAgents })` registers a `chat`
+ * tool (and, under `tools: "per-subagent"`, one tool per sub-agent) that all
+ * delegate to the injected `invoke`, then binds the requested transport:
+ *   - `stdio` → a `StdioMcpServer` you `listen()` on the process stdio.
+ *   - `sse`   → an `SseMcpServer` whose `fetch(Request)` handler mounts in any
+ *     Web-Standard `fetch` pipeline (Bun / Workers / gateway-server).
+ */
+import { type CreateMcpServerOptions, type McpServerHandle } from "./types.js";
+/**
+ * Build an MCP server that projects `invoke` as tools over the chosen transport.
+ * Throws {@link McpServerError} on a misconfigured projection. Narrow the return
+ * on `.transport` to reach the transport-specific methods.
+ */
+export declare function createMcpServer(opts: CreateMcpServerOptions): McpServerHandle;
+export { CHAT_TOOL_NAME, McpServerError } from "./types.js";
+export type { CreateMcpServerOptions, McpInvoke, McpInvokeContext, McpServerHandle, McpSubAgentDescriptor, McpToolsMode, McpTransportKind, SseMcpServer, StdioMcpServer, StdioStreams, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,110 @@
+/**
+ * `@crewhaus/mcp-server` — project a compiled bundle's turn function as an MCP
+ * server (Loop-contract 0.4, Item 1 / G30). See `./types.ts` for the design
+ * rationale and the `IrExpose`/`IrExposeMcp` correspondence.
+ *
+ * `createMcpServer({ invoke, transport, tools, subAgents })` registers a `chat`
+ * tool (and, under `tools: "per-subagent"`, one tool per sub-agent) that all
+ * delegate to the injected `invoke`, then binds the requested transport:
+ *   - `stdio` → a `StdioMcpServer` you `listen()` on the process stdio.
+ *   - `sse`   → an `SseMcpServer` whose `fetch(Request)` handler mounts in any
+ *     Web-Standard `fetch` pipeline (Bun / Workers / gateway-server).
+ */
+import { randomUUID } from "node:crypto";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { buildConfiguredServer, computeToolNames, validateOptions } from "./build.js";
+import { McpServerError, } from "./types.js";
+/**
+ * Build an MCP server that projects `invoke` as tools over the chosen transport.
+ * Throws {@link McpServerError} on a misconfigured projection. Narrow the return
+ * on `.transport` to reach the transport-specific methods.
+ */
+export function createMcpServer(opts) {
+    validateOptions(opts);
+    return opts.transport === "stdio" ? createStdioServer(opts) : createSseServer(opts);
+}
+function createStdioServer(opts) {
+    const { server, toolNames } = buildConfiguredServer(opts);
+    let connected = false;
+    const connect = async (transport) => {
+        if (connected) {
+            throw new McpServerError("this MCP server is already connected to a transport");
+        }
+        connected = true;
+        try {
+            await server.connect(transport);
+        }
+        catch (err) {
+            connected = false;
+            throw err;
+        }
+    };
+    const listen = (streams) => connect(new StdioServerTransport(streams?.stdin, streams?.stdout));
+    const close = async () => {
+        await server.close();
+        connected = false;
+    };
+    return { transport: "stdio", server, toolNames, connect, listen, close };
+}
+function createSseServer(opts) {
+    const toolNames = computeToolNames(opts);
+    const sessions = new Map();
+    let closed = false;
+    const closeSession = async (id) => {
+        const session = sessions.get(id);
+        if (session === undefined)
+            return;
+        sessions.delete(id);
+        await session.transport.close().catch(() => { });
+        await session.server.close().catch(() => { });
+    };
+    const openSession = async (request) => {
+        const { server } = buildConfiguredServer(opts);
+        const transport = new WebStandardStreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            onsessioninitialized: (id) => {
+                sessions.set(id, { server, transport });
+            },
+            onsessionclosed: (id) => {
+                void closeSession(id);
+            },
+        });
+        await server.connect(transport);
+        const response = await transport.handleRequest(request);
+        // A request that never initialized a session (e.g. an invalid non-initialize
+        // POST with no session id) leaves an orphan transport — tear it down so a
+        // misbehaving client cannot leak servers.
+        const id = transport.sessionId;
+        if (id === undefined || !sessions.has(id)) {
+            await transport.close().catch(() => { });
+            await server.close().catch(() => { });
+        }
+        return response;
+    };
+    const fetch = async (request) => {
+        if (closed)
+            return jsonRpcErrorResponse(503, -32000, "MCP server is closed");
+        const sessionId = request.headers.get("mcp-session-id") ?? undefined;
+        if (sessionId !== undefined) {
+            const session = sessions.get(sessionId);
+            if (session !== undefined)
+                return session.transport.handleRequest(request);
+            return jsonRpcErrorResponse(404, -32001, "MCP session not found");
+        }
+        return openSession(request);
+    };
+    const close = async () => {
+        closed = true;
+        await Promise.all([...sessions.keys()].map((id) => closeSession(id)));
+    };
+    return { transport: "sse", toolNames, fetch, close };
+}
+/** A minimal JSON-RPC error envelope for transport-level rejections. */
+function jsonRpcErrorResponse(status, code, message) {
+    return new Response(JSON.stringify({ jsonrpc: "2.0", error: { code, message }, id: null }), {
+        status,
+        headers: { "content-type": "application/json" },
+    });
+}
+export { CHAT_TOOL_NAME, McpServerError } from "./types.js";

package/dist/types.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Catalog R5 (`mcp-server`) — public surface for the MCP-server PROJECTION
+ * (Loop-contract 0.4, Item 1 / G30).
+ *
+ * The `expose:` spec block lowers to `IrExpose`/`IrExposeMcp` (`@crewhaus/ir`)
+ * and asks the compiler to project THIS compiled bundle's turn function as an
+ * MCP server so Claude Code / IDEs / other CrewHaus runtimes can call the whole
+ * agent as a tool. This package is the runtime half of that projection.
+ *
+ * Deliberately IR- and runtime-agnostic: the bundle's turn function is INJECTED
+ * as `invoke`, so `mcp-server` depends on neither `@crewhaus/compiler` nor
+ * `@crewhaus/runtime-core`. The CLI slice builds `invoke` from a compiled
+ * bundle and hands it here; `mcp-server` only knows how to wrap it in the
+ * official `@modelcontextprotocol/sdk` server + a transport.
+ *
+ *   - `transport: "stdio"` → a spawned stdio MCP server (the
+ *     `crewhaus serve --mcp` path). Node/Bun only.
+ *   - `transport: "sse"` → a Web-Standard `fetch(Request): Promise<Response>`
+ *     handler that SSE-streams responses (built on the SDK's Streamable-HTTP
+ *     transport). Mountable in a `Bun.serve` / Cloudflare Workers /
+ *     `gateway-server` fetch pipeline so the SSE exposure can ride the
+ *     gateway's tenancy/budgets where the shape has them.
+ *
+ * Tool projection mirrors `IrExposeMcp.tools`:
+ *   - `"chat"` (default) → one primary `chat` tool taking `{ message }` and
+ *     returning the final assistant text.
+ *   - `"per-subagent"` → the `chat` tool PLUS one tool per declared sub-agent,
+ *     each delegating to `invoke` with the sub-agent's name in the call
+ *     context so the injected fn can route to that sub-agent.
+ */
+import type { Readable, Writable } from "node:stream";
+import { McpError } from "@crewhaus/errors";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+/** Wire transport for the projected MCP server. Mirrors `IrExposeMcp.transport`. */
+export type McpTransportKind = "stdio" | "sse";
+/** Which tools to project. Mirrors the RESOLVED `IrExposeMcp.tools`. */
+export type McpToolsMode = "chat" | "per-subagent";
+/** Name of the primary invoke tool that delegates the whole agent turn. */
+export declare const CHAT_TOOL_NAME = "chat";
+/**
+ * Context handed to the injected `invoke` on every MCP tool call.
+ *
+ * `toolName` is the MCP tool the client called. `subAgent` is set ONLY for a
+ * per-sub-agent tool and carries the ORIGINAL spec sub-agent name (before MCP
+ * tool-name sanitization), so the injected fn can route the message to that
+ * sub-agent. Absent for the primary `chat` tool.
+ */
+export interface McpInvokeContext {
+    readonly toolName: string;
+    readonly subAgent?: string;
+}
+/**
+ * The injected delegate: run one agent turn for `message` and resolve with the
+ * final assistant text. A plain `(message: string) => Promise<string>` is
+ * assignable here — the `context` argument is optional for callers that don't
+ * need per-sub-agent routing.
+ */
+export type McpInvoke = (message: string, context: McpInvokeContext) => Promise<string>;
+/** A sub-agent to project as its own MCP tool under `tools: "per-subagent"`. */
+export interface McpSubAgentDescriptor {
+    /** The spec sub-agent name (`sub_agents.<name>`). Passed back via `McpInvokeContext.subAgent`. */
+    readonly name: string;
+    /** Shown to the calling model as the tool's description. */
+    readonly description: string;
+}
+/** Options for {@link createMcpServer}. */
+export interface CreateMcpServerOptions {
+    /** The bundle's turn function. Required. */
+    readonly invoke: McpInvoke;
+    /** Which transport to bind. Required. */
+    readonly transport: McpTransportKind;
+    /** Tool projection mode. Defaults to `"chat"`. */
+    readonly tools?: McpToolsMode;
+    /** Sub-agents to project — required (and non-empty) when `tools: "per-subagent"`. */
+    readonly subAgents?: readonly McpSubAgentDescriptor[];
+    /** MCP server info `name` advertised to clients. Defaults to `"crewhaus"`. */
+    readonly name?: string;
+    /** MCP server info `version`. Defaults to `"0.0.0"`. */
+    readonly version?: string;
+    /** Optional MCP server instructions advertised in the initialize result. */
+    readonly instructions?: string;
+    /** Override the primary `chat` tool's description. */
+    readonly chatToolDescription?: string;
+}
+/**
+ * Streams for {@link StdioMcpServer.listen}. Defaults to the process's
+ * `stdin`/`stdout` when omitted; the injection hook exists mainly for tests.
+ */
+export interface StdioStreams {
+    readonly stdin?: Readable;
+    readonly stdout?: Writable;
+}
+interface McpServerHandleBase {
+    readonly transport: McpTransportKind;
+    /** The MCP tool names registered per session, in registration order. */
+    readonly toolNames: readonly string[];
+    /** Close the server and every transport/session it owns. */
+    close(): Promise<void>;
+}
+/** Handle returned by {@link createMcpServer} for `transport: "stdio"`. */
+export interface StdioMcpServer extends McpServerHandleBase {
+    readonly transport: "stdio";
+    /** The underlying SDK server (advanced use: notifications, custom handlers). */
+    readonly server: McpServer;
+    /**
+     * Connect the server to any SDK {@link Transport} and start serving.
+     * Transport-agnostic — `listen()` wraps this with a `StdioServerTransport`,
+     * and tests link it to an `InMemoryTransport`. Throws if already connected.
+     */
+    connect(transport: Transport): Promise<void>;
+    /** Bind to the process's stdio (or the injected `streams`) and serve until `close()`. */
+    listen(streams?: StdioStreams): Promise<void>;
+}
+/** Handle returned by {@link createMcpServer} for `transport: "sse"`. */
+export interface SseMcpServer extends McpServerHandleBase {
+    readonly transport: "sse";
+    /**
+     * Web-Standard fetch handler. Mount it directly:
+     * `Bun.serve({ fetch: handle.fetch })`, or from a Workers/gateway `fetch`.
+     * MCP sessions are managed internally (one Streamable-HTTP transport + SDK
+     * server per session, keyed by the `mcp-session-id` header).
+     */
+    fetch(request: Request): Promise<Response>;
+}
+/** Discriminated handle over the two transports. Narrow on `.transport`. */
+export type McpServerHandle = StdioMcpServer | SseMcpServer;
+/**
+ * Raised for misconfigured projections (missing `invoke`, unknown transport,
+ * `per-subagent` with no sub-agents, double-connect). Carries the shared
+ * `"mcp"` error code via {@link McpError}.
+ */
+export declare class McpServerError extends McpError {
+    readonly name = "McpServerError";
+}
+export {};

package/dist/types.js

@@ -0,0 +1,41 @@
+/**
+ * Catalog R5 (`mcp-server`) — public surface for the MCP-server PROJECTION
+ * (Loop-contract 0.4, Item 1 / G30).
+ *
+ * The `expose:` spec block lowers to `IrExpose`/`IrExposeMcp` (`@crewhaus/ir`)
+ * and asks the compiler to project THIS compiled bundle's turn function as an
+ * MCP server so Claude Code / IDEs / other CrewHaus runtimes can call the whole
+ * agent as a tool. This package is the runtime half of that projection.
+ *
+ * Deliberately IR- and runtime-agnostic: the bundle's turn function is INJECTED
+ * as `invoke`, so `mcp-server` depends on neither `@crewhaus/compiler` nor
+ * `@crewhaus/runtime-core`. The CLI slice builds `invoke` from a compiled
+ * bundle and hands it here; `mcp-server` only knows how to wrap it in the
+ * official `@modelcontextprotocol/sdk` server + a transport.
+ *
+ *   - `transport: "stdio"` → a spawned stdio MCP server (the
+ *     `crewhaus serve --mcp` path). Node/Bun only.
+ *   - `transport: "sse"` → a Web-Standard `fetch(Request): Promise<Response>`
+ *     handler that SSE-streams responses (built on the SDK's Streamable-HTTP
+ *     transport). Mountable in a `Bun.serve` / Cloudflare Workers /
+ *     `gateway-server` fetch pipeline so the SSE exposure can ride the
+ *     gateway's tenancy/budgets where the shape has them.
+ *
+ * Tool projection mirrors `IrExposeMcp.tools`:
+ *   - `"chat"` (default) → one primary `chat` tool taking `{ message }` and
+ *     returning the final assistant text.
+ *   - `"per-subagent"` → the `chat` tool PLUS one tool per declared sub-agent,
+ *     each delegating to `invoke` with the sub-agent's name in the call
+ *     context so the injected fn can route to that sub-agent.
+ */
+import { McpError } from "@crewhaus/errors";
+/** Name of the primary invoke tool that delegates the whole agent turn. */
+export const CHAT_TOOL_NAME = "chat";
+/**
+ * Raised for misconfigured projections (missing `invoke`, unknown transport,
+ * `per-subagent` with no sub-agents, double-connect). Carries the shared
+ * `"mcp"` error code via {@link McpError}.
+ */
+export class McpServerError extends McpError {
+    name = "McpServerError";
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@crewhaus/mcp-server",
+  "version": "0.4.0",
+  "type": "module",
+  "description": "Project a compiled bundle's turn function as an MCP server (stdio + SSE) — a chat/invoke tool plus optional per-sub-agent tools delegating to an injected invoke fn, built on @modelcontextprotocol/sdk",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.4.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.23.8"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/mcp-server"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
+}