# Exa MCP Server（Operit 适配版）

[![version](https://img.shields.io/badge/version-3.4.0--operit.1-4A90D9?style=flat-square)](https://github.com/x15907982411/exa-mcp-server-for-operit)
[![license](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)

本仓库是 [exa-labs/exa-mcp-server](https://github.com/exa-labs/exa-mcp-server) **v3.4.0 的 Operit 平台适配版**。

原版 Exa MCP Server 用于将 Exa 的搜索能力（web search / code search / company research）接入 AI 助手；本适配版在保持全部功能不变的前提下，修复了 Exa MCP 与 **Operit 平台**（旧版 Kotlin MCP SDK / Zod schema 校验）握手失败的问题，使 `web_search_exa` / `web_fetch_exa` 等工具可在 Operit 中稳定加载与调用。

---

## 为什么需要适配（背景）

Operit 使用的 MCP 客户端 SDK 版本较旧，其 Zod 校验要求 **serverInfo 响应中不允许出现 `icons` 字段**：

| 现象 | 原因 |
|---|---|
| MCP 插件一直"卡在加载" | 客户端发起 `initialize` 后，服务端返回的 `serverInfo` 携带 `icons`，旧 SDK 校验报 `invalid_type`，握手失败 |
| 工具列表拉不到 / 工具不可用 | 握手未完成，`tools/list` 无法正常返回 |

本仓库将 `src/stdio.ts` 中 `McpServer` 构造参数的 `icons` 字段移除，并使**源码与构建产物（dist/stdio.cjs）保持一致**，构建可复现。

> 注：`dist/stdio.cjs` 中仍保留 SDK 库内部的 `IconSchema`/`IconsSchema` 定义（用于校验客户端传入字段的 schema 声明），这与 serverInfo **响应**中的 `icons` 无关，不影响兼容性。

## 与原仓库的差异（全部）

| 文件 | 修改 | 说明 |
|---|---|---|
| `src/stdio.ts` | 移除 `McpServer` 的 `icons` 参数 | 兼容 Operit 旧 SDK 的 Zod 校验（修复根因） |
| `src/stdio.ts` / `package.json` | 版本号 `3.4.0` → `3.4.0-operit.1` | 发布版本可识别，serverInfo 回显该版本 |

除此之外，工具集、API、skills、测试、Dockerfile、vercel 配置等均与上游 v3.4.0 完全一致。

## 快速开始

### 1. 构建（可复现）

```bash
npm ci                    # 安装依赖（国内可换 npmmirror 加速：npm config set registry https://registry.npmmirror.com）
npm run build:stdio       # esbuild 打包 → dist/stdio.cjs（自包含，约 2.2MB）
```

> ⚠️ npm 11+ 默认阻止 postinstall 脚本，若报 `esbuild: command not found`，执行：
> ```bash
> npm approve-scripts esbuild   # 或 npm approve-builds
> node node_modules/esbuild/install.js
> ```

### 2. 验证握手（initialize）

```bash
node dist/stdio.cjs <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}
EOF
```

预期 `serverInfo` 响应（**无 icons 字段**）：

```json
{
  "name": "exa-search-server",
  "title": "Exa",
  "version": "3.4.0-operit.1",
  "websiteUrl": "https://exa.ai"
}
```

### 3. 部署到 Operit

1. 将本仓库（或仅 `dist/` 目录）放入 Operit 的 MCP 插件目录：
   - Android 源目录：`/sdcard/Download/Operit/mcp_plugins/<pluginId>/`
   - Linux 运行目录：`~/mcp_plugins/<shortName>/`（含 `dist/stdio.cjs`）
2. 在 `mcp_config.json` 注册（示例）：

```json
{
  "mcpServers": {
    "exa": {
      "command": "node",
      "args": ["dist/stdio.cjs"],
      "env": {
        "EXA_API_KEY": "<your-exa-api-key>",
        "EXA_TOOL_ENABLES": "web_search_exa,web_fetch_exa"
      }
    }
  }
}
```

3. 重启 MCP 服务（Operit 内触发 `restart_mcp_with_logs`），验证 `ping_mcp` 可列出工具。

## 可用工具

- `web_search_exa` — 默认启用，Exa 语义搜索
- `web_fetch_exa` — 默认启用，任意 URL 转 Markdown
- `web_search_advanced_exa` 等高级工具 — 需在 `EXA_TOOL_ENABLES` 中追加工具名后启用

详见上游 [Full Documentation](https://docs.exa.ai/reference/exa-mcp)。

## 详细适配说明

构建细节、踩坑记录与适配前后对比见 [README-OPERIT.md](./README-OPERIT.md)。

## 上游信息

- 上游仓库：https://github.com/exa-labs/exa-mcp-server
- 上游版本：v3.4.0
- 上游文档：https://docs.exa.ai/reference/exa-mcp
- API Key：https://dashboard.exa.ai/api-keys

## License

MIT — 保留上游 [exa-labs/exa-mcp-server](https://github.com/exa-labs/exa-mcp-server) 版权声明，详见 [LICENSE](LICENSE)。