@compilr-dev/agents 0.0.1

package/dist/mcp/client.js

@@ -0,0 +1,287 @@
+/**
+ * MCP Client - Connects to MCP servers and discovers tools
+ *
+ * Uses the official @modelcontextprotocol/sdk as an optional peer dependency.
+ * If the SDK is not installed, attempting to use MCP features will throw
+ * a helpful error with installation instructions.
+ */
+import { MCPError, MCPErrorCode, createSDKNotInstalledError } from './errors.js';
+/**
+ * Cached SDK imports
+ * Using loose constructor types to accommodate SDK version changes
+ */
+let sdkCache = null;
+/**
+ * Dynamically load the MCP SDK
+ * @throws MCPError if SDK is not installed
+ */
+async function getMCPSDK() {
+    if (sdkCache)
+        return sdkCache;
+    try {
+        // Dynamic imports to keep SDK optional
+        const [clientModule, stdioModule, httpModule] = await Promise.all([
+            import('@modelcontextprotocol/sdk/client/index.js'),
+            import('@modelcontextprotocol/sdk/client/stdio.js'),
+            import('@modelcontextprotocol/sdk/client/streamableHttp.js'),
+        ]);
+        sdkCache = {
+            Client: clientModule.Client,
+            StdioClientTransport: stdioModule.StdioClientTransport,
+            StreamableHTTPClientTransport: httpModule.StreamableHTTPClientTransport,
+        };
+        // Non-null assertion safe: we just assigned sdkCache above
+        return sdkCache;
+    }
+    catch (error) {
+        // Check if it's a module not found error
+        if (error instanceof Error &&
+            (error.message.includes('Cannot find module') ||
+                error.message.includes('ERR_MODULE_NOT_FOUND'))) {
+            throw createSDKNotInstalledError();
+        }
+        throw error;
+    }
+}
+/**
+ * MCP Client for connecting to a single MCP server
+ *
+ * @example
+ * ```typescript
+ * const client = new MCPClient({
+ *   name: 'filesystem',
+ *   transport: 'stdio',
+ *   stdio: {
+ *     command: 'npx',
+ *     args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
+ *   },
+ * });
+ *
+ * await client.connect();
+ * const tools = await client.listTools();
+ * const result = await client.callTool('read_file', { path: '/tmp/test.txt' });
+ * await client.disconnect();
+ * ```
+ */
+export class MCPClient {
+    name;
+    config;
+    client = null;
+    transport = null;
+    _status = 'disconnected';
+    eventHandlers = new Set();
+    cachedTools = null;
+    constructor(config) {
+        this.name = config.name;
+        this.config = config;
+        // Validate config
+        if (config.transport === 'stdio' && !config.stdio) {
+            throw new MCPError(`MCP server '${config.name}': stdio transport requires 'stdio' options`, config.name, MCPErrorCode.INVALID_CONFIG);
+        }
+        if (config.transport === 'http' && !config.http) {
+            throw new MCPError(`MCP server '${config.name}': http transport requires 'http' options`, config.name, MCPErrorCode.INVALID_CONFIG);
+        }
+    }
+    /**
+     * Current connection status
+     */
+    get status() {
+        return this._status;
+    }
+    /**
+     * Whether the client is connected
+     */
+    get isConnected() {
+        return this._status === 'connected';
+    }
+    /**
+     * Connect to the MCP server
+     * @throws MCPError if connection fails
+     */
+    async connect() {
+        if (this._status === 'connected') {
+            return; // Already connected
+        }
+        this._status = 'connecting';
+        try {
+            const sdk = await getMCPSDK();
+            // Create transport based on config
+            if (this.config.transport === 'stdio' && this.config.stdio) {
+                this.transport = new sdk.StdioClientTransport({
+                    command: this.config.stdio.command,
+                    args: this.config.stdio.args,
+                    env: this.config.stdio.env,
+                    cwd: this.config.stdio.cwd,
+                });
+            }
+            else if (this.config.transport === 'http' && this.config.http) {
+                this.transport = new sdk.StreamableHTTPClientTransport(new URL(this.config.http.url));
+            }
+            // Create client
+            this.client = new sdk.Client({
+                name: this.config.clientName ?? '@compilr-dev/agents',
+                version: this.config.clientVersion ?? '1.0.0',
+            });
+            // Set up notification handler for tools changed
+            this.client.setNotificationHandler('notifications/tools/list_changed', () => {
+                this.cachedTools = null; // Invalidate cache
+                this.emit({ type: 'tools_changed', serverName: this.name });
+            });
+            // Connect with timeout
+            const timeoutMs = this.config.timeout ?? 30000;
+            const connectPromise = this.client.connect(this.transport);
+            const timeoutPromise = new Promise((_, reject) => {
+                setTimeout(() => {
+                    reject(new MCPError(`Connection to '${this.name}' timed out after ${String(timeoutMs)}ms`, this.name, MCPErrorCode.TIMEOUT));
+                }, timeoutMs);
+            });
+            await Promise.race([connectPromise, timeoutPromise]);
+            this._status = 'connected';
+            this.emit({ type: 'connected', serverName: this.name });
+        }
+        catch (error) {
+            this._status = 'error';
+            if (error instanceof MCPError) {
+                this.emit({ type: 'error', serverName: this.name, error });
+                throw error;
+            }
+            const mcpError = new MCPError(`Failed to connect to MCP server '${this.name}': ${error instanceof Error ? error.message : String(error)}`, this.name, MCPErrorCode.CONNECTION_FAILED, error instanceof Error ? error : undefined);
+            this.emit({ type: 'error', serverName: this.name, error: mcpError });
+            throw mcpError;
+        }
+    }
+    /**
+     * Disconnect from the MCP server
+     */
+    async disconnect() {
+        if (this._status === 'disconnected') {
+            return;
+        }
+        try {
+            if (this.client) {
+                await this.client.close();
+            }
+        }
+        catch {
+            // Ignore disconnect errors
+        }
+        finally {
+            this.client = null;
+            this.transport = null;
+            this.cachedTools = null;
+            this._status = 'disconnected';
+            this.emit({ type: 'disconnected', serverName: this.name });
+        }
+    }
+    /**
+     * List available tools from the server
+     * @throws MCPError if not connected or listing fails
+     */
+    async listTools() {
+        const client = this.getConnectedClient();
+        // Return cached tools if available
+        if (this.cachedTools) {
+            return this.cachedTools;
+        }
+        try {
+            const result = await client.listTools();
+            this.cachedTools = result.tools;
+            return result.tools;
+        }
+        catch (error) {
+            throw new MCPError(`Failed to list tools from '${this.name}': ${error instanceof Error ? error.message : String(error)}`, this.name, MCPErrorCode.TRANSPORT_ERROR, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Call a tool on the server
+     * @param toolName Name of the tool to call
+     * @param args Arguments to pass to the tool
+     * @throws MCPError if not connected, tool not found, or execution fails
+     */
+    async callTool(toolName, args) {
+        const client = this.getConnectedClient();
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+            const result = await client.callTool({
+                name: toolName,
+                arguments: args,
+            });
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+            return result;
+        }
+        catch (error) {
+            // Check if it's a tool not found error
+            const message = error instanceof Error ? error.message : String(error);
+            if (message.includes('not found') || message.includes('unknown tool')) {
+                throw new MCPError(`Tool '${toolName}' not found on server '${this.name}'`, this.name, MCPErrorCode.TOOL_NOT_FOUND, error instanceof Error ? error : undefined);
+            }
+            throw new MCPError(`Failed to call tool '${toolName}' on '${this.name}': ${message}`, this.name, MCPErrorCode.TOOL_EXECUTION_FAILED, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Register an event handler
+     */
+    onEvent(handler) {
+        this.eventHandlers.add(handler);
+        return () => this.eventHandlers.delete(handler);
+    }
+    /**
+     * Convenience method to listen for tools changed events
+     */
+    onToolsChanged(callback) {
+        return this.onEvent((event) => {
+            if (event.type === 'tools_changed') {
+                // Fetch new tools and call callback
+                this.listTools()
+                    .then(callback)
+                    .catch(() => {
+                    /* ignore errors in callback */
+                });
+            }
+        });
+    }
+    /**
+     * Convenience method to listen for errors
+     */
+    onError(callback) {
+        return this.onEvent((event) => {
+            if (event.type === 'error' && event.error) {
+                callback(event.error);
+            }
+        });
+    }
+    /**
+     * Convenience method to listen for disconnect
+     */
+    onDisconnect(callback) {
+        return this.onEvent((event) => {
+            if (event.type === 'disconnected') {
+                callback();
+            }
+        });
+    }
+    /**
+     * Emit an event to all handlers
+     */
+    emit(event) {
+        for (const handler of this.eventHandlers) {
+            try {
+                handler(event);
+            }
+            catch {
+                // Ignore handler errors
+            }
+        }
+    }
+    /**
+     * Get the connected client, throwing if not connected
+     * @throws MCPError if not connected
+     * @returns The connected SDK client
+     */
+    getConnectedClient() {
+        if (!this.client || this._status !== 'connected') {
+            throw new MCPError(`MCP client '${this.name}' is not connected`, this.name, MCPErrorCode.CONNECTION_FAILED);
+        }
+        return this.client;
+    }
+}

package/dist/mcp/errors.d.ts

@@ -0,0 +1,60 @@
+/**
+ * MCP-specific error classes
+ */
+import { AgentError } from '../errors.js';
+/**
+ * Error codes for MCP operations
+ */
+export declare enum MCPErrorCode {
+    /** MCP SDK is not installed */
+    SDK_NOT_INSTALLED = "SDK_NOT_INSTALLED",
+    /** Failed to connect to MCP server */
+    CONNECTION_FAILED = "CONNECTION_FAILED",
+    /** Server not found in manager */
+    SERVER_NOT_FOUND = "SERVER_NOT_FOUND",
+    /** Tool not found on server */
+    TOOL_NOT_FOUND = "TOOL_NOT_FOUND",
+    /** Tool execution failed */
+    TOOL_EXECUTION_FAILED = "TOOL_EXECUTION_FAILED",
+    /** Transport error (stdio/http) */
+    TRANSPORT_ERROR = "TRANSPORT_ERROR",
+    /** Connection or operation timeout */
+    TIMEOUT = "TIMEOUT",
+    /** Invalid server configuration */
+    INVALID_CONFIG = "INVALID_CONFIG",
+    /** Server already exists */
+    SERVER_EXISTS = "SERVER_EXISTS"
+}
+/**
+ * Error thrown for MCP-related failures
+ *
+ * @example
+ * ```typescript
+ * throw new MCPError(
+ *   'Failed to connect to server',
+ *   'filesystem',
+ *   MCPErrorCode.CONNECTION_FAILED
+ * );
+ * ```
+ */
+export declare class MCPError extends AgentError {
+    readonly serverName: string;
+    readonly code: MCPErrorCode;
+    constructor(message: string, serverName: string, code: MCPErrorCode, cause?: Error);
+    /**
+     * Check if the error is due to missing SDK
+     */
+    isSDKNotInstalled(): boolean;
+    /**
+     * Check if the error is retryable (connection/timeout issues)
+     */
+    isRetryable(): boolean;
+}
+/**
+ * Type guard to check if an error is an MCPError
+ */
+export declare function isMCPError(error: unknown): error is MCPError;
+/**
+ * Create an SDK not installed error with helpful message
+ */
+export declare function createSDKNotInstalledError(): MCPError;

package/dist/mcp/errors.js

@@ -0,0 +1,78 @@
+/**
+ * MCP-specific error classes
+ */
+import { AgentError } from '../errors.js';
+/**
+ * Error codes for MCP operations
+ */
+export var MCPErrorCode;
+(function (MCPErrorCode) {
+    /** MCP SDK is not installed */
+    MCPErrorCode["SDK_NOT_INSTALLED"] = "SDK_NOT_INSTALLED";
+    /** Failed to connect to MCP server */
+    MCPErrorCode["CONNECTION_FAILED"] = "CONNECTION_FAILED";
+    /** Server not found in manager */
+    MCPErrorCode["SERVER_NOT_FOUND"] = "SERVER_NOT_FOUND";
+    /** Tool not found on server */
+    MCPErrorCode["TOOL_NOT_FOUND"] = "TOOL_NOT_FOUND";
+    /** Tool execution failed */
+    MCPErrorCode["TOOL_EXECUTION_FAILED"] = "TOOL_EXECUTION_FAILED";
+    /** Transport error (stdio/http) */
+    MCPErrorCode["TRANSPORT_ERROR"] = "TRANSPORT_ERROR";
+    /** Connection or operation timeout */
+    MCPErrorCode["TIMEOUT"] = "TIMEOUT";
+    /** Invalid server configuration */
+    MCPErrorCode["INVALID_CONFIG"] = "INVALID_CONFIG";
+    /** Server already exists */
+    MCPErrorCode["SERVER_EXISTS"] = "SERVER_EXISTS";
+})(MCPErrorCode || (MCPErrorCode = {}));
+/**
+ * Error thrown for MCP-related failures
+ *
+ * @example
+ * ```typescript
+ * throw new MCPError(
+ *   'Failed to connect to server',
+ *   'filesystem',
+ *   MCPErrorCode.CONNECTION_FAILED
+ * );
+ * ```
+ */
+export class MCPError extends AgentError {
+    serverName;
+    code;
+    constructor(message, serverName, code, cause) {
+        super(message, cause);
+        this.serverName = serverName;
+        this.code = code;
+        this.name = 'MCPError';
+    }
+    /**
+     * Check if the error is due to missing SDK
+     */
+    isSDKNotInstalled() {
+        return this.code === MCPErrorCode.SDK_NOT_INSTALLED;
+    }
+    /**
+     * Check if the error is retryable (connection/timeout issues)
+     */
+    isRetryable() {
+        return (this.code === MCPErrorCode.CONNECTION_FAILED ||
+            this.code === MCPErrorCode.TIMEOUT ||
+            this.code === MCPErrorCode.TRANSPORT_ERROR);
+    }
+}
+/**
+ * Type guard to check if an error is an MCPError
+ */
+export function isMCPError(error) {
+    return error instanceof MCPError;
+}
+/**
+ * Create an SDK not installed error with helpful message
+ */
+export function createSDKNotInstalledError() {
+    return new MCPError('MCP SDK is not installed. To use MCP features, install the SDK:\n\n' +
+        '  npm install @modelcontextprotocol/sdk\n\n' +
+        'The SDK is an optional peer dependency - only install if you need MCP support.', '', MCPErrorCode.SDK_NOT_INSTALLED);
+}

package/dist/mcp/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * MCP (Model Context Protocol) Support
+ *
+ * This module provides integration with MCP servers, allowing agents to
+ * use tools provided by MCP-compliant servers.
+ *
+ * IMPORTANT: The MCP SDK (@modelcontextprotocol/sdk) is an optional peer dependency.
+ * If you want to use MCP features, install it:
+ *
+ *   npm install @modelcontextprotocol/sdk
+ *
+ * @example
+ * ```typescript
+ * import { MCPManager, MCPClient } from '@compilr-dev/agents';
+ *
+ * // Using MCPManager (recommended for multiple servers)
+ * const manager = new MCPManager();
+ * await manager.addServer({
+ *   name: 'filesystem',
+ *   transport: 'stdio',
+ *   command: 'npx',
+ *   args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
+ * });
+ *
+ * const tools = await manager.discoverTools();
+ *
+ * // Using MCPClient directly (for single server)
+ * const client = new MCPClient({
+ *   name: 'filesystem',
+ *   transport: 'stdio',
+ *   stdio: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'] },
+ * });
+ * await client.connect();
+ * const mcpTools = await client.listTools();
+ * ```
+ */
+export { MCPClient } from './client.js';
+export { MCPManager } from './manager.js';
+export { mcpToolToTool, mcpToolsToTools, convertMCPResult, contentBlocksToString, generateToolName, } from './tools.js';
+export type { MCPToolConversionOptions } from './tools.js';
+export type { MCPTransport, MCPConnectionStatus, MCPStdioOptions, MCPHttpOptions, MCPClientConfig, MCPServerConfig, MCPToolDefinition, MCPContentBlock, MCPToolResult, MCPClientEventType, MCPClientEvent, MCPClientEventHandler, MCPManagerOptions, } from './types.js';
+export { normalizeServerConfig } from './types.js';
+export { MCPError, MCPErrorCode, isMCPError, createSDKNotInstalledError } from './errors.js';

package/dist/mcp/index.js

@@ -0,0 +1,45 @@
+/**
+ * MCP (Model Context Protocol) Support
+ *
+ * This module provides integration with MCP servers, allowing agents to
+ * use tools provided by MCP-compliant servers.
+ *
+ * IMPORTANT: The MCP SDK (@modelcontextprotocol/sdk) is an optional peer dependency.
+ * If you want to use MCP features, install it:
+ *
+ *   npm install @modelcontextprotocol/sdk
+ *
+ * @example
+ * ```typescript
+ * import { MCPManager, MCPClient } from '@compilr-dev/agents';
+ *
+ * // Using MCPManager (recommended for multiple servers)
+ * const manager = new MCPManager();
+ * await manager.addServer({
+ *   name: 'filesystem',
+ *   transport: 'stdio',
+ *   command: 'npx',
+ *   args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
+ * });
+ *
+ * const tools = await manager.discoverTools();
+ *
+ * // Using MCPClient directly (for single server)
+ * const client = new MCPClient({
+ *   name: 'filesystem',
+ *   transport: 'stdio',
+ *   stdio: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'] },
+ * });
+ * await client.connect();
+ * const mcpTools = await client.listTools();
+ * ```
+ */
+// Client
+export { MCPClient } from './client.js';
+// Manager
+export { MCPManager } from './manager.js';
+// Tool conversion utilities
+export { mcpToolToTool, mcpToolsToTools, convertMCPResult, contentBlocksToString, generateToolName, } from './tools.js';
+export { normalizeServerConfig } from './types.js';
+// Errors
+export { MCPError, MCPErrorCode, isMCPError, createSDKNotInstalledError } from './errors.js';

package/dist/mcp/manager.d.ts

@@ -0,0 +1,120 @@
+/**
+ * MCP Manager - Manages multiple MCP server connections
+ *
+ * Provides a high-level interface for:
+ * - Managing multiple MCP servers
+ * - Discovering and registering tools from servers
+ * - Handling server lifecycle (connect, disconnect, reconnect)
+ */
+import type { Tool } from '../tools/index.js';
+import { DefaultToolRegistry } from '../tools/index.js';
+import { MCPClient } from './client.js';
+import type { MCPServerConfig, MCPManagerOptions, MCPClientEventHandler } from './types.js';
+/**
+ * MCP Manager for managing multiple MCP server connections
+ *
+ * @example
+ * ```typescript
+ * const manager = new MCPManager();
+ *
+ * // Add servers
+ * await manager.addServer({
+ *   name: 'filesystem',
+ *   transport: 'stdio',
+ *   command: 'npx',
+ *   args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
+ * });
+ *
+ * // Discover and get tools
+ * const tools = await manager.discoverTools();
+ *
+ * // Use with agent
+ * const agent = new Agent({
+ *   provider: claude,
+ *   tools: [...builtinTools, ...tools],
+ * });
+ *
+ * // Cleanup
+ * await manager.disconnectAll();
+ * ```
+ */
+export declare class MCPManager {
+    private readonly clients;
+    private toolRegistry;
+    private readonly toolPrefix;
+    private readonly autoConnect;
+    private readonly eventHandlers;
+    constructor(options?: MCPManagerOptions);
+    /**
+     * Set a tool registry for automatic tool registration
+     * When set, tools from MCP servers will be automatically registered
+     */
+    setToolRegistry(registry: DefaultToolRegistry): void;
+    /**
+     * Add an MCP server
+     *
+     * @param config Server configuration
+     * @returns The created MCPClient
+     * @throws MCPError if server with same name already exists
+     */
+    addServer(config: MCPServerConfig): Promise<MCPClient>;
+    /**
+     * Remove an MCP server
+     *
+     * @param name Server name
+     * @throws MCPError if server not found
+     */
+    removeServer(name: string): Promise<void>;
+    /**
+     * Get an MCP client by name
+     */
+    getServer(name: string): MCPClient | undefined;
+    /**
+     * Get all MCP clients
+     */
+    getServers(): MCPClient[];
+    /**
+     * Get all server names
+     */
+    getServerNames(): string[];
+    /**
+     * Check if a server exists
+     */
+    hasServer(name: string): boolean;
+    /**
+     * Discover tools from all connected servers
+     *
+     * @returns Array of converted tools ready for registration
+     */
+    discoverTools(): Promise<Tool[]>;
+    /**
+     * Discover tools from a specific server
+     */
+    discoverToolsFrom(serverName: string): Promise<Tool[]>;
+    /**
+     * Refresh tools from servers and update the tool registry
+     *
+     * @param serverName Optional server name to refresh. If not provided, refreshes all.
+     */
+    refreshTools(serverName?: string): Promise<void>;
+    /**
+     * Get raw MCP tool definitions from a server
+     */
+    private getMCPTools;
+    /**
+     * Connect all servers
+     */
+    connectAll(): Promise<void>;
+    /**
+     * Disconnect all servers
+     */
+    disconnectAll(): Promise<void>;
+    /**
+     * Register an event handler
+     */
+    onEvent(handler: MCPClientEventHandler): () => void;
+    /**
+     * Emit an event to all handlers
+     */
+    private emit;
+}