cf-search-mcp

• 参考 https://github.com/Yrobot/cloudflare-search

• 提供 web 界面，如果设置 token 了，则弹出提示框，输入以后才可以使用web 界面

• 需要在后台配置 TOKEN （文本）变量，默认配置，用户也可以选择不配置

• 支持这几个站

  • tavily（一个月 1000 次）

  • serpapi（一个月 250 次）

  • serper（总共2500次）

  • search1api（一个月100次）

  • jina （赠送 token 额度）

  • baidu （一个月1500次） 参考：https://github.com/ferocknew/claude_code_public_skills/blob/main/baidu_search_nodejs/skill.js

• 以上搜索 api ，可以用户自行配置开放那些，用户可以自行配置搜索接口的权重，逐个降级搜索，不支持并行搜索（费请求次数，没意义）

• 支持其他搜索

  • wikipedia （维基百科）

  • wikisource （维基文库）

  • https://pedia.cloud.edu.tw/ （教育百科）

• 支持 fetch web

  • fetch txt （基于 阅读模式 获取主要内容）

  • fetch markdown（基于 阅读模式 获取带格式的主要内容）

  • fetch html_body

  • fetch html_raw

tools list

• search（搜索）

• wiki_search

• wikisource_search

• pedia_search

• web_fetch

技术说明

• 语言:TypeScript(strict + @cloudflare/workers-types)

• 构建:npm run build(先 tsc --noEmit 类型检查,再 esbuild 打包到 dist/worker.js)

• 部署:npm run deploy;推荐 CF Workers Builds Git 自动部署(push 触发,免 wrangler login)

项目架构

• Worker 直接提供 MCP HTTP 端点(Streamable HTTP),非独立 npm 包

• 多引擎降级搜索:按权重顺序逐个尝试(非并行,省请求次数),首个有结果即返回

• 自集成 @mozilla/readability + linkedom + turndown(网页抓取阅读模式)

• 百科搜索(wikipedia/wikisource/教育百科)为独立工具

• TOKEN 鉴权(可选),JSON 配置搜索引擎开关与优先级

配置(在 CF 后台设置,须在首次部署前配好)

CF Dashboard → Workers & Pages → cf-search-mcp → Settings → Variables and Secrets,逐个添加,改完即时生效。

必须在 wrangler.toml 保留 keep_vars = true,否则部署会清除后台文本变量。

⚠️ 部署顺序(反复测试得出,非常重要):Worker 正式部署成功后,后台再编辑变量/密钥会报 403(POST /workers/scripts/{name}/versions),无法保存。 正确做法:

1. 删除该 Worker,重新新建;

2. 先在 Settings -> Variables and Secrets 配好所有变量(TOKEN/SEARCH_CONFIG/各引擎 key);

3. 再链接 GitHub 触发部署。

顺序不能反:先部署后配变量会 403,只能删了重建。

替代部署:手动粘贴代码(推荐,彻底避开 403)

不绑 GitHub,直接粘贴构建产物——这种方式变量可随时增删改、绝不报 403:

1. 本地 npm run build,生成 dist/worker.js;

2. CF Dashboard → Workers & Pages → Create → Hello World 模板(不要链 GitHub);

3. Settings → Variables and Secrets 配好变量(顺序无所谓,后续也能随时改);

4. Edit code 编辑器里,用 dist/worker.js 全文覆盖默认代码,Save and Deploy。

优点:变量随时改不报 403、不依赖 Git;缺点:每次代码更新都要重新粘贴 dist/worker.js。

变量总览

引擎 key 至少配一个,且需与 SEARCH_CONFIG 列出的引擎对应;没配 key 的引擎会被跳过。

SEARCH_CONFIG 格式

JSON 简洁式,键为引擎名,值为优先级(数字小的先尝试,未列出=禁用):

{"tavily":1,"baidu":2,"serper":3,"jina":4,"search1api":5,"serpapi":6}

只有同时配置了对应 API key 的引擎才会真正参与降级搜索。

CF 后台变量类型选 Text(填 JSON 字符串)或 JSON(填对象)均可,代码两种都兼容。wrangler.toml [vars] 仅支持字符串,写配置文件时须用 Text 形式。

配置后验证

• 看 Web 界面(降级搜索+Token 弹框)

• 搜索验证:/search?q=test;若配了 TOKEN,加 &token=你的token

• 鉴权:不带 token 应返回 401

日志(Workers Logs)

wrangler.toml 已启用 [observability] 与 keep_vars = true:

• keep_vars 保留后台变量,避免部署清除

• [observability] 让 console.error 进 Workers Logs

部署后 CF Dashboard → cf-search-mcp → Logs/Observability 查看(如 [baidu] HTTP 401 可排查引擎 key 是否有效)。

免费套餐限制:每天 200K events,超出后事件将被采样。

开发规范

• TypeScript strict 模式;纯类型导入用 import type(verbatimModuleSyntax)

• 改代码后务必 npm run typecheck(tsc --noEmit);esbuild 只转译不查类型

• wrangler.toml 必须保留 keep_vars = true

• 引擎 key 用 Secret;SEARCH_CONFIG/TOKEN/DEFAULT_TIMEOUT 为文本变量

• 不在本机测试付费搜索 API,用假 key 验证降级结构,真 key 靠线上验证

• Wikimedia API 必须浏览器级 UA+Referer,否则 403;百科搜索为独立工具不进降级链

• 无 DOM lib:Readability 用构造签名断言绕过 Document 类型(见 src/webfetch.ts)

• esbuild neutral 平台需 mainFields:['module','main'],否则 turndown/cssom 打包失败

• web.ts 模板字符串嵌客户端 JS 时用单引号拼接,勿用反引号/反斜杠转义

搜索引擎 API 格式

详见 docs/search_readme.md

注意事项

• 不要在本机测试付费 LLM API,先 CF 部署配 key 验证

• search1api/jina 响应字段按文档推断,需真 key 确认(baidu 已实测通过)

• wiki_search/wikisource_search/web_fetch 已实现并线上验证;pedia_search(教育百科)暂缓

mcp

{
	"mcpServers": {
      "cloudflare-search": {
        "type": "http",
        "url": "https://your-worker.workers.dev/mcp",
        "headers": {
          "Authorization": "Bearer <TOKEN>"
        }
      }
    }
}