@oh-my-pi/pi-coding-agent 0.1.0

package/src/core/mcp/loader.ts

@@ -0,0 +1,99 @@
+/**
+ * MCP tools loader.
+ *
+ * Integrates MCP tool discovery with the custom tools system.
+ */
+
+import type { LoadedCustomTool } from "../custom-tools/types";
+import { type MCPLoadResult, MCPManager } from "./manager";
+import { parseMCPToolName } from "./tool-bridge";
+
+/** Result from loading MCP tools */
+export interface MCPToolsLoadResult {
+	/** MCP manager (for lifecycle management) */
+	manager: MCPManager;
+	/** Loaded tools as LoadedCustomTool format */
+	tools: LoadedCustomTool[];
+	/** Errors keyed by server name */
+	errors: Array<{ path: string; error: string }>;
+	/** Connected server names */
+	connectedServers: string[];
+	/** Extracted Exa API keys from filtered MCP servers */
+	exaApiKeys: string[];
+}
+
+/** Options for loading MCP tools */
+export interface MCPToolsLoadOptions {
+	/** Called when starting to connect to servers */
+	onConnecting?: (serverNames: string[]) => void;
+	/** Whether to load project-level config (default: true) */
+	enableProjectConfig?: boolean;
+	/** Whether to filter out Exa MCP servers (default: true) */
+	filterExa?: boolean;
+}
+
+/**
+ * Discover and load MCP tools from .mcp.json files.
+ *
+ * @param cwd Working directory (project root)
+ * @param options Load options including progress callbacks
+ * @returns MCP tools in LoadedCustomTool format for integration
+ */
+export async function discoverAndLoadMCPTools(cwd: string, options?: MCPToolsLoadOptions): Promise<MCPToolsLoadResult> {
+	const manager = new MCPManager(cwd);
+
+	let result: MCPLoadResult;
+	try {
+		result = await manager.discoverAndConnect({
+			onConnecting: options?.onConnecting,
+			enableProjectConfig: options?.enableProjectConfig,
+			filterExa: options?.filterExa,
+		});
+	} catch (error) {
+		// If discovery fails entirely, return empty result
+		const message = error instanceof Error ? error.message : String(error);
+		return {
+			manager,
+			tools: [],
+			errors: [{ path: ".mcp.json", error: message }],
+			connectedServers: [],
+			exaApiKeys: [],
+		};
+	}
+
+	// Convert MCP tools to LoadedCustomTool format
+	const loadedTools: LoadedCustomTool[] = result.tools.map((tool) => {
+		// Parse the MCP tool name to get server name
+		const parsed = parseMCPToolName(tool.name);
+		const serverName = parsed?.serverName;
+
+		// Get provider info from manager's connection if available
+		const connection = serverName ? manager.getConnection(serverName) : undefined;
+		const provider = connection?._source?.provider;
+
+		// Format path with provider info if available
+		// Format: "mcp:serverName via providerName" (e.g., "mcp:agentx via Claude Code")
+		const path =
+			provider && serverName ? `mcp:${serverName} via ${connection._source!.providerName}` : `mcp:${tool.name}`;
+
+		return {
+			path,
+			resolvedPath: `mcp:${tool.name}`,
+			tool: tool as any, // MCPToolDetails is compatible with CustomTool<TSchema, any>
+		};
+	});
+
+	// Convert error map to array format
+	const errors: Array<{ path: string; error: string }> = [];
+	for (const [serverName, errorMsg] of result.errors) {
+		errors.push({ path: `mcp:${serverName}`, error: errorMsg });
+	}
+
+	return {
+		manager,
+		tools: loadedTools,
+		errors,
+		connectedServers: result.connectedServers,
+		exaApiKeys: result.exaApiKeys,
+	};
+}

package/src/core/mcp/manager.ts

