@zauso-ai/capstan-agent 0.2.0 → 0.3.1

package/dist/mcp-client.js

@@ -0,0 +1,289 @@
+/**
+ * MCP Client — connect to external MCP servers and consume their tools.
+ *
+ * Uses the official `@modelcontextprotocol/sdk` Client and
+ * StreamableHTTPClientTransport for spec-compliant communication.
+ * Falls back to a raw JSON-RPC 2.0 implementation when the SDK
+ * transport encounters issues (e.g. the remote server does not
+ * support Streamable HTTP).
+ */
+// SDK imports are dynamic to avoid resolution failures when subpath
+// exports are not declared in the package.json exports map.
+import { withSpan } from "./telemetry.js";
+// ---------------------------------------------------------------------------
+// SDK-backed implementation
+// ---------------------------------------------------------------------------
+class SdkMcpClient {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    client;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    transport;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    constructor(client, transport) {
+        this.client = client;
+        this.transport = transport;
+    }
+    async listTools() {
+        return withSpan("capstan.mcp_client.listTools", {}, async () => {
+            const result = await this.client.listTools();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return result.tools.map((t) => ({
+                name: t.name,
+                description: t.description,
+                inputSchema: t.inputSchema,
+            }));
+        });
+    }
+    async callTool(name, args) {
+        return withSpan(`capstan.mcp_client.callTool.${name}`, { "capstan.mcp_client.tool": name }, async () => {
+            const result = await this.client.callTool({
+                name,
+                arguments: args,
+            });
+            // The SDK returns a union type; the standard shape has a `content`
+            // array of text/image/audio/resource items.
+            if ("content" in result && Array.isArray(result.content)) {
+                // If there's a single text content item, unwrap it for convenience.
+                if (result.content.length === 1 &&
+                    result.content[0] != null &&
+                    "type" in result.content[0] &&
+                    result.content[0].type === "text") {
+                    const text = result.content[0].text;
+                    try {
+                        return JSON.parse(text);
+                    }
+                    catch {
+                        return text;
+                    }
+                }
+                return result.content;
+            }
+            // Compatibility result shape (`toolResult` field).
+            if ("toolResult" in result) {
+                return result.toolResult;
+            }
+            return result;
+        });
+    }
+    async close() {
+        await this.transport.close();
+    }
+}
+// ---------------------------------------------------------------------------
+// Raw JSON-RPC 2.0 fallback implementation
+// ---------------------------------------------------------------------------
+class RawMcpClient {
+    url;
+    headers;
+    sessionId;
+    nextId = 1;
+    constructor(url, headers) {
+        this.url = url;
+        this.headers = headers;
+    }
+    /** Perform the MCP initialize handshake. */
+    async initialize(clientName) {
+        await this.sendRequest("initialize", {
+            protocolVersion: "2025-03-26",
+            capabilities: {},
+            clientInfo: { name: clientName, version: "1.0.0" },
+        });
+        // Send initialized notification (no response expected).
+        await this.sendNotification("notifications/initialized", {});
+    }
+    async listTools() {
+        return withSpan("capstan.mcp_client.listTools", {}, async () => {
+            const result = (await this.sendRequest("tools/list", {}));
+            return (result.tools ?? []).map((t) => ({
+                name: t.name,
+                description: t.description,
+                inputSchema: t.inputSchema,
+            }));
+        });
+    }
+    async callTool(name, args) {
+        return withSpan(`capstan.mcp_client.callTool.${name}`, { "capstan.mcp_client.tool": name }, async () => {
+            const result = (await this.sendRequest("tools/call", {
+                name,
+                arguments: args ?? {},
+            }));
+            if (result.content && Array.isArray(result.content)) {
+                if (result.content.length === 1 &&
+                    result.content[0]?.type === "text" &&
+                    result.content[0].text != null) {
+                    try {
+                        return JSON.parse(result.content[0].text);
+                    }
+                    catch {
+                        return result.content[0].text;
+                    }
+                }
+                return result.content;
+            }
+            if (result.toolResult !== undefined) {
+                return result.toolResult;
+            }
+            return result;
+        });
+    }
+    async close() {
+        if (this.sessionId) {
+            try {
+                await fetch(this.url, {
+                    method: "DELETE",
+                    headers: {
+                        ...this.headers,
+                        "Mcp-Session-Id": this.sessionId,
+                    },
+                });
+            }
+            catch {
+                // Best-effort session termination — ignore errors.
+            }
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Internal helpers
+    // -----------------------------------------------------------------------
+    async sendRequest(method, params) {
+        const id = this.nextId++;
+        const body = {
+            jsonrpc: "2.0",
+            id,
+            method,
+            params,
+        };
+        const reqHeaders = {
+            ...this.headers,
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+        };
+        if (this.sessionId) {
+            reqHeaders["Mcp-Session-Id"] = this.sessionId;
+        }
+        const res = await fetch(this.url, {
+            method: "POST",
+            headers: reqHeaders,
+            body: JSON.stringify(body),
+        });
+        // Capture session ID from the response.
+        const newSessionId = res.headers.get("mcp-session-id");
+        if (newSessionId) {
+            this.sessionId = newSessionId;
+        }
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`MCP request ${method} failed: HTTP ${String(res.status)} ${text}`);
+        }
+        const contentType = res.headers.get("content-type") ?? "";
+        // The server may respond with SSE (text/event-stream) or plain JSON.
+        if (contentType.includes("text/event-stream")) {
+            return this.parseSseResponse(res, id);
+        }
+        const json = (await res.json());
+        if (json.error) {
+            throw new Error(`MCP error ${String(json.error.code)}: ${json.error.message}`);
+        }
+        return json.result;
+    }
+    async sendNotification(method, params) {
+        const body = {
+            jsonrpc: "2.0",
+            method,
+            params,
+        };
+        const reqHeaders = {
+            ...this.headers,
+            "Content-Type": "application/json",
+        };
+        if (this.sessionId) {
+            reqHeaders["Mcp-Session-Id"] = this.sessionId;
+        }
+        const res = await fetch(this.url, {
+            method: "POST",
+            headers: reqHeaders,
+            body: JSON.stringify(body),
+        });
+        // Capture session ID.
+        const newSessionId = res.headers.get("mcp-session-id");
+        if (newSessionId) {
+            this.sessionId = newSessionId;
+        }
+        // Notifications may return 202 Accepted or 204 No Content — either is fine.
+        if (!res.ok && res.status !== 202 && res.status !== 204) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`MCP notification ${method} failed: HTTP ${String(res.status)} ${text}`);
+        }
+    }
+    async parseSseResponse(res, expectedId) {
+        const text = await res.text();
+        // Parse SSE events and find the JSON-RPC response matching our request ID.
+        for (const line of text.split("\n")) {
+            if (line.startsWith("data: ")) {
+                try {
+                    const parsed = JSON.parse(line.slice(6));
+                    if (parsed.id === expectedId) {
+                        if (parsed.error) {
+                            throw new Error(`MCP error ${String(parsed.error.code)}: ${parsed.error.message}`);
+                        }
+                        return parsed.result;
+                    }
+                }
+                catch (e) {
+                    if (e instanceof Error && e.message.startsWith("MCP error")) {
+                        throw e;
+                    }
+                    // Skip unparseable SSE data lines.
+                }
+            }
+        }
+        throw new Error("No matching JSON-RPC response found in SSE stream");
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory function
+// ---------------------------------------------------------------------------
+/**
+ * Create an MCP client connected to a remote server.
+ *
+ * Attempts to connect using the official SDK `Client` +
+ * `StreamableHTTPClientTransport` first. Falls back to a raw JSON-RPC 2.0
+ * implementation if the SDK transport fails (e.g. unsupported server).
+ *
+ * @param options - Connection options (URL, auth, client name).
+ * @returns A connected `McpClient` ready to list and call tools.
+ */
+export async function createMcpClient(options) {
+    const clientName = options.clientName ?? "capstan-mcp-client";
+    const url = new URL(options.url);
+    const requestInit = {};
+    if (options.authorization) {
+        requestInit.headers = {
+            Authorization: options.authorization,
+        };
+    }
+    // --- Attempt 1: SDK transport (lazy import) ---
+    try {
+        const clientMod = await import("@modelcontextprotocol/sdk/client/index.js");
+        const transportMod = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
+        const SdkClient = clientMod.Client;
+        const SdkTransport = transportMod.StreamableHTTPClientTransport;
+        const transport = new SdkTransport(url, { requestInit });
+        const client = new SdkClient({ name: clientName, version: "1.0.0" }, { capabilities: {} });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        await client.connect(transport);
+        return new SdkMcpClient(client, transport);
+    }
+    catch {
+        // SDK transport failed or not available — fall back to raw JSON-RPC.
+    }
+    // --- Attempt 2: Raw JSON-RPC 2.0 ---
+    const headers = {};
+    if (options.authorization) {
+        headers["Authorization"] = options.authorization;
+    }
+    const rawClient = new RawMcpClient(options.url, headers);
+    await rawClient.initialize(clientName);
+    return rawClient;
+}
+//# sourceMappingURL=mcp-client.js.map

package/dist/mcp-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client.js","sourceRoot":"","sources":["../src/mcp-client.ts"],"names":[],"mappings":"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"}

package/dist/mcp.d.ts

@@ -1,4 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ZodTypeAny } from "zod";
 import type { AgentConfig, RouteRegistryEntry } from "./types.js";
 /**
  * Convert an HTTP method + URL path into a snake_case MCP tool name.
@@ -11,6 +12,14 @@ import type { AgentConfig, RouteRegistryEntry } from "./types.js";
  *   DELETE /orgs/:orgId/members/:memberId -> "delete_orgs_by_orgId_members_by_memberId"
  */
 export declare function routeToToolName(method: string, path: string): string;
