@agentick/core 0.0.1

package/dist/mcp/create-mcp-tool.js

@@ -0,0 +1,228 @@
+/**
+ * MCP Tool Creation
+ *
+ * Factory functions for creating MCP tools that work like regular tools:
+ * - Pass to models: engine.execute({ tools: [tool] })
+ * - Run directly: await tool.run(input)
+ * - Use in JSX: <MyMCPTool />
+ *
+ * Three main entry points:
+ * 1. createMCPTool() - Component factory with discovery, for JSX usage
+ * 2. createMCPToolFromDefinition() - Direct creation from known definition
+ * 3. discoverMCPTools() - Batch discovery of all tools on a server
+ */
+import React from "react";
+import { MCPClient } from "./client";
+import { MCPService } from "./service";
+import { MCPTool } from "./tool";
+import { MCPToolComponent } from "./component";
+// ============================================================================
+// Config Utilities
+// ============================================================================
+/**
+ * Normalizes Cursor-style config to full MCPConfig.
+ *
+ * Cursor-style: { command: 'npx', args: [...], env: {...} }
+ * Full MCPConfig: { serverName, transport, connection: {...} }
+ */
+export function normalizeMCPConfig(serverName, config) {
+    // Already a full MCPConfig
+    if ("transport" in config && "connection" in config) {
+        return config;
+    }
+    // Convert Cursor-style to MCPConfig (assumes stdio transport)
+    const c = config;
+    return {
+        serverName,
+        transport: "stdio",
+        connection: {
+            command: c.command,
+            args: c.args || [],
+            env: c.env,
+        },
+    };
+}
+/**
+ * Merges base config with runtime overrides.
+ * Runtime values take precedence.
+ */
+export function mergeMCPConfig(base, runtime) {
+    if (!runtime)
+        return base;
+    return {
+        ...base,
+        ...runtime,
+        connection: {
+            ...base.connection,
+            ...runtime.connection,
+        },
+        auth: runtime.auth || base.auth,
+    };
+}
+/**
+ * Creates an MCP tool component that discovers and registers on mount.
+ *
+ * Use this when you need:
+ * - Dynamic discovery at runtime
+ * - Runtime configuration (auth tokens)
+ * - JSX-based tool declaration
+ *
+ * @example Basic usage
+ * ```tsx
+ * const ReadFile = createMCPTool({
+ *   server: 'filesystem',
+ *   config: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '/path'] },
+ *   toolName: 'read_file',
+ * });
+ *
+ * function MyAgent() {
+ *   return (
+ *     <>
+ *       <ReadFile />
+ *       <Model />
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example With runtime auth
+ * ```tsx
+ * const APITool = createMCPTool({
+ *   server: 'api',
+ *   config: { transport: 'sse', connection: { url: 'https://api.example.com/mcp' } },
+ *   toolName: 'query',
+ * });
+ *
+ * // Runtime config from user context
+ * <APITool runtimeConfig={{ auth: { type: 'bearer', token: userToken } }} />
+ * ```
+ */
+export function createMCPTool(options) {
+    // Return a functional component that wraps MCPToolComponent with merged props
+    const SingleMCPToolComponent = (props) => {
+        // Build merged props
+        const mergedProps = {
+            server: props?.server ?? options.server,
+            config: props?.config ?? options.config,
+            // If toolName specified, only include that tool; otherwise include first tool
+            include: options.toolName ? [options.toolName] : undefined,
+            toolPrefix: props?.toolPrefix ?? options.toolPrefix,
+            mcpClient: props?.client ?? options.client,
+            runtimeConfig: props?.runtimeConfig ?? options.runtimeConfig,
+            // Pass lifecycle hooks from options
+            onMount: options.onMount,
+            onUnmount: options.onUnmount,
+            onStart: options.onStart,
+            onTickStart: options.onTickStart,
+            onTickEnd: options.onTickEnd,
+            onComplete: options.onComplete,
+            onError: options.onError,
+        };
+        return React.createElement(MCPToolComponent, mergedProps);
+    };
+    return SingleMCPToolComponent;
+}
+/**
+ * Creates an ExecutableTool from an MCP tool definition.
+ *
+ * Use this when you already have:
+ * - An active MCPClient connection
+ * - The tool definition from discovery
+ *
+ * @example
+ * ```typescript
+ * const client = new MCPClient();
+ * const service = new MCPService(client);
+ *
+ * // Connect and discover
+ * const config: MCPConfig = {
+ *   serverName: 'filesystem',
+ *   transport: 'stdio',
+ *   connection: { command: 'npx', args: [...] }
+ * };
+ * const tools = await service.connectAndDiscover(config);
+ *
+ * // Create specific tool
+ * const readFile = createMCPToolFromDefinition({
+ *   client,
+ *   config,
+ *   definition: tools.find(t => t.name === 'read_file')!,
+ * });
+ *
+ * // Pass to model
+ * engine.execute({ tools: [readFile] });
+ *
+ * // Or run directly
+ * const result = await readFile.run({ path: '/file.txt' });
+ * ```
+ */
+export function createMCPToolFromDefinition(options) {
+    const { client, config, definition } = options;
+    const name = options.name || definition.name;
+    const mcpConfig = {
+        serverName: config.serverName,
+        serverUrl: config.connection.url,
+        transport: config.transport,
+    };
+    return new MCPTool(client, config.serverName, { ...definition, name }, mcpConfig);
+}
+/**
+ * Discovers all tools from an MCP server and creates ExecutableTools.
+ *
+ * Use this for batch tool registration or when you need all tools
+ * from a server without JSX.
+ *
+ * @example Basic discovery
+ * ```typescript
+ * const tools = await discoverMCPTools({
+ *   config: {
+ *     serverName: 'filesystem',
+ *     transport: 'stdio',
+ *     connection: { command: 'npx', args: [...] }
+ *   },
+ * });
+ *
+ * // Pass all to model
+ * engine.execute({ tools });
+ * ```
+ *
+ * @example With filtering
+ * ```typescript
+ * const tools = await discoverMCPTools({
+ *   config,
+ *   include: ['read_file', 'list_directory'], // Only these
+ *   toolPrefix: 'fs_',
+ * });
+ * ```
+ *
+ * @example Register with COM
+ * ```typescript
+ * const tools = await discoverMCPTools({ config });
+ * tools.forEach(tool => ctx.addTool(tool));
+ * ```
+ */
+export async function discoverMCPTools(options) {
+    const { config } = options;
+    const client = options.client ?? new MCPClient();
+    const service = new MCPService(client);
+    // Discover
+    let definitions = await service.connectAndDiscover(config);
+    // Filter
+    if (options.include?.length) {
+        definitions = definitions.filter((t) => options.include.includes(t.name));
+    }
+    else if (options.exclude?.length) {
+        definitions = definitions.filter((t) => !options.exclude.includes(t.name));
+    }
+    // Create tools
+    return definitions.map((def) => {
+        const name = options.toolPrefix ? `${options.toolPrefix}${def.name}` : def.name;
+        return createMCPToolFromDefinition({
+            client,
+            config,
+            definition: def,
+            name,
+        });
+    });
+}
+//# sourceMappingURL=create-mcp-tool.js.map

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

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