@@ -0,0 +1,235 @@
+/**
+ * MCP Server Manager.
+ *
+ * Discovers, connects to, and manages MCP servers.
+ * Handles tool loading and lifecycle.
+ */
+
+import type { TSchema } from "@sinclair/typebox";
+import type { CustomTool } from "../custom-tools/types";
+import { connectToServer, disconnectServer, listTools } from "./client";
+import { loadAllMCPConfigs, validateServerConfig } from "./config";
+import type { MCPToolDetails } from "./tool-bridge";
+import { createMCPTools } from "./tool-bridge";
+import type { MCPServerConfig, MCPServerConnection } from "./types";
+
+/** Result of loading MCP tools */
+export interface MCPLoadResult {
+	/** Loaded tools as CustomTool instances */
+	tools: CustomTool<TSchema, MCPToolDetails>[];
+	/** Connection errors by server name */
+	errors: Map<string, string>;
+	/** Connected server names */
+	connectedServers: string[];
+	/** Extracted Exa API keys from filtered MCP servers */
+	exaApiKeys: string[];
+}
+
+/** Options for discovering and connecting to MCP servers */
+export interface MCPDiscoverOptions {
+	/** Whether to load project-level config (default: true) */
+	enableProjectConfig?: boolean;
+	/** Whether to filter out Exa MCP servers (default: true) */
+	filterExa?: boolean;
+	/** Called when starting to connect to servers */
+	onConnecting?: (serverNames: string[]) => void;
+}
+
+/**
+ * MCP Server Manager.
+ *
+ * Manages connections to MCP servers and provides tools to the agent.
+ */
+export class MCPManager {
+	private connections = new Map<string, MCPServerConnection>();
+	private tools: CustomTool<TSchema, MCPToolDetails>[] = [];
+
+	constructor(private cwd: string) {}
+
+	/**
+	 * Discover and connect to all MCP servers from .mcp.json files.
+	 * Returns tools and any connection errors.
+	 */
+	async discoverAndConnect(options?: MCPDiscoverOptions): Promise<MCPLoadResult> {
+		const { configs, exaApiKeys, sources } = await loadAllMCPConfigs(this.cwd, {
+			enableProjectConfig: options?.enableProjectConfig,
+			filterExa: options?.filterExa,
+		});
+		const result = await this.connectServers(configs, sources, options?.onConnecting);
+		result.exaApiKeys = exaApiKeys;
+		return result;
+	}
+
+	/**
+	 * Connect to specific MCP servers.
+	 * Connections are made in parallel for faster startup.
+	 */
+	async connectServers(
+		configs: Record<string, MCPServerConfig>,
+		sources: Record<string, import("../../capability/types").SourceMeta>,
+		onConnecting?: (serverNames: string[]) => void,
+	): Promise<MCPLoadResult> {
+		const errors = new Map<string, string>();
+		const connectedServers: string[] = [];
+		const allTools: CustomTool<TSchema, MCPToolDetails>[] = [];
+
+		// Prepare connection tasks
+		const connectionTasks: Array<{
+			name: string;
+			config: MCPServerConfig;
+			validationErrors: string[];
+		}> = [];
+
+		for (const [name, config] of Object.entries(configs)) {
+			// Skip if already connected
+			if (this.connections.has(name)) {
+				connectedServers.push(name);
+				continue;
+			}
+
+			// Validate config
+			const validationErrors = validateServerConfig(name, config);
+			if (validationErrors.length > 0) {
+				errors.set(name, validationErrors.join("; "));
+				continue;
+			}
+
+			connectionTasks.push({ name, config, validationErrors });
+		}
+
+		// Notify about servers we're connecting to
+		if (connectionTasks.length > 0 && onConnecting) {
+			onConnecting(connectionTasks.map((t) => t.name));
+		}
+
+		// Connect to all servers in parallel
+		const results = await Promise.allSettled(
+			connectionTasks.map(async ({ name, config }) => {
+				const connection = await connectToServer(name, config);
+				// Attach source metadata to connection
+				if (sources[name]) {
+					connection._source = sources[name];
+				}
+				const serverTools = await listTools(connection);
+				return { name, connection, serverTools };
+			}),
+		);
+
+		// Process results
+		for (let i = 0; i < results.length; i++) {
+			const result = results[i];
+			const { name } = connectionTasks[i];
+
+			if (result.status === "fulfilled") {
+				const { connection, serverTools } = result.value;
+				this.connections.set(name, connection);
+				connectedServers.push(name);
+
+				const customTools = createMCPTools(connection, serverTools);
+				allTools.push(...customTools);
+			} else {
+				const message = result.reason instanceof Error ? result.reason.message : String(result.reason);
+				errors.set(name, message);
+			}
+		}
+
+		// Update cached tools
+		this.tools = allTools;
+
+		return {
+			tools: allTools,
+			errors,
+			connectedServers,
+			exaApiKeys: [], // Will be populated by discoverAndConnect
+		};
+	}
+
+	/**
+	 * Get all loaded tools.
+	 */
+	getTools(): CustomTool<TSchema, MCPToolDetails>[] {
+		return this.tools;
+	}
+
+	/**
+	 * Get a specific connection.
+	 */
+	getConnection(name: string): MCPServerConnection | undefined {
+		return this.connections.get(name);
+	}
+
+	/**
+	 * Get all connected server names.
+	 */
+	getConnectedServers(): string[] {
+		return Array.from(this.connections.keys());
+	}
+
+	/**
+	 * Disconnect from a specific server.
+	 */
+	async disconnectServer(name: string): Promise<void> {
+		const connection = this.connections.get(name);
+		if (!connection) return;
+
+		await disconnectServer(connection);
+		this.connections.delete(name);
+
+		// Remove tools from this server
+		this.tools = this.tools.filter((t) => !t.name.startsWith(`mcp_${name}_`));
+	}
+
+	/**
+	 * Disconnect from all servers.
+	 */
+	async disconnectAll(): Promise<void> {
+		const promises = Array.from(this.connections.values()).map((conn) => disconnectServer(conn));
+		await Promise.allSettled(promises);
+
+		this.connections.clear();
+		this.tools = [];
+	}
+
+	/**
+	 * Refresh tools from a specific server.
+	 */
+	async refreshServerTools(name: string): Promise<void> {
+		const connection = this.connections.get(name);
+		if (!connection) return;
+
+		// Clear cached tools
+		connection.tools = undefined;
+
+		// Reload tools
+		const serverTools = await listTools(connection);
+		const customTools = createMCPTools(connection, serverTools);
+
+		// Replace tools from this server
+		this.tools = this.tools.filter((t) => !t.name.startsWith(`mcp_${name}_`));
+		this.tools.push(...customTools);
+	}
+
+	/**
+	 * Refresh tools from all servers.
+	 */
+	async refreshAllTools(): Promise<void> {
+		const promises = Array.from(this.connections.keys()).map((name) => this.refreshServerTools(name));
+		await Promise.allSettled(promises);
+	}
+}
+
+/**
+ * Create an MCP manager and discover servers.
+ * Convenience function for quick setup.
+ */
+export async function createMCPManager(
+	cwd: string,
+	options?: MCPDiscoverOptions,
+): Promise<{
+	manager: MCPManager;
+	result: MCPLoadResult;
+}> {
+	const manager = new MCPManager(cwd);
+	const result = await manager.discoverAndConnect(options);
+	return { manager, result };
+}