+/**
+ * Convert a route's `inputSchema` (JSON Schema object) into a Zod raw shape
+ * suitable for the MCP SDK's `server.tool()` method.
+ *
+ * If the route has no input schema, returns an empty shape so the tool
+ * accepts no arguments.
+ */
+export declare function inputSchemaToZodShape(inputSchema: Record<string, unknown> | undefined): Record<string, ZodTypeAny>;
 /**
  * Create an MCP server that exposes all Capstan API routes as MCP tools.
  *
@@ -38,4 +47,27 @@ export declare function createMcpServer(config: AgentConfig, routes: RouteRegist
  * that communicates over stdin/stdout.
  */
 export declare function serveMcpStdio(server: McpServer): Promise<void>;
+/**
+ * Create a Streamable HTTP handler for an MCP server.
+ *
+ * The MCP specification (2025-03-26) introduced Streamable HTTP as the
+ * recommended remote transport, deprecating the older SSE transport.
+ * This function returns a `(req: Request) => Promise<Response>` handler
+ * that can be mounted in any web-standard framework (Hono, Cloudflare
+ * Workers, Deno, Bun, etc.).
+ *
+ * The handler supports:
+ * - **POST** — JSON-RPC messages (tool calls, initialization)
+ * - **GET** — SSE stream for server-initiated notifications
+ * - **DELETE** — session termination
+ *
+ * Session management is enabled by default using `crypto.randomUUID()`.
+ * Each session maintains its own transport instance, which is connected
+ * to a freshly built `McpServer` that shares the same tool registrations.
+ *
+ * @param registry - The CapabilityRegistry (or equivalent) providing
+ *   agent configuration and registered routes.
+ * @returns A web-standard request handler.
+ */
+export declare function createMcpHttpHandler(config: AgentConfig, routes: RouteRegistryEntry[], executeRoute: (method: string, path: string, input: unknown) => Promise<unknown>): (req: Request) => Promise<Response>;
 //# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAElE;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAkBpE;AAYD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,kBAAkB,EAAE,EAC5B,YAAY,EAAE,CACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,KACX,OAAO,CAAC,OAAO,CAAC,GACpB;IACD,MAAM,EAAE,SAAS,CAAC;IAClB,kBAAkB,EAAE,MAAM,KAAK,CAAC;QAC9B,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC,CAAC;CACJ,CAyDA;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAGpE"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAEtC,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGlE;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAkBpE;AA4DD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC/C,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAqB5B;AAYD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,kBAAkB,EAAE,EAC5B,YAAY,EAAE,CACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,KACX,OAAO,CAAC,OAAO,CAAC,GACpB;IACD,MAAM,EAAE,SAAS,CAAC;IAClB,kBAAkB,EAAE,MAAM,KAAK,CAAC;QAC9B,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC,CAAC;CACJ,CAuDA;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAGpE;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,kBAAkB,EAAE,EAC5B,YAAY,EAAE,CACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,KACX,OAAO,CAAC,OAAO,CAAC,GACpB,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAuErC"}

