@nghyane/arcane 0.1.0

package/src/mcp/config.ts

@@ -0,0 +1,363 @@
+/**
+ * MCP configuration loader.
+ *
+ * Uses the capability system to load MCP servers from multiple sources.
+ */
+
+import { getMCPConfigPath } from "@nghyane/arcane-utils/dirs";
+import { mcpCapability } from "../capability/mcp";
+import type { SourceMeta } from "../capability/types";
+import type { MCPServer } from "../discovery";
+import { loadCapability } from "../discovery";
+import { readDisabledServers } from "./config-writer";
+import type { MCPServerConfig } from "./types";
+
+/** Options for loading MCP configs */
+export interface LoadMCPConfigsOptions {
+	/** Whether to load project-level config (default: true) */
+	enableProjectConfig?: boolean;
+	/** Whether to filter out Exa MCP servers (default: true) */
+	filterExa?: boolean;
+	/** Whether to filter out browser MCP servers when builtin browser tool is enabled (default: false) */
+	filterBrowser?: boolean;
+}
+
+/** Result of loading MCP configs */
+export interface LoadMCPConfigsResult {
+	/** Loaded server configs */
+	configs: Record<string, MCPServerConfig>;
+	/** Extracted Exa API keys (if any were filtered) */
+	exaApiKeys: string[];
+	/** Source metadata for each server */
+	sources: Record<string, SourceMeta>;
+}
+
+/**
+ * Convert canonical MCPServer to legacy MCPServerConfig.
+ */
+function convertToLegacyConfig(server: MCPServer): MCPServerConfig {
+	// Determine transport type
+	const transport = server.transport ?? (server.command ? "stdio" : server.url ? "http" : "stdio");
+	const shared = {
+		enabled: server.enabled,
+		timeout: server.timeout,
+		auth: server.auth,
+	};
+
+	if (transport === "stdio") {
+		const config: MCPServerConfig = {
+			...shared,
+			type: "stdio" as const,
+			command: server.command ?? "",
+		};
+		if (server.args) config.args = server.args;
+		if (server.env) config.env = server.env;
+		return config;
+	}
+
+	if (transport === "http") {
+		const config: MCPServerConfig = {
+			...shared,
+			type: "http" as const,
+			url: server.url ?? "",
+		};
+		if (server.headers) config.headers = server.headers;
+		return config;
+	}
+
+	if (transport === "sse") {
+		const config: MCPServerConfig = {
+			...shared,
+			type: "sse" as const,
+			url: server.url ?? "",
+		};
+		if (server.headers) config.headers = server.headers;
+		return config;
+	}
+
+	// Fallback to stdio
+	return {
+		...shared,
+		type: "stdio" as const,
+		command: server.command ?? "",
+	};
+}
+
+/**
+ * Load all MCP server configs from standard locations.
+ * Uses the capability system for multi-source discovery.
+ *
+ * @param cwd Working directory (project root)
+ * @param options Load options
+ */
+export async function loadAllMCPConfigs(cwd: string, options?: LoadMCPConfigsOptions): Promise<LoadMCPConfigsResult> {
+	const enableProjectConfig = options?.enableProjectConfig ?? true;
+	const filterExa = options?.filterExa ?? true;
+	const filterBrowser = options?.filterBrowser ?? false;
+
+	// Load MCP servers via capability system
+	const result = await loadCapability<MCPServer>(mcpCapability.id, { cwd });
+
+	// Filter out project-level configs if disabled
+	const servers = enableProjectConfig
+		? result.items
+		: result.items.filter(server => server._source.level !== "project");
+
+	// Load user-level disabled servers list
+	const disabledServers = new Set(await readDisabledServers(getMCPConfigPath("user", cwd)));
+	// Convert to legacy format and preserve source metadata
+	let configs: Record<string, MCPServerConfig> = {};
+	let sources: Record<string, SourceMeta> = {};
+	for (const server of servers) {
+		const config = convertToLegacyConfig(server);
+		if (config.enabled === false || (server._source.level !== "user" && disabledServers.has(server.name))) {
+			continue;
+		}
+		configs[server.name] = config;
+		sources[server.name] = server._source;
+	}
+
+	let exaApiKeys: string[] = [];
+
+	if (filterExa) {
+		const exaResult = filterExaMCPServers(configs, sources);
+		configs = exaResult.configs;
+		sources = exaResult.sources;
+		exaApiKeys = exaResult.exaApiKeys;
+	}
+
+	if (filterBrowser) {
+		const browserResult = filterBrowserMCPServers(configs, sources);
+		configs = browserResult.configs;
+		sources = browserResult.sources;
+	}
+
+	return { configs, exaApiKeys, sources };
+}
+
+/** Pattern to match Exa MCP servers */
+const EXA_MCP_URL_PATTERN = /mcp\.exa\.ai/i;
+const EXA_API_KEY_PATTERN = /exaApiKey=([^&\s]+)/i;
+
+/**
+ * Check if a server config is an Exa MCP server.
+ */
+export function isExaMCPServer(name: string, config: MCPServerConfig): boolean {
+	// Check by server name
+	if (name.toLowerCase() === "exa") {
+		return true;
+	}
+
+	// Check by URL for HTTP/SSE servers
+	if (config.type === "http" || config.type === "sse") {
+		const httpConfig = config as { url?: string };
+		if (httpConfig.url && EXA_MCP_URL_PATTERN.test(httpConfig.url)) {
+			return true;
+		}
+	}
+
+	// Check by args for stdio servers (e.g., mcp-remote to exa)
+	if (!config.type || config.type === "stdio") {
+		const stdioConfig = config as { args?: string[] };
+		if (stdioConfig.args?.some(arg => EXA_MCP_URL_PATTERN.test(arg))) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+/**
+ * Extract Exa API key from an MCP server config.
+ */
+export function extractExaApiKey(config: MCPServerConfig): string | undefined {
+	// Check URL for HTTP/SSE servers
+	if (config.type === "http" || config.type === "sse") {
+		const httpConfig = config as { url?: string };
+		if (httpConfig.url) {
+			const match = EXA_API_KEY_PATTERN.exec(httpConfig.url);
+			if (match) return match[1];
+		}
+	}
+
+	// Check args for stdio servers
+	if (!config.type || config.type === "stdio") {
+		const stdioConfig = config as { args?: string[] };
+		if (stdioConfig.args) {
+			for (const arg of stdioConfig.args) {
+				const match = EXA_API_KEY_PATTERN.exec(arg);
+				if (match) return match[1];
+			}
+		}
+	}
+
+	// Check env vars
+	if ("env" in config && config.env) {
+		const envConfig = config as { env: Record<string, string> };
+		if (envConfig.env.EXA_API_KEY) {
+			return envConfig.env.EXA_API_KEY;
+		}
+	}
+
+	return undefined;
+}
+
+/** Result of filtering Exa MCP servers */
+export interface ExaFilterResult {
+	/** Configs with Exa servers removed */
+	configs: Record<string, MCPServerConfig>;
+	/** Extracted Exa API keys (if any) */
+	exaApiKeys: string[];
+	/** Source metadata for remaining servers */
+	sources: Record<string, SourceMeta>;
+}
+
+/**
+ * Filter out Exa MCP servers and extract their API keys.
+ * Since we have native Exa integration, we don't need the MCP server.
+ */
+export function filterExaMCPServers(
+	configs: Record<string, MCPServerConfig>,
+	sources: Record<string, SourceMeta>,
+): ExaFilterResult {
+	const filtered: Record<string, MCPServerConfig> = {};
+	const filteredSources: Record<string, SourceMeta> = {};
+	const exaApiKeys: string[] = [];
+
+	for (const [name, config] of Object.entries(configs)) {
+		if (isExaMCPServer(name, config)) {
+			// Extract API key before filtering
+			const apiKey = extractExaApiKey(config);
+			if (apiKey) {
+				exaApiKeys.push(apiKey);
+			}
+		} else {
+			filtered[name] = config;
+			if (sources[name]) {
+				filteredSources[name] = sources[name];
+			}
+		}
+	}
+
+	return { configs: filtered, exaApiKeys, sources: filteredSources };
+}
+
+/**
+ * Validate server config has required fields.
+ */
+export function validateServerConfig(name: string, config: MCPServerConfig): string[] {
+	const errors: string[] = [];
+
+	const serverType = config.type ?? "stdio";
+
+	// Check for conflicting transport fields
+	const hasCommand = "command" in config && config.command;
+	const hasUrl = "url" in config && (config as { url?: string }).url;
+	if (hasCommand && hasUrl) {
+		errors.push(
+			`Server "${name}": both "command" and "url" are set - server should be either stdio (command) OR http/sse (url), not both`,
+		);
+	}
+
+	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;
+}
+
+/** Known browser automation MCP server names (lowercase) */
+const BROWSER_MCP_NAMES = new Set([
+	"puppeteer",
+	"playwright",
+	"browserbase",
+	"browser-tools",
+	"browser-use",
+	"browser",
+]);
+
+/** Patterns matching browser MCP package names in command/args */
+const BROWSER_MCP_PKG_PATTERN =
+	// Official packages
+	// - @modelcontextprotocol/server-puppeteer
+	// - @playwright/mcp
+	// - @browserbasehq/mcp-server-browserbase
+	// - @agentdeskai/browser-tools-mcp
+	// - @agent-infra/mcp-server-browser
+	// Community packages: puppeteer-mcp-server, playwright-mcp, pptr-mcp, etc.
+	/(?:@modelcontextprotocol\/server-puppeteer|@playwright\/mcp|@browserbasehq\/mcp-server-browserbase|@agentdeskai\/browser-tools-mcp|@agent-infra\/mcp-server-browser|puppeteer-mcp|playwright-mcp|pptr-mcp|browser-use-mcp|mcp-browser-use)/i;
+
+/** URL patterns for hosted browser MCP services */
+const BROWSER_MCP_URL_PATTERN = /browserbase\.com|browser-use\.com/i;
+
+/**
+ * Check if a server config is a browser automation MCP server.
+ */
+export function isBrowserMCPServer(name: string, config: MCPServerConfig): boolean {
+	// Check by server name
+	if (BROWSER_MCP_NAMES.has(name.toLowerCase())) {
+		return true;
+	}
+
+	// Check by URL for HTTP/SSE servers
+	if (config.type === "http" || config.type === "sse") {
+		const httpConfig = config as { url?: string };
+		if (httpConfig.url && BROWSER_MCP_URL_PATTERN.test(httpConfig.url)) {
+			return true;
+		}
+	}
+
+	// Check by command/args for stdio servers
+	if (!config.type || config.type === "stdio") {
+		const stdioConfig = config as { command?: string; args?: string[] };
+		if (stdioConfig.command && BROWSER_MCP_PKG_PATTERN.test(stdioConfig.command)) {
+			return true;
+		}
+		if (stdioConfig.args?.some(arg => BROWSER_MCP_PKG_PATTERN.test(arg))) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+/** Result of filtering browser MCP servers */
+export interface BrowserFilterResult {
+	/** Configs with browser servers removed */
+	configs: Record<string, MCPServerConfig>;
+	/** Source metadata for remaining servers */
+	sources: Record<string, SourceMeta>;
+}
+
+/**
+ * Filter out browser automation MCP servers.
+ * Since we have a native browser tool, we don't need these MCP servers.
+ */
+export function filterBrowserMCPServers(
+	configs: Record<string, MCPServerConfig>,
+	sources: Record<string, SourceMeta>,
+): BrowserFilterResult {
+	const filtered: Record<string, MCPServerConfig> = {};
+	const filteredSources: Record<string, SourceMeta> = {};
+
+	for (const [name, config] of Object.entries(configs)) {
+		if (!isBrowserMCPServer(name, config)) {
+			filtered[name] = config;
+			if (sources[name]) {
+				filteredSources[name] = sources[name];
+			}
+		}
+	}
+
+	return { configs: filtered, sources: filteredSources };
+}

package/src/mcp/index.ts

@@ -0,0 +1,55 @@
+/**
+ * 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";
+// Config
+export type { BrowserFilterResult, ExaFilterResult, LoadMCPConfigsOptions, LoadMCPConfigsResult } from "./config";
+export {
+	extractExaApiKey,
+	filterBrowserMCPServers,
+	filterExaMCPServers,
+	isBrowserMCPServer,
+	isExaMCPServer,
+	loadAllMCPConfigs,
+	validateServerConfig,
+} from "./config";
+export { validateServerName } from "./config-writer";
+// JSON-RPC (lightweight HTTP-based MCP calls)
+export type { JsonRpcResponse } from "./json-rpc";
+export { callMCP, parseSSE } from "./json-rpc";
+// Loader (for SDK integration)
+export type { MCPToolsLoadOptions, MCPToolsLoadResult } from "./loader";
+export { discoverAndLoadMCPTools } from "./loader";
+// Manager
+export type { MCPDiscoverOptions, MCPLoadResult } from "./manager";
+export { createMCPManager, MCPManager } from "./manager";
+// OAuth Discovery
+export type { AuthDetectionResult, OAuthEndpoints } from "./oauth-discovery";
+export { analyzeAuthError, detectAuthError, discoverOAuthEndpoints, extractOAuthEndpoints } from "./oauth-discovery";
+// Tool bridge
+export type { MCPToolDetails } from "./tool-bridge";
+export { createMCPToolName, DeferredMCPTool, MCPTool, parseMCPToolName } from "./tool-bridge";
+// Tool cache
+export { MCPToolCache } from "./tool-cache";
+// Transports
+export { createHttpTransport, HttpTransport } from "./transports/http";
+export { createStdioTransport, StdioTransport } from "./transports/stdio";
+// Types
+export type {
+	MCPConfigFile,
+	MCPContent,
+	MCPHttpServerConfig,
+	MCPServerCapabilities,
+	MCPServerConfig,
+	MCPServerConnection,
+	MCPSseServerConfig,
+	MCPStdioServerConfig,
+	MCPToolDefinition,
+	MCPToolWithServer,
+	MCPTransport,
+} from "./types";

package/src/mcp/json-rpc.ts

@@ -0,0 +1,84 @@
+/**
+ * MCP JSON-RPC 2.0 over HTTPS.
+ *
+ * Lightweight utilities for calling MCP servers directly via HTTP
+ * without maintaining persistent connections.
+ */
+import { logger } from "@nghyane/arcane-utils";
+
+/** Parse SSE response format (lines starting with "data: ") */
+export function parseSSE(text: string): unknown {
+	const lines = text.split("\n");
+	for (const line of lines) {
+		if (line.startsWith("data: ")) {
+			const data = line.slice(6).trim();
+			if (data === "[DONE]") continue;
+			const result = JSON.parse(data) as unknown;
+			if (result) return result;
+		}
+	}
+	// Fallback: try parsing entire response as JSON
+	try {
+		return JSON.parse(text);
+	} catch {
+		return null;
+	}
+}
+
+/** JSON-RPC 2.0 response structure */
+export interface JsonRpcResponse<T = unknown> {
+	jsonrpc: "2.0";
+	id: string | number;
+	result?: T;
+	error?: {
+		code: number;
+		message: string;
+		data?: unknown;
+	};
+}
+
+/**
+ * Call an MCP server with JSON-RPC 2.0 over HTTPS.
+ *
+ * @param url - Full MCP server URL (including any query parameters)
+ * @param method - JSON-RPC method name (e.g., "tools/list", "tools/call")
+ * @param params - Method parameters
+ * @returns Parsed JSON-RPC response
+ */
+export async function callMCP<T = unknown>(
+	url: string,
+	method: string,
+	params?: Record<string, unknown>,
+): Promise<JsonRpcResponse<T>> {
+	const body = {
+		jsonrpc: "2.0",
+		id: Math.random().toString(36).slice(2),
+		method,
+		params: params ?? {},
+	};
+
+	const response = await fetch(url, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			Accept: "application/json, text/event-stream",
+		},
+		body: JSON.stringify(body),
+	});
+
+	if (!response.ok) {
+		const errorMsg = `MCP request failed: ${response.status} ${response.statusText}`;
+		logger.error(errorMsg, { url, method, params });
+		throw new Error(errorMsg);
+	}
+
+	const text = await response.text();
+	const result = parseSSE(text) as JsonRpcResponse<T> | null;
+
+	if (!result) {
+		logger.error("Failed to parse MCP response", { url, method, responseText: text.slice(0, 500) });
+		throw new Error("Failed to parse MCP response");
+	}
+
+	return result;
+}

package/src/mcp/loader.ts

@@ -0,0 +1,124 @@
+/**
+ * MCP tools loader.
+ *
+ * Integrates MCP tool discovery with the custom tools system.
+ */
+import { logger } from "@nghyane/arcane-utils";
+import type { LoadedCustomTool } from "../extensibility/custom-tools/types";
+import { AgentStorage } from "../session/agent-storage";
+import type { AuthStorage } from "../session/auth-storage";
+import { type MCPLoadResult, MCPManager } from "./manager";
+import { MCPToolCache } from "./tool-cache";
+
+/** 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;
+	/** Whether to filter out browser MCP servers when builtin browser tool is enabled (default: false) */
+	filterBrowser?: boolean;
+	/** SQLite storage for MCP tool cache (null disables cache) */
+	cacheStorage?: AgentStorage | null;
+	/** Auth storage used to resolve OAuth credentials before initial MCP connect */
+	authStorage?: AuthStorage;
+}
+
+async function resolveToolCache(storage: AgentStorage | null | undefined): Promise<MCPToolCache | null> {
+	if (storage === null) return null;
+	try {
+		const resolved = storage ?? (await AgentStorage.open());
+		return new MCPToolCache(resolved);
+	} catch (error) {
+		logger.warn("MCP tool cache unavailable", { error: String(error) });
+		return null;
+	}
+}
+
+/**
+ * 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 toolCache = await resolveToolCache(options?.cacheStorage);
+	const manager = new MCPManager(cwd, toolCache);
+	if (options?.authStorage) {
+		manager.setAuthStorage(options.authStorage);
+	}
+
+	let result: MCPLoadResult;
+	try {
+		result = await manager.discoverAndConnect({
+			onConnecting: options?.onConnecting,
+			enableProjectConfig: options?.enableProjectConfig,
+			filterExa: options?.filterExa,
+			filterBrowser: options?.filterBrowser,
+		});
+	} 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 => {
+		// MCPTool and DeferredMCPTool have these properties
+		const mcpTool = tool as { mcpServerName?: string };
+		const serverName = mcpTool.mcpServerName;
+
+		// Get provider info from manager's connection if available
+		const connection = serverName ? manager.getConnection(serverName) : undefined;
+		const source = serverName ? manager.getSource(serverName) : undefined;
+		const providerName =
+			connection?._source?.providerName ?? source?.providerName ?? connection?._source?.provider ?? source?.provider;
+
+		// Format path with provider info if available
+		// Format: "mcp:serverName via providerName" (e.g., "mcp:agentx via Claude Code")
+		const path = serverName && providerName ? `mcp:${serverName} via ${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,
+	};
+}