@simulacra-ai/mcp 0.0.2 → 0.0.4

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+The MCP (Model Context Protocol) bridge connects Simulacra to MCP tool servers and exposes their tools as Simulacra tool classes, so the model can use them without writing custom tool implementations.
 
 ## Installation
 
@@ -12,10 +12,9 @@ npm install @simulacra-ai/core @simulacra-ai/mcp @modelcontextprotocol/sdk
 
 ```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";
 
+// connect to an MCP server
 const mcp = new McpToolProvider({
   servers: [
     {
@@ -25,21 +24,23 @@ const mcp = new McpToolProvider({
     },
   ],
 });
-
 await mcp.connect();
 
-const provider = new AnthropicProvider(new Anthropic(), { model: MODEL_NAME });
-const conversation = new Conversation(provider);
+// add MCP tools to the conversation's toolkit
+using conversation = new Conversation(provider);
 conversation.toolkit = [...conversation.toolkit, ...mcp.getToolClasses()];
-const manager = new WorkflowManager(conversation);
+using manager = new WorkflowManager(conversation);
 
 await conversation.prompt("List the files in /tmp");
 
+// disconnect when done
 await mcp.disconnect();
 ```
 
 ### Multiple Servers
 
+Multiple MCP servers can be configured at once. Tools from all servers are merged into a single toolkit.
+
 ```typescript
 const mcp = new McpToolProvider({
   servers: [
@@ -60,9 +61,10 @@ const mcp = new McpToolProvider({
 
 ### Tool Overrides
 
-By default, all MCP tools are `parallelizable: true`. Override specific tools with side effects or ordering requirements:
+By default, all MCP tools are `parallelizable: true`. Specific tools with side effects or ordering requirements can be overridden.
 
 ```typescript
