@compilr-dev/agents 0.0.1

package/dist/mcp/manager.js

@@ -0,0 +1,276 @@
+/**
+ * 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 { MCPClient } from './client.js';
+import { normalizeServerConfig } from './types.js';
+import { MCPError, MCPErrorCode } from './errors.js';
+import { mcpToolsToTools } from './tools.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 class MCPManager {
+    clients = new Map();
+    toolRegistry = null;
+    toolPrefix;
+    autoConnect;
+    eventHandlers = new Set();
+    constructor(options = {}) {
+        this.toolPrefix = options.toolPrefix ?? 'mcp';
+        this.autoConnect = options.autoConnect ?? true;
+        if (options.onEvent) {
+            this.eventHandlers.add(options.onEvent);
+        }
+    }
+    /**
+     * Set a tool registry for automatic tool registration
+     * When set, tools from MCP servers will be automatically registered
+     */
+    setToolRegistry(registry) {
+        this.toolRegistry = registry;
+    }
+    /**
+     * Add an MCP server
+     *
+     * @param config Server configuration
+     * @returns The created MCPClient
+     * @throws MCPError if server with same name already exists
+     */
+    async addServer(config) {
+        if (this.clients.has(config.name)) {
+            throw new MCPError(`MCP server '${config.name}' already exists`, config.name, MCPErrorCode.SERVER_EXISTS);
+        }
+        // Normalize shorthand config to full config
+        const fullConfig = normalizeServerConfig(config);
+        // Create client
+        const client = new MCPClient(fullConfig);
+        // Forward events
+        client.onEvent((event) => {
+            this.emit(event);
+        });
+        // Store client
+        this.clients.set(config.name, client);
+        // Auto-connect if enabled
+        if (this.autoConnect) {
+            await client.connect();
+            // Auto-register tools if registry is set
+            if (this.toolRegistry) {
+                await this.refreshTools(config.name);
+            }
+        }
+        return client;
+    }
+    /**
+     * Remove an MCP server
+     *
+     * @param name Server name
+     * @throws MCPError if server not found
+     */
+    async removeServer(name) {
+        const client = this.clients.get(name);
+        if (!client) {
+            throw new MCPError(`MCP server '${name}' not found`, name, MCPErrorCode.SERVER_NOT_FOUND);
+        }
+        // Disconnect if connected
+        await client.disconnect();
+        // Remove from registry
+        this.clients.delete(name);
+        // Remove tools from tool registry
+        const registry = this.toolRegistry;
+        if (registry) {
+            const prefix = `${this.toolPrefix}_${name}_`;
+            const toolNamesToRemove = registry
+                .getNames()
+                .filter((toolName) => toolName.startsWith(prefix));
+            for (const toolName of toolNamesToRemove) {
+                registry.unregister(toolName);
+            }
+        }
+    }
+    /**
+     * Get an MCP client by name
+     */
+    getServer(name) {
+        return this.clients.get(name);
+    }
+    /**
+     * Get all MCP clients
+     */
+    getServers() {
+        return Array.from(this.clients.values());
+    }
+    /**
+     * Get all server names
+     */
+    getServerNames() {
+        return Array.from(this.clients.keys());
+    }
+    /**
+     * Check if a server exists
+     */
+    hasServer(name) {
+        return this.clients.has(name);
+    }
+    /**
+     * Discover tools from all connected servers
+     *
+     * @returns Array of converted tools ready for registration
+     */
+    async discoverTools() {
+        const allTools = [];
+        for (const client of this.clients.values()) {
+            if (!client.isConnected)
+                continue;
+            try {
+                const mcpTools = await client.listTools();
+                const tools = mcpToolsToTools(mcpTools, client, { prefix: this.toolPrefix });
+                allTools.push(...tools);
+            }
+            catch (error) {
+                // Log but don't fail - other servers may still work
+                this.emit({
+                    type: 'error',
+                    serverName: client.name,
+                    error: error instanceof Error ? error : new Error(String(error)),
+                });
+            }
+        }
+        return allTools;
+    }
+    /**
+     * Discover tools from a specific server
+     */
+    async discoverToolsFrom(serverName) {
+        const client = this.clients.get(serverName);
+        if (!client) {
+            throw new MCPError(`MCP server '${serverName}' not found`, serverName, MCPErrorCode.SERVER_NOT_FOUND);
+        }
+        if (!client.isConnected) {
+            throw new MCPError(`MCP server '${serverName}' is not connected`, serverName, MCPErrorCode.CONNECTION_FAILED);
+        }
+        const mcpTools = await client.listTools();
+        return mcpToolsToTools(mcpTools, client, { prefix: this.toolPrefix });
+    }
+    /**
+     * Refresh tools from servers and update the tool registry
+     *
+     * @param serverName Optional server name to refresh. If not provided, refreshes all.
+     */
+    async refreshTools(serverName) {
+        const registry = this.toolRegistry;
+        if (!registry) {
+            return; // No registry to update
+        }
+        if (serverName) {
+            // Refresh single server
+            const tools = await this.discoverToolsFrom(serverName);
+            const prefix = `${this.toolPrefix}_${serverName}_`;
+            // Remove old tools from this server
+            const oldToolNames = registry.getNames().filter((toolName) => toolName.startsWith(prefix));
+            for (const toolName of oldToolNames) {
+                registry.unregister(toolName);
+            }
+            // Register new tools
+            for (const tool of tools) {
+                registry.register(tool);
+            }
+            this.emit({ type: 'tools_changed', serverName, tools: await this.getMCPTools(serverName) });
+        }
+        else {
+            // Refresh all servers
+            for (const name of this.clients.keys()) {
+                try {
+                    await this.refreshTools(name);
+                }
+                catch {
+                    // Continue with other servers
+                }
+            }
+        }
+    }
+    /**
+     * Get raw MCP tool definitions from a server
+     */
+    async getMCPTools(serverName) {
+        const client = this.clients.get(serverName);
+        if (!client || !client.isConnected)
+            return [];
+        return client.listTools();
+    }
+    /**
+     * Connect all servers
+     */
+    async connectAll() {
+        const promises = Array.from(this.clients.values()).map(async (client) => {
+            if (!client.isConnected) {
+                try {
+                    await client.connect();
+                }
+                catch (error) {
+                    this.emit({
+                        type: 'error',
+                        serverName: client.name,
+                        error: error instanceof Error ? error : new Error(String(error)),
+                    });
+                }
+            }
+        });
+        await Promise.all(promises);
+    }
+    /**
+     * Disconnect all servers
+     */
+    async disconnectAll() {
+        const promises = Array.from(this.clients.values()).map((client) => client.disconnect());
+        await Promise.all(promises);
+    }
+    /**
+     * Register an event handler
+     */
+    onEvent(handler) {
+        this.eventHandlers.add(handler);
+        return () => this.eventHandlers.delete(handler);
+    }
+    /**
+     * Emit an event to all handlers
+     */
+    emit(event) {
+        for (const handler of this.eventHandlers) {
+            try {
+                handler(event);
+            }
+            catch {
+                // Ignore handler errors
+            }
+        }
+    }
+}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,54 @@
+/**
+ * MCP Tool Conversion Utilities
+ *
+ * Converts MCP tools to the @compilr-dev/agents Tool format
+ */
+import type { Tool, ToolInputSchema } from '../tools/index.js';
+import { createSuccessResult } from '../tools/index.js';
+import type { MCPClient } from './client.js';
+import type { MCPToolDefinition, MCPToolResult, MCPContentBlock } from './types.js';
+/**
+ * Options for converting MCP tools
+ */
+export interface MCPToolConversionOptions {
+    /** Prefix for tool names (default: 'mcp') */
+    prefix?: string;
+    /** Whether to include server name in tool name (default: true) */
+    includeServerName?: boolean;
+}
+/**
+ * Convert MCP content blocks to a string result
+ */
+export declare function contentBlocksToString(blocks: MCPContentBlock[]): string;
+/**
+ * Convert an MCP tool result to our ToolExecutionResult format
+ */
+export declare function convertMCPResult(result: MCPToolResult): ReturnType<typeof createSuccessResult>;
+/**
+ * Convert MCP input schema to our ToolInputSchema format
+ */
+export declare function convertInputSchema(schema: MCPToolDefinition['inputSchema']): ToolInputSchema;
+/**
+ * Generate a unique tool name for an MCP tool
+ */
+export declare function generateToolName(serverName: string, toolName: string, options?: MCPToolConversionOptions): string;
+/**
+ * Convert a single MCP tool to our Tool format
+ *
+ * @param mcpTool The MCP tool definition from the server
+ * @param client The MCP client to use for calling the tool
+ * @param options Conversion options
+ * @returns A Tool that can be registered with the agent
+ *
+ * @example
+ * ```typescript
+ * const tools = await client.listTools();
+ * const convertedTools = tools.map(t => mcpToolToTool(t, client));
+ * agent.toolRegistry.registerTools(convertedTools);
+ * ```
+ */
+export declare function mcpToolToTool(mcpTool: MCPToolDefinition, client: MCPClient, options?: MCPToolConversionOptions): Tool;
+/**
+ * Convert multiple MCP tools to our Tool format
+ */
+export declare function mcpToolsToTools(mcpTools: MCPToolDefinition[], client: MCPClient, options?: MCPToolConversionOptions): Tool[];

