Exa MCP Server（Operit 适配版）

version license

本仓库是 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

将本仓库（或仅 dist/ 目录）放入 Operit 的 MCP 插件目录：
- Android 源目录：/sdcard/Download/Operit/mcp_plugins/<pluginId>/
- Linux 运行目录：~/mcp_plugins/<shortName>/（含 dist/stdio.cjs）
在 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"
      }
    }
  }
}

重启 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

exa-mcp-server-for-operit