概览

它解决什么问题

搜索是 Agent 使用频率最高的工具，但现有可选方案都存在明显短板。这个项目要填的是同一个空档： 不用花钱、不用配置、输出就能直接用。

核心能力

• 零配置开箱即用 —— npx -y ai-search-mcp 直接运行，不需要任何 API Key。
• 多引擎可插拔 —— 免费引擎 duckduckgo · bing · baidu · sogou · so360 · google · yandex，付费引擎 brave · tavily。
• 区域感知自动选引擎 —— SEARCH_ENGINE=auto（默认）时按 SEARCH_REGION 选择引擎链；429 / 超时自动故障转移；也支持逗号分隔的自定义链。
• 时效过滤 —— freshness=day|week|month|year 或精确的 timeRange="YYYY-MM-DD..YYYY-MM-DD"，按引擎能力自动映射。
• 结构化输出 —— 返回 { id, title, url, snippet, domain }；每条结果带稳定 id（URL 的 sha1 前缀），可直接引用与深读。
• research 组合工具 —— 一次调用完成「搜索 + 并行抓取 Top 页」，产出证据简报，消灭 5~10 次工具往返。
• 内置 TTL 缓存 —— 默认 10 分钟；可用 SEARCH_CACHE_FILE 持久化，进程重启不丢缓存。
• 引擎健康追踪与优雅降级 —— 冷却中的引擎被引擎链跳过，全部失败时给出逐引擎归因诊断。
• 解析规则外置 —— 引擎改版时用本地文件或远程 URL 覆盖解析规则，无需等待新版本发布。
• 礼貌爬虫内置 —— 按引擎限频 + 随机请求间隔，主动避免触发平台风控，不做任何反爬对抗。

四个工具

一次搜索发生了什么

1. 校验与改写

   校验参数（maxResults 1–20、域名列表最多各 5 个等），解析时效窗口。 若查询含中文且带「20xx 年」年份词，会移除年份并自动补偿 freshness=year。

2. 解析引擎链

   按 SEARCH_ENGINE 与 region 得出有序引擎列表；没有 API Key 的付费引擎被剔除， 免费引擎作为兜底候选附加在后面。开启 SEARCH_LANG_ROUTING=1 时中文查询会优先原生中文引擎。

3. 逐个尝试，失败即转移

   每个请求前先过限频器与随机延迟；成功即停止，失败则记录健康状态并尝试下一个引擎。 处于冷却期的引擎会被直接跳过，不再浪费请求。

4. 去重、打 id、缓存

   URL 归一化后去重，为每条结果生成稳定 id，执行客户端侧的域名包含/排除兜底过滤， 最后写入 TTL 缓存并返回结构化 JSON。

运行要求

• Node.js≥ 18（使用内置 fetch / test runner）
• 模块系统CommonJS，无构建步骤
• 运行依赖@modelcontextprotocol/sdk、undici、zod（共 3 个）
• 传输方式stdio（JSON-RPC over stdin/stdout）
• 日志输出到 stderr，不污染 MCP 协议流

# 直接运行（无需安装）
npx -y ai-search-mcp

# 或全局安装
npm i -g ai-search-mcp
ai-search-mcp

# 从源码运行
git clone https://github.com/zhulingyu666/ai-search-mcp.git
cd ai-search-mcp && npm install && npm start

项目状态

• 当前版本0.4.1（2026-08-26）
• 测试137 个单元测试（Node 内置 test runner）+ 端到端冒烟脚本
• 许可证MIT
• 仓库github.com/zhulingyu666/ai-search-mcp
• 变更记录CHANGELOG.md

接下来

• 快速开始 —— 三步接入你的 MCP 客户端
• 工具指南 —— 四个工具的参数与用法
• 引擎详解 —— 9 个引擎的能力差异与选型
• 配置指南 —— 19 个环境变量