Exa MCP Server

# `development_guide.md` ## 1. 项目概览 ### 1.1 项目的主要功能和用途 `exa-mcp-server` 是一个基于 Model Context Protocol (MCP) 的服务器端应用，旨在通过集成 Exa AI 的强大功能，为 MCP 客户端（如 Claude AI）提供一系列高级工具。其主要功能和用途包括： * **增强 AI 助手的外部交互能力**: 允许 AI 模型通过结构化的 API 调用与外部世界进行交互，从而增强其信息获取和处理能力。 * **提供标准化接口**: 为 MCP 客户端调用 Exa AI 服务提供一套标准化的接口。 * **封装 Exa AI API 复杂性**: 封装 Exa AI API 的复杂性，提供简洁易用的工具函数。 * **多样化的研究和信息检索工具**: 提供包括网络搜索 (`webSearch.ts`), 网页抓取 (`crawling.ts`), 深度研究 (`deepResearchStart.ts`, `deepResearchCheck.ts`), 公司研究 (`companyResearch.ts`), LinkedIn 搜索 (`linkedInSearch.ts`) 以及 Exa 代码搜索 (`exaCode.ts`) 等功能。 * **支持灵活的工具配置**: 允许灵活启用/禁用不同的工具。 * **安全性与稳定性**: 确保请求的类型安全和参数验证，并提供基础的日志记录和错误处理机制。 ### 1.2 核心模块/组件及其职责 项目的核心模块/组件及其职责如下： * **MCP 服务器核心 (`src/index.ts`)**: 作为服务器的入口点，负责接收 MCP 客户端的工具调用请求，并根据配置进行工具路由和检查。 * **工具注册器**: 在 [`src/index.ts`](src/index.ts) 中实现，管理所有可用的 Exa AI 工具，并根据请求将任务分发到相应的工具实现。 * **工具实现 (`src/tools/*.ts`)**: 位于 [`src/tools/`](src/tools/) 目录下，每个文件对应一个具体的 Exa AI 工具，例如 [`webSearch.ts`](src/tools/webSearch.ts)、[`crawling.ts`](src/tools/crawling.ts)、[`exaCode.ts`](src/tools/exaCode.ts) 等。它们负责构造并发送 HTTP 请求到 Exa AI API，解析响应并格式化结果。 * **配置模块 (`src/tools/config.ts`)**: 集中管理 Exa AI API 相关的配置，如 `baseURL`、`endpoints`、API Key 列表、代理列表、失败阈值和限流参数等。 * **类型定义 (`src/types.ts`)**: 定义全局类型，特别是 Exa AI API 相关的请求和响应接口，并通过 Zod 进行运行时验证，确保类型安全。 * **日志模块 (`src/utils/logger.ts`)**: 提供日志记录功能，记录请求的生命周期和错误信息，并对敏感信息（如 API Key）进行脱敏处理。 * **工具函数 (`src/utils/`)**: 包含通用的工具函数，如日志记录 (`logger.ts`)。 ### 1.3 主要技术栈 `exa-mcp-server` 项目使用的主要技术栈包括： * **TypeScript**: 作为主要的开发语言，提供类型安全和更好的代码可维护性。 * **Node.js**: 作为运行时环境，利用其异步非阻塞特性处理并发请求。 * **`@modelcontextprotocol/sdk`**: 用于实现 MCP 服务器的核心功能和协议交互。 * **`axios`**: 用于发送 HTTP 请求到 Exa AI API。 * **`zod`**: 用于进行运行时的数据验证，确保请求和响应的数据结构符合预期。 * **`npm`**: 用于项目依赖管理和脚本执行。 * **`Docker`**: 用于容器化部署。 * **`Smithery`**: 可能用于构建和发布 MCP 服务器。 ## 2. 优化设计方案 ### 2.1 架构概览 **优化后的 `exa-mcp-server` 系统架构描述** **1. 概述** 优化后的 `exa-mcp-server` 旨在构建一个高效、高可用且具备反检测能力的 Exa AI API 代理服务。该架构借鉴了 `gemini-balance` 的成功经验，并针对 `exa-mcp-server` 的特定需求进行了扩展和优化。系统核心在于智能管理 API Key 和代理，同时提供强大的容错、并发控制和全面的可观测性。 **2. 核心组件及其交互** * **API Gateway/Router**: * **职责**: 作为系统的入口点，接收所有来自用户的 Exa AI API 请求。它负责初步的请求解析、认证（如果需要）和将请求路由到后续处理组件。 * **交互**: 将请求转发给 `ConcurrencyLimiter` 进行并发控制，并通过 `SmartRoutingMiddleware` 进行智能路由。 * **ConcurrencyLimiter (并发限制器)**: * **职责**: 控制系统同时处理的请求数量，防止系统过载。它维护一个全局请求队列和并发限制，确保请求在 Exa AI API 的承载能力范围内被处理。 * **交互**: 从 `API Gateway/Router` 接收请求，并将受控的请求传递给 `SmartRoutingMiddleware`。 * **SmartRoutingMiddleware (智能路由中间件)**: * **职责**: 根据请求的特性（例如，用户 ID、请求类型）和当前系统状态，决定如何智能地选择 API Key 和代理。它与 `ExaKeyManager` 和 `ProxyManager` 紧密协作。 * **交互**: 从 `ConcurrencyLimiter` 接收请求，向 `ExaKeyManager` 请求 API Key，向 `ProxyManager` 请求代理 IP，并将这些信息传递给 `ExaAPIService`。 * **ExaKeyManager (Exa AI API Key 管理器)**: * **职责**: 负责 Exa AI API Key 的生命周期管理、健康检查、智能轮训和状态维护。它维护一个 Key 池，跟踪每个 Key 的使用情况、失败次数和活跃状态。 * **Key 存储与轮训**: 使用无限循环迭代器实现 Key 的无缝轮训。 * **失败计数与无效 Key**: 维护每个 Key 的连续失败计数器，当达到阈值时标记为无效并暂时移除。 * **健康检查与恢复**: 后台任务定期检查无效 Key，成功后重新激活。 * **并发安全**: 内部使用锁机制确保并发环境下的数据一致性。 * **交互**: 接收来自 `SmartRoutingMiddleware` 和 `RetryHandler` 的 Key 请求和状态更新。 * **ProxyManager (代理管理器)**: * **职责**: 维护一个高质量的代理 IP 池，并负责代理的健康检查、选择和管理。它支持“一个 API Key 对应一个代理 IP”的绑定策略。 * **代理 IP 池**: 管理可用的代理 IP 列表。 * **Key-Proxy 绑定**: 根据 Key 的哈希值稳定绑定代理 IP，降低检测风险。 * **代理健康检查**: 定期检查代理的可用性和延迟。 * **交互**: 接收来自 `SmartRoutingMiddleware` 和 `RetryHandler` 的代理请求和状态更新。 * **ExaAPIService (Exa AI API 服务)**: * **职责**: 封装与 Exa AI API 的具体交互逻辑，包括构建请求、发送请求和解析响应。它是实际与外部 Exa AI API 通信的组件。 * **交互**: 从 `SmartRoutingMiddleware` 接收带有 API Key 和代理信息的请求，向外部 Exa AI API 发送请求，并将原始响应或错误返回给 `ErrorHandler`。 * **ErrorHandler (错误处理器)**: * **职责**: 捕获并规范化 Exa AI API 返回的各种错误（HTTP 状态码、API 错误码等）。它区分可重试错误和不可重试错误。 * **统一错误处理**: 将外部错误转换为内部定义的错误类型。 * **交互**: 从 `ExaAPIService` 接收响应和错误。对于可重试错误，通知 `RetryHandler`；对于不可重试错误或重试耗尽的错误，将错误记录到 `LoggingService` 和 `MonitoringSystem`，并返回给 `API Gateway/Router`。 * **RetryHandler (重试处理器)**: * **职责**: 为可重试错误提供智能重试机制，包括指数退避、切换 Key 或代理。 * **智能重试**: 对可重试错误采用指数退避策略。 * **与 KeyManager/ProxyManager 协作**: 当重试失败时，通知 `ExaKeyManager` 和 `ProxyManager` 更新 Key/代理状态，并尝试获取新的 Key/代理进行重试。 * **熔断机制**: 当 Key 或代理连续失败达到阈值时，触发熔断。 * **交互**: 从 `ErrorHandler` 接收重试请求，并与 `ExaKeyManager` 和 `ProxyManager` 交互获取新的资源，然后再次调用 `ExaAPIService`。 * **ConfigService (配置服务)**: * **职责**: 集中管理所有系统配置，包括 API Key 列表、代理列表、`MAX_FAILURES` 阈值、限流参数等。支持环境变量和潜在的动态配置加载。 * **集中式配置**: 提供统一的配置访问接口。 * **环境变量支持**: 从环境变量加载敏感信息。 * **配置验证**: 启动时校验配置的正确性。 * **交互**: 为所有需要配置信息的组件提供配置数据。 * **LoggingService (日志服务)**: * **职责**: 负责系统所有日志的记录，包括结构化日志、API Key 脱敏和不同日志级别的管理。 * **结构化日志**: 记录关键信息。 * **API Key 脱敏**: 防止敏感信息泄露。 * **日志级别**: 根据需求控制日志详细程度。 * **交互**: 接收来自所有组件的日志信息。 * **MonitoringSystem (监控系统)**: * **职责**: 收集并展示系统各项关键指标，如请求量、延迟、Key/代理状态、错误率和并发数。 * **监控指标**: 提供实时数据。 * **交互**: 接收来自 `ErrorHandler`、`ExaKeyManager`、`ProxyManager` 等组件的监控数据。 * **AlertingSystem (告警系统)**: * **职责**: 基于 `MonitoringSystem` 收集的指标设置告警规则，并在异常情况发生时及时通知运维人员。 * **告警规则**: 定义触发告警的条件。 * **通知机制**: 通过邮件、短信或其他渠道发送告警。 * **交互**: 从 `MonitoringSystem` 获取指标数据，并在满足条件时触发告警。 **3. 数据流与控制流** 用户请求首先到达 `API Gateway/Router`，经过 `ConcurrencyLimiter` 进行并发控制后，由 `SmartRoutingMiddleware` 智能选择合适的 Exa AI API Key（通过 `ExaKeyManager`）和代理 IP（通过 `ProxyManager`）。随后，`ExaAPIService` 使用这些资源与外部 Exa AI API 进行通信。API 响应或错误返回给 `ErrorHandler` 进行统一处理，可重试的错误将由 `RetryHandler` 负责智能重试，并在必要时切换 Key 或代理。所有组件的运行状态和关键事件都通过 `LoggingService` 记录，并通过 `MonitoringSystem` 收集指标，最终由 `AlertingSystem` 进行告警。`ConfigService` 为所有组件提供统一的配置管理。 **4. 非容器化部署考虑** 该架构设计不依赖于容器化技术（如 Docker）。所有组件将作为独立的进程或模块在宿主机操作系统上直接运行。这意味着： * **部署**: 组件的部署将通过传统的服务安装、脚本启动等方式进行。 * **资源管理**: 资源隔离和管理将依赖于操作系统层面的机制。 * **扩展性**: 扩展性主要通过增加物理或虚拟服务器实例，并在其上部署更多服务实例来实现。负载均衡器（可能作为 `API Gateway/Router` 的一部分或独立组件）将负责将请求分发到不同的服务实例。 ```mermaid graph TD UserRequest[用户请求] --> API_Gateway(API Gateway/Router) API_Gateway --> ConcurrencyLimiter(并发限制器) ConcurrencyLimiter --> SmartRoutingMiddleware(智能路由中间件) SmartRoutingMiddleware --> ExaKeyManager[ExaKeyManager: Key管理与轮训] SmartRoutingMiddleware --> ProxyManager[ProxyManager: 代理IP管理] ExaKeyManager -- 提供 Key --> SmartRoutingMiddleware ProxyManager -- 提供代理IP --> SmartRoutingMiddleware SmartRoutingMiddleware --> ExaAPIService(ExaAPIService: Exa AI API交互) ExaAPIService --> Exa_AI_API[外部 Exa AI API] Exa_AI_API --> ExaAPIService ExaAPIService --> ErrorHandler(ErrorHandler: 错误处理器) ErrorHandler -- 可重试错误 --> RetryHandler(RetryHandler: 智能重试机制) RetryHandler -- 请求新Key/代理 --> ExaKeyManager RetryHandler -- 请求新Key/代理 --> ProxyManager RetryHandler -- 重新调用 --> ExaAPIService ErrorHandler -- 不可重试/重试耗尽错误 --> LoggingService(LoggingService: 日志服务) ErrorHandler -- 不可重试/重试耗尽错误 --> MonitoringSystem(MonitoringSystem: 监控系统) LoggingService -- 记录日志 --> PersistentStorage[持久化存储] MonitoringSystem -- 收集指标 --> AlertingSystem(AlertingSystem: 告警系统) AlertingSystem -- 触发告警 --> OpsTeam[运维团队] ConfigService(ConfigService: 配置服务) -- 提供配置 --> ExaKeyManager ConfigService -- 提供配置 --> ProxyManager ConfigService -- 提供配置 --> ConcurrencyLimiter ConfigService -- 提供配置 --> ExaAPIService ConfigService -- 提供配置 --> ErrorHandler ConfigService -- 提供配置 --> RetryHandler ConfigService -- 提供配置 --> LoggingService ConfigService -- 提供配置 --> MonitoringSystem ConfigService -- 提供配置 --> AlertingSystem ErrorHandler -- 原始响应/错误 --> API_Gateway API_Gateway --> UserResponse[用户响应] subgraph 可观测性 LoggingService MonitoringSystem AlertingSystem end subgraph 核心服务 ExaKeyManager ProxyManager ConcurrencyLimiter SmartRoutingMiddleware ExaAPIService ErrorHandler RetryHandler end style API_Gateway fill:#f9f,stroke:#333,stroke-width:2px style ConcurrencyLimiter fill:#bbf,stroke:#333,stroke-width:2px style SmartRoutingMiddleware fill:#bbf,stroke:#333,stroke-width:2px style ExaKeyManager fill:#f9f,stroke:#333,stroke-width:2px style ProxyManager fill:#bbf,stroke:#333,stroke-width:2px style ExaAPIService fill:#ccf,stroke:#333,stroke-width:2px style ErrorHandler fill:#fbb,stroke:#333,stroke-width:2px style RetryHandler fill:#fbb,stroke:#333,stroke-width:2px style ConfigService fill:#cfc,stroke:#333,stroke-width:2px style LoggingService fill:#eee,stroke:#333,stroke-width:2px style MonitoringSystem fill:#eee,stroke:#333,stroke-width:2px style AlertingSystem fill:#fee,stroke:#333,stroke-width:2px ``` ### 2.2 核心组件设计 * **`ExaKeyManager`**: 集中管理 Exa AI API Key 的存储、轮训、失败计数、健康检查和并发安全。 * **`ProxyManager`**: 管理代理 IP 池、实现 Key-Proxy 绑定、代理健康检查、User-Agent 和请求头随机化。 * **错误处理与重试机制**: 包含 `ErrorHandler` 进行统一错误规范化，`RetryHandler` 实现智能重试（指数退避、Key/代理切换），并引入熔断机制。 * **并发控制**: 利用 Node.js 异步特性，结合全局请求队列和并发限制器，优化超时机制和 HTTP 连接池。 * **配置管理 (`ConfigService`)**: 支持集中式配置、环境变量加载、动态配置热加载和前端管理界面。 * **日志与监控**: `LoggingService` 提供结构化日志和敏感信息脱敏，`MonitoringSystem` 结合 Prometheus、Grafana 和 Alertmanager 实现全面的监控指标收集、告警和可视化。 * **安全考量**: * **API Key 安全存储**: 阐述 API Key 的加密存储方案（例如使用环境变量、Vault 等）。 * **访问控制**: 考虑是否需要对 MCP 服务器的调用方进行身份验证和授权。 * **输入验证强化**: 强调对所有外部输入的严格验证，防止注入攻击等。 * **敏感信息脱敏**: 确保日志中对敏感信息（如 API Key、用户数据）进行彻底脱敏。 ### 2.3 技术选型建议 推荐使用 TypeScript (Node.js) 作为开发语言，并结合 `axios` (HTTP 客户端), `async-mutex`, `p-limit` (并发控制), `winston`/`pino` (日志), `prom-client` (监控), `opossum` (熔断器) 等库。 ### 2.4 实现步骤概述 提供了从环境准备到部署测试的详细路线图，涵盖了各个模块的实现顺序和关键集成点。 * **阶段一：基础架构搭建** * 初始化项目并集成 MCP SDK。 * 实现 `ExaKeyManager` 的基本功能（Key 存储、轮训）。 * 集成 `axios` 并改造现有工具使其使用新的配置管理。 * **阶段二：增强功能与容错** * 实现 `ProxyManager` 的基础功能（代理池管理）。 * 开发 `ErrorHandler` 和 `RetryHandler`。 * 引入熔断机制。 * **阶段三：性能与可观测性** * 实现并发控制 `ConcurrencyLimiter`。 * 集成 `LoggingService`。 * 部署 `MonitoringSystem` (Prometheus, Grafana, Alertmanager)。 * **阶段四：部署与测试** * 编写单元测试和集成测试。 * 性能测试和稳定性测试。