package/dist/mcp/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * # Agentick MCP (Model Context Protocol)
+ *
+ * Integration with MCP servers for external tool execution.
+ * MCP allows agents to use tools provided by external servers.
+ *
+ * ## Features
+ *
+ * - **MCPClient** - Connect to MCP servers
+ * - **MCPService** - Manage multiple MCP connections
+ * - **Tool Discovery** - Auto-discover tools from MCP servers
+ * - **Tool Components** - Use MCP tools as JSX components
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { discoverMCPTools } from 'agentick/mcp';
+ *
+ * // Discover tools from an MCP server
+ * const tools = await discoverMCPTools({
+ *   server: {
+ *     command: 'npx',
+ *     args: ['-y', '@modelcontextprotocol/server-filesystem'],
+ *   },
+ * });
+ *
+ * // Use in an agent
+ * const MyAgent = () => (
+ *   <>
+ *     <System>You can read and write files.</System>
+ *     {tools.map(tool => <Tool key={tool.name} tool={tool} />)}
+ *   </>
+ * );
+ * ```
+ *
+ * @see {@link MCPClient} - MCP server client
+ * @see {@link MCPService} - MCP connection manager
+ * @see {@link discoverMCPTools} - Tool discovery
+ *
+ * @module agentick/mcp
+ */
+export * from "./types";
+export * from "./client";
+export * from "./service";
+export * from "./tool";
+export { MCPToolComponent, MCPTool } from "./component";
+export { createMCPTool, createMCPToolFromDefinition, discoverMCPTools, normalizeMCPConfig, mergeMCPConfig, } from "./create-mcp-tool";
+export type { CreateMCPToolOptions, CreateMCPToolFromDefinitionOptions, DiscoverMCPToolsOptions, } from "./create-mcp-tool";
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EACL,aAAa,EACb,2BAA2B,EAC3B,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,GACf,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,oBAAoB,EACpB,kCAAkC,EAClC,uBAAuB,GACxB,MAAM,mBAAmB,CAAC"}

package/dist/mcp/index.js

@@ -0,0 +1,48 @@
+/**
+ * # Agentick MCP (Model Context Protocol)
+ *
+ * Integration with MCP servers for external tool execution.
+ * MCP allows agents to use tools provided by external servers.
+ *
+ * ## Features
+ *
+ * - **MCPClient** - Connect to MCP servers
+ * - **MCPService** - Manage multiple MCP connections
+ * - **Tool Discovery** - Auto-discover tools from MCP servers
+ * - **Tool Components** - Use MCP tools as JSX components
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { discoverMCPTools } from 'agentick/mcp';
+ *
+ * // Discover tools from an MCP server
+ * const tools = await discoverMCPTools({
+ *   server: {
+ *     command: 'npx',
+ *     args: ['-y', '@modelcontextprotocol/server-filesystem'],
+ *   },
+ * });
+ *
+ * // Use in an agent
+ * const MyAgent = () => (
+ *   <>
+ *     <System>You can read and write files.</System>
+ *     {tools.map(tool => <Tool key={tool.name} tool={tool} />)}
+ *   </>
+ * );
+ * ```
+ *
+ * @see {@link MCPClient} - MCP server client
+ * @see {@link MCPService} - MCP connection manager
+ * @see {@link discoverMCPTools} - Tool discovery
+ *
+ * @module agentick/mcp
+ */
+export * from "./types";
+export * from "./client";
+export * from "./service";
+export * from "./tool";
+export { MCPToolComponent, MCPTool } from "./component";
+export { createMCPTool, createMCPToolFromDefinition, discoverMCPTools, normalizeMCPConfig, mergeMCPConfig, } from "./create-mcp-tool";
+//# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EACL,aAAa,EACb,2BAA2B,EAC3B,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,GACf,MAAM,mBAAmB,CAAC"}

