@oh-my-pi/pi-coding-agent 1.338.0 → 1.341.0

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## [Unreleased]
+
+## [1.341.0] - 2026-01-03
+### Added
+
+- Added interruptMode setting to control when queued messages are processed during tool execution.
+- Implemented getter and setter methods in SettingsManager for interrupt mode persistence.
+- Exposed interruptMode configuration in interactive settings UI with immediate/wait options.
+- Wired interrupt mode through AgentSession and SDK to enable runtime configuration.
+- Model roles: Configure different models for different purposes (default, smol, slow) via `/model` selector
+- Model selector key bindings: Enter sets default, S sets smol, L sets slow, Escape closes
+- Model selector shows role markers: ✓ for default, ⚡ for smol, 🧠 for slow
+- `pi/<role>` model aliases in Task tool agent definitions (e.g., `model: pi/smol, haiku, flash, mini`)
+- Smol model auto-discovery using priority chain: haiku > flash > mini
+- Slow model auto-discovery using priority chain: gpt-5.2-codex > codex > gpt > opus > pro
+- CLI args for model roles: `--smol <model>` and `--slow <model>` (ephemeral, not persisted)
+- Env var overrides: `PI_SMOL_MODEL` and `PI_SLOW_MODEL`
+- Title generation now uses configured smol model from settings
+- LSP diagnostics on edit: Edit tool can now return LSP diagnostics after editing code files. Disabled by default to avoid noise during multi-edit sequences. Enable via `lsp.diagnosticsOnEdit` setting.
+- LSP workspace diagnostics: New `lsp action=workspace_diagnostics` command checks the entire project for errors. Auto-detects project type and uses appropriate checker (rust-analyzer/cargo for Rust, tsc for TypeScript, go build for Go, pyright for Python).
+- LSP local binary resolution: LSP servers installed in project-local directories are now discovered automatically. Checks `node_modules/.bin/` for Node.js projects, `.venv/bin/`/`venv/bin/` for Python projects, and `vendor/bundle/bin/` for Ruby projects before falling back to `$PATH`.
+- LSP format on write: Write tool now automatically formats code files using LSP after writing. Uses the language server's built-in formatter (e.g., rustfmt for Rust, gofmt for Go). Controlled via `lsp.formatOnWrite` setting (enabled by default).
+- LSP diagnostics on write: Write tool now returns LSP diagnostics (errors/warnings) after writing code files. This gives immediate feedback on syntax errors and type issues. Controlled via `lsp.diagnosticsOnWrite` setting (enabled by default).
+- LSP server warmup at startup: LSP servers are now started at launch to avoid cold-start delays when first writing files.
+- LSP server status in welcome banner: Shows which language servers are active and ready.
+- Edit fuzzy match setting: Added `edit.fuzzyMatch` setting (enabled by default) to control whether the edit tool accepts high-confidence fuzzy matches for whitespace/indentation differences. Toggle via `/settings`.
+- Multi-server LSP diagnostics: Diagnostics now query all applicable language servers for a file type. For TypeScript/JavaScript projects with Biome, this means both type errors (from tsserver) and lint errors (from Biome) are reported together.
+- Comprehensive LSP server configurations for 40+ languages including Rust, Go, Python, Java, Kotlin, Scala, Haskell, OCaml, Elixir, Ruby, PHP, C#, Lua, Nix, and many more. Each server includes sensible defaults for args, settings, and init options.
+- Extended LSP config file search paths: Now searches for `lsp.json`, `.lsp.json` in project root and `.pi/` subdirectory, plus user-level configs in `~/.pi/` and home directory.
+
+### Changed
+
+- LSP settings moved to dedicated "LSP" tab in `/settings` for better organization
+- Improved grep tool description to document pagination options (`headLimit`, `offset`) and clarify recursive search behavior
+- LSP idle timeout now disabled by default. Configure via `idleTimeoutMs` in lsp.json to auto-shutdown inactive servers.
+- Model settings now use role-based storage (`modelRoles` map) instead of single `defaultProvider`/`defaultModel` fields. Supports multiple model roles (default, small, etc.)
+- Session model persistence now uses `"provider/modelId"` string format with optional role field
+
+### Fixed
+
+- Recent sessions now show in welcome banner (was never wired up).
+- Auto-generated session titles: Sessions are now automatically titled based on the first message using a small model (Haiku/GPT-4o-mini/Flash). Titles are shown in the terminal window title, recent sessions list, and --resume picker. The resume picker shows title with dimmed first message preview below.
+
+## [1.340.0] - 2026-01-03
+
+### Changed
+
+- Replaced vendored highlight.js and marked.js with CDN-hosted versions for smaller exports
+- Added runtime minification for HTML, CSS, and JS in session exports
+- Session share URL now uses gistpreview.github.io instead of shittycodingagent.ai
+
+## [1.339.0] - 2026-01-03
+
+### Added
+
+- MCP project config setting to disable loading `.mcp.json`/`mcp.json` from project root
+- Support for both `mcp.json` and `.mcp.json` filenames (prefers `mcp.json` if both exist)
+- Automatic Exa MCP server filtering with API key extraction for native integration
+
 ## [1.338.0] - 2026-01-03
 
 ### Added
