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

package/src/core/index.ts

@@ -0,0 +1,52 @@
+/**
+ * Core modules shared between all run modes.
+ */
+
+export {
+	AgentSession,
+	type AgentSessionConfig,
+	type AgentSessionEvent,
+	type AgentSessionEventListener,
+	type ModelCycleResult,
+	type PromptOptions,
+	type SessionStats,
+} from "./agent-session.js";
+export { type BashExecutorOptions, type BashResult, executeBash } from "./bash-executor.js";
+export type { CompactionResult } from "./compaction/index.js";
+export {
+	type CustomTool,
+	type CustomToolAPI,
+	type CustomToolFactory,
+	type CustomToolsLoadResult,
+	type CustomToolUIContext,
+	discoverAndLoadCustomTools,
+	type ExecResult,
+	type LoadedCustomTool,
+	loadCustomTools,
+	type RenderResultOptions,
+} from "./custom-tools/index.js";
+export {
+	type HookAPI,
+	type HookContext,
+	type HookError,
+	type HookEvent,
+	type HookFactory,
+	HookRunner,
+	type HookUIContext,
+	loadHooks,
+} from "./hooks/index.js";
+export {
+	createMCPManager,
+	discoverAndLoadMCPTools,
+	expandEnvVars,
+	loadAllMCPConfigs,
+	type MCPConfigFile,
+	type MCPLoadResult,
+	MCPManager,
+	type MCPServerConfig,
+	type MCPServerConnection,
+	type MCPToolDefinition,
+	type MCPToolDetails,
+	type MCPToolsLoadResult,
+	type MCPTransport,
+} from "./mcp/index.js";

package/src/core/mcp/client.ts

@@ -0,0 +1,158 @@
+/**
+ * MCP Client.
+ *
+ * Handles connection initialization, tool listing, and tool calling.
+ */
+
+import { createHttpTransport } from "./transports/http.js";
+import { createStdioTransport } from "./transports/stdio.js";
+import type {
+	MCPHttpServerConfig,
+	MCPInitializeParams,
+	MCPInitializeResult,
+	MCPServerCapabilities,
+	MCPServerConfig,
+	MCPServerConnection,
+	MCPSseServerConfig,
+	MCPStdioServerConfig,
+	MCPToolCallParams,
+	MCPToolCallResult,
+	MCPToolDefinition,
+	MCPToolsListResult,
+	MCPTransport,
+} from "./types.js";
+
+/** MCP protocol version we support */
+const PROTOCOL_VERSION = "2025-03-26";
+
+/** Client info sent during initialization */
+const CLIENT_INFO = {
+	name: "pi-coding-agent",
+	version: "1.0.0",
+};
+
+/**
+ * Create a transport for the given server config.
+ */
+async function createTransport(config: MCPServerConfig): Promise<MCPTransport> {
+	const serverType = config.type ?? "stdio";
+
+	switch (serverType) {
+		case "stdio":
+			return createStdioTransport(config as MCPStdioServerConfig);
+		case "http":
+		case "sse":
+			return createHttpTransport(config as MCPHttpServerConfig | MCPSseServerConfig);
+		default:
+			throw new Error(`Unknown server type: ${serverType}`);
+	}
+}
+
+/**
+ * Initialize connection with MCP server.
+ */
+async function initializeConnection(transport: MCPTransport): Promise<MCPInitializeResult> {
+	const params: MCPInitializeParams = {
+		protocolVersion: PROTOCOL_VERSION,
+		capabilities: {
+			roots: { listChanged: false },
+		},
+		clientInfo: CLIENT_INFO,
+	};
+
+	const result = await transport.request<MCPInitializeResult>(
+		"initialize",
+		params as unknown as Record<string, unknown>,
+	);
+
+	// Send initialized notification
+	await transport.notify("notifications/initialized");
+
+	return result;
+}
+
+/**
+ * Connect to an MCP server.
+ */
+export async function connectToServer(name: string, config: MCPServerConfig): Promise<MCPServerConnection> {
+	const transport = await createTransport(config);
+
+	try {
+		const initResult = await initializeConnection(transport);
+
+		return {
+			name,
+			config,
+			transport,
+			serverInfo: initResult.serverInfo,
+			capabilities: initResult.capabilities,
+		};
+	} catch (error) {
+		await transport.close();
+		throw error;
+	}
+}
+
+/**
+ * List tools from a connected server.
+ */
+export async function listTools(connection: MCPServerConnection): Promise<MCPToolDefinition[]> {
+	// Check if server supports tools
+	if (!connection.capabilities.tools) {
+		return [];
+	}
+
+	// Return cached tools if available
+	if (connection.tools) {
+		return connection.tools;
+	}
+
+	const allTools: MCPToolDefinition[] = [];
+	let cursor: string | undefined;
+
+	do {
+		const params: Record<string, unknown> = {};
+		if (cursor) {
+			params.cursor = cursor;
+		}
+
+		const result = await connection.transport.request<MCPToolsListResult>("tools/list", params);
+		allTools.push(...result.tools);
+		cursor = result.nextCursor;
+	} while (cursor);
+
+	// Cache tools
+	connection.tools = allTools;
+
+	return allTools;
+}
+
+/**
+ * Call a tool on a connected server.
+ */
+export async function callTool(
+	connection: MCPServerConnection,
+	toolName: string,
+	args: Record<string, unknown> = {},
+): Promise<MCPToolCallResult> {
+	const params: MCPToolCallParams = {
+		name: toolName,
+		arguments: args,
+	};
+
+	return connection.transport.request<MCPToolCallResult>("tools/call", params as unknown as Record<string, unknown>);
+}
+
+/**
+ * Disconnect from a server.
+ */
+export async function disconnectServer(connection: MCPServerConnection): Promise<void> {
+	await connection.transport.close();
+}
+
+/**
+ * Check if a server supports tools.
+ */
+export function serverSupportsTools(capabilities: MCPServerCapabilities): boolean {
+	return capabilities.tools !== undefined;
+}