package/dist/mcp/service.d.ts

@@ -0,0 +1,39 @@
+/**
+ * MCP Service
+ *
+ * Manages MCP server connections, tool discovery, and registration.
+ * Uses the official @modelcontextprotocol/sdk Client.
+ */
+import type { Client } from "@modelcontextprotocol/sdk/client";
+import type { MCPClient } from "./client";
+import type { MCPConfig, MCPToolDefinition } from "./types";
+import type { COM } from "../com/object-model";
+/**
+ * MCP Service handles discovery and registration of MCP tools
+ */
+export declare class MCPService {
+    private mcpClient;
+    constructor(mcpClient: MCPClient);
+    connect(config: MCPConfig): Promise<Client>;
+    disconnect(serverName: string): Promise<void>;
+    disconnectAll(): Promise<void>;
+    /**
+     * Connect to an MCP server and discover its tools using SDK
+     */
+    connectAndDiscover(config: MCPConfig): Promise<MCPToolDefinition[]>;
+    /**
+     * Discover tools from an MCP server and register them with the COM
+     */
+    discoverAndRegister(config: MCPConfig, ctx: COM): Promise<void>;
+    listTools(serverName: string): Promise<MCPToolDefinition[]>;
+    /**
+     * Register a single MCP tool (useful for manual registration)
+     */
+    registerMCPTool(config: MCPConfig, mcpToolDef: MCPToolDefinition, ctx: COM): Promise<void>;
+    /**
+     * Disconnect from an MCP server and remove its tools.
+     * Finds tools belonging to this server by checking metadata.mcpConfig.serverName.
+     */
+    disconnectAndUnregister(serverName: string, ctx: COM): Promise<void>;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/mcp/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/mcp/service.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AAE/C;;GAEG;AACH,qBAAa,UAAU;IACT,OAAO,CAAC,SAAS;gBAAT,SAAS,EAAE,SAAS;IAElC,OAAO,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IAI3C,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAIpC;;OAEG;IACG,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAMzE;;OAEG;IACG,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAc/D,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAIjE;;OAEG;IACG,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,iBAAiB,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAUhG;;;OAGG;IACG,uBAAuB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;CAc3E"}

package/dist/mcp/service.js

@@ -0,0 +1,77 @@
+/**
+ * MCP Service
+ *
+ * Manages MCP server connections, tool discovery, and registration.
+ * Uses the official @modelcontextprotocol/sdk Client.
+ */
+import { MCPTool } from "./tool";
+/**
+ * MCP Service handles discovery and registration of MCP tools
+ */
+export class MCPService {
+    mcpClient;
+    constructor(mcpClient) {
+        this.mcpClient = mcpClient;
+    }
+    async connect(config) {
+        return await this.mcpClient.connect(config);
+    }
+    async disconnect(serverName) {
+        await this.mcpClient.disconnect(serverName);
+    }
+    async disconnectAll() {
+        await this.mcpClient.disconnectAll();
+    }
+    /**
+     * Connect to an MCP server and discover its tools using SDK
+     */
+    async connectAndDiscover(config) {
+        await this.connect(config);
+        return await this.listTools(config.serverName);
+    }
+    /**
+     * Discover tools from an MCP server and register them with the COM
+     */
+    async discoverAndRegister(config, ctx) {
+        const tools = await this.connectAndDiscover(config);
+        for (const mcpToolDef of tools) {
+            const tool = new MCPTool(this.mcpClient, config.serverName, mcpToolDef, {
+                serverUrl: config.connection.url,
+                serverName: config.serverName,
+                transport: config.transport,
+            });
+            await ctx.addTool(tool);
+        }
+    }
+    async listTools(serverName) {
+        return await this.mcpClient.listTools(serverName);
+    }
+    /**
+     * Register a single MCP tool (useful for manual registration)
+     */
+    async registerMCPTool(config, mcpToolDef, ctx) {
+        const tool = new MCPTool(this.mcpClient, config.serverName, mcpToolDef, {
+            serverUrl: config.connection.url,
+            serverName: config.serverName,
+            transport: config.transport,
+        });
+        await ctx.addTool(tool);
+    }
+    /**
+     * Disconnect from an MCP server and remove its tools.
+     * Finds tools belonging to this server by checking metadata.mcpConfig.serverName.
+     */
+    async disconnectAndUnregister(serverName, ctx) {
+        // Find all tools that belong to this MCP server
+        const allTools = ctx.getTools();
+        const toolsToRemove = allTools
+            .filter((tool) => tool.metadata.mcpConfig?.serverName === serverName)
+            .map((tool) => tool.metadata.name);
+        // Remove each tool from the COM
+        for (const toolName of toolsToRemove) {
+            ctx.removeTool(toolName);
+        }
+        await this.disconnect(serverName);
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/mcp/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/mcp/service.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAIjC;;GAEG;AACH,MAAM,OAAO,UAAU;IACD;IAApB,YAAoB,SAAoB;QAApB,cAAS,GAAT,SAAS,CAAW;IAAG,CAAC;IAE5C,KAAK,CAAC,OAAO,CAAC,MAAiB;QAC7B,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9C,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,UAAkB;QACjC,MAAM,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;IAC9C,CAAC;IAED,KAAK,CAAC,aAAa;QACjB,MAAM,IAAI,CAAC,SAAS,CAAC,aAAa,EAAE,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,kBAAkB,CAAC,MAAiB;QACxC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAE3B,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IACjD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,mBAAmB,CAAC,MAAiB,EAAE,GAAQ;QACnD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAEpD,KAAK,MAAM,UAAU,IAAI,KAAK,EAAE,CAAC;YAC/B,MAAM,IAAI,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,UAAU,EAAE,UAAU,EAAE;gBACtE,SAAS,EAAE,MAAM,CAAC,UAAU,CAAC,GAAG;gBAChC,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,SAAS,EAAE,MAAM,CAAC,SAAS;aAC5B,CAAC,CAAC;YAEH,MAAM,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,UAAkB;QAChC,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IACpD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,eAAe,CAAC,MAAiB,EAAE,UAA6B,EAAE,GAAQ;QAC9E,MAAM,IAAI,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,UAAU,EAAE,UAAU,EAAE;YACtE,SAAS,EAAE,MAAM,CAAC,UAAU,CAAC,GAAG;YAChC,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,SAAS,EAAE,MAAM,CAAC,SAAS;SAC5B,CAAC,CAAC;QAEH,MAAM,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,uBAAuB,CAAC,UAAkB,EAAE,GAAQ;QACxD,gDAAgD;QAChD,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;QAChC,MAAM,aAAa,GAAG,QAAQ;aAC3B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,UAAU,KAAK,UAAU,CAAC;aACpE,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAErC,gCAAgC;QAChC,KAAK,MAAM,QAAQ,IAAI,aAAa,EAAE,CAAC;YACrC,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QAC3B,CAAC;QAED,MAAM,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;IACpC,CAAC;CACF"}

package/dist/mcp/tool.d.ts

@@ -0,0 +1,55 @@
+/**
+ * MCP Tool
+ *
+ * Wraps an MCP server tool as an ExecutableTool.
+ * The tool forwards execution to the MCP server via MCPClient.
+ */
+import { type ToolMetadata, type ExecutableTool, type ToolHandler } from "../tool/tool";
+import type { ContentBlock } from "@agentick/shared";
+import type { MCPClient } from "./client";
+import type { MCPToolDefinition } from "./types";
+import { z } from "zod";
+import type { Procedure } from "@agentick/kernel";
+/**
+ * Converts MCP JSON Schema to Zod schema.
+ * Basic conversion - supports common types.
+ */
+export declare function mcpSchemaToZod(schema: MCPToolDefinition["inputSchema"]): z.ZodSchema;
+/**
+ * Normalize MCP tool result to ContentBlock[].
+ */
+export declare function normalizeResult(result: any): ContentBlock[];
+/**
+ * MCP tool configuration stored in metadata.mcpConfig.
+ */
+export interface MCPToolConfig {
+    serverUrl?: string;
+    serverName?: string;
+    transport?: "stdio" | "sse" | "websocket";
+    [key: string]: any;
+}
+/**
+ * MCPTool wraps an MCP server tool as an ExecutableTool.
+ *
+ * This class is used internally by MCP creation functions.
+ * For most use cases, prefer `createMCPTool()` or `discoverMCPTools()`.
+ *
+ * @example Direct usage (advanced)
+ * ```typescript
+ * const tool = new MCPTool(mcpClient, 'server-name', toolDefinition, mcpConfig);
+ *
+ * // Register with COM
+ * ctx.addTool(tool);
+ *
+ * // Or execute directly
+ * const result = await tool.run({ path: '/file.txt' });
+ * ```
+ */
+export declare class MCPTool<THandler extends ToolHandler = ToolHandler> implements ExecutableTool<THandler> {
+    private mcpClient;
+    private serverName;
+    readonly metadata: ToolMetadata<Parameters<THandler>[0]>;
+    readonly run: Procedure<THandler>;
+    constructor(mcpClient: MCPClient, serverName: string, mcpToolDefinition: MCPToolDefinition, mcpConfig?: MCPToolConfig);
+}
+//# sourceMappingURL=tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/mcp/tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,WAAW,EAEjB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAOlD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,iBAAiB,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,SAAS,CAyCpF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,GAAG,GAAG,YAAY,EAAE,CAa3D;AAMD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,WAAW,CAAC;IAC1C,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,OAAO,CAClB,QAAQ,SAAS,WAAW,GAAG,WAAW,CAC1C,YAAW,cAAc,CAAC,QAAQ,CAAC;IAKjC,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,UAAU;IALpB,SAAgB,QAAQ,EAAE,YAAY,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChE,SAAgB,GAAG,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;gBAG/B,SAAS,EAAE,SAAS,EACpB,UAAU,EAAE,MAAM,EAC1B,iBAAiB,EAAE,iBAAiB,EACpC,SAAS,CAAC,EAAE,aAAa;CAoC5B"}

package/dist/mcp/tool.js

@@ -0,0 +1,119 @@
+/**
+ * MCP Tool
+ *
+ * Wraps an MCP server tool as an ExecutableTool.
+ * The tool forwards execution to the MCP server via MCPClient.
+ */
+import { ToolExecutionType, } from "../tool/tool";
+import { z } from "zod";
+import { createEngineProcedure } from "../procedure";
+// ============================================================================
+// Schema Conversion
+// ============================================================================
+/**
+ * Converts MCP JSON Schema to Zod schema.
+ * Basic conversion - supports common types.
+ */
+export function mcpSchemaToZod(schema) {
+    const properties = schema.properties || {};
+    const required = schema.required || [];
+    const shape = {};
+    for (const [key, prop] of Object.entries(properties)) {
+        let zType;
+        switch (prop.type) {
+            case "string":
+                zType = z.string();
+                break;
+            case "number":
+            case "integer":
+                zType = z.number();
+                break;
+            case "boolean":
+                zType = z.boolean();
+                break;
+            case "array":
+                zType = z.array(z.any());
+                break;
+            case "object":
+                zType = z.record(z.string(), z.any());
+                break;
+            default:
+                zType = z.any();
+        }
+        if (prop.description) {
+            zType = zType.describe(prop.description);
+        }
+        if (!required.includes(key)) {
+            zType = zType.optional();
+        }
+        shape[key] = zType;
+    }
+    return z.object(shape);
+}
+/**
+ * Normalize MCP tool result to ContentBlock[].
+ */
+export function normalizeResult(result) {
+    if (typeof result === "string") {
+        return [{ type: "text", text: result }];
+    }
+    if (result && typeof result === "object") {
+        if (Array.isArray(result.content)) {
+            return result.content;
+        }
+        return [{ type: "text", text: JSON.stringify(result, null, 2) }];
+    }
+    return [{ type: "text", text: String(result) }];
+}
+/**
+ * MCPTool wraps an MCP server tool as an ExecutableTool.
+ *
+ * This class is used internally by MCP creation functions.
+ * For most use cases, prefer `createMCPTool()` or `discoverMCPTools()`.
+ *
+ * @example Direct usage (advanced)
+ * ```typescript
+ * const tool = new MCPTool(mcpClient, 'server-name', toolDefinition, mcpConfig);
+ *
+ * // Register with COM
+ * ctx.addTool(tool);
+ *
+ * // Or execute directly
+ * const result = await tool.run({ path: '/file.txt' });
+ * ```
+ */
+export class MCPTool {
+    mcpClient;
+    serverName;
+    metadata;
+    run;
+    constructor(mcpClient, serverName, mcpToolDefinition, mcpConfig) {
+        this.mcpClient = mcpClient;
+        this.serverName = serverName;
+        // Convert MCP schema to Zod
+        const zodSchema = mcpSchemaToZod(mcpToolDefinition.inputSchema);
+        // Build metadata
+        this.metadata = {
+            name: mcpToolDefinition.name,
+            description: mcpToolDefinition.description,
+            input: zodSchema,
+            type: ToolExecutionType.MCP,
+            mcpConfig: mcpConfig,
+        };
+        // Create procedure that forwards to MCP server
+        this.run = createEngineProcedure({
+            name: "tool:run", // Low cardinality span name (same as regular tools)
+            metadata: {
+                type: "mcp",
+                toolName: mcpToolDefinition.name,
+                id: mcpToolDefinition.name,
+                operation: "run",
+                server: this.serverName,
+            },
+        }, (async (input) => {
+            const result = await this.mcpClient.callTool(this.serverName, mcpToolDefinition.name, input);
+            return normalizeResult(result);
+        }));
+    }
+}
+//# sourceMappingURL=tool.js.map

package/dist/mcp/tool.js.map

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