@@ -1268,4 +1327,4 @@ Initial public release.
 - Git branch display in footer
 - Message queueing during streaming responses
 - OAuth integration for Gmail and Google Calendar access
-- HTML export with syntax highlighting and collapsible sections
+- HTML export with syntax highlighting and collapsible sections

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "1.338.0",
+	"version": "1.341.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"piConfig": {
@@ -33,8 +33,8 @@
 		"clean": "rm -rf dist",
 		"build": "tsgo -p tsconfig.build.json && chmod +x dist/cli.js && npm run copy-assets",
 		"build:binary": "npm run build && bun build --compile ./dist/cli.js --outfile dist/pi && npm run copy-binary-assets",
-		"copy-assets": "mkdir -p dist/modes/interactive/theme && cp src/modes/interactive/theme/*.json dist/modes/interactive/theme/ && mkdir -p dist/core/export-html/vendor && cp src/core/export-html/template.html src/core/export-html/template.css src/core/export-html/template.js dist/core/export-html/ && cp src/core/export-html/vendor/*.js dist/core/export-html/vendor/",
-		"copy-binary-assets": "cp package.json dist/ && cp README.md dist/ && cp CHANGELOG.md dist/ && mkdir -p dist/theme && cp src/modes/interactive/theme/*.json dist/theme/ && mkdir -p dist/export-html/vendor && cp src/core/export-html/template.html dist/export-html/ && cp src/core/export-html/vendor/*.js dist/export-html/vendor/ && cp -r docs dist/ && cp -r examples dist/",
+		"copy-assets": "mkdir -p dist/modes/interactive/theme && cp src/modes/interactive/theme/*.json dist/modes/interactive/theme/ && mkdir -p dist/core/export-html && cp src/core/export-html/template.html src/core/export-html/template.css src/core/export-html/template.js dist/core/export-html/",
+		"copy-binary-assets": "cp package.json dist/ && cp README.md dist/ && cp CHANGELOG.md dist/ && mkdir -p dist/theme && cp src/modes/interactive/theme/*.json dist/theme/ && mkdir -p dist/export-html && cp src/core/export-html/template.html src/core/export-html/template.css src/core/export-html/template.js dist/export-html/ && cp -r docs dist/ && cp -r examples dist/",
 		"test": "vitest --run",
 		"prepublishOnly": "npm run clean && npm run build"
 	},

package/src/cli/args.ts

