Exa MCP Server

# exa-mcp-server 用户使用说明 ## 1. 引言 `exa-mcp-server` 是一个基于 Model Context Protocol (MCP) 的服务器，旨在提供一系列强大的工具，以增强您的研究、信息检索和代码分析能力。本指南将详细介绍如何有效利用这些工具，帮助您快速上手并高效工作。 ## 2. 核心功能 `exa-mcp-server` 提供了以下核心工具： * **`companyResearch` (公司研究)**: 用于深入分析特定公司信息。 * **`crawling` (网页抓取)**: 用于从指定 URL 抓取网页内容。 * **`deepResearchCheck` (深度研究检查)**: 用于检查正在进行的深度研究任务的状态。 * **`deepResearchStart` (深度研究启动)**: 用于启动新的深度研究任务。 * **`exaCode` (Exa 代码搜索)**: 利用 Exa 平台进行代码库搜索和分析。 * **`linkedInSearch` (LinkedIn 搜索)**: 用于在 LinkedIn 上进行人物或公司搜索。 * **`webSearch` (通用网页搜索)**: 提供通用的互联网搜索功能。 ## 3. 安装指南 `exa-mcp-server` 是一个基于 Node.js 的 MCP 服务器。在本地开发环境中安装项目依赖的步骤如下： 1. **克隆仓库**： ```bash git clone https://github.com/exa-labs/exa-mcp-server.git cd exa-mcp-server ``` 2. **安装 Node.js 和 npm**： 确保您的系统已安装 Node.js (版本 >= 18.0.0) 和 npm。您可以通过以下命令检查版本： ```bash node -v npm -v ``` 如果未安装，请访问 [Node.js 官方网站](https://nodejs.org/) 下载并安装。 3. **安装项目依赖**： 在项目根目录下运行以下命令安装所有依赖： ```bash npm install ``` 这将安装 `package.json` 中列出的所有生产和开发依赖。 4. **构建项目**： 项目需要进行构建才能运行。执行以下命令： ```bash npm run build ``` 此命令会调用 `npm run build:shttp`，它使用 `@smithery/cli` 将 TypeScript 源代码编译为 JavaScript。 ## 4. 部署指南 项目的部署主要通过 `Dockerfile` 进行，实现 Docker 镜像的构建和运行。 **部署流程概览**： 1. **构建阶段 (builder)**： * 使用 `node:18-alpine` 作为基础镜像。 * 设置工作目录为 `/app`。 * 复制 `package.json` 和 `package-lock.json`。 * 运行 `npm ci --ignore-scripts` 安装依赖。 * 复制 `src/` 目录和 `tsconfig.json` 文件。 * 运行 `npm run build` 构建项目。 2. **运行阶段 (runner)**： * 使用 `node:18-alpine` 作为基础镜像，保持镜像精简。 * 设置工作目录为 `/app`。 * 从构建阶段复制编译后的 `.smithery` 目录。 * 复制 `package.json` 和 `package-lock.json`。 * 运行 `npm ci --production --ignore-scripts` 只安装生产依赖。 * 设置环境变量 `EXA_API_KEY`。**请务必替换为您的实际 API 密钥。** * 暴露端口 `3000`。 * 定义 `ENTRYPOINT` 为 `node .smithery/index.cjs`，启动应用程序。 **部署步骤**： 1. **获取 Exa API 密钥**： 在部署之前，您需要从 [https://dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys) 获取您的 `EXA_API_KEY`。 2. **构建 Docker 镜像**： 在项目根目录下执行以下命令构建 Docker 镜像。请将 `your-exa-api-key` 替换为您的实际 API 密钥。 ```bash docker build --build-arg EXA_API_KEY=your-exa-api-key -t exa-mcp-server . ``` 或者，您可以在 `Dockerfile` 中直接修改 `ENV EXA_API_KEY=your-api-key-here`。 3. **运行 Docker 容器**： 构建完成后，您可以通过以下命令运行 Docker 容器： ```bash docker run -p 3000:3000 -e EXA_API_KEY=your-exa-api-key exa-mcp-server ``` 这将把容器的 3000 端口映射到主机的 3000 端口，并传递 `EXA_API_KEY` 环境变量。 ## 5. 启动指南 `exa-mcp-server` 提供了两种主要的启动方式：本地开发启动和 Docker 容器启动。 ### 5.1 本地开发启动 在本地开发环境中启动 MCP 服务器，您可以使用 `npm run dev` 脚本。 1. **设置 `EXA_API_KEY` 环境变量**： 在运行服务器之前，您需要设置 `EXA_API_KEY` 环境变量。 * **macOS/Linux**： ```bash export EXA_API_KEY="your-exa-api-key" ``` * **Windows (Command Prompt)**： ```bash set EXA_API_KEY="your-exa-api-key" ``` * **Windows (PowerShell)**： ```powershell $env:EXA_API_KEY="your-exa-api-key" ``` 请将 `"your-exa-api-key"` 替换为您的实际 Exa AI API 密钥。 2. **启动开发服务器**： 在项目根目录下运行： ```bash npm run dev ``` 这将启动一个开发服务器，通常会在 `http://localhost:3000` 上监听请求。`src/index.ts` 中定义的 `McpServer` 实例将在此端口上运行。 ### 5.2 Docker 容器启动 如果您已经按照部署指南构建了 Docker 镜像，可以通过以下命令启动： 1. **运行 Docker 容器**： ```bash docker run -p 3000:3000 -e EXA_API_KEY=your-exa-api-key exa-mcp-server ``` 确保将 `your-exa-api-key` 替换为您的实际 API 密钥。容器启动后，MCP 服务器将在主机的 `3000` 端口上可用。 ## 6. `curl` 手动测试说明 MCP 服务器通过 HTTP POST 请求接收工具调用。所有工具请求都发送到服务器的根路径 `/`。 **通用 `curl` 请求结构**： ```bash curl -X POST \ http://localhost:3000/ \ -H 'Content-Type: application/json' \ -H 'X-MCP-Tool: <tool_name>' \ -d '{ "arguments": { "param1": "value1", "param2": "value2" } }' ``` * **`http://localhost:3000/`**：服务器地址和端口。如果您在 Docker 中运行并映射到不同端口，请相应修改。 * **`-H 'Content-Type: application/json'`**：指定请求体为 JSON 格式。 * **`-H 'X-MCP-Tool: <tool_name>'`**：**这是关键！** 它指定了要调用的 MCP 工具的名称。 * **`-d '{ "arguments": { ... } }'`**：请求体，包含工具的参数。`arguments` 字段的值是一个 JSON 对象，其键值对对应工具的输入参数。 **`EXA_API_KEY` 环境变量处理**： 服务器启动时会从环境变量 `EXA_API_KEY` 或通过配置 (`config.exaApiKey`) 获取 Exa API 密钥。在 `curl` 测试中，您无需在请求头中传递 `EXA_API_KEY`，只需确保服务器启动时已正确配置该环境变量即可。 ### 核心工具 `curl` 示例 以下是 `exa-mcp-server` 提供的核心工具及其 `curl` 示例： #### 6.1 `web_search_exa` (Web Search) * **描述**：使用 Exa AI 进行实时网页搜索。 * **参数**： * `query` (string, required): 搜索查询。 * `numResults` (number, optional): 返回的搜索结果数量 (默认: 8)。 * **`curl` 示例**： ```bash curl -X POST \ http://localhost:3000/ \ -H 'Content-Type: application/json' \ -H 'X-MCP-Tool: web_search_exa' \ -d '{ "arguments": { "query": "最新的AI技术进展", "numResults": 3 } }' ``` * **预期响应格式**： 一个 JSON 对象，包含 `requestId`、`autopromptString`、`resolvedSearchType` 和 `results` 数组。每个 `result` 对象包含 `id`, `title`, `url`, `publishedDate`, `author`, `text` 等字段。 #### 6.2 `company_research_exa` (Company Research) * **描述**：使用 Exa AI 查找公司综合信息，包括运营、新闻、财务和行业分析。 * **参数**： * `companyName` (string, required): 要研究的公司名称。 * `numResults` (number, optional): 返回的搜索结果数量 (默认: 8)。 * **`curl` 示例**： ```bash curl -X POST \ http://localhost:3000/ \ -H 'Content-Type: application/json' \ -H 'X-MCP-Tool: company_research_exa' \ -d '{ "arguments": { "companyName": "Google", "numResults": 2 } }' ``` * **预期响应格式**： 与 `web_search_exa` 类似，返回包含公司相关搜索结果的 JSON 对象。 #### 6.3 `crawling_exa` (Web Crawling) * **描述**：使用 Exa AI 从特定 URL 提取和抓取内容。 * **参数**： * `url` (string, required): 要抓取内容的 URL。 * `maxCharacters` (number, optional): 要提取的最大字符数 (默认: 2000)。 * **`curl` 示例**： ```bash curl -X POST \ http://localhost:3000/ \ -H 'Content-Type: application/json' \ -H 'X-MCP-Tool: crawling_exa' \ -d '{ "arguments": { "url": "https://www.example.com", "maxCharacters": 1000 } }' ``` * **预期响应格式**： 一个 JSON 对象，包含从指定 URL 抓取到的内容。 #### 6.4 `deep_researcher_start` (Deep Research Start) * **描述**：启动一个由 AI 驱动的深度研究任务，用于复杂查询。 * **参数**： * `instructions` (string, required): 复杂的研究问题或详细指令。 * `model` (enum: 'exa-research' | 'exa-research-pro', optional): 研究模型 (默认: 'exa-research')。 * **`curl` 示例**： ```bash curl -X POST \ http://localhost:3000/ \ -H 'Content-Type: application/json' \ -H 'X-MCP-Tool: deep_researcher_start' \ -d '{ "arguments": { "instructions": "分析2023年全球人工智能市场的主要趋势和挑战", "model": "exa-research-pro" } }' ``` * **预期响应格式**： 一个 JSON 对象，包含 `success: true`、`taskId` (任务 ID)、`model`、`instructions` 和 `message`，指示研究任务已成功启动。您需要使用返回的 `taskId` 调用 `deep_researcher_check` 来获取结果。 #### 6.5 `deep_researcher_check` (Deep Research Check) * **描述**：检查深度研究任务的状态并检索结果。 * **参数**： * `taskId` (string, required): 由 `deep_researcher_start` 工具返回的任务 ID。 * **`curl` 示例**： ```bash curl -X POST \ http://localhost:3000/ \ -H 'Content-Type: application/json' \ -H 'X-MCP-Tool: deep_researcher_check' \ -d '{ "arguments": { "taskId": "your-task-id-here" } }' ``` 请将 `your-task-id-here` 替换为 `deep_researcher_start` 返回的实际任务 ID。 * **预期响应格式**： 一个 JSON 对象，包含 `success`、`status` (`running`, `completed`, `failed`)、`taskId`。如果 `status` 为 `completed`，则会包含 `report` 字段。如果为 `running`，则会建议继续轮询。 #### 6.6 `get_code_context_exa` (Code Context Search) * **描述**：搜索并获取任何编程任务的相关上下文。 * **参数**： * `query` (string, required): 搜索查询，用于查找 API、库和 SDK 的相关上下文。 * `tokensNum` (enum: 'dynamic' | number, optional): Token 分配策略 (默认: 'dynamic')。 * **`curl` 示例**： ```bash curl -X POST \ http://localhost:3000/ \ -H 'Content-Type: application/json' \ -H 'X-MCP-Tool: get_code_context_exa' \ -d '{ "arguments": { "query": "React useState hook 示例", "tokensNum": "dynamic" } }' ``` * **预期响应格式**： 一个 JSON 对象，包含 `requestId`、`query`、`response` (实际代码内容或文档)、`resultsCount` 等字段。 #### 6.7 `linkedin_search_exa` (LinkedIn Search) * **描述**：使用 Exa AI 搜索 LinkedIn 个人资料和公司。 * **参数**： * `query` (string, required): LinkedIn 搜索查询 (例如：人名、公司、职位)。 * `searchType` (enum: 'profiles' | 'companies' | 'all', optional): LinkedIn 内容搜索类型 (默认: 'all')。 * `numResults` (number, optional): 返回的 LinkedIn 结果数量 (默认: 8)。 * **`curl` 示例**： ```bash curl -X POST \ http://localhost:3000/ \ -H 'Content-Type: application/json' \ -H 'X-MCP-Tool: linkedin_search_exa' \ -d '{ "arguments": { "query": "Software Engineer Google", "searchType": "profiles", "numResults": 3 } }' ``` * **预期响应格式**： 与 `web_search_exa` 类似，返回包含 LinkedIn 相关搜索结果的 JSON 对象。 ## 7. 配置指南 部分工具可能需要配置 `EXA_API_KEY`。请确保您的 MCP 服务器已正确配置了必要的 API 密钥，以便工具能够正常工作。具体配置方法请参考本指南的 [4. 部署指南](#4-部署指南) 和 [5. 启动指南](#5-启动指南) 部分。 ## 8. 常见问题 (FAQ) * **Q: 如何获取 `EXA_API_KEY`?** A: 请访问 [Exa AI 官方网站](https://exa.ai/) 注册并获取您的 API 密钥。 * **Q: 如果工具返回错误怎么办?** A: 请检查您的输入参数是否正确，并确保所有必要的配置（例如 API 密钥）已正确设置。如果问题依然存在，请联系技术支持。