k-search-mcp

部署在阿里云函数计算（Function Compute，FC）中国大陆地域的远程网页搜索 MCP。手机 AI 通过阿里云公网 HTTPS 触发器访问，不依赖在中国大陆可能无法打开的 workers.dev 域名。

搜索优先级

服务按以下固定顺序搜索：

Exa → Tavily → 豆包搜索 Custom → Bocha Web Search

只有配置了 API Key 的供应商才会参与搜索。当前供应商出现网络错误、超时、HTTP 错误、业务错误、响应格式异常或空结果时，会自动切换下一家。供应商不会并行请求，因此优先级严格、额外费用更可控。

Related MCP server: Web Search Router

特性

• MCP Streamable HTTP，入口为 /mcp

• MCP 工具名保持为 web_search

• Bearer Token 鉴权，手机端不会接触搜索供应商的 API Key

• Exa 按官方 Coding Agent 建议使用 type: auto 和 highlights

• Tavily 保留默认 80 RPM 排队限速与 429 重试

• 豆包搜索优先使用官方推荐给大模型的 Summary

• Bocha 请求文本摘要并兼容其 Bing 风格响应

• 进程内 15 分钟缓存

• 相同并发查询合并，只执行一条完整供应商调用链

• 单次客户端搜索只计算一次月度软配额，内部 fallback 不重复计数

• /health 仅显示配置状态，不显示密钥

架构

手机 AI / MCP 客户端
        │ HTTPS + Bearer Token
        ▼
阿里云 FC HTTP 触发器（默认杭州）
        │
        ▼
Node.js MCP 服务
  ├─ 鉴权、Origin 校验和月度软配额
  ├─ 缓存与相同查询合并
  └─ 搜索供应商链
       ├─ Exa
       ├─ Tavily（80 RPM 队列与 429 重试）
       ├─ 豆包搜索 Custom
       └─ Bocha Web Search

准备条件

• 已实名认证的阿里云账号

• Node.js 20 或更高版本

• 至少一个搜索 API Key：Exa、Tavily、豆包搜索或 Bocha

• 手机 AI 支持 MCP Streamable HTTP 和自定义请求头

1. 安装依赖

cd ~/Desktop/k-search-mcp
npm install
cp .env.example .env

用文本编辑器打开 .env。至少填写一个搜索供应商的 Key，并设置 MCP Token：

EXA_API_KEY=
TAVILY_API_KEY=你的_Tavily_API_Key
DOUBAO_API_KEY=
BOCHA_API_KEY=
MCP_API_TOKEN=你自己生成的长随机访问令牌

空白供应商会被自动跳过。可以生成 MCP 访问令牌：

openssl rand -hex 32

.env 已加入 .gitignore，不会被提交。不要把真实密钥发到聊天或粘贴到公开日志中。

豆包使用“豆包搜索 Custom 版”控制台生成的 API Key，不是火山引擎 AccessKey/Secret。调用地址为 https://open.feedcoopapi.com/search_api/web_search。

2. 配置阿里云登录凭据

运行：

npx s config add

配置名称填写 default。建议在阿里云 RAM 控制台创建专用 RAM 用户，不要使用主账号 AccessKey，并给该用户添加系统策略 AliyunFCFullAccess。

3. 本地测试

npm run build
npm start

另开终端检查：

curl http://127.0.0.1:9000/health

正常结果类似：

{
  "status": "ok",
  "service": "k-search-mcp",
  "version": "1.2.0",
  "exaConfigured": false,
  "tavilyConfigured": true,
  "doubaoConfigured": false,
  "bochaConfigured": false,
  "searchConfigured": true,
  "authConfigured": true,
  "providerPriority": ["exa", "tavily", "doubao", "bocha"]
}

4. 部署到阿里云函数计算

npm run deploy

部署命令会捕获并过滤 Serverless Devs 输出，对四个搜索 API Key 和 MCP Token 进行打码。成功时只显示部署状态和公网 URL。也可以安全查询公网触发器 URL：

