Exa MCP Server

## Exa MCP Server 用户指南 ### 1. 简介 * **项目目的**: 解释 `exa-mcp-server` 如何通过 Model Context Protocol (MCP) 集成 Exa AI 功能，增强 MCP 客户端（如 Claude AI）的研究、信息检索和代码分析能力。 * **核心目标**: 概述标准化接口、封装 Exa AI API、灵活配置、类型安全、日志记录和可扩展性。 * **主要组件**: 简要介绍 MCP 服务器核心、工具注册器、工具实现（`src/tools/`）、配置模块、类型定义和日志模块。 * **技术栈**: 列出 TypeScript, Node.js, `@modelcontextprotocol/sdk`, `axios`, `zod` 等关键技术。 * **工作流程**: 通过 Mermaid 流程图和文字说明，展示用户、MCP 客户端、`exa-mcp-server` 和 Exa AI API 之间的交互和数据流。 ```mermaid graph TD A[MCP Client (e.g., Claude AI)] -->|发送工具调用请求 (stdio/shttp)| B(exa-mcp-server) B -->|请求路由到| C{工具注册器 & 配置检查 src/index.ts} C -->|工具已启用| D[对应工具实现 src/tools/*.ts] D -->|构造并发送 HTTP 请求| E[Exa AI API] E -->|返回数据| D D -->|解析响应并格式化| F[MCP 服务器核心] F -->|返回格式化结果或错误| A C -->|工具未启用| G[返回错误或禁用信息] G --> A ``` ### 2. 安装 本节提供三种安装 `exa-mcp-server` 的方法：通过 npm、Docker 或直接运行 TypeScript。 #### 2.1 通过 npm 安装 1. **先决条件**: 确保已安装 Node.js (版本 `>=18.0.0`) 和 npm。 2. **安装依赖**: 在项目根目录运行 [`npm install`](https://docs.npmjs.com/cli/v10/commands/npm-install)。 3. **构建项目**: 运行 [`npm run build`](package.json:11) 以编译 TypeScript 代码。 4. **运行服务器**: 运行 [`npm start`](package.json:12) 启动 MCP 服务器。 #### 2.2 通过 Docker 安装 1. **先决条件**: 确保已安装 Docker 和 Docker Compose。 2. **构建 Docker 镜像**: 在项目根目录运行 [`docker build -t exa-mcp-server .`](Dockerfile) 3. **使用 Docker Compose 运行**: * 编辑 [`docker-compose.yml`](docker-compose.yml) 文件，设置 `EXA_API_KEY` 环境变量。 * 运行 [`docker-compose up -d`](docker-compose.yml) 启动容器。 #### 2.3 直接运行 TypeScript (开发模式) 1. **先决条件**: 确保已安装 Node.js (版本 `>=18.0.0`)、npm 和 `tsx`。 2. **安装依赖**: 在项目根目录运行 [`npm install`](https://docs.npmjs.com/cli/v10/commands/npm-install)。 3. **运行服务器**: 运行 [`npm run dev`](package.json:10) 以在开发模式下直接运行 TypeScript 文件。 ### 3. 配置 本节详细说明 `exa-mcp-server` 的关键配置选项。 #### 3.1 `EXA_API_KEY` * **用途**: 用于认证 Exa AI API 调用。 * **获取方式**: 从 [dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys) 获取您的 Exa AI API 密钥。 * **配置方式**: * **环境变量**: 推荐方式。在运行服务器前，设置环境变量 `EXA_API_KEY`。 ```bash export EXA_API_KEY="YOUR_EXA_API_KEY" npm start ``` * **MCP 客户端配置**: 在 MCP 客户端的配置文件中（例如 `claude_desktop_config.json` 或 `server.json`），作为 `exaApiKey` 参数提供。例如： ```json { "servers": [ { "name": "exa-mcp-server", "path": "./path/to/exa-mcp-server", "config": { "exaApiKey": "YOUR_EXA_API_KEY" } } ] } ``` #### 3.2 `enabledTools` (可选) * **用途**: 控制服务器启动时启用的特定 Exa AI 工具。 * **默认行为**: 如果未提供此配置，则默认启用 [`src/index.ts`](src/index.ts) 中 `availableTools` 对象里 `enabled: true` 的工具。 * **配置方式**: * **MCP 客户端配置**: 在 MCP 客户端的配置文件中，作为 `enabledTools` 数组提供。例如： ```json { "servers": [ { "name": "exa-mcp-server", "path": "./path/to/exa-mcp-server", "config": { "enabledTools": ["webSearch", "companyResearch"] } } ] } ``` * **命令行参数**: 在启动服务器时，通过 `--tools` 参数指定。 ```bash npm start -- --tools webSearch companyResearch ``` #### 3.3 `debug` (可选) * **用途**: 启用或禁用详细的调试日志输出。 * **配置方式**: * **MCP 客户端配置**: 在 MCP 客户端的配置文件中，作为 `debug` 布尔值提供。 ```json { "servers": [ { "name": "exa-mcp-server", "path": "./path/to/exa-mcp-server", "config": { "debug": true } } ] } ``` * **命令行参数**: 在启动服务器时，通过 `--debug` 参数启用。 ```bash npm start -- --debug ``` ### 4. 使用 本节描述用户如何通过 MCP 客户端调用 `exa-mcp-server` 提供的 Exa AI 工具，并提供每个工具的简要功能说明和示例。 #### 4.1 通用工具调用格式 用户通过 MCP 客户端（如 Claude AI）调用工具时，通常会使用以下格式： ```xml <use_mcp_tool> <server_name>exa-mcp-server</server_name> <tool_name>工具名称</tool_name> <arguments> { "参数1": "值1", "参数2": "值2" } </arguments> </use_mcp_tool> ``` 其中： * `<server_name>`: 始终为 `exa-mcp-server`。 * `<tool_name>`: 要调用的具体工具的名称。 * `<arguments>`: 一个 JSON 对象，包含工具所需的输入参数。 #### 4.2 可用工具参考 以下是 `exa-mcp-server` 提供的 Exa AI 工具列表及其功能说明和示例： ##### 4.2.1 `webSearch` (通用网页搜索) * **功能**: 执行通用网页搜索，返回相关网页的标题、URL 和摘要。 * **输入参数**: * `query` (string, 必需): 搜索查询字符串。 * `numResults` (number, 可选, 默认: 5): 返回结果的数量。 * **示例**: ```xml <use_mcp_tool> <server_name>exa-mcp-server</server_name> <tool_name>webSearch</tool_name> <arguments> { "query": "最新人工智能发展趋势", "numResults": 3 } </arguments> </use_mcp_tool> ``` * **预期输出**: 包含搜索结果的 JSON 数组，每个结果包含 `title`, `url`, `summary` 等字段。 ##### 4.2.2 `companyResearch` (公司信息研究) * **功能**: 收集特定公司的详细信息，如概述、新闻、财务数据等。 * **输入参数**: * `companyName` (string, 必需): 公司名称。 * **示例**: ```xml <use_mcp_tool> <server_name>exa-mcp-server</server_name> <tool_name>companyResearch</tool_name> <arguments> { "companyName": "Google" } </arguments> </use_mcp_tool> ``` * **预期输出**: 包含公司研究结果的 JSON 对象。 ##### 4.2.3 `crawling` (网页内容抓取) * **功能**: 抓取指定 URL 的网页内容。 * **输入参数**: * `url` (string, 必需): 要抓取的网页 URL。 * **示例**: ```xml <use_mcp_tool> <server_name>exa-mcp-server</server_name> <tool_name>crawling</tool_name> <arguments> { "url": "https://www.example.com/blog/article" } </arguments> </use_mcp_tool> ``` * **预期输出**: 包含抓取到的网页内容的 JSON 对象。 ##### 4.2.4 `linkedInSearch` (LinkedIn 个人资料和公司搜索) * **功能**: 在 LinkedIn 上搜索个人资料或公司信息。 * **输入参数**: * `query` (string, 必需): 搜索查询字符串（例如，人名或公司名）。 * `type` (string, 可选, 默认: "person"): 搜索类型，可以是 "person" 或 "company"。 * **示例**: ```xml <use_mcp_tool> <server_name>exa-mcp-server</server_name> <tool_name>linkedInSearch</tool_name> <arguments> { "query": "John Doe", "type": "person" } </arguments> </use_mcp_tool> ``` * **预期输出**: 包含 LinkedIn 搜索结果的 JSON 数组。 ##### 4.2.5 `deepResearchStart` (启动多步骤深度研究任务) * **功能**: 启动一个复杂的、多步骤的深度研究任务，例如对某个主题进行全面分析。此工具会返回一个 `taskId`。 * **输入参数**: * `topic` (string, 必需): 深度研究的主题。 * **示例**: ```xml <use_mcp_tool> <server_name>exa-mcp-server</server_name> <tool_name>deepResearchStart</tool_name> <arguments> { "topic": "量子计算的最新进展" } </arguments> </use_mcp_tool> ``` * **预期输出**: 包含 `taskId` 的 JSON 对象。 ##### 4.2.6 `deepResearchCheck` (检查深度研究任务状态并检索结果) * **功能**: 使用 `deepResearchStart` 返回的 `taskId` 检查深度研究任务的当前状态并检索最终结果。 * **输入参数**: * `taskId` (string, 必需): `deepResearchStart` 返回的任务 ID。 * **示例**: ```xml <use_mcp_tool> <server_name>exa-mcp-server</server_name> <tool_name>deepResearchCheck</tool_name> <arguments> { "taskId": "YOUR_TASK_ID" } </arguments> </use_mcp_tool> ``` * **预期输出**: 包含任务状态（例如 "in_progress", "completed"）和研究结果的 JSON 对象。 ##### 4.2.7 `exaCode` (利用 Exa 平台进行代码库上下文搜索) * **功能**: 利用 Exa 平台对代码库进行上下文相关的搜索，适用于代码分析和理解。 * **输入参数**: * `query` (string, 必需): 代码搜索查询字符串。 * **示例**: ```xml <use_mcp_tool> <server_name>exa-mcp-server</server_name> <tool_name>exaCode</tool_name> <arguments> { "query": "如何实现用户认证功能" } </arguments> </use_mcp_tool> ``` * **预期输出**: 包含代码搜索结果的 JSON 数组。 ### 5. 故障排除 * **API 密钥错误**: 检查 `EXA_API_KEY` 是否正确配置。 * **工具未启用**: 检查 `enabledTools` 配置，确保所需工具已启用。 * **网络连接问题**: 确保服务器可以访问 Exa AI API。 * **日志分析**: 在 `debug` 模式下查看详细日志 (`src/utils/logger.ts`) 以获取更多信息。 ### 6. 贡献与开发 * **如何贡献**: 指南如何提交 PR、报告 Bug 等。 * **开发环境设置**: 详细说明如何设置开发环境，包括运行测试和代码规范。 ### 7. 许可证 * **许可证信息**: 提供项目的许可证详情。 ### 8. 常见问题 (FAQ) * 列出常见问题及其解答。