feat: switch exa MCP to local environment-based configuration

- Change exa MCP from remote URL-based to local exa-mcp-server package
- Use environment variable (EXA_API_KEY) instead of URL parameter for API key
- Update buildMcpServerConfig to support environment variable configuration
- Add comprehensive tests for environment variable-based MCP services
- Improve security by avoiding API key exposure in command arguments

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: WitMiao

.claude/plan/exa-mcp-config-update.md

@@ -0,0 +1,37 @@
+# Exa MCP配置格式更新计划
+
+## 任务背景
+将exa MCP服务配置从URL参数方式改为环境变量方式，提高安全性和规范性。
+
+## 目标配置格式
+```json
+{
+  "exa": {
+    "command": "npx",
+    "args": ["-y", "exa-mcp-server"],
+    "env": {
+      "EXA_API_KEY": "your-api-key-here"
+    }
+  }
+}
+```
+
+## 实施步骤
+
+### 1. 修改MCP服务定义
+- 文件：`src/constants.ts`
+- 修改exa服务配置结构
+
+### 2. 更新配置构建逻辑  
+- 文件：`src/utils/mcp.ts`
+- 增强buildMcpServerConfig函数支持环境变量
+
+### 3. 更新类型定义
+- 检查并确保类型正确
+
+### 4. 测试验证
+- 运行类型检查和测试
+- 验证配置生成正确
+
+## 执行时间
+2025-08-08

CLAUDE.md

@@ -9,6 +9,7 @@ ZCF (Zero-Config Claude-Code Flow) is a CLI tool that automatically configures C
 ## Development Guidelines
 
 - **Documentation Language**: Except for README_zh, all code comments and documentation should be written in English
+- When writing tests, first verify if relevant test files already exist to avoid unnecessary duplication
 
 ## Development Commands
 

src/commands/init.ts

@@ -322,7 +322,7 @@ export async function init(options: InitOptions = {}) {
               }
 
               if (apiKey) {
-                config = buildMcpServerConfig(service.config, apiKey, service.apiKeyPlaceholder);
+                config = buildMcpServerConfig(service.config, apiKey, service.apiKeyPlaceholder, service.apiKeyEnvVar);
               } else {
                 // Skip this service if no API key provided
                 continue;

src/constants.ts

@@ -467,12 +467,14 @@ export const MCP_SERVICES: McpService[] = [
       'zh-CN': '请输入 Exa API Key',
       en: 'Enter Exa API Key',
     },
-    apiKeyPlaceholder: 'YOUR_EXA_API_KEY',
+    apiKeyEnvVar: 'EXA_API_KEY',
     config: {
       type: 'stdio',
       command: 'npx',
-      args: ['-y', 'mcp-remote', 'https://mcp.exa.ai/mcp?exaApiKey=YOUR_EXA_API_KEY'],
-      env: {},
+      args: ['-y', 'exa-mcp-server'],
+      env: {
+        EXA_API_KEY: 'YOUR_EXA_API_KEY',
+      },
     },
   },
 ];

src/types.ts

@@ -5,6 +5,7 @@ export interface McpService {
   requiresApiKey: boolean
   apiKeyPrompt?: { en: string; 'zh-CN': string }
   apiKeyPlaceholder?: string
+  apiKeyEnvVar?: string
   config: McpServerConfig
 }
 

src/utils/features.ts

@@ -207,7 +207,7 @@ export async function configureMcpFeature(scriptLang: SupportedLang) {
         });
 
         if (apiKey) {
-          config = buildMcpServerConfig(service.config, apiKey, service.apiKeyPlaceholder);
+          config = buildMcpServerConfig(service.config, apiKey, service.apiKeyPlaceholder, service.apiKeyEnvVar);
         } else {
           continue;
         }

src/utils/mcp.ts