package/src/core/mcp/config.ts

@@ -0,0 +1,154 @@
+/**
+ * MCP configuration loader.
+ *
+ * Loads .mcp.json files from project root with environment variable expansion.
+ * Supports ${VAR} and ${VAR:-default} syntax.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { MCPConfigFile, MCPServerConfig } from "./types.js";
+
+/** Environment variable expansion pattern: ${VAR} or ${VAR:-default} */
+const ENV_VAR_PATTERN = /\$\{([^}:]+)(?::-([^}]*))?\}/g;
+
+/**
+ * Expand environment variables in a string.
+ * Supports ${VAR} and ${VAR:-default} syntax.
+ */
+export function expandEnvVars(value: string, extraEnv?: Record<string, string>): string {
+	return value.replace(ENV_VAR_PATTERN, (_, varName: string, defaultValue?: string) => {
+		const envValue = extraEnv?.[varName] ?? process.env[varName];
+		if (envValue !== undefined) {
+			return envValue;
+		}
+		if (defaultValue !== undefined) {
+			return defaultValue;
+		}
+		// If no value and no default, leave the placeholder (will likely cause an error later)
+		return `\${${varName}}`;
+	});
+}
+
+/**
+ * Recursively expand environment variables in an object.
+ */
+function expandEnvVarsInObject<T>(obj: T, extraEnv?: Record<string, string>): T {
+	if (typeof obj === "string") {
+		return expandEnvVars(obj, extraEnv) as T;
+	}
+	if (Array.isArray(obj)) {
+		return obj.map((item) => expandEnvVarsInObject(item, extraEnv)) as T;
+	}
+	if (obj !== null && typeof obj === "object") {
+		const result: Record<string, unknown> = {};
+		for (const [key, value] of Object.entries(obj)) {
+			result[key] = expandEnvVarsInObject(value, extraEnv);
+		}
+		return result as T;
+	}
+	return obj;
+}
+
+/**
+ * Load and parse an .mcp.json file.
+ * Returns null if file doesn't exist or is invalid.
+ */
+export function loadMCPConfigFile(filePath: string, extraEnv?: Record<string, string>): MCPConfigFile | null {
+	if (!existsSync(filePath)) {
+		return null;
+	}
+
+	try {
+		const content = readFileSync(filePath, "utf-8");
+		const parsed = JSON.parse(content) as MCPConfigFile;
+
+		// Expand environment variables in server configs
+		if (parsed.mcpServers) {
+			parsed.mcpServers = expandEnvVarsInObject(parsed.mcpServers, extraEnv);
+		}
+
+		return parsed;
+	} catch (error) {
+		console.error(`Warning: Failed to parse ${filePath}: ${error}`);
+		return null;
+	}
+}
+
+/**
+ * Configuration locations (in order of priority, later overrides earlier).
+ */
+export interface MCPConfigLocations {
+	/** User-level config: ~/.pi/mcp.json or ~/.claude.json */
+	user?: string;
+	/** Project-level config: <cwd>/.mcp.json */
+	project?: string;
+}
+
+/**
+ * Get standard MCP config file paths.
+ */
+export function getMCPConfigPaths(cwd: string): MCPConfigLocations {
+	const home = homedir();
+	return {
+		// User-level: ~/.pi/mcp.json (our standard)
+		user: join(home, ".pi", "mcp.json"),
+		// Project-level: .mcp.json at project root
+		project: join(cwd, ".mcp.json"),
+	};
+}
+
+/**
+ * Merge MCP configs from multiple sources.
+ * Later sources override earlier ones for servers with same name.
+ */
+export function mergeMCPConfigs(...configs: (MCPConfigFile | null)[]): Record<string, MCPServerConfig> {
+	const result: Record<string, MCPServerConfig> = {};
+
+	for (const config of configs) {
+		if (config?.mcpServers) {
+			Object.assign(result, config.mcpServers);
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Load all MCP server configs from standard locations.
+ * Returns merged config with project overriding user.
+ */
+export function loadAllMCPConfigs(cwd: string, extraEnv?: Record<string, string>): Record<string, MCPServerConfig> {
+	const paths = getMCPConfigPaths(cwd);
+
+	const userConfig = paths.user ? loadMCPConfigFile(paths.user, extraEnv) : null;
+	const projectConfig = paths.project ? loadMCPConfigFile(paths.project, extraEnv) : null;
+
+	return mergeMCPConfigs(userConfig, projectConfig);
+}
+
+/**
+ * Validate server config has required fields.
+ */
+export function validateServerConfig(name: string, config: MCPServerConfig): string[] {
+	const errors: string[] = [];
+
+	const serverType = config.type ?? "stdio";
+
+	if (serverType === "stdio") {
+		const stdioConfig = config as { command?: string };
+		if (!stdioConfig.command) {
+			errors.push(`Server "${name}": stdio server requires "command" field`);
+		}
+	} else if (serverType === "http" || serverType === "sse") {
+		const httpConfig = config as { url?: string };
+		if (!httpConfig.url) {
+			errors.push(`Server "${name}": ${serverType} server requires "url" field`);
+		}
+	} else {
+		errors.push(`Server "${name}": unknown server type "${serverType}"`);
+	}
+
+	return errors;
+}

package/src/core/mcp/index.ts

@@ -0,0 +1,45 @@
+/**
+ * MCP (Model Context Protocol) support.
+ *
+ * Provides per-project .mcp.json configuration for connecting to
+ * MCP servers via stdio or HTTP transports.
+ */
+
+// Client
+export { callTool, connectToServer, disconnectServer, listTools, serverSupportsTools } from "./client.js";
+
+// Config
+export {
+	expandEnvVars,
+	getMCPConfigPaths,
+	loadAllMCPConfigs,
+	loadMCPConfigFile,
+	mergeMCPConfigs,
+	validateServerConfig,
+} from "./config.js";
+// Loader (for SDK integration)
+export type { MCPToolsLoadResult } from "./loader.js";
+export { discoverAndLoadMCPTools } from "./loader.js";
+// Manager
+export type { MCPLoadResult } from "./manager.js";
+export { createMCPManager, MCPManager } from "./manager.js";
+// Tool bridge
+export type { MCPToolDetails } from "./tool-bridge.js";
+export { createMCPTool, createMCPToolName, createMCPTools, parseMCPToolName } from "./tool-bridge.js";
+// Transports
+export { createHttpTransport, HttpTransport } from "./transports/http.js";
+export { createStdioTransport, StdioTransport } from "./transports/stdio.js";
+// Types
+export type {
+	MCPConfigFile,
+	MCPContent,
+	MCPHttpServerConfig,
+	MCPServerCapabilities,
+	MCPServerConfig,
+	MCPServerConnection,
+	MCPSseServerConfig,
+	MCPStdioServerConfig,
+	MCPToolDefinition,
+	MCPToolWithServer,
+	MCPTransport,
+} from "./types.js";

package/src/core/mcp/loader.ts

@@ -0,0 +1,68 @@
+/**
+ * MCP tools loader.
+ *
+ * Integrates MCP tool discovery with the custom tools system.
+ */
+
+import type { LoadedCustomTool } from "../custom-tools/types.js";
+import { type MCPLoadResult, MCPManager } from "./manager.js";
+
+/** 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[];
+}
+
+/**
+ * Discover and load MCP tools from .mcp.json files.
+ *
+ * @param cwd Working directory (project root)
+ * @param extraEnv Additional environment variables for expansion
+ * @returns MCP tools in LoadedCustomTool format for integration
+ */
+export async function discoverAndLoadMCPTools(
+	cwd: string,
+	extraEnv?: Record<string, string>,
+): Promise<MCPToolsLoadResult> {
+	const manager = new MCPManager(cwd);
+
+	let result: MCPLoadResult;
+	try {
+		result = await manager.discoverAndConnect(extraEnv);
+	} 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: [],
+		};
+	}
+
+	// Convert MCP tools to LoadedCustomTool format
+	const loadedTools: LoadedCustomTool[] = result.tools.map((tool) => ({
+		path: `mcp:${tool.name}`,
+		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,
+	};
+}

package/src/core/mcp/manager.ts

@@ -0,0 +1,181 @@
+/**
+ * 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.js";
+import { connectToServer, disconnectServer, listTools } from "./client.js";
+import { loadAllMCPConfigs, validateServerConfig } from "./config.js";
+import type { MCPToolDetails } from "./tool-bridge.js";
+import { createMCPTools } from "./tool-bridge.js";
+import type { MCPServerConfig, MCPServerConnection } from "./types.js";
+
+/** 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[];
+}
+
+/**
+ * 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(extraEnv?: Record<string, string>): Promise<MCPLoadResult> {
+		const configs = loadAllMCPConfigs(this.cwd, extraEnv);
+		return this.connectServers(configs);
+	}
+
+	/**
+	 * Connect to specific MCP servers.
+	 */
+	async connectServers(configs: Record<string, MCPServerConfig>): Promise<MCPLoadResult> {
+		const errors = new Map<string, string>();
+		const connectedServers: string[] = [];
+		const allTools: CustomTool<TSchema, MCPToolDetails>[] = [];
+
+		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;
+			}
+
+			try {
+				const connection = await connectToServer(name, config);
+				this.connections.set(name, connection);
+				connectedServers.push(name);
+
+				// Load tools from this server
+				const serverTools = await listTools(connection);
+				const customTools = createMCPTools(connection, serverTools);
+				allTools.push(...customTools);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				errors.set(name, message);
+			}
+		}
+
+		// Update cached tools
+		this.tools = allTools;
+
+		return {
+			tools: allTools,
+			errors,
+			connectedServers,
+		};
+	}
+
+	/**
+	 * 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,
+	extraEnv?: Record<string, string>,
+): Promise<{
+	manager: MCPManager;
+	result: MCPLoadResult;
+}> {
+	const manager = new MCPManager(cwd);
+	const result = await manager.discoverAndConnect(extraEnv);
+	return { manager, result };
+}