npm run fc:info

不要直接运行并公开粘贴未经处理的 s deploy 或 s info 完整输出，因为其中可能包含函数环境变量。

5. 部署到 Cloudflare Workers

阿里云 FC 与 Cloudflare Workers 使用不同的入口和命令，互不覆盖。Cloudflare 部署前先登录 Wrangler：

npx wrangler login

构建、开发和部署命令分别是：

npm run cf:build
npm run cf:dev
npm run cf:deploy

将密钥写入 Cloudflare Secret（不要放入 wrangler.toml）：

npx wrangler secret put MCP_API_TOKEN
npx wrangler secret put TAVILY_API_KEY

其余供应商密钥可按需设置：EXA_API_KEY、DOUBAO_API_KEY、BOCHA_API_KEY。查看实时日志：

npm run cf:tail

部署后 MCP 地址为 Worker 域名加 /mcp。workers.dev 在部分网络环境（包括中国大陆）可能无法稳定访问，正式使用建议绑定并验证自己的域名。

6. 手机 AI 配置

把部署结果的公网 URL 加上 /mcp：

{
  "url": "https://你的阿里云HTTP触发器地址/mcp",
  "headers": {
    "Authorization": "Bearer 你在.env中设置的MCP_API_TOKEN"
  }
}

手机端无需配置任何搜索供应商 Key。先在手机浏览器打开触发器地址的 /health；能快速显示 JSON，说明中国大陆入口正常。

配置项

四个搜索 API Key 至少配置一个。缓存、月度软上限和相同查询合并状态保存在函数实例内存中，冷启动或重新部署后会清空；各供应商账户仍负责最终额度限制。

并发和限流说明

s.yaml 将函数总并发与单实例并发均设置为 100，使正常允许的并发可由一个实例承载。Tavily 免费 Key 的队列限流保存在 Node 进程内；豆包搜索 Custom 内测目前按 QPS 5 限制，项目也会在每个实例内按 5 QPS 排队。如果提高函数总并发并触发多个实例，每个实例都会拥有独立队列，可能合计超过供应商的账户限制。

Exa、豆包和 Bocha 当前不使用 Tavily 的 80 RPM 队列；它们收到限流或额度错误时会切换下一家。需要对这些供应商做跨实例精确限流时，应使用 Redis、Tablestore 等共享原子存储。

常见问题

• /health 显示 misconfigured：确认 MCP_API_TOKEN 已设置，并且四个搜索 Key 至少填写一个。

• MCP 返回 401：手机里的 Bearer Token 与 MCP_API_TOKEN 不一致。

• 高优先级供应商 Key 错误：服务会记录安全错误并自动切换下一家；/health 只检查是否配置，不会在线验证 Key。

• 搜索全部失败：检查函数日志、供应商余额和 API Key 权限；客户端只会看到统一安全错误。

• Tavily 返回排队已满：服务会继续尝试豆包和 Bocha；如果没有后续供应商，则返回统一失败提示。

• 旧客户端使用 /sse：需要改用 /mcp Streamable HTTP。

开发验证

npm test
npm run typecheck
npm run build

项目结构

src/
├── application/       MCP HTTP 应用编排与 web_search 工具
├── config/            环境变量解析和运行时配置
├── coordinators/      并发请求合并、排队、限流与重试
├── entries/           Node.js 与阿里云 FC 启动入口
├── providers/         Exa、Tavily、豆包、Bocha 适配器与 fallback 链
│   └── shared/        供应商公共错误、HTTP 请求和值规范化方法
├── security/          Bearer 鉴权、Origin 与 CORS
├── services/          进程内缓存和月度软上限
├── shared/            跨层共享类型
└── transport/         Node HTTP 与 FC 事件协议适配器
s.yaml                 阿里云 FC 部署配置

License

MIT