package/dist/mcp/tools.js

@@ -0,0 +1,99 @@
+/**
+ * MCP Tool Conversion Utilities
+ *
+ * Converts MCP tools to the @compilr-dev/agents Tool format
+ */
+import { createSuccessResult, createErrorResult } from '../tools/index.js';
+/**
+ * Convert MCP content blocks to a string result
+ */
+export function contentBlocksToString(blocks) {
+    const parts = [];
+    for (const block of blocks) {
+        if (block.type === 'text' && block.text) {
+            parts.push(block.text);
+        }
+        else if (block.type === 'image') {
+            // For images, return a placeholder with the mime type
+            parts.push(`[Image: ${block.mimeType ?? 'unknown type'}]`);
+        }
+        else if (block.type === 'resource' && block.uri) {
+            parts.push(`[Resource: ${block.uri}]`);
+        }
+    }
+    return parts.join('\n');
+}
+/**
+ * Convert an MCP tool result to our ToolExecutionResult format
+ */
+export function convertMCPResult(result) {
+    const content = contentBlocksToString(result.content);
+    if (result.isError) {
+        return createErrorResult(content || 'Tool execution failed');
+    }
+    return createSuccessResult(content || 'Success');
+}
+/**
+ * Convert MCP input schema to our ToolInputSchema format
+ */
+export function convertInputSchema(schema) {
+    // MCP schemas are already JSON Schema compliant
+    // We just need to ensure the structure matches our type
+    return {
+        type: 'object',
+        properties: schema.properties ?? {},
+        required: schema.required,
+    };
+}
+/**
+ * Generate a unique tool name for an MCP tool
+ */
+export function generateToolName(serverName, toolName, options = {}) {
+    const prefix = options.prefix ?? 'mcp';
+    const includeServer = options.includeServerName ?? true;
+    if (includeServer) {
+        return `${prefix}_${serverName}_${toolName}`;
+    }
+    return `${prefix}_${toolName}`;
+}
+/**
+ * Convert a single MCP tool to our Tool format
+ *
+ * @param mcpTool The MCP tool definition from the server
+ * @param client The MCP client to use for calling the tool
+ * @param options Conversion options
+ * @returns A Tool that can be registered with the agent
+ *
+ * @example
+ * ```typescript
+ * const tools = await client.listTools();
+ * const convertedTools = tools.map(t => mcpToolToTool(t, client));
+ * agent.toolRegistry.registerTools(convertedTools);
+ * ```
+ */
+export function mcpToolToTool(mcpTool, client, options = {}) {
+    const toolName = generateToolName(client.name, mcpTool.name, options);
+    const definition = {
+        name: toolName,
+        description: mcpTool.description ?? `MCP tool '${mcpTool.name}' from server '${client.name}'`,
+        inputSchema: convertInputSchema(mcpTool.inputSchema),
+    };
+    return {
+        definition,
+        execute: async (input) => {
+            try {
+                const result = await client.callTool(mcpTool.name, input);
+                return convertMCPResult(result);
+            }
+            catch (error) {
+                return createErrorResult(error instanceof Error ? error.message : String(error));
+            }
+        },
+    };
+}
+/**
+ * Convert multiple MCP tools to our Tool format
+ */
+export function mcpToolsToTools(mcpTools, client, options = {}) {
+    return mcpTools.map((tool) => mcpToolToTool(tool, client, options));
+}