@@ -50,7 +50,8 @@ function applyPlatformCommand(config: McpServerConfig): void {
 export function buildMcpServerConfig(
   baseConfig: McpServerConfig,
   apiKey?: string,
-  placeholder: string = 'YOUR_EXA_API_KEY'
+  placeholder: string = 'YOUR_EXA_API_KEY',
+  envVarName?: string
 ): McpServerConfig {
   // Deep clone the config to avoid mutation
   const config = deepClone(baseConfig);
@@ -62,12 +63,17 @@ export function buildMcpServerConfig(
     return config;
   }
 
-  // Replace API key placeholder in args if exists
+  // New approach: If environment variable name is specified, set it directly
+  if (envVarName && config.env) {
+    config.env[envVarName] = apiKey;
+    return config; // Return early for env-based configuration
+  }
+
+  // Legacy approach: Replace placeholder in args and URL
   if (config.args) {
     config.args = config.args.map((arg: string) => arg.replace(placeholder, apiKey));
   }
 
-  // Replace in URL if exists
   if (config.url) {
     config.url = config.url.replace(placeholder, apiKey);
   }

test/unit/utils/mcp.test.ts

@@ -11,7 +11,7 @@ import {
 import * as jsonConfig from '../../../src/utils/json-config';
 import * as platform from '../../../src/utils/platform';
 import * as objectUtils from '../../../src/utils/object-utils';
-import { ClAUDE_CONFIG_FILE, CLAUDE_DIR } from '../../../src/constants';
+import { ClAUDE_CONFIG_FILE, CLAUDE_DIR, MCP_SERVICES } from '../../../src/constants';
 
 vi.mock('../../../src/utils/json-config');
 vi.mock('../../../src/utils/platform');
@@ -185,6 +185,39 @@ describe('mcp utilities', () => {
 
       expect(result.args).toEqual(['--key', 'api-key']);
     });
+
+    it('should set environment variable when envVarName is provided', () => {
+      const baseConfig = { 
+        type: 'stdio' as const,
+        command: 'npx', 
+        args: ['-y', 'exa-mcp-server'],
+        env: { EXA_API_KEY: 'placeholder' }
+      };
+      vi.mocked(objectUtils.deepClone).mockReturnValue({ ...baseConfig });
+      vi.mocked(platform.isWindows).mockReturnValue(false);
+
+      const result = buildMcpServerConfig(baseConfig, 'test-api-key', 'placeholder', 'EXA_API_KEY');
+
+      expect(result.env).toEqual({ EXA_API_KEY: 'test-api-key' });
+    });
+
+    it('should handle environment variable config on Windows', () => {
+      const baseConfig = { 
+        type: 'stdio' as const,
+        command: 'npx', 
+        args: ['-y', 'exa-mcp-server'],
+        env: { EXA_API_KEY: 'placeholder' }
+      };
+      vi.mocked(objectUtils.deepClone).mockReturnValue({ ...baseConfig });
+      vi.mocked(platform.isWindows).mockReturnValue(true);
+      vi.mocked(platform.getMcpCommand).mockReturnValue(['cmd', '/c', 'npx']);
+
+      const result = buildMcpServerConfig(baseConfig, 'test-api-key', 'placeholder', 'EXA_API_KEY');
+
+      expect(result.command).toBe('cmd');
+      expect(result.args).toEqual(['/c', 'npx', '-y', 'exa-mcp-server']);
+      expect(result.env).toEqual({ EXA_API_KEY: 'test-api-key' });
+    });
   });
 
   describe('fixWindowsMcpConfig', () => {
@@ -224,5 +257,52 @@ describe('mcp utilities', () => {
     });
   });
 
-  // Extended Tests
+  describe('Exa MCP Service Integration', () => {
+    beforeEach(() => {
+      // Mock deepClone to return a proper copy
+      vi.mocked(objectUtils.deepClone).mockImplementation(obj => JSON.parse(JSON.stringify(obj)));
+    });
+
+    it('should have exa service configured with environment variable', () => {
+      const exaService = MCP_SERVICES.find(s => s.id === 'exa');
+      
+      expect(exaService).toBeDefined();
+      expect(exaService!.config.command).toBe('npx');
+      expect(exaService!.config.args).toContain('exa-mcp-server');
+      expect(exaService!.config.env).toHaveProperty('EXA_API_KEY');
+      expect(exaService!.apiKeyEnvVar).toBe('EXA_API_KEY');
+    });
+
+    it('should build exa service config with API key in environment', () => {
+      const exaService = MCP_SERVICES.find(s => s.id === 'exa');
+      vi.mocked(platform.isWindows).mockReturnValue(false);
+
+      const config = buildMcpServerConfig(
+        exaService!.config,
+        'test-exa-key-123',
+        undefined,
+        exaService!.apiKeyEnvVar
+      );
+
+      expect(config.env).toEqual({ EXA_API_KEY: 'test-exa-key-123' });
+      expect(config.args).toEqual(['-y', 'exa-mcp-server']);
+    });
+
+    it('should handle exa service on Windows platform', () => {
+      const exaService = MCP_SERVICES.find(s => s.id === 'exa');
+      vi.mocked(platform.isWindows).mockReturnValue(true);
+      vi.mocked(platform.getMcpCommand).mockReturnValue(['cmd', '/c', 'npx']);
+
+      const config = buildMcpServerConfig(
+        exaService!.config,
+        'test-key',
+        undefined,
+        exaService!.apiKeyEnvVar
+      );
+
+      expect(config.command).toBe('cmd');
+      expect(config.args).toEqual(['/c', 'npx', '-y', 'exa-mcp-server']);
+      expect(config.env).toEqual({ EXA_API_KEY: 'test-key' });
+    });
+  });
 });