@simulacra-ai/mcp 0.0.1

package/README.md

@@ -0,0 +1,79 @@
+# Simulacra MCP Bridge
+
+MCP (Model Context Protocol) client bridge for the Simulacra conversation engine. Connects to MCP servers and exposes their tools as Simulacra tool classes.
+
+## Installation
+
+```bash
+npm install @simulacra-ai/core @simulacra-ai/mcp @modelcontextprotocol/sdk
+```
+
+## Usage
+
+```typescript
+import { Conversation, WorkflowManager } from "@simulacra-ai/core";
+import { AnthropicProvider } from "@simulacra-ai/anthropic";
+import Anthropic from "@anthropic-ai/sdk";
+import { McpToolProvider } from "@simulacra-ai/mcp";
+
+const mcp = new McpToolProvider({
+  servers: [
+    {
+      name: "filesystem",
+      command: "npx",
+      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+    },
+  ],
+});
+
+await mcp.connect();
+
+const provider = new AnthropicProvider(new Anthropic(), { model: MODEL_NAME });
+const conversation = new Conversation(provider);
+conversation.toolkit = [...conversation.toolkit, ...mcp.getToolClasses()];
+const manager = new WorkflowManager(conversation);
+
+await conversation.prompt("List the files in /tmp");
+
+await mcp.disconnect();
+```
+
+### Multiple Servers
+
+```typescript
+const mcp = new McpToolProvider({
+  servers: [
+    {
+      name: "filesystem",
+      command: "npx",
+      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+    },
+    {
+      name: "database",
+      command: "node",
+      args: ["./my-db-server.js"],
+      env: { DATABASE_URL: "postgres://localhost/mydb" },
+    },
+  ],
+});
+```
+
+### Tool Overrides
+
+By default, all MCP tools are `parallelizable: true`. Override specific tools with side effects or ordering requirements:
+
+```typescript
+{
+  name: "database",
+  command: "node",
+  args: ["./my-db-server.js"],
+  tool_overrides: {
+    "execute_query": { parallelizable: false },
+    "create_table": { parallelizable: false },
+  },
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types.ts";
+export * from "./schema-converter.ts";
+export * from "./mcp-tool-provider.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./schema-converter.js";
+export * from "./mcp-tool-provider.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC"}

package/dist/mcp-tool-provider.d.ts

@@ -0,0 +1,58 @@
+import type { ToolClass } from "@simulacra-ai/core";
+import type { McpToolProviderConfig } from "./types.ts";
+/**
+ * A provider that connects to Model Context Protocol (MCP) servers and exposes
+ * their tools as Simulacra-compatible tool classes.
+ *
+ * This class manages the lifecycle of MCP server connections, converts MCP tools
+ * into the Simulacra tool format, and provides access to all tools from connected
+ * servers.
+ */
+export declare class McpToolProvider {
+    #private;
+    /**
+     * Creates a new MCP tool provider.
+     *
+     * @param config - Configuration specifying which MCP servers to connect to.
+     */
+    constructor(config: McpToolProviderConfig);
+    /**
+     * Establishes connections to all configured MCP servers and retrieves their tools.
+     *
+     * This method spawns each server process, establishes communication over stdio,
+     * and queries each server for its available tools. The tools are converted to
+     * Simulacra-compatible tool classes and stored internally.
+     *
+     * @returns A promise that resolves when all servers are connected and tools are loaded.
+     */
+    connect(): Promise<void>;
+    /**
+     * Closes all MCP server connections and clears the cached tool classes.
+     *
+     * This method gracefully shuts down all server processes and cleans up
+     * internal state. After calling this method, the tool classes are no longer
+     * available.
+     *
+     * @returns A promise that resolves when all servers are disconnected.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Enables automatic cleanup when the provider is disposed.
+     *
+     * This method implements the disposable pattern, allowing the provider to be
+     * used with explicit resource management syntax (using keyword). When disposed,
+     * it attempts to disconnect from all servers.
+     */
+    [Symbol.dispose](): void;
+    /**
+     * Retrieves all tool classes from connected MCP servers.
+     *
+     * This method returns a shallow copy of the internal tool classes array,
+     * containing Simulacra-compatible tool classes for all tools from all
+     * connected servers.
+     *
+     * @returns An array of tool classes ready to be used in a Simulacra workflow.
+     */
+    getToolClasses(): ToolClass[];
+}
+//# sourceMappingURL=mcp-tool-provider.d.ts.map

package/dist/mcp-tool-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tool-provider.d.ts","sourceRoot":"","sources":["../src/mcp-tool-provider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,SAAS,EAKV,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAmB,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAQzE;;;;;;;GAOG;AACH,qBAAa,eAAe;;IAK1B;;;;OAIG;gBACS,MAAM,EAAE,qBAAqB;IAIzC;;;;;;;;OAQG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA2C9B;;;;;;;;OAQG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC;;;;;;OAMG;IACH,CAAC,MAAM,CAAC,OAAO,CAAC;IAMhB;;;;;;;;OAQG;IACH,cAAc,IAAI,SAAS,EAAE;CAiE9B"}

package/dist/mcp-tool-provider.js

@@ -0,0 +1,159 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { convertJsonSchemaToParameters } from "./schema-converter.js";
+/**
+ * A provider that connects to Model Context Protocol (MCP) servers and exposes
+ * their tools as Simulacra-compatible tool classes.
+ *
+ * This class manages the lifecycle of MCP server connections, converts MCP tools
+ * into the Simulacra tool format, and provides access to all tools from connected
+ * servers.
+ */
+export class McpToolProvider {
+    #config;
+    #servers = [];
+    #tool_classes = [];
+    /**
+     * Creates a new MCP tool provider.
+     *
+     * @param config - Configuration specifying which MCP servers to connect to.
+     */
+    constructor(config) {
+        this.#config = config;
+    }
+    /**
+     * Establishes connections to all configured MCP servers and retrieves their tools.
+     *
+     * This method spawns each server process, establishes communication over stdio,
+     * and queries each server for its available tools. The tools are converted to
+     * Simulacra-compatible tool classes and stored internally.
+     *
+     * @returns A promise that resolves when all servers are connected and tools are loaded.
+     */
+    async connect() {
+        const connected = [];
+        const added_tool_classes = [];
+        try {
+            for (const server_config of this.#config.servers) {
+                const transport = new StdioClientTransport({
+                    command: server_config.command,
+                    args: server_config.args,
+                    env: server_config.env,
+                });
+                const client = new Client({ name: "simulacra", version: "0.1.0" }, { capabilities: {} });
+                await client.connect(transport);
+                const server = { config: server_config, client, transport };
+                connected.push(server);
+                this.#servers.push(server);
+                const tools_result = await client.listTools();
+                for (const mcp_tool of tools_result.tools) {
+                    const tool_class = this.#create_tool_class(client, mcp_tool, server_config);
+                    added_tool_classes.push(tool_class);
+                    this.#tool_classes.push(tool_class);
+                }
+            }
+        }
+        catch (error) {
+            for (const server of connected) {
+                await server.client.close().catch((close_error) => {
+                    this.#config.on_error?.({
+                        error: close_error,
+                        operation: "disconnect",
+                        context: { during: "connect_rollback" },
+                    });
+                });
+            }
+            this.#servers = this.#servers.filter((s) => !connected.includes(s));
+            this.#tool_classes = this.#tool_classes.filter((t) => !added_tool_classes.includes(t));
+            throw error;
+        }
+    }
+    /**
+     * Closes all MCP server connections and clears the cached tool classes.
+     *
+     * This method gracefully shuts down all server processes and cleans up
+     * internal state. After calling this method, the tool classes are no longer
+     * available.
+     *
+     * @returns A promise that resolves when all servers are disconnected.
+     */
+    async disconnect() {
+        await Promise.allSettled(this.#servers.map((s) => s.client.close()));
+        this.#servers = [];
+        this.#tool_classes = [];
+    }
+    /**
+     * Enables automatic cleanup when the provider is disposed.
+     *
+     * This method implements the disposable pattern, allowing the provider to be
+     * used with explicit resource management syntax (using keyword). When disposed,
+     * it attempts to disconnect from all servers.
+     */
+    [Symbol.dispose]() {
+        this.disconnect().catch((error) => {
+            this.#config.on_error?.({ error, operation: "disconnect", context: { during: "dispose" } });
+        });
+    }
+    /**
+     * Retrieves all tool classes from connected MCP servers.
+     *
+     * This method returns a shallow copy of the internal tool classes array,
+     * containing Simulacra-compatible tool classes for all tools from all
+     * connected servers.
+     *
+     * @returns An array of tool classes ready to be used in a Simulacra workflow.
+     */
+    getToolClasses() {
+        return [...this.#tool_classes];
+    }
+    #create_tool_class(client, mcp_tool, server_config) {
+        const parameters = mcp_tool.inputSchema
+            ? convertJsonSchemaToParameters(mcp_tool.inputSchema)
+            : [];
+        const parallelizable = server_config.tool_overrides?.[mcp_tool.name]?.parallelizable;
+        const definition = {
+            name: mcp_tool.name,
+            description: mcp_tool.description ?? "",
+            parameters,
+            ...(parallelizable !== undefined ? { parallelizable } : {}),
+        };
+        const McpTool = class {
+            static get_definition() {
+                return definition;
+            }
+            constructor(_context) { }
+            async execute(params) {
+                try {
+                    const result = await client.callTool({
+                        name: mcp_tool.name,
+                        arguments: params,
+                    });
+                    if (result.isError) {
+                        const text = result.content
+                            ?.filter((c) => c.type === "text")
+                            .map((c) => c.text ?? "")
+                            .join("\n") || "MCP tool error";
+                        return { result: false, message: text };
+                    }
+                    const text = result.content
+                        ?.filter((c) => c.type === "text")
+                        .map((c) => c.text ?? "")
+                        .join("\n");
+                    return {
+                        result: true,
+                        ...{ output: text || "success" },
+                    };
+                }
+                catch (error) {
+                    return {
+                        result: false,
+                        message: error instanceof Error ? error.message : String(error),
+                        error,
+                    };
+                }
+            }
+        };
+        return McpTool;
+    }
+}
+//# sourceMappingURL=mcp-tool-provider.js.map

package/dist/mcp-tool-provider.js.map

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

package/dist/schema-converter.d.ts

@@ -0,0 +1,13 @@
+import type { ToolParameterDefinition } from "@simulacra-ai/core";
+/**
+ * Converts a JSON Schema object into an array of Simulacra tool parameter definitions.
+ *
+ * This function transforms MCP tool input schemas (which use JSON Schema format)
+ * into the parameter format expected by Simulacra tools. It handles nested objects,
+ * arrays, enums, and all standard JSON Schema primitive types.
+ *
+ * @param schema - A JSON Schema object describing the tool's input parameters.
+ * @returns An array of tool parameter definitions compatible with Simulacra.
+ */
+export declare function convertJsonSchemaToParameters(schema: Record<string, unknown>): ToolParameterDefinition[];
+//# sourceMappingURL=schema-converter.d.ts.map

package/dist/schema-converter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-converter.d.ts","sourceRoot":"","sources":["../src/schema-converter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAiB,MAAM,oBAAoB,CAAC;AAiHjF;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,uBAAuB,EAAE,CAU3B"}

package/dist/schema-converter.js

@@ -0,0 +1,103 @@
+function convertProperty(name, prop, required) {
+    const param_type = convertType(prop, required);
+    const def = { ...param_type, name };
+    if (prop.description) {
+        def.description = prop.description;
+    }
+    return def;
+}
+function convertType(prop, required) {
+    if (prop.type === "object" && prop.properties) {
+        const nested = {};
+        for (const [key, value] of Object.entries(prop.properties)) {
+            const child_required = prop.required?.includes(key) ?? false;
+            nested[key] = convertType(value, child_required);
+        }
+        return {
+            type: "object",
+            required,
+            properties: nested,
+            ...(prop.description ? { description: prop.description } : {}),
+        };
+    }
+    if (prop.type === "array" && prop.items) {
+        return {
+            type: "array",
+            required,
+            items: convertType(prop.items, false),
+            ...(prop.description ? { description: prop.description } : {}),
+        };
+    }
+    if (prop.type === "string" && prop.enum) {
+        return required
+            ? {
+                type: "string",
+                required: true,
+                enum: prop.enum,
+                ...(prop.description ? { description: prop.description } : {}),
+            }
+            : {
+                type: "string",
+                required: false,
+                enum: prop.enum,
+                ...(prop.description ? { description: prop.description } : {}),
+            };
+    }
+    if (prop.type === "number" || prop.type === "integer") {
+        return required
+            ? {
+                type: "number",
+                required: true,
+                ...(prop.description ? { description: prop.description } : {}),
+            }
+            : {
+                type: "number",
+                required: false,
+                ...(prop.description ? { description: prop.description } : {}),
+            };
+    }
+    if (prop.type === "boolean") {
+        return required
+            ? {
+                type: "boolean",
+                required: true,
+                ...(prop.description ? { description: prop.description } : {}),
+            }
+            : {
+                type: "boolean",
+                required: false,
+                ...(prop.description ? { description: prop.description } : {}),
+            };
+    }
+    // Default: treat as string (covers type === "string" and unknown types)
+    return required
+        ? {
+            type: "string",
+            required: true,
+            ...(prop.description ? { description: prop.description } : {}),
+        }
+        : {
+            type: "string",
+            required: false,
+            ...(prop.description ? { description: prop.description } : {}),
+        };
+}
+/**
+ * Converts a JSON Schema object into an array of Simulacra tool parameter definitions.
+ *
+ * This function transforms MCP tool input schemas (which use JSON Schema format)
+ * into the parameter format expected by Simulacra tools. It handles nested objects,
+ * arrays, enums, and all standard JSON Schema primitive types.
+ *
+ * @param schema - A JSON Schema object describing the tool's input parameters.
+ * @returns An array of tool parameter definitions compatible with Simulacra.
+ */
+export function convertJsonSchemaToParameters(schema) {
+    const s = schema;
+    if (!s.properties) {
+        return [];
+    }
+    const required_set = new Set(s.required ?? []);
+    return Object.entries(s.properties).map(([name, prop]) => convertProperty(name, prop, required_set.has(name)));
+}
+//# sourceMappingURL=schema-converter.js.map

package/dist/schema-converter.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,57 @@
+import type { LifecycleErrorEvent } from "@simulacra-ai/core";
+/**
+ * Configuration for a single Model Context Protocol (MCP) server connection.
+ *
+ * This interface defines how to connect to and configure an MCP server,
+ * including the command to execute, environment variables, and tool-specific
+ * overrides.
+ */
+export interface McpServerConfig {
+    /**
+     * A unique identifier for this MCP server.
+     */
+    name: string;
+    /**
+     * The command to execute to start the MCP server process.
+     */
+    command: string;
+    /**
+     * Command-line arguments to pass to the server command.
+     */
+    args?: string[];
+    /**
+     * Environment variables to set for the server process.
+     */
+    env?: Record<string, string>;
+    /**
+     * The transport mechanism used to communicate with the server.
+     * Currently only "stdio" is supported.
+     */
+    transport?: "stdio";
+    /**
+     * Tool-specific configuration overrides, keyed by tool name.
+     */
+    tool_overrides?: Record<string, {
+        /**
+         * Whether this tool can be executed in parallel with other tools.
+         */
+        parallelizable?: boolean;
+    }>;
+}
+/**
+ * Configuration for the MCP tool provider.
+ *
+ * This interface defines the configuration needed to connect to one or more
+ * MCP servers and make their tools available to a Simulacra workflow.
+ */
+export interface McpToolProviderConfig {
+    /**
+     * An array of MCP server configurations to connect to.
+     */
+    servers: McpServerConfig[];
+    /**
+     * Optional callback invoked when a background operation fails during cleanup or disposal.
+     */
+    on_error?: (event: LifecycleErrorEvent) => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE7B;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CACrB,MAAM,EACN;QACE;;WAEG;QACH,cAAc,CAAC,EAAE,OAAO,CAAC;KAC1B,CACF,CAAC;CACH;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,OAAO,EAAE,eAAe,EAAE,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;CACjD"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@simulacra-ai/mcp",
+  "version": "0.0.1",
+  "description": "MCP (Model Context Protocol) client bridge for the Simulacra conversation engine",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "peerDependencies": {
+    "@simulacra-ai/core": "0.0.1",
+    "@modelcontextprotocol/sdk": ">=1.0.0"
+  },
+  "license": "MIT"
+}