用 Agent Search MCP 给 Agent 装「自带证据」的联网检索：免密钥接入、证据包解读与预算控制

这个服务最省心的设计是「免费优先」：不配任何凭证时，它依然会用免费可用的检索源返回结果，只是证据更薄一些；付费供应商只有在路由策略与凭证都允许的情况下才会被启用。这意味着你可以先用零配置把链路打通、看清返回结构，再决定要不要为更高的召回付钱。运行方式是纯 Node.js，支持 stdio、Streamable HTTP 与命令行三种形态，所以既能挂进桌面客户端，也能跑在服务器或 CI 里。先做一次体检，确认运行时健康，再谈接入。

# 直接跑（stdio 形态，供 MCP 客户端拉起）
npx -y agent-search-mcp

# 全局安装后自检运行时（不发起真实检索）
npm install -g agent-search-mcp
fasm doctor

需要留意它的定位边界：它不是一个「多引擎聚合器」，而是一个「带证据的检索器」。普通聚合器给你 N 条去重结果就结束了；它额外告诉你这 N 条来自几个彼此独立的信源家族、哪几个上游超时或触发了验证码、以及它是因为「够了」还是因为「撞到预算了」才停下来的。这个区别对 Agent 很关键——模型拿到的是可判断的信息，而不是一片看起来很像答案的文本。

接入方式和绝大多数 MCP 服务一致：在客户端的 mcpServers 配置里声明一个命令即可。Claude Desktop、Cursor、VS Code、Windsurf 这类接受 mcpServers JSON 的客户端可以直接抄下面这段；Claude Code 与 Codex 也能用同样那条 stdio 命令注册。改完配置一定要重启客户端，然后在对话里让它列一次工具，确认工具真的挂上了再开始用——「配置写了但没生效」是这一步最高频的故障，多半是没重启或配置文件路径选错了。

{
  "mcpServers": {
    "agent-search": {
      "command": "npx",
      "args": ["-y", "agent-search-mcp"]
    }
  }
}

# Claude Code 的等价命令行写法
claude mcp add agent-search -- npx -y agent-search-mcp

# 改完先验证工具可见，再开始干活
# 在客户端里问一句：「你有哪些联网检索工具？」

工具挂上之后还有一个问题：模型知道有工具，但不知道什么场景该用哪种搜法。项目额外提供了一个 Agent Skill（兼容 Agent Skills 的客户端可装），装上之后模型会按四条有界路径选择：快速发现、严格验证、中文源检索、以及抽取指定 URL。它的行为很克制——会先检查需要的 MCP 工具是否真的存在，并且在进行任何安装或配置变更之前先问你，不会自作主张改你的环境。这一点对「把工具交给自治 Agent」的场景很关键。

# 安装仓库自带的路由指南（需先接好 MCP Server）
npx skills add lennney/agent-search-mcp --skill agent-search

# 装上之后的典型用法
用 $agent-search 用官方来源核实这条说法。

这是整套设计里最值得学的部分。每次检索的响应里都带一个「证据包」，它用结构化字段回答了 Agent 在引用一条结果之前必须知道的六件事：跑了哪些适配层（searched_engines）、路由为什么停（stop_reason 与 quality_gate）、有没有撞到工作上限（budget）、证据有没有被截断（evidence_budget）、上游有没有失败（partialFailures）、以及若干条结果到底算几个独立信源（source_count）。最后这一条尤其重要：它按「供应商家族」而不是「适配层名字」计数，同一个上游通过多个适配层进来不会被重复计数，避免了「看起来十条其实是一家」的假多源。

# 响应里该看的字段（示意）
{
  "results": [
    { "title": "...", "url": "...", "snippet": "...", "source_count": 3 }
  ],
  "meta": {
    "execution": {
      "searched_engines": ["duckduckgo", "sogou"],
      "stop_reason": "quality_gate_reached",
      "quality_gate": { "count": 8, "relevance": 0.72, "confidence": 0.66 }
    },
    "budget": { "requests": 3, "elapsed_ms": 2100 },
    "evidence_budget": { "truncated": false }
  },
  "partialFailures": [
    { "engine": "brave", "reason": "timeout" }
  ]
}

把这些字段用起来，你的 Agent 行为会有明显变化：看到 partialFailures 非空，它就知道这批结果有缺口，该补一轮或明说「部分源不可用」，而不是拿半份证据下结论；看到 stop_reason 是预算耗尽而非质量达标，它会知道证据可能还不够；看到 source_count 偏低，它会知道这更像孤证，需要交叉验证。换句话说，它把「检索质量」从看不见的东西变成了可判断的信号。

检索类工具最容易失控的地方不是钱，而是上下文：十条结果每条带一大段正文，一轮下去就把窗口吃掉一小半。项目的做法是用一个统一的「证据预算」约束响应体积，输出保持紧凑但保留出处（provenance）；同时用质量闸门来决定何时停——不是「看起来条数够了」就停，而是要满足条数、相关度、置信度与信源覆盖度这一组条件才停。付费供应商只在路由策略明确允许且凭证存在时才跑，所以默认情况下你不用担心意外产生费用。

# 命令行侧：不配任何 key 也能查（走免费源）
npm run build
fasm search "MCP server without an API key" --json

# 响应契约把三件事分开，便于你分别处理
# result evidence  → 证据本体
# meta.execution   → 执行过程与停止原因
# partialFailures  → 上游失败，保持可见

想在接入前先确认它的评分与格式化逻辑长什么样，项目还提供了一个离线契约演示：它用三个合成场景（同源适配层重叠、可见的回退失败、以及撞到质量闸门而停止）跑一遍生产环境的证据打分与格式化代码，全程不发任何网络请求，也不对可用性或搜索质量做任何承诺。这个演示很适合在 CI 里当回归用——你改了提示词或参数，它仍然能验证「契约没变」。

# 离线契约演示（无网络请求，不声明可用性）
npm run demo:evidence
npm run demo:evidence -- --json

跑通之后，有三类用法最见收益。其一是给编码 Agent 查现成方案：遇到不熟的库或报错，让它先搜官方文档再动手，比直接凭记忆写要稳。其二是做事实核查：明确要求「至少两个独立信源」，用 source_count 兜底。其三是中文信息检索：走搜狗与百度适配层，不必把查询翻译成英文，本地文档、博客与公告的召回会明显好于纯英文引擎。无论哪种，都建议把「证据不足时必须明说」写进你的系统提示词。

# 想确认服务本身健康
fasm doctor

# 想看一次真实返回的结构（再据此写提示词）
fasm search "某个你要查的问题" --json

# 客户端里推荐的说法
先用 agent-search 严格验证这条说法，要求至少 2 个独立信源；
如果 partialFailures 非空或 source_count 少于 2，就明确回答「证据不足」。