package/src/core/mcp/tool-bridge.ts

@@ -0,0 +1,156 @@
+/**
+ * MCP to CustomTool bridge.
+ *
+ * Converts MCP tool definitions to CustomTool format for the agent.
+ */
+
+import type { TSchema } from "@sinclair/typebox";
+import type { CustomTool, CustomToolResult } from "../custom-tools/types";
+import { callTool } from "./client";
+import type { MCPContent, MCPServerConnection, MCPToolDefinition } from "./types";
+
+/** Details included in MCP tool results for rendering */
+export interface MCPToolDetails {
+	/** Server name */
+	serverName: string;
+	/** Original MCP tool name */
+	mcpToolName: string;
+	/** Whether the call resulted in an error */
+	isError?: boolean;
+	/** Raw content from MCP response */
+	rawContent?: MCPContent[];
+	/** Provider ID (e.g., "claude", "mcp-json") */
+	provider?: string;
+	/** Provider display name (e.g., "Claude Code", "MCP Config") */
+	providerName?: string;
+}
+
+/**
+ * Convert JSON Schema from MCP to TypeBox-compatible schema.
+ * MCP uses standard JSON Schema, TypeBox uses a compatible subset.
+ */
+function convertSchema(mcpSchema: MCPToolDefinition["inputSchema"]): TSchema {
+	// MCP schemas are JSON Schema objects, TypeBox can use them directly
+	// as long as we ensure the structure is correct
+	return mcpSchema as unknown as TSchema;
+}
+
+/**
+ * Format MCP content for LLM consumption.
+ */
+function formatMCPContent(content: MCPContent[]): string {
+	const parts: string[] = [];
+
+	for (const item of content) {
+		switch (item.type) {
+			case "text":
+				parts.push(item.text);
+				break;
+			case "image":
+				parts.push(`[Image: ${item.mimeType}]`);
+				break;
+			case "resource":
+				if (item.resource.text) {
+					parts.push(`[Resource: ${item.resource.uri}]\n${item.resource.text}`);
+				} else {
+					parts.push(`[Resource: ${item.resource.uri}]`);
+				}
+				break;
+		}
+	}
+
+	return parts.join("\n\n");
+}
+
+/**
+ * Create a unique tool name for an MCP tool.
+ * Prefixes with server name to avoid conflicts.
+ */
+export function createMCPToolName(serverName: string, toolName: string): string {
+	// Use underscore separator since tool names can't have special chars
+	return `mcp_${serverName}_${toolName}`;
+}
+
+/**
+ * Parse an MCP tool name back to server and tool components.
+ */
+export function parseMCPToolName(name: string): { serverName: string; toolName: string } | null {
+	if (!name.startsWith("mcp_")) return null;
+
+	const rest = name.slice(4);
+	const underscoreIdx = rest.lastIndexOf("_");
+	if (underscoreIdx === -1) return null;
+
+	return {
+		serverName: rest.slice(0, underscoreIdx),
+		toolName: rest.slice(underscoreIdx + 1),
+	};
+}
+
+/**
+ * Convert an MCP tool definition to a CustomTool.
+ */
+export function createMCPTool(
+	connection: MCPServerConnection,
+	tool: MCPToolDefinition,
+): CustomTool<TSchema, MCPToolDetails> {
+	const name = createMCPToolName(connection.name, tool.name);
+	const schema = convertSchema(tool.inputSchema);
+
+	return {
+		name,
+		label: `${connection.name}/${tool.name}`,
+		description: tool.description ?? `MCP tool from ${connection.name}`,
+		parameters: schema,
+
+		async execute(_toolCallId, params, _onUpdate, _ctx, _signal): Promise<CustomToolResult<MCPToolDetails>> {
+			try {
+				const result = await callTool(connection, tool.name, params as Record<string, unknown>);
+
+				const text = formatMCPContent(result.content);
+				const details: MCPToolDetails = {
+					serverName: connection.name,
+					mcpToolName: tool.name,
+					isError: result.isError,
+					rawContent: result.content,
+					provider: connection._source?.provider,
+					providerName: connection._source?.providerName,
+				};
+
+				if (result.isError) {
+					return {
+						content: [{ type: "text", text: `Error: ${text}` }],
+						details,
+					};
+				}
+
+				return {
+					content: [{ type: "text", text }],
+					details,
+				};
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return {
+					content: [{ type: "text", text: `MCP error: ${message}` }],
+					details: {
+						serverName: connection.name,
+						mcpToolName: tool.name,
+						isError: true,
+						provider: connection._source?.provider,
+						providerName: connection._source?.providerName,
+					},
+				};
+			}
+		},
+	};
+}
+
+/**
+ * Convert all tools from an MCP server to CustomTools.
+ */
+export function createMCPTools(
+	connection: MCPServerConnection,
+	tools: MCPToolDefinition[],
+): CustomTool<TSchema, MCPToolDetails>[] {
+	return tools.map((tool) => createMCPTool(connection, tool));
+}