@@ -12,6 +12,8 @@ export type Mode = "text" | "json" | "rpc";
 export interface Args {
 	provider?: string;
 	model?: string;
+	smol?: string;
+	slow?: string;
 	apiKey?: string;
 	systemPrompt?: string;
 	appendSystemPrompt?: string;
@@ -69,6 +71,10 @@ export function parseArgs(args: string[]): Args {
 			result.provider = args[++i];
 		} else if (arg === "--model" && i + 1 < args.length) {
 			result.model = args[++i];
+		} else if (arg === "--smol" && i + 1 < args.length) {
+			result.smol = args[++i];
+		} else if (arg === "--slow" && i + 1 < args.length) {
+			result.slow = args[++i];
 		} else if (arg === "--api-key" && i + 1 < args.length) {
 			result.apiKey = args[++i];
 		} else if (arg === "--system-prompt" && i + 1 < args.length) {
@@ -148,6 +154,8 @@ ${chalk.bold("Usage:")}
 ${chalk.bold("Options:")}
   --provider <name>              Provider name (default: google)
   --model <id>                   Model ID (default: gemini-2.5-flash)
+  --smol <id>                    Smol/fast model for lightweight tasks (or PI_SMOL_MODEL env)
+  --slow <id>                    Slow/reasoning model for thorough analysis (or PI_SLOW_MODEL env)
   --api-key <key>                API key (defaults to env vars)
   --system-prompt <text>         System prompt (default: coding assistant prompt)
   --append-system-prompt <text>  Append text or file contents to the system prompt

package/src/core/agent-session.ts

@@ -424,6 +424,11 @@ export class AgentSession {
 		return this.agent.getQueueMode();
 	}
 
+	/** Current interrupt mode */
+	get interruptMode(): "immediate" | "wait" {
+		return this.agent.getInterruptMode();
+	}
+
 	/** Current session file path, or undefined if sessions are disabled */
 	get sessionFile(): string | undefined {
 		return this.sessionManager.getSessionFile();
@@ -701,15 +706,15 @@ export class AgentSession {
 	 * Validates API key, saves to session and settings.
 	 * @throws Error if no API key available for the model
 	 */
-	async setModel(model: Model<any>): Promise<void> {
+	async setModel(model: Model<any>, role: string = "default"): Promise<void> {
 		const apiKey = await this._modelRegistry.getApiKey(model);
 		if (!apiKey) {
 			throw new Error(`No API key for ${model.provider}/${model.id}`);
 		}
 
 		this.agent.setModel(model);
-		this.sessionManager.appendModelChange(model.provider, model.id);
-		this.settingsManager.setDefaultModelAndProvider(model.provider, model.id);
+		this.sessionManager.appendModelChange(`${model.provider}/${model.id}`, role);
+		this.settingsManager.setModelRole(role, `${model.provider}/${model.id}`);
 
 		// Re-clamp thinking level for new model's capabilities
 		this.setThinkingLevel(this.thinkingLevel);
@@ -747,8 +752,8 @@ export class AgentSession {
 
 		// Apply model
 		this.agent.setModel(next.model);
-		this.sessionManager.appendModelChange(next.model.provider, next.model.id);
-		this.settingsManager.setDefaultModelAndProvider(next.model.provider, next.model.id);
+		this.sessionManager.appendModelChange(`${next.model.provider}/${next.model.id}`);
+		this.settingsManager.setModelRole("default", `${next.model.provider}/${next.model.id}`);
 
 		// Apply thinking level (setThinkingLevel clamps to model capabilities)
 		this.setThinkingLevel(next.thinkingLevel);
@@ -774,8 +779,8 @@ export class AgentSession {
 		}
 
 		this.agent.setModel(nextModel);
-		this.sessionManager.appendModelChange(nextModel.provider, nextModel.id);
-		this.settingsManager.setDefaultModelAndProvider(nextModel.provider, nextModel.id);
+		this.sessionManager.appendModelChange(`${nextModel.provider}/${nextModel.id}`);
+		this.settingsManager.setModelRole("default", `${nextModel.provider}/${nextModel.id}`);
 
 		// Re-clamp thinking level for new model's capabilities
 		this.setThinkingLevel(this.thinkingLevel);
@@ -861,6 +866,15 @@ export class AgentSession {
 		this.settingsManager.setQueueMode(mode);
 	}
 
+	/**
+	 * Set interrupt mode.
+	 * Saves to settings.
+	 */
+	setInterruptMode(mode: "immediate" | "wait"): void {
+		this.agent.setInterruptMode(mode);
+		this.settingsManager.setInterruptMode(mode);
+	}
+
 	// =========================================================================
 	// Compaction
 	// =========================================================================
@@ -1472,13 +1486,17 @@ export class AgentSession {
 		this.agent.replaceMessages(sessionContext.messages);
 
 		// Restore model if saved
-		if (sessionContext.model) {
-			const availableModels = await this._modelRegistry.getAvailable();
-			const match = availableModels.find(
-				(m) => m.provider === sessionContext.model!.provider && m.id === sessionContext.model!.modelId,
-			);
-			if (match) {
-				this.agent.setModel(match);
+		const defaultModelStr = sessionContext.models.default;
+		if (defaultModelStr) {
+			const slashIdx = defaultModelStr.indexOf("/");
+			if (slashIdx > 0) {
+				const provider = defaultModelStr.slice(0, slashIdx);
+				const modelId = defaultModelStr.slice(slashIdx + 1);
+				const availableModels = await this._modelRegistry.getAvailable();
+				const match = availableModels.find((m) => m.provider === provider && m.id === modelId);
+				if (match) {
+					this.agent.setModel(match);
+				}
 			}
 		}
 

package/src/core/export-html/index.ts

@@ -5,6 +5,34 @@ import { APP_NAME, getExportTemplateDir } from "../../config.js";
 import { getResolvedThemeColors, getThemeExportColors } from "../../modes/interactive/theme/theme.js";
 import { SessionManager } from "../session-manager.js";
 
+// Cached minified assets (populated on first use)
+let cachedTemplate: string | null = null;
+let cachedJs: string | null = null;
+
+/** Minify CSS by removing comments, unnecessary whitespace, and newlines. */
+function minifyCss(css: string): string {
+	return css
+		.replace(/\/\*[\s\S]*?\*\//g, "") // Remove comments
+		.replace(/\s+/g, " ") // Collapse whitespace
+		.replace(/\s*([{}:;,>+~])\s*/g, "$1") // Remove space around punctuation
+		.replace(/;}/g, "}") // Remove trailing semicolons
+		.trim();
+}
+
+/** Minify JS using Bun's transpiler. */
+function minifyJs(js: string): string {
+	const transpiler = new Bun.Transpiler({ loader: "js", minifyWhitespace: true });
+	return transpiler.transformSync(js);
+}
+
+/** Minify HTML by collapsing whitespace outside of tags. */
+function minifyHtml(html: string): string {
+	return html
+		.replace(/>\s+</g, "><") // Remove whitespace between tags
+		.replace(/\s{2,}/g, " ") // Collapse multiple spaces
+		.trim();
+}
+
 export interface ExportOptions {
 	outputPath?: string;
 	themeName?: string;
@@ -111,11 +139,16 @@ interface SessionData {
  */
 function generateHtml(sessionData: SessionData, themeName?: string): string {
 	const templateDir = getExportTemplateDir();
-	const template = readFileSync(join(templateDir, "template.html"), "utf-8");
+
+	// Load and minify assets on first use
+	if (!cachedTemplate) {
+		cachedTemplate = minifyHtml(readFileSync(join(templateDir, "template.html"), "utf-8"));
+	}
+	if (!cachedJs) {
+		cachedJs = minifyJs(readFileSync(join(templateDir, "template.js"), "utf-8"));
+	}
+
 	const templateCss = readFileSync(join(templateDir, "template.css"), "utf-8");
-	const templateJs = readFileSync(join(templateDir, "template.js"), "utf-8");
-	const markedJs = readFileSync(join(templateDir, "vendor", "marked.min.js"), "utf-8");
-	const hljsJs = readFileSync(join(templateDir, "vendor", "highlight.min.js"), "utf-8");
 
 	const themeVars = generateThemeVars(themeName);
 	const colors = getResolvedThemeColors(themeName);
@@ -127,19 +160,19 @@ function generateHtml(sessionData: SessionData, themeName?: string): string {
 	// Base64 encode session data to avoid escaping issues
 	const sessionDataBase64 = Buffer.from(JSON.stringify(sessionData)).toString("base64");
 
-	// Build the CSS with theme variables injected
-	const css = templateCss
-		.replace("{{THEME_VARS}}", themeVars)
-		.replace("{{BODY_BG}}", bodyBg)
-		.replace("{{CONTAINER_BG}}", containerBg)
-		.replace("{{INFO_BG}}", infoBg);
+	// Build and minify the CSS with theme variables injected
+	const css = minifyCss(
+		templateCss
+			.replace("{{THEME_VARS}}", themeVars)
+			.replace("{{BODY_BG}}", bodyBg)
+			.replace("{{CONTAINER_BG}}", containerBg)
+			.replace("{{INFO_BG}}", infoBg),
+	);
 
-	return template
+	return cachedTemplate
 		.replace("{{CSS}}", css)
-		.replace("{{JS}}", templateJs)
-		.replace("{{SESSION_DATA}}", sessionDataBase64)
-		.replace("{{MARKED_JS}}", markedJs)
-		.replace("{{HIGHLIGHT_JS}}", hljsJs);
+		.replace("{{JS}}", cachedJs)
+		.replace("{{SESSION_DATA}}", sessionDataBase64);
 }
 
 /**

package/src/core/export-html/template.html

@@ -39,16 +39,8 @@
   </div>
 
   <script id="session-data" type="application/json">{{SESSION_DATA}}</script>
-
-  <!-- Vendored libraries -->
-  <script>{{MARKED_JS}}</script>
-
-  <!-- highlight.js -->
-  <script>{{HIGHLIGHT_JS}}</script>
-
-  <!-- Main application code -->
-  <script>
-{{JS}}
-  </script>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/marked/15.0.4/marked.min.js" integrity="sha512-VmLxPVdDGeR+F0DzUHVqzHwaR4ZSSh1g/7aYXwKT1PAGVxunOEcysta+4H5Utvmpr2xExEPybZ8q+iM9F1tGdw==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js" integrity="sha512-D9gUyxqja7hBtkWpPWGt9wfbfaMGVt9gnyCvYa+jojwwPHLCzUm5i8rpk7vD7wNee9bA35eYIjobYPaQuKS1MQ==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+  <script>{{JS}}</script>
 </body>
 </html>

package/src/core/mcp/client.ts

@@ -25,12 +25,32 @@ import type {
 /** MCP protocol version we support */
 const PROTOCOL_VERSION = "2025-03-26";
 
+/** Default connection timeout in ms */
+const CONNECTION_TIMEOUT_MS = 30_000;
+
 /** Client info sent during initialization */
 const CLIENT_INFO = {
 	name: "pi-coding-agent",
 	version: "1.0.0",
 };
 
+/** Wrap a promise with a timeout */
+function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => reject(new Error(message)), ms);
+		promise.then(
+			(value) => {
+				clearTimeout(timer);
+				resolve(value);
+			},
+			(error) => {
+				clearTimeout(timer);
+				reject(error);
+			},
+		);
+	});
+}
+
 /**
  * Create a transport for the given server config.
  */
@@ -73,24 +93,31 @@ async function initializeConnection(transport: MCPTransport): Promise<MCPInitial
 
 /**
  * Connect to an MCP server.
+ * Has a 30 second timeout to prevent blocking startup.
  */
 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;
-	}
+	const timeoutMs = config.timeout ?? CONNECTION_TIMEOUT_MS;
+
+	const connect = async (): 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;
+		}
+	};
+
+	return withTimeout(connect(), timeoutMs, `Connection to MCP server "${name}" timed out after ${timeoutMs}ms`);
 }
 
 /**

package/src/core/mcp/config.ts

@@ -91,11 +91,17 @@ export interface MCPConfigLocations {
  */
 export function getMCPConfigPaths(cwd: string): MCPConfigLocations {
 	const home = homedir();
+
+	// Project-level: check both mcp.json and .mcp.json (prefer mcp.json if both exist)
+	const mcpJson = join(cwd, "mcp.json");
+	const dotMcpJson = join(cwd, ".mcp.json");
+	const projectPath = existsSync(mcpJson) ? mcpJson : dotMcpJson;
+
 	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"),
+		// Project-level: mcp.json or .mcp.json at project root
+		project: projectPath,
 	};
 }
 
@@ -115,17 +121,157 @@ export function mergeMCPConfigs(...configs: (MCPConfigFile | null)[]): Record<st
 	return result;
 }
 
+/** Options for loading MCP configs */
+export interface LoadMCPConfigsOptions {
+	/** Additional environment variables for expansion */
+	extraEnv?: Record<string, string>;
+	/** Whether to load project-level config (default: true) */
+	enableProjectConfig?: boolean;
+	/** Whether to filter out Exa MCP servers (default: true) */
+	filterExa?: 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[];
+}
+
 /**
  * Load all MCP server configs from standard locations.
  * Returns merged config with project overriding user.
+ *
+ * @param cwd Working directory (project root)
+ * @param options Load options or extraEnv for backwards compatibility
  */
-export function loadAllMCPConfigs(cwd: string, extraEnv?: Record<string, string>): Record<string, MCPServerConfig> {
+export function loadAllMCPConfigs(
+	cwd: string,
+	options?: LoadMCPConfigsOptions | Record<string, string>,
+): LoadMCPConfigsResult {
+	// Support old signature: loadAllMCPConfigs(cwd, extraEnv)
+	const opts: LoadMCPConfigsOptions =
+		options && ("extraEnv" in options || "enableProjectConfig" in options || "filterExa" in options)
+			? (options as LoadMCPConfigsOptions)
+			: { extraEnv: options as Record<string, string> | undefined };
+
+	const enableProjectConfig = opts.enableProjectConfig ?? true;
+	const filterExa = opts.filterExa ?? true;
+
 	const paths = getMCPConfigPaths(cwd);
 
-	const userConfig = paths.user ? loadMCPConfigFile(paths.user, extraEnv) : null;
-	const projectConfig = paths.project ? loadMCPConfigFile(paths.project, extraEnv) : null;
+	const userConfig = paths.user ? loadMCPConfigFile(paths.user, opts.extraEnv) : null;
+	const projectConfig = enableProjectConfig && paths.project ? loadMCPConfigFile(paths.project, opts.extraEnv) : null;
+
+	let configs = mergeMCPConfigs(userConfig, projectConfig);
+	let exaApiKeys: string[] = [];
+
+	if (filterExa) {
+		const result = filterExaMCPServers(configs);
+		configs = result.configs;
+		exaApiKeys = result.exaApiKeys;
+	}
+
+	return { configs, exaApiKeys };
+}
+
+/** 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[];
+}
+
+/**
+ * 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>): ExaFilterResult {
+	const filtered: Record<string, MCPServerConfig> = {};
+	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;
+		}
+	}
 
-	return mergeMCPConfigs(userConfig, projectConfig);
+	return { configs: filtered, exaApiKeys };
 }
 
 /**

package/src/core/mcp/index.ts

@@ -9,19 +9,23 @@
 export { callTool, connectToServer, disconnectServer, listTools, serverSupportsTools } from "./client.js";
 
 // Config
+export type { ExaFilterResult, LoadMCPConfigsOptions, LoadMCPConfigsResult } from "./config.js";
 export {
 	expandEnvVars,
+	extractExaApiKey,
+	filterExaMCPServers,
 	getMCPConfigPaths,
+	isExaMCPServer,
 	loadAllMCPConfigs,
 	loadMCPConfigFile,
 	mergeMCPConfigs,
 	validateServerConfig,
 } from "./config.js";
 // Loader (for SDK integration)
-export type { MCPToolsLoadResult } from "./loader.js";
+export type { MCPToolsLoadOptions, MCPToolsLoadResult } from "./loader.js";
 export { discoverAndLoadMCPTools } from "./loader.js";
 // Manager
-export type { MCPLoadResult } from "./manager.js";
+export type { MCPDiscoverOptions, MCPLoadResult } from "./manager.js";
 export { createMCPManager, MCPManager } from "./manager.js";
 // Tool bridge
 export type { MCPToolDetails } from "./tool-bridge.js";