Exa MCP Server

# `exa-mcp-server` 升级为多账号轮巡机制架构设计报告 ## 1. 项目概述与背景 `exa-mcp-server` 是一个基于 Model Context Protocol (MCP) 的服务器端应用，旨在通过集成 Exa AI 的功能，为 MCP 客户端提供一系列高级工具。现有架构主要依赖单个 Exa AI API Key 进行配置和使用，缺乏多账号轮巡、资源分配与负载均衡能力。本报告旨在设计并实现一个更高效、更智能的多账号轮巡机制，以提高系统的可用性、吞吐量和韧性。 ## 1.1 现有系统架构与 API 设计 ### 现有架构设计 `exa-mcp-server` 是一个基于 Model Context Protocol (MCP) 的服务器端应用，旨在通过集成 Exa AI 的功能，为 MCP 客户端提供一系列高级工具。其核心目标是提供标准化的接口、封装 Exa AI API 的复杂性、支持灵活的工具配置、确保类型安全和参数验证，并提供基础的日志记录和错误处理。 **主要组成部分:** * **MCP Server ([`src/index.ts`](src/index.ts))**: 项目的入口点，负责初始化 MCP 服务器并根据配置动态注册启用的 Exa AI 工具。它使用 `Zod` 进行服务器配置的结构验证。 * **工具模块 ([`src/tools/`](src/tools/))**: 包含所有 Exa AI 工具的具体实现（如 `webSearch.ts`、`companyResearch.ts`、`crawling.ts`、`deepResearchCheck.ts`、`deepResearchStart.ts`、`exaCode.ts`、`linkedInSearch.ts`）。每个工具文件都定义了其输入参数的 `Zod Schema`，封装了与 Exa AI API 的交互逻辑（使用 `axios` 发送 HTTP 请求），并处理响应和错误。 * **类型定义 ([`src/types.ts`](src/types.ts))**: 集中管理所有与 Exa AI API 交互相关的 TypeScript 类型和接口，是数据模型的单一真相来源，确保了类型安全和代码提示。 * **配置模块 ([`src/tools/config.ts`](src/tools/config.ts))**: 定义 Exa AI API 的基本 URL、端点和默认参数。 * **日志模块 ([`src/utils/logger.ts`](src/utils/logger.ts))**: 提供统一的、基于控制台的日志记录功能，便于请求追踪和问题诊断，并支持通过 `config.debug` 环境变量控制调试日志输出。 **架构概览:** ```mermaid graph TD A[MCP Client] -->|Tool Call| B(MCP Server - src/index.ts) B -->|Config Check| C{Enabled Tool?} C -- No --> D[Tool Not Registered Error] C -- Yes --> E(Register Tool - e.g., registerWebSearchTool) E --> F[Tool Implementation - e.g., src/tools/webSearch.ts] F -->|Construct Exa API Request| G(Axios - HTTP Request) G -->|Send Request| H[Exa AI API - https://api.exa.ai] H -->|Exa API Response| G G -->|Process Response| F F -->|Format Result for MCP Client| I(Return to MCP Server) I --> J[MCP Server] J -->|Return Result| A F -- Logger (src/utils/logger.ts) --> K[Console/Error Log] ``` **数据流转核心逻辑:** MCP 客户端通过 `stdio` 或 `shttp` 调用工具。服务器接收请求，检查工具是否启用，然后将请求路由到对应的工具实现。工具构造并发送 HTTP 请求到 Exa AI API，接收响应，格式化结果后返回给 MCP 客户端。日志模块记录整个过程，错误则返回包含 `isError: true` 的错误信息。 ### API 接口说明 所有工具成功执行后，通常会返回一个包含 `type: "text"` 和 `content` 字段的对象，其中 `content` 是包含 Exa AI API 原始数据或精简版本的 JSON 字符串。发生错误时，返回对象将包含 `isError: true` 和 `content` 中的错误信息。 以下是主要工具的接口说明： 1. **Web Search Tool (`web_search_exa`)** * **描述**: 使用 Exa AI 进行网络搜索。 * **参数**: `query` (string, required), `num_results` (number, optional, default: 5), `start_published_date` (string, optional), `end_published_date` (string, optional), `domain` (string, optional), `exclude_domains` (string[], optional), `category` (string, optional), `exclude_categories` (string[], optional), `sort_by` (string, optional, default: "relevance"), `highlights` (boolean, optional, default: false), `text` (boolean, optional, default: false), `url` (boolean, optional, default: false)。 * **返回值**: 包含 `title`, `url`, `publishedDate`, `highlights`, `text` 等字段的搜索结果数组。 2. **Company Research Tool (`company_research_exa`)** * **描述**: 对特定公司进行研究。 * **参数**: `company_name` (string, required), `num_results` (number, optional, default: 5), `highlights` (boolean, optional, default: false), `text` (boolean, optional, default: false), `url` (boolean, optional, default: false)。 * **返回值**: 同 `web_search_exa` 的结果结构，但内容侧重于公司信息。 3. **Crawling Tool (`crawl_exa`)** * **描述**: 抓取指定 URL 的内容。 * **参数**: `url` (string, required)。 * **返回值**: 包含 `url`, `title`, `text`, `html` 字段的对象。 4. **LinkedIn Search Tool (`linkedin_search_exa`)** * **描述**: 在 LinkedIn 上搜索人物或公司。 * **参数**: `query` (string, required), `search_type` (string, optional, default: "people"), `num_results` (number, optional, default: 5)。 * **返回值**: 包含 `name`, `profileUrl`, `headline`, `company` 等字段的搜索结果数组。 5. **Deep Research Start Tool (`deep_research_start_exa`)** * **描述**: 启动一个深度研究任务。 * **参数**: `query` (string, required)。 * **返回值**: 包含 `researchId`, `status` ("started"), `message` 字段的对象。 6. **Deep Research Check Tool (`deep_research_check_exa`)** * **描述**: 检查一个深度研究任务的状态和结果。 * **参数**: `research_id` (string, required)。 * **返回值**: * **进行中**: 包含 `researchId`, `status` ("in_progress"), `progress`, `message` 字段。 * **已完成**: 包含 `researchId`, `status` ("completed"), `result` (内含 `summary` 和 `sources` 数组) 字段。 * **失败**: 包含 `researchId`, `status` ("failed"), `message` 字段。 7. **Exa Code Tool (`exa_code_exa`)** * **描述**: 使用 Exa AI 进行代码上下文搜索。 * **参数**: `query` (string, required), `num_results` (number, optional, default: 5), `repo_url` (string, optional)。 * **返回值**: 包含 `repo`, `path`, `language`, `code`, `highlights` 等字段的代码搜索结果数组。 ## 1.2 技术栈对比 ### 升级前的技术栈 根据 `mydocs/kilo.md` 和现有代码分析，`exa-mcp-server` 升级前的核心技术栈如下： * **语言:** TypeScript * **运行时:** Node.js * **核心协议:** `@modelcontextprotocol/sdk` (MCP SDK) * **HTTP 客户端:** `axios` * **数据验证:** `zod` * **包管理:** `npm` * **容器化:** Docker (可选，用于部署) * **配置管理:** 环境变量 (`EXA_API_KEY`) 和简单的配置文件 (`src/tools/config.ts`) * **日志:** 基于控制台的简单日志 (`src/utils/logger.ts`) ### 升级后的技术栈 在引入多账号轮巡和负载均衡功能后，根据本报告的设计，`exa-mcp-server` 的技术栈将得到增强，新增或强化的主要技术包括： * **语言:** TypeScript * **运行时:** Node.js * **核心协议:** `@modelcontextprotocol/sdk` (MCP SDK) * **HTTP 客户端:** `axios` * **数据验证:** `zod` * **包管理:** `npm` * **容器化:** Docker (可选，用于部署) * **并发控制:** `p-limit` (用于 `ConcurrencyLimiter`) * **异步锁:** `async-mutex` (用于 `ExaKeyManager` 的并发安全) * **熔断器:** `opossum` (或类似库，用于熔断与降级) * **日志系统:** `winston` 或 `pino` (增强的结构化日志，用于 `LoggingService`) * **监控与告警:** `prom-client` (用于暴露 Prometheus 指标，集成 Grafana 和 Alertmanager) * **秘密管理:** AWS Secrets Manager, Azure Key Vault, HashiCorp Vault (生产环境推荐，用于 API Key 安全存储) ## 2. 架构总览 引入多账号轮巡机制后，`exa-mcp-server` 的架构将从单一 API Key 直接调用模式转变为一个健壮、可扩展的代理服务，具备智能路由、负载均衡、错误处理和重试能力。 ```mermaid graph TD A[MCP Client Request] --> B(MCP Server - src/index.ts) B --> C(ConcurrencyLimiter) C -- Permitted Request --> D(SmartRoutingMiddleware) D -- Select Key (Strategy) --> E[ExaKeyManager] E -- Selected Key (e.g., sk-keyX) --> D D -- (Optional) Select Proxy --> F[ProxyManager] F -- Selected Proxy --> D D --> G(ExaAPIService: Call Exa AI API) G --> H[Exa AI API] H --> G G -- Response/Error --> I(ErrorHandler) I -- Retryable Error --> J(RetryHandler) J -- Re-select Key/Proxy & Re-invoke --> D I -- Final Response/Error --> B B --> K[MCP Client Response] subgraph Core Services E F ConfigService(ConfigService: Centralized Config) LoggingService(LoggingService: Enhanced Logging) MonitoringSystem(MonitoringSystem: Metrics & Alerts) ConfigService -- Provides Config --> E ConfigService -- Provides Config --> F ConfigService -- Provides Config --> C ConfigService -- Provides Config --> D ConfigService -- Provides Config --> G ConfigService -- Provides Config --> I ConfigService -- Provides Config --> J E -- Logs & Metrics --> LoggingService E -- Logs & Metrics --> MonitoringSystem F -- Logs & Metrics --> LoggingService F -- Logs & Metrics --> MonitoringSystem G -- Logs & Metrics --> LoggingService G -- Logs & Metrics --> MonitoringSystem I -- Logs & Metrics --> LoggingService I -- Logs & Metrics --> MonitoringSystem J -- Logs & Metrics --> LoggingService J -- Logs & Metrics --> MonitoringSystem end subgraph Existing Tools L[src/tools/webSearch.ts] M[src/tools/crawling.ts] N[...] D -- Route to Tool Handler --> L L -- Calls ExaAPIService --> G D -- Route to Tool Handler --> M M -- Calls ExaAPIService --> G D -- Route to Tool Handler --> N N -- Calls ExaAPIService --> G end ``` ## 3. 多账号管理方案 ### 3.1 API Key 存储与加载 * **安全存储：** * **环境变量：** 支持 `EXA_API_KEY` (兼容单个 Key) 和 `EXA_API_KEYS` (JSON 数组，支持加权配置)。 * **配置文件：** `config/keys.json` (不应提交到版本控制)。 * **秘密管理服务：** 生产环境推荐集成 AWS Secrets Manager, Azure Key Vault, HashiCorp Vault。 * **加载机制：** `ConfigService` 在启动时按优先级（秘密管理服务 > 环境变量 > 配置文件）加载 Key，并传递给 `ExaKeyManager`。 ### 3.2 Key 结构定义 ```typescript interface ExaApiKey { id: string; // 唯一标识符，可以是 Key 的哈希值或部分字符串 key: string; // 实际的 API Key status: 'enabled' | 'disabled' | 'faulty' | 'cooling_down'; // 启用、禁用、故障、冷却中 weight: number; // 加权轮询的权重 lastUsed: number | null; // 上次使用时间戳 failures: number; // 连续失败次数 rateLimitReset: number | null; // 速率限制重置时间戳 concurrency: number; // 当前并发请求数 priority: number; // 可选，优先级，用于更复杂的调度 metadata?: Record<string, any>; // 可选，其他元数据 } ``` ### 3.3 动态管理与 `ExaKeyManager` 职责 * **增删改查：** `ExaKeyManager` 提供动态添加、删除、启用/禁用 Key 的方法，可通过配置热加载或管理 API 触发。 * **状态更新：** `ExaKeyManager` 根据 API 调用结果 (成功、失败、速率限制) 更新 Key 状态 (`faulty`, `cooling_down`, `enabled`)。 * **健康检查：** 后台任务定期检查 `faulty` 或 `cooling_down` 的 Key，成功后恢复为 `enabled`。 * **并发安全：** 使用锁机制 (`async-mutex`) 确保并发环境下的数据一致性。 ## 4. 资源分配策略 `ExaKeyManager` 将实现以下策略来选择最合适的 API Key： 1. **轮询 (Round-Robin)：** 按顺序循环使用 `enabled` 状态的 Key。适用于 Key 性能、配额相似的场景。 2. **加权轮询 (Weighted Round-Robin)：** 根据 Key 的 `weight` 属性进行分配，权重越高，选中概率越大。适用于 Key 性能、配额有差异的场景。 3. **基于负载的分配 (Load-Based)：** 根据 Key 的实时使用情况动态分配，包括： * **并发请求数 (`concurrency`)：** 优先选择 `concurrency` 最低的 Key。 * **错误率 (`failures`)：** 优先选择错误率低的 Key。 * **速率限制 (`rateLimitReset`)：** 避免选择处于 `cooling_down` 状态的 Key。 * **综合评分：** 结合多指标计算综合评分，选择最优 Key。 4. **熔断与降级 (Circuit Breaker and Fallback)：** 当 Key 连续失败或触发速率限制时，自动熔断 (`faulty`, `cooling_down`) 并切换到其他可用 Key。经过冷却期后，允许少量试探性请求恢复。 ## 5. 负载均衡机制 负载均衡通过 `ConcurrencyLimiter` 和 `SmartRoutingMiddleware` 的协同实现： 1. **`ConcurrencyLimiter`：** * **职责：** 控制整个 `exa-mcp-server` 实例的全局并发请求数量，防止系统过载。 * **实现：** 使用全局信号量或令牌桶算法 (如 `p-limit`)。 2. **`SmartRoutingMiddleware`：** * **职责：** 在 `ConcurrencyLimiter` 允许请求通过后，根据配置策略和 Key 状态，智能地选择一个最合适的 Exa AI API Key (通过 `ExaKeyManager`) 和可选的代理 IP (通过 `ProxyManager`)。 * **Key 绑定 (可选)：** 可根据请求特性 (如 `userId`) 进行哈希，将请求路由到特定 Key 和代理，保持会话粘性。 * **请求转发：** 将选定的 Key 和代理注入请求，转发给 `ExaAPIService`。 3. **`ExaAPIService`：** 接收注入的 Key 和代理信息，实际执行 HTTP 请求到 Exa AI API。 4. **错误处理与重试：** `ErrorHandler` 识别可重试错误，`RetryHandler` 在重试时会再次调用 `SmartRoutingMiddleware` 获取新的 Key/代理，实现故障 Key 的自动切换和负载的动态调整。 ## 6. 架构变更 * **新增模块：** * `ConfigService` (`src/config/index.ts` 或 `src/services/ConfigService.ts`) * `ExaKeyManager` (`src/services/ExaKeyManager.ts`) * `ProxyManager` (可选，`src/services/ProxyManager.ts`) * `ConcurrencyLimiter` (`src/middleware/ConcurrencyLimiter.ts`) * `SmartRoutingMiddleware` (`src/middleware/SmartRoutingMiddleware.ts`) * `ErrorHandler` (`src/middleware/ErrorHandler.ts`) * `RetryHandler` (`src/middleware/RetryHandler.ts`) * `ExaAPIService` (`src/services/ExaAPIService.ts`) * `MonitoringSystem` (`src/services/MonitoringService.ts`) * **修改模块：** * `src/index.ts`：初始化新服务，调整请求处理链，引入中间件。 * `src/types.ts`：新增 Key、代理、错误等类型定义。 * `src/tools/config.ts`：不再包含 API Key 配置。 * `src/tools/*.ts`：不再直接调用 `axios`，而是通过 `ExaAPIService` 调用 API。 * `src/utils/logger.ts`：重构为更强大的 `LoggingService`。 ## 7. 核心技术实现细节 * **`ConfigService`：** 单例模式，从环境变量/配置文件/秘密管理服务加载配置，使用 Zod 验证。 * **`ExaKeyManager`：** 使用 `Map` 存储 Key，实现轮询、加权轮询、基于负载的 Key 选择算法，通过 `async-mutex` 保证并发安全，后台任务进行健康检查和状态恢复。 * **`ProxyManager`：** (可选) 存储代理信息，实现 Key-Proxy 绑定，周期性健康检查。 * **`ConcurrencyLimiter`：** 使用 `p-limit` 限制全局并发请求。 * **`SmartRoutingMiddleware`：** 获取 Key/代理，注入请求上下文，调用 `ExaAPIService`。 * **`ExaAPIService`：** 封装 `axios` 调用，设置 Key/代理/超时，更新 Key 的 `concurrency`。 * **`ErrorHandler`：** 捕获 `ExaAPIService` 错误，分类为可重试/不可重试，规范化错误格式，通知 `ExaKeyManager`/`ProxyManager` 更新状态。 * **`RetryHandler`：** 处理可重试错误，实现指数退避、Key/代理切换和熔断逻辑，重新调用 `ExaAPIService`。 * **日志与监控：** `LoggingService` (基于 `winston`/`pino`) 提供结构化日志和敏感信息脱敏。`MonitoringSystem` (基于 `prom-client`) 暴露关键指标 (请求量、延迟、Key 状态、并发数等)，集成 Grafana 和 Alertmanager。 ## 8. 潜在风险评估与解决方案 1. **API Key 失效/泄漏：** 秘密管理服务、动态管理、脱敏处理、定期轮换。 2. **速率限制与配额耗尽：** `ConcurrencyLimiter`、基于负载的分配、熔断与降级、智能重试、监控告警。 3. **Exa AI 对多账号使用的检测：** `ProxyManager` (Key-Proxy 绑定)、请求头随机化、会话粘性、IP 轮换、异常行为监控。 4. **性能瓶颈：** 优化 Key 选择算法、异步操作、合理配置并发限制、缓存。 5. **复杂性增加与维护成本：** 模块化设计、完善文档、自动化测试、可观测性、代码审查。 6. **错误处理不完善：** `ErrorHandler` 统一处理、错误码映射、详细日志。 ## 9. 测试计划与验证策略 * **单元测试：** 针对每个模块 (ConfigService, ExaKeyManager, ErrorHandler, RetryHandler 等) 进行独立逻辑验证。 * **集成测试：** 模拟 MCP 客户端请求，验证模块间协同工作的正确性，包括 Key 轮巡、错误处理、重试等完整请求流。 * **性能测试：** 使用 JMeter, k6 等工具进行基准测试、负载测试、压力测试，评估吞吐量、延迟和资源利用率。 * **故障注入测试：** 模拟 Key 失效、速率限制、代理失效等场景，验证系统韧性。 * **安全测试：** 验证 API Key 存储安全、日志脱敏、输入验证等。 * **验证策略：** 持续集成 (CI)、监控告警、日志分析、灰度发布。 ## 10. 部署与回滚方案 * **部署策略：** * **容器化部署：** 更新 Dockerfile，包含新增依赖和环境变量配置。 * **蓝绿部署：** 快速回滚，零停机时间，需要双倍资源。 * **金丝雀发布：** 逐步切换流量，风险较低，但部署和监控复杂。 * **推荐：** 核心服务优先蓝绿部署，资源有限或需精细控制时采用金丝雀发布。 * **回滚方案：** * **自动化回滚：** 部署流程包含自动回滚机制。 * **触发条件：** 监控告警、健康检查失败、手动触发。 * **回滚流程：** 蓝绿部署只需切换负载均衡流量，金丝雀发布则回退流量并销毁金丝雀实例。 * **数据兼容性：** 确保新旧版本数据兼容。 * **CI/CD：** 将构建、测试、部署、回滚流程自动化，减少人为错误。 ## 11. 未来的优化方向 1. **更高级的 Key 调度策略：** 成本优化、用户/租户隔离、基于请求内容的路由、预测性调度。 2. **动态 Key 管理界面/API：** 实时查看/管理 Key 状态、调整权重。 3. **智能代理管理增强：** 代理池动态扩展、地理位置路由、更精细的代理健康检查。 4. **细粒度权限控制：** 针对不同 MCP 客户端的工具/Key 组访问控制。 5. **缓存机制：** 引入缓存层减少对 Exa AI API 的实际调用。 6. **异步处理与消息队列：** 针对长时间任务，提高可伸缩性和响应性。 7. **更好的可观测性工具集成：** 分布式追踪、更丰富的自定义指标。 8. **自动 Key 轮换与续期：** 减少人工干预。 9. **成本报告与优化：** 基于成本数据优化 Key 调度策略。