+// inside the servers array
 {
   name: "database",
   command: "node",

package/dist/index.cjs

@@ -0,0 +1,261 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  McpToolProvider: () => McpToolProvider,
+  convertJsonSchemaToParameters: () => convertJsonSchemaToParameters
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/schema-converter.ts
+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 } : {}
+    };
+  }
+  return required ? {
+    type: "string",
+    required: true,
+    ...prop.description ? { description: prop.description } : {}
+  } : {
+    type: "string",
+    required: false,
+    ...prop.description ? { description: prop.description } : {}
+  };
+}
+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))
+  );
+}
+
+// src/mcp-tool-provider.ts
+var import_client = require("@modelcontextprotocol/sdk/client/index.js");
+var import_stdio = require("@modelcontextprotocol/sdk/client/stdio.js");
+var McpToolProvider = class {
+  #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 import_stdio.StdioClientTransport({
+          command: server_config.command,
+          args: server_config.args,
+          env: server_config.env
+        });
+        const client = new import_client.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 !== void 0 ? { 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 text2 = result.content?.filter((c) => c.type === "text").map((c) => c.text ?? "").join("\n") || "MCP tool error";
+            return { result: false, message: text2 };
+          }
+          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;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  McpToolProvider,
+  convertJsonSchemaToParameters
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/schema-converter.ts","../src/mcp-tool-provider.ts"],"sourcesContent":["export * from \"./types.ts\";\nexport * from \"./schema-converter.ts\";\nexport * from \"./mcp-tool-provider.ts\";\n","import type { ToolParameterDefinition, ParameterType } from \"@simulacra-ai/core\";\n\ninterface JsonSchemaProperty {\n  type?: string;\n  description?: string;\n  enum?: string[];\n  properties?: Record<string, JsonSchemaProperty>;\n  required?: string[];\n  items?: JsonSchemaProperty;\n  default?: unknown;\n}\n\ninterface JsonSchema {\n  type?: string;\n  properties?: Record<string, JsonSchemaProperty>;\n  required?: string[];\n}\n\nfunction convertProperty(\n  name: string,\n  prop: JsonSchemaProperty,\n  required: boolean,\n): ToolParameterDefinition {\n  const param_type = convertType(prop, required);\n  const def: ToolParameterDefinition = { ...param_type, name };\n  if (prop.description) {\n    def.description = prop.description;\n  }\n  return def;\n}\n\nfunction convertType(prop: JsonSchemaProperty, required: boolean): ParameterType {\n  if (prop.type === \"object\" && prop.properties) {\n    const nested: Record<string, ParameterType> = {};\n    for (const [key, value] of Object.entries(prop.properties)) {\n      const child_required = prop.required?.includes(key) ?? false;\n      nested[key] = convertType(value, child_required);\n    }\n    return {\n      type: \"object\",\n      required,\n      properties: nested,\n      ...(prop.description ? { description: prop.description } : {}),\n    };\n  }\n\n  if (prop.type === \"array\" && prop.items) {\n    return {\n      type: \"array\",\n      required,\n      items: convertType(prop.items, false),\n      ...(prop.description ? { description: prop.description } : {}),\n    };\n  }\n\n  if (prop.type === \"string\" && prop.enum) {\n    return required\n      ? {\n          type: \"string\",\n          required: true,\n          enum: prop.enum,\n          ...(prop.description ? { description: prop.description } : {}),\n        }\n      : {\n          type: \"string\",\n          required: false,\n          enum: prop.enum,\n          ...(prop.description ? { description: prop.description } : {}),\n        };\n  }\n\n  if (prop.type === \"number\" || prop.type === \"integer\") {\n    return required\n      ? {\n          type: \"number\",\n          required: true,\n          ...(prop.description ? { description: prop.description } : {}),\n        }\n      : {\n          type: \"number\",\n          required: false,\n          ...(prop.description ? { description: prop.description } : {}),\n        };\n  }\n\n  if (prop.type === \"boolean\") {\n    return required\n      ? {\n          type: \"boolean\",\n          required: true,\n          ...(prop.description ? { description: prop.description } : {}),\n        }\n      : {\n          type: \"boolean\",\n          required: false,\n          ...(prop.description ? { description: prop.description } : {}),\n        };\n  }\n\n  // Default: treat as string (covers type === \"string\" and unknown types)\n  return required\n    ? {\n        type: \"string\",\n        required: true,\n        ...(prop.description ? { description: prop.description } : {}),\n      }\n    : {\n        type: \"string\",\n        required: false,\n        ...(prop.description ? { description: prop.description } : {}),\n      };\n}\n\n/**\n * Converts a JSON Schema object into an array of Simulacra tool parameter definitions.\n *\n * This function transforms MCP tool input schemas (which use JSON Schema format)\n * into the parameter format expected by Simulacra tools. It handles nested objects,\n * arrays, enums, and all standard JSON Schema primitive types.\n *\n * @param schema - A JSON Schema object describing the tool's input parameters.\n * @returns An array of tool parameter definitions compatible with Simulacra.\n */\nexport function convertJsonSchemaToParameters(\n  schema: Record<string, unknown>,\n): ToolParameterDefinition[] {\n  const s = schema as unknown as JsonSchema;\n  if (!s.properties) {\n    return [];\n  }\n\n  const required_set = new Set(s.required ?? []);\n  return Object.entries(s.properties).map(([name, prop]) =>\n    convertProperty(name, prop, required_set.has(name)),\n  );\n}\n","import { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport { StdioClientTransport } from \"@modelcontextprotocol/sdk/client/stdio.js\";\nimport type {\n  ToolClass,\n  ToolDefinition,\n  ToolContext,\n  ToolSuccessResult,\n  ToolErrorResult,\n} from \"@simulacra-ai/core\";\nimport { convertJsonSchemaToParameters } from \"./schema-converter.ts\";\nimport type { McpServerConfig, McpToolProviderConfig } from \"./types.ts\";\n\ninterface ConnectedServer {\n  config: McpServerConfig;\n  client: Client;\n  transport: StdioClientTransport;\n}\n\n/**\n * A provider that connects to Model Context Protocol (MCP) servers and exposes\n * their tools as Simulacra-compatible tool classes.\n *\n * This class manages the lifecycle of MCP server connections, converts MCP tools\n * into the Simulacra tool format, and provides access to all tools from connected\n * servers.\n */\nexport class McpToolProvider {\n  readonly #config: McpToolProviderConfig;\n  #servers: ConnectedServer[] = [];\n  #tool_classes: ToolClass[] = [];\n\n  /**\n   * Creates a new MCP tool provider.\n   *\n   * @param config - Configuration specifying which MCP servers to connect to.\n   */\n  constructor(config: McpToolProviderConfig) {\n    this.#config = config;\n  }\n\n  /**\n   * Establishes connections to all configured MCP servers and retrieves their tools.\n   *\n   * This method spawns each server process, establishes communication over stdio,\n   * and queries each server for its available tools. The tools are converted to\n   * Simulacra-compatible tool classes and stored internally.\n   *\n   * @returns A promise that resolves when all servers are connected and tools are loaded.\n   */\n  async connect(): Promise<void> {\n    const connected: ConnectedServer[] = [];\n    const added_tool_classes: ToolClass[] = [];\n    try {\n      for (const server_config of this.#config.servers) {\n        const transport = new StdioClientTransport({\n          command: server_config.command,\n          args: server_config.args,\n          env: server_config.env,\n        });\n\n        const client = new Client({ name: \"simulacra\", version: \"0.1.0\" }, { capabilities: {} });\n\n        await client.connect(transport);\n\n        const server: ConnectedServer = { config: server_config, client, transport };\n        connected.push(server);\n        this.#servers.push(server);\n\n        const tools_result = await client.listTools();\n\n        for (const mcp_tool of tools_result.tools) {\n          const tool_class = this.#create_tool_class(client, mcp_tool, server_config);\n          added_tool_classes.push(tool_class);\n          this.#tool_classes.push(tool_class);\n        }\n      }\n    } catch (error) {\n      for (const server of connected) {\n        await server.client.close().catch((close_error) => {\n          this.#config.on_error?.({\n            error: close_error,\n            operation: \"disconnect\",\n            context: { during: \"connect_rollback\" },\n          });\n        });\n      }\n      this.#servers = this.#servers.filter((s) => !connected.includes(s));\n      this.#tool_classes = this.#tool_classes.filter((t) => !added_tool_classes.includes(t));\n      throw error;\n    }\n  }\n\n  /**\n   * Closes all MCP server connections and clears the cached tool classes.\n   *\n   * This method gracefully shuts down all server processes and cleans up\n   * internal state. After calling this method, the tool classes are no longer\n   * available.\n   *\n   * @returns A promise that resolves when all servers are disconnected.\n   */\n  async disconnect(): Promise<void> {\n    await Promise.allSettled(this.#servers.map((s) => s.client.close()));\n    this.#servers = [];\n    this.#tool_classes = [];\n  }\n\n  /**\n   * Enables automatic cleanup when the provider is disposed.\n   *\n   * This method implements the disposable pattern, allowing the provider to be\n   * used with explicit resource management syntax (using keyword). When disposed,\n   * it attempts to disconnect from all servers.\n   */\n  [Symbol.dispose]() {\n    this.disconnect().catch((error) => {\n      this.#config.on_error?.({ error, operation: \"disconnect\", context: { during: \"dispose\" } });\n    });\n  }\n\n  /**\n   * Retrieves all tool classes from connected MCP servers.\n   *\n   * This method returns a shallow copy of the internal tool classes array,\n   * containing Simulacra-compatible tool classes for all tools from all\n   * connected servers.\n   *\n   * @returns An array of tool classes ready to be used in a Simulacra workflow.\n   */\n  getToolClasses(): ToolClass[] {\n    return [...this.#tool_classes];\n  }\n\n  #create_tool_class(\n    client: Client,\n    mcp_tool: { name: string; description?: string; inputSchema?: unknown },\n    server_config: McpServerConfig,\n  ): ToolClass {\n    const parameters = mcp_tool.inputSchema\n      ? convertJsonSchemaToParameters(mcp_tool.inputSchema as Record<string, unknown>)\n      : [];\n\n    const parallelizable = server_config.tool_overrides?.[mcp_tool.name]?.parallelizable;\n\n    const definition: ToolDefinition = {\n      name: mcp_tool.name,\n      description: mcp_tool.description ?? \"\",\n      parameters,\n      ...(parallelizable !== undefined ? { parallelizable } : {}),\n    };\n\n    const McpTool = class {\n      static get_definition() {\n        return definition;\n      }\n\n      constructor(_context: ToolContext) {}\n\n      async execute(params: Record<string, unknown>): Promise<ToolSuccessResult | ToolErrorResult> {\n        try {\n          const result = await client.callTool({\n            name: mcp_tool.name,\n            arguments: params,\n          });\n\n          if (result.isError) {\n            const text =\n              (result.content as Array<{ type: string; text?: string }>)\n                ?.filter((c) => c.type === \"text\")\n                .map((c) => c.text ?? \"\")\n                .join(\"\\n\") || \"MCP tool error\";\n            return { result: false, message: text };\n          }\n\n          const text = (result.content as Array<{ type: string; text?: string }>)\n            ?.filter((c) => c.type === \"text\")\n            .map((c) => c.text ?? \"\")\n            .join(\"\\n\");\n          return {\n            result: true,\n            ...({ output: text || \"success\" } as Record<string, unknown>),\n          } as ToolSuccessResult;\n        } catch (error) {\n          return {\n            result: false,\n            message: error instanceof Error ? error.message : String(error),\n            error,\n          };\n        }\n      }\n    };\n\n    return McpTool as unknown as ToolClass;\n  }\n}\n"],"mappings":"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","names":["text"]}

package/dist/index.d.cts

@@ -0,0 +1,127 @@
+import { LifecycleErrorEvent, ToolParameterDefinition, ToolClass } 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.
+ */
+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.
+ */
+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;
+}
+
+/**
+ * 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.
+ */
+declare function convertJsonSchemaToParameters(schema: Record<string, unknown>): ToolParameterDefinition[];
+
+/**
+ * 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.
+ */
+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[];
+}
+
+export { type McpServerConfig, McpToolProvider, type McpToolProviderConfig, convertJsonSchemaToParameters };

package/dist/index.d.ts

@@ -1,4 +1,127 @@
-export * from "./types.ts";
-export * from "./schema-converter.ts";
-export * from "./mcp-tool-provider.ts";
-//# sourceMappingURL=index.d.ts.map
+import { LifecycleErrorEvent, ToolParameterDefinition, ToolClass } 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.
+ */
+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.
+ */
+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;
+}
+
+/**
+ * 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.
+ */
+declare function convertJsonSchemaToParameters(schema: Record<string, unknown>): ToolParameterDefinition[];
+
+/**
+ * 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.
+ */
+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[];
+}
+
+export { type McpServerConfig, McpToolProvider, type McpToolProviderConfig, convertJsonSchemaToParameters };