package/dist/mcp.js

@@ -1,6 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { withSpan } from "./telemetry.js";
 /**
  * Convert an HTTP method + URL path into a snake_case MCP tool name.
  *
@@ -30,6 +31,80 @@ export function routeToToolName(method, path) {
     }
     return `${prefix}_${parts.join("_")}`;
 }
+/**
+ * Convert a JSON Schema type string to the corresponding Zod type.
+ */
+function jsonSchemaTypeToZod(prop) {
+    const type = prop["type"];
+    switch (type) {
+        case "string": {
+            const enumValues = prop["enum"];
+            if (enumValues && enumValues.length > 0) {
+                return z.enum(enumValues);
+            }
+            return z.string();
+        }
+        case "number":
+        case "integer":
+            return z.number();
+        case "boolean":
+            return z.boolean();
+        case "array": {
+            const items = prop["items"];
+            if (items) {
+                return z.array(jsonSchemaTypeToZod(items));
+            }
+            return z.array(z.unknown());
+        }
+        case "object": {
+            const nested = prop["properties"];
+            if (nested) {
+                const nestedRequired = prop["required"] ?? [];
+                return jsonSchemaToZodObject(nested, nestedRequired);
+            }
+            return z.record(z.string(), z.unknown());
+        }
+        default:
+            return z.unknown();
+    }
+}
+/**
+ * Convert a JSON Schema `properties` object into a `z.object()` schema.
+ *
+ * Properties listed in `required` are kept mandatory; all others become
+ * `.optional()`.
+ */
+function jsonSchemaToZodObject(properties, required) {
+    const shape = {};
+    for (const [key, prop] of Object.entries(properties)) {
+        const base = jsonSchemaTypeToZod(prop);
+        shape[key] = required.includes(key) ? base : base.optional();
+    }
+    return z.object(shape);
+}
+/**
+ * Convert a route's `inputSchema` (JSON Schema object) into a Zod raw shape
+ * suitable for the MCP SDK's `server.tool()` method.
+ *
+ * If the route has no input schema, returns an empty shape so the tool
+ * accepts no arguments.
+ */
+export function inputSchemaToZodShape(inputSchema) {
+    if (!inputSchema) {
+        return {};
+    }
+    const properties = inputSchema["properties"];
+    if (!properties) {
+        return {};
+    }
+    const required = inputSchema["required"] ?? [];
+    const shape = {};
+    for (const [key, prop] of Object.entries(properties)) {
+        const base = jsonSchemaTypeToZod(prop);
+        shape[key] = required.includes(key) ? base : base.optional();
+    }
+    return shape;
+}
 /**
  * Build a tool description from a route.
  */
