Exa MCP Server（Operit 适配版）

本仓库是 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. 构建（可复现）

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，执行：

npm approve-scripts esbuild   # 或 npm approve-builds
node node_modules/esbuild/install.js

2. 验证握手（initialize）

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 字段）：

{
  "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 注册（示例）：

{
  "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。

详细适配说明

构建细节、踩坑记录与适配前后对比见 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 版权声明，详见 LICENSE。