package/dist/mcp/types.d.ts

@@ -0,0 +1,150 @@
+/**
+ * MCP (Model Context Protocol) types and interfaces
+ *
+ * MCP is an open protocol by Anthropic that standardizes how AI applications
+ * connect to external tools and data sources.
+ *
+ * @see https://modelcontextprotocol.io/specification/2024-11-05/
+ */
+/**
+ * Transport type for MCP server connection
+ */
+export type MCPTransport = 'stdio' | 'http';
+/**
+ * Connection status of an MCP client
+ */
+export type MCPConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+/**
+ * Options for connecting to an MCP server via stdio transport
+ */
+export interface MCPStdioOptions {
+    /** Command to spawn (e.g., 'npx', 'node', 'python') */
+    command: string;
+    /** Arguments to pass to the command */
+    args?: string[];
+    /** Environment variables for the spawned process */
+    env?: Record<string, string>;
+    /** Working directory for the spawned process */
+    cwd?: string;
+}
+/**
+ * Options for connecting to an MCP server via HTTP transport
+ */
+export interface MCPHttpOptions {
+    /** Server URL (e.g., 'http://localhost:3000/mcp') */
+    url: string;
+    /** Custom headers for HTTP requests */
+    headers?: Record<string, string>;
+}
+/**
+ * Configuration for an MCP client
+ */
+export interface MCPClientConfig {
+    /** Unique name/identifier for this server connection */
+    name: string;
+    /** Transport type */
+    transport: MCPTransport;
+    /** Stdio transport options (required if transport is 'stdio') */
+    stdio?: MCPStdioOptions;
+    /** HTTP transport options (required if transport is 'http') */
+    http?: MCPHttpOptions;
+    /** Connection timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Client name reported to server (default: '@compilr-dev/agents') */
+    clientName?: string;
+    /** Client version reported to server (default: '1.0.0') */
+    clientVersion?: string;
+}
+/**
+ * Simplified configuration for quick server setup
+ * Allows shorthand notation for common configurations
+ */
+export interface MCPServerConfig {
+    /** Unique name/identifier for this server */
+    name: string;
+    /** Transport type */
+    transport: MCPTransport;
+    /** Command to spawn */
+    command?: string;
+    /** Command arguments */
+    args?: string[];
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Working directory */
+    cwd?: string;
+    /** Server URL */
+    url?: string;
+    /** Custom headers */
+    headers?: Record<string, string>;
+    /** Connection timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * MCP tool definition from the server
+ * Based on MCP specification's Tool type
+ */
+export interface MCPToolDefinition {
+    /** Tool name (unique identifier) */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** JSON Schema for tool input */
+    inputSchema: {
+        type: 'object';
+        properties?: Record<string, unknown>;
+        required?: string[];
+        additionalProperties?: boolean;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Content block in MCP tool result
+ */
+export interface MCPContentBlock {
+    type: 'text' | 'image' | 'resource' | 'audio';
+    text?: string;
+    data?: string;
+    mimeType?: string;
+    uri?: string;
+}
+/**
+ * Result from calling an MCP tool
+ */
+export interface MCPToolResult {
+    /** Content blocks (text, images, resources) */
+    content: MCPContentBlock[];
+    /** Whether the tool execution resulted in an error */
+    isError?: boolean;
+}
+/**
+ * Event types emitted by MCPClient
+ */
+export type MCPClientEventType = 'tools_changed' | 'error' | 'disconnected' | 'connected';
+/**
+ * Event emitted by MCPClient
+ */
+export interface MCPClientEvent {
+    type: MCPClientEventType;
+    serverName: string;
+    error?: Error;
+    tools?: MCPToolDefinition[];
+}
+/**
+ * Handler for MCP client events
+ */
+export type MCPClientEventHandler = (event: MCPClientEvent) => void;
+/**
+ * Options for MCPManager
+ */
+export interface MCPManagerOptions {
+    /** Prefix for tool names (default: 'mcp') */
+    toolPrefix?: string;
+    /** Whether to auto-connect servers when added (default: true) */
+    autoConnect?: boolean;
+    /** Event handler for manager events */
+    onEvent?: MCPClientEventHandler;
+}
+/**
+ * Convert shorthand MCPServerConfig to full MCPClientConfig
+ */
+export declare function normalizeServerConfig(config: MCPServerConfig): MCPClientConfig;

package/dist/mcp/types.js

@@ -0,0 +1,40 @@
+/**
+ * MCP (Model Context Protocol) types and interfaces
+ *
+ * MCP is an open protocol by Anthropic that standardizes how AI applications
+ * connect to external tools and data sources.
+ *
+ * @see https://modelcontextprotocol.io/specification/2024-11-05/
+ */
+/**
+ * Convert shorthand MCPServerConfig to full MCPClientConfig
+ */
+export function normalizeServerConfig(config) {
+    const normalized = {
+        name: config.name,
+        transport: config.transport,
+        timeout: config.timeout,
+    };
+    if (config.transport === 'stdio') {
+        if (!config.command) {
+            throw new Error(`MCP server '${config.name}': stdio transport requires 'command'`);
+        }
+        normalized.stdio = {
+            command: config.command,
+            args: config.args,
+            env: config.env,
+            cwd: config.cwd,
+        };
+    }
+    else {
+        // transport === 'http'
+        if (!config.url) {
+            throw new Error(`MCP server '${config.name}': http transport requires 'url'`);
+        }
+        normalized.http = {
+            url: config.url,
+            headers: config.headers,
+        };
+    }
+    return normalized;
+}

package/dist/memory/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Memory module - Project-level instruction loading
+ *
+ * Supports various LLM-specific naming conventions and generic patterns
+ * for discovering and loading project instructions.
+ */
+export { ProjectMemoryLoader, createProjectMemoryLoader, loadProjectMemory, hasProjectMemory, getProviderPatterns, getSupportedProviders, getGenericPatterns, PROVIDER_PATTERNS, GENERIC_PATTERNS, } from './loader.js';
+export type { LLMProviderName, MemoryFile, ProjectMemory, FilePattern, CombineStrategy, ProjectMemoryOptions, ProjectMemoryEventType, ProjectMemoryEvent, ProjectMemoryEventHandler, MemoryDiscoveryResult, ProviderPatterns, } from './types.js';

package/dist/memory/index.js

@@ -0,0 +1,7 @@
+/**
+ * Memory module - Project-level instruction loading
+ *
+ * Supports various LLM-specific naming conventions and generic patterns
+ * for discovering and loading project instructions.
+ */
+export { ProjectMemoryLoader, createProjectMemoryLoader, loadProjectMemory, hasProjectMemory, getProviderPatterns, getSupportedProviders, getGenericPatterns, PROVIDER_PATTERNS, GENERIC_PATTERNS, } from './loader.js';