@@ -57,11 +132,6 @@ export function createMcpServer(config, routes, executeRoute) {
         version: "1.0.0",
     });
     const toolDefinitions = [];
-    // A permissive Zod schema that accepts any object and passes all
-    // properties through. This lets the MCP SDK forward client-supplied
-    // arguments to our handler while avoiding the need to convert each
-    // route's JSON Schema into a Zod type at registration time.
-    const passthroughShape = { _input: z.unknown().optional() };
     for (const route of routes) {
         const toolName = routeToToolName(route.method, route.path);
         const description = buildToolDescription(route);
@@ -71,19 +141,18 @@ export function createMcpServer(config, routes, executeRoute) {
             description,
             inputSchema: route.inputSchema ?? { type: "object", properties: {} },
         });
+        // Convert the route's JSON Schema inputSchema to a Zod shape so MCP
+        // clients receive proper parameter validation and documentation.
+        const zodShape = inputSchemaToZodShape(route.inputSchema);
         // Register the tool with the MCP server.
         //
-        // We use the `tool(name, description, paramsSchema, callback)` overload
-        // with a minimal Zod shape so the SDK invokes `callback(args, extra)`.
-        // The `passthroughShape` ensures the SDK parses the incoming arguments
-        // as an object and hands them to us — we then forward them to the
-        // actual route handler via `executeRoute`.
-        server.tool(toolName, description, passthroughShape, async (args) => {
-            // Forward all arguments (minus our synthetic _input marker) to the
-            // route handler.  Agents will send the actual input properties
-            // directly in the tool arguments object.
+        // We use the `tool(name, description, paramsSchema, callback)` overload.
+        // The Zod shape gives the MCP SDK real type information for each
+        // parameter, so clients see proper names, types, and required markers
+        // instead of a permissive passthrough.
+        server.tool(toolName, description, zodShape, async (args) => {
             const input = Object.keys(args).length > 0 ? args : undefined;
-            const result = await executeRoute(route.method, route.path, input);
+            const result = await withSpan(`capstan.mcp.tool.${toolName}`, { "capstan.mcp.toolName": toolName, "capstan.mcp.inputSize": JSON.stringify(args).length }, async () => executeRoute(route.method, route.path, input));
             return {
                 content: [{ type: "text", text: JSON.stringify(result) }],
             };
@@ -104,4 +173,87 @@ export async function serveMcpStdio(server) {
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
+// ---------------------------------------------------------------------------
+// Streamable HTTP transport
+// ---------------------------------------------------------------------------
+/**
+ * Create a Streamable HTTP handler for an MCP server.
+ *
+ * The MCP specification (2025-03-26) introduced Streamable HTTP as the
+ * recommended remote transport, deprecating the older SSE transport.
+ * This function returns a `(req: Request) => Promise<Response>` handler
+ * that can be mounted in any web-standard framework (Hono, Cloudflare
+ * Workers, Deno, Bun, etc.).
+ *
+ * The handler supports:
+ * - **POST** — JSON-RPC messages (tool calls, initialization)
+ * - **GET** — SSE stream for server-initiated notifications
+ * - **DELETE** — session termination
+ *
+ * Session management is enabled by default using `crypto.randomUUID()`.
+ * Each session maintains its own transport instance, which is connected
+ * to a freshly built `McpServer` that shares the same tool registrations.
+ *
+ * @param registry - The CapabilityRegistry (or equivalent) providing
+ *   agent configuration and registered routes.
+ * @returns A web-standard request handler.
+ */
+export function createMcpHttpHandler(config, routes, executeRoute) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const sessions = new Map();
+    /**
+     * Build a new McpServer with all the current routes registered.
+     * This mirrors `createMcpServer` but returns only the server — we
+     * don't need the `getToolDefinitions` helper here.
+     */
+    function buildServer() {
+        return createMcpServer(config, routes, executeRoute).server;
+    }
+    /**
+     * Create a fresh transport + server pair, wire them together, and
+     * store in the session map.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async function createSession() {
+        const { WebStandardStreamableHTTPServerTransport } = await import("@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js");
+        const transport = new WebStandardStreamableHTTPServerTransport({
+            sessionIdGenerator: () => crypto.randomUUID(),
+            onsessioninitialized(sessionId) {
+                // Store the session once the MCP handshake completes.
+                sessions.set(sessionId, entry);
+            },
+            onsessionclosed(sessionId) {
+                sessions.delete(sessionId);
+            },
+            enableJsonResponse: true,
+        });
+        const server = buildServer();
+        const entry = { transport, server };
+        // Connect the server to the transport (registers handlers).
+        await server.connect(transport);
+        return entry;
+    }
+    return async function handleMcpHttp(req) {
+        // Look up an existing session from the request header.
+        const sessionId = req.headers.get("mcp-session-id");
+        if (sessionId) {
+            const existing = sessions.get(sessionId);
+            if (existing) {
+                return existing.transport.handleRequest(req);
+            }
+            // Unknown session ID — return 404 per the MCP spec.
+            return new Response(JSON.stringify({
+                jsonrpc: "2.0",
+                error: { code: -32000, message: "Session not found" },
+                id: null,
+            }), {
+                status: 404,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+        // No session header — create a new session for initialization.
+        const { transport } = await createSession();
+        return transport.handleRequest(req);
+    };
+}
 //# sourceMappingURL=mcp.js.map

package/dist/mcp.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,IAAY;IAC1D,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAE7D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5B,oCAAoC;YACpC,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACvC,CAAC;aAAM,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5D,2CAA2C;YAC3C,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3C,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAED,OAAO,GAAG,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AACxC,CAAC;AAED;;GAEG;AACH,SAAS,oBAAoB,CAAC,KAAyB;IACrD,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;QACtB,OAAO,KAAK,CAAC,WAAW,CAAC;IAC3B,CAAC;IACD,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;AACvD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAmB,EACnB,MAA4B,EAC5B,YAIqB;IASrB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,MAAM,eAAe,GAIhB,EAAE,CAAC;IAER,iEAAiE;IACjE,oEAAoE;IACpE,mEAAmE;IACnE,4DAA4D;IAC5D,MAAM,gBAAgB,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,EAAW,CAAC;IAErE,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3D,MAAM,WAAW,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;QAEhD,0CAA0C;QAC1C,eAAe,CAAC,IAAI,CAAC;YACnB,IAAI,EAAE,QAAQ;YACd,WAAW;YACX,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;SACrE,CAAC,CAAC;QAEH,yCAAyC;QACzC,EAAE;QACF,wEAAwE;QACxE,uEAAuE;QACvE,uEAAuE;QACvE,kEAAkE;QAClE,2CAA2C;QAC3C,MAAM,CAAC,IAAI,CACT,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,KAAK,EAAE,IAA6B,EAAE,EAAE;YACtC,mEAAmE;YACnE,+DAA+D;YAC/D,yCAAyC;YACzC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;YAC9D,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YACnE,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;aACnE,CAAC;QACJ,CAAC,CACF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,MAAM;QACN,kBAAkB,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,eAAe,CAAC;KAC/C,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAiB;IACnD,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC"}
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,IAAY;IAC1D,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAE7D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5B,oCAAoC;YACpC,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACvC,CAAC;aAAM,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5D,2CAA2C;YAC3C,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3C,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAED,OAAO,GAAG,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AACxC,CAAC;AAED;;GAEG;AACH,SAAS,mBAAmB,CAAC,IAA6B;IACxD,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAuB,CAAC;IAChD,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAyB,CAAC;YACxD,IAAI,UAAU,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACxC,OAAO,CAAC,CAAC,IAAI,CAAC,UAAmC,CAAC,CAAC;YACrD,CAAC;YACD,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC;QACpB,CAAC;QACD,KAAK,QAAQ,CAAC;QACd,KAAK,SAAS;YACZ,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC;QACpB,KAAK,SAAS;YACZ,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC;QACrB,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAwC,CAAC;YACnE,IAAI,KAAK,EAAE,CAAC;gBACV,OAAO,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC;YAC7C,CAAC;YACD,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QAC9B,CAAC;QACD,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAEnB,CAAC;YACd,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,cAAc,GAAI,IAAI,CAAC,UAAU,CAA0B,IAAI,EAAE,CAAC;gBACxE,OAAO,qBAAqB,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;YACvD,CAAC;YACD,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QAC3C,CAAC;QACD;YACE,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC;IACvB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,qBAAqB,CAC5B,UAAmD,EACnD,QAAkB;IAElB,MAAM,KAAK,GAA+B,EAAE,CAAC;IAC7C,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;QACvC,KAAK,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;IAC/D,CAAC;IACD,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,WAAgD;IAEhD,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,UAAU,GAAG,WAAW,CAAC,YAAY,CAE9B,CAAC;IACd,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,QAAQ,GAAI,WAAW,CAAC,UAAU,CAA0B,IAAI,EAAE,CAAC;IACzE,MAAM,KAAK,GAA+B,EAAE,CAAC;IAE7C,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;QACvC,KAAK,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;IAC/D,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,SAAS,oBAAoB,CAAC,KAAyB;IACrD,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;QACtB,OAAO,KAAK,CAAC,WAAW,CAAC;IAC3B,CAAC;IACD,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;AACvD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAmB,EACnB,MAA4B,EAC5B,YAIqB;IASrB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,MAAM,eAAe,GAIhB,EAAE,CAAC;IAER,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3D,MAAM,WAAW,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;QAEhD,0CAA0C;QAC1C,eAAe,CAAC,IAAI,CAAC;YACnB,IAAI,EAAE,QAAQ;YACd,WAAW;YACX,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;SACrE,CAAC,CAAC;QAEH,oEAAoE;QACpE,iEAAiE;QACjE,MAAM,QAAQ,GAAG,qBAAqB,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QAE1D,yCAAyC;QACzC,EAAE;QACF,yEAAyE;QACzE,iEAAiE;QACjE,sEAAsE;QACtE,uCAAuC;QACvC,MAAM,CAAC,IAAI,CACT,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,KAAK,EAAE,IAA6B,EAAE,EAAE;YACtC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;YAC9D,MAAM,MAAM,GAAG,MAAM,QAAQ,CAC3B,oBAAoB,QAAQ,EAAE,EAC9B,EAAE,sBAAsB,EAAE,QAAQ,EAAE,uBAAuB,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAC1F,KAAK,IAAI,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAC1D,CAAC;YACF,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;aACnE,CAAC;QACJ,CAAC,CACF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,MAAM;QACN,kBAAkB,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,eAAe,CAAC;KAC/C,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAiB;IACnD,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,8EAA8E;AAC9E,4BAA4B;AAC5B,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAmB,EACnB,MAA4B,EAC5B,YAIqB;IAErB,8DAA8D;IAC9D,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAiD,CAAC;IAE1E;;;;OAIG;IACH,SAAS,WAAW;QAClB,OAAO,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,MAAM,CAAC;IAC9D,CAAC;IAED;;;OAGG;IACH,8DAA8D;IAC9D,KAAK,UAAU,aAAa;QAC1B,MAAM,EAAE,wCAAwC,EAAE,GAAG,MAAM,MAAM,CAC/D,+DAA+D,CAChE,CAAC;QACF,MAAM,SAAS,GAAG,IAAI,wCAAwC,CAAC;YAC7D,kBAAkB,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE;YAC7C,oBAAoB,CAAC,SAAiB;gBACpC,sDAAsD;gBACtD,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;YACjC,CAAC;YACD,eAAe,CAAC,SAAiB;gBAC/B,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAC7B,CAAC;YACD,kBAAkB,EAAE,IAAI;SACzB,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;QAEpC,4DAA4D;QAC5D,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAEhC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,KAAK,UAAU,aAAa,CAAC,GAAY;QAC9C,uDAAuD;QACvD,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;QAEpD,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACzC,IAAI,QAAQ,EAAE,CAAC;gBACb,OAAO,QAAQ,CAAC,SAAS,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;YAC/C,CAAC;YAED,oDAAoD;YACpD,OAAO,IAAI,QAAQ,CACjB,IAAI,CAAC,SAAS,CAAC;gBACb,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE;gBACrD,EAAE,EAAE,IAAI;aACT,CAAC,EACF;gBACE,MAAM,EAAE,GAAG;gBACX,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;aAChD,CACF,CAAC;QACJ,CAAC;QAED,+DAA+D;QAC/D,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,aAAa,EAAE,CAAC;QAC5C,OAAO,SAAS,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC,CAAC;AACJ,CAAC"}

package/dist/openapi.js

@@ -195,7 +195,7 @@ export function generateOpenApiSpec(config, routes) {
             ...(config.description !== undefined
                 ? { description: config.description }
                 : {}),
-            version: "0.1.0",
+            version: "0.3.0",
         },
         ...(config.baseUrl !== undefined
             ? { servers: [{ url: config.baseUrl }] }

package/dist/registry.d.ts

@@ -1,5 +1,7 @@
 import type { AgentConfig, AgentManifest, RouteRegistryEntry } from "./types.js";
-import type { A2AAgentCard } from "./a2a.js";
+import type { A2AAgentCard, A2AStreamEvent } from "./a2a.js";
+import type { McpClient, McpClientOptions } from "./mcp-client.js";
+import type { LangChainToolDefinition, ToLangChainOptions } from "./langchain.js";
 /**
  * Unified capability registry — the central abstraction for Capstan's
  * multi-protocol adapter layer.
@@ -44,6 +46,18 @@ export declare class CapabilityRegistry {
             inputSchema: unknown;
         }>;
     };
+    /**
+     * Project to MCP Streamable HTTP handler.
+     *
+     * Returns a web-standard `(req: Request) => Promise<Response>` handler
+     * implementing the MCP Streamable HTTP transport (2025-03-26 spec).
+     * Mount it on any route (e.g. `/mcp`) to serve MCP over HTTP.
+     *
+     * @param executeRoute - Callback that invokes the actual route handler
+     *   given an HTTP method, path, and input payload.
+     * @returns A web-standard request handler.
+     */
+    toMcpHttp(executeRoute: (method: string, path: string, input: unknown) => Promise<unknown>): (req: Request) => Promise<Response>;
     /**
      * Project to A2A agent card and JSON-RPC handler.
      *
@@ -53,7 +67,15 @@ export declare class CapabilityRegistry {
      */
     toA2A(executeRoute: (method: string, path: string, input: unknown) => Promise<unknown>): {
         handleRequest: (body: unknown) => Promise<unknown>;
+        handleStreamRequest: (body: unknown) => AsyncGenerator<A2AStreamEvent, void, unknown>;
         getAgentCard: () => A2AAgentCard;
     };
+    private mcpClients;
+    /** Connect to an external MCP server and import its tools. */
+    connectMcp(options: McpClientOptions): Promise<McpClient>;
+    /** Close all MCP client connections. */
+    closeMcpClients(): Promise<void>;
+    /** Project to LangChain-compatible tool definitions. */
+    toLangChain(options: ToLangChainOptions): LangChainToolDefinition[];
 }
 //# sourceMappingURL=registry.d.ts.map