Agent Search mcp

Agent Search MCP：优先免费、证据可查的网页搜索

用于英语和中文网页搜索的 Node.js MCP 服务和 CLI。

Agent Search MCP 无需 API 密钥即可启动。它会返回精简的多来源证据、记录提供方故障，并通过请求和证据预算限制工作量。只有在策略和凭据均允许时，才会调用付费提供方。

中文文档 · 产品页面 · 基准测试 · 架构 · 更新日志

---

安装

npx -y agent-search-mcp

需要 Node.js >= 18.17。默认运行时无需浏览器、数据库、Python 或搜索 API 账户。

连接 MCP 客户端

在接受 mcpServers JSON 的 MCP 客户端中使用此 stdio 配置，包括 Claude Desktop、Cursor、VS Code 和 Windsurf：

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

Claude Code 和 Codex 可以通过各自的 MCP 设置注册相同的 npx -y agent-search-mcp stdio 命令。

添加可选的 Agent Skill

连接 MCP 服务后，兼容 Agent Skills 的客户端可以安装仓库提供的路由指南：

npx skills add lennney/agent-search-mcp --skill agent-search

可使用类似 Use $agent-search to verify this claim with official sources. 的请求调用它。Agent Search Skill 会选择四种有界路径之一：快速发现、更严格的验证、中文来源搜索，或提取指定 URL 的内容。它会检查所需的 MCP 工具是否存在，并在安装或更改配置前征求同意。安装 Skill 不会启动或配置 MCP 服务。

示例：检查有界搜索结果

构建本地软件包后，无需添加提供方密钥即可运行 CLI 查询：

npm run build
fasm search "MCP server without an API key" --json

响应约定将结果证据、meta.execution 和 partialFailures 分开。提供方超时或遇到质询时，Agent 仍能看到相关信息，而不会收到无法解释的空结果。这是约定示例，并非实时可用性或搜索质量基准测试。

全局安装后，无需发起搜索请求即可检查本地运行时：

npm install -g agent-search-mcp
fasm doctor

为什么选择 Agent Search MCP

需求	产品行为
免费网页搜索	无需 API 账户即可使用无需密钥的来源
提供方成本控制	只有在明确的路由策略下才会调用付费提供方
令牌成本控制	精简输出和统一的证据预算限制响应大小
多来源证据	结果保留来源信息、相关性、提供方系列数量和部分故障
中文网页搜索	Sogou 和 Baidu 可直接处理中文查询，无需翻译层
轻量级自托管	纯 Node.js 运行时，支持 stdio、Streamable HTTP 和 CLI 访问

与普通多引擎封装的区别

普通多引擎聚合	Agent Search MCP
返回 N 条去重结果	返回结果以及独立来源的数量（按提供方系列统计，而非适配器名称）
提供方故障时会悄然丢弃部分结果	每项故障都会保留在 partialFailures 中（超时、速率限制、质询、权限、预算）
结果数量看起来足够时就停止	仅在通过质量门槛（数量、相关性、置信度、来源覆盖率）后停止，并返回 stop_reason
固定大小的输出	所有响应令牌共用一个证据预算上限；精简文本会保留来源信息
一个适配器算作一个来源	同一上游通过多个适配器提供结果，也不会增加 source_count

一分钟离线演示会通过生产环境的证据评分器和格式化器，重现这些差异：

检查搜索证据

每个 JSON 响应都包含一个 Search Evidence Packet。它会回答 Agent 使用结果前所需的路由问题：

问题	响应字段
哪些适配器已运行？	meta.execution.searched_engines
路由器为何停止？	meta.execution.stop_reason 和 meta.execution.quality_gate
请求是否触及工作限制？	meta.execution.budget
证据是否被截断？	meta.evidence_budget
上游提供方是否发生故障？	partialFailures
多个适配器是否代表独立来源？	results[].source_count 按提供方系列统计，而非适配器名称

运行一分钟离线契约演示：

npm run demo:evidence
npm run demo:evidence -- --json

它会通过生产环境的证据评分器、格式化器和 MCP 输出辅助工具，重现三个合成场景：同系列适配器重叠、可见的回退故障，以及受限的质量门槛停止。它不声称实时可用性或搜索质量，也不会发起网络请求。

默认的 free_first 策略绝不会使用已配置的 API 凭据。 free_only 会屏蔽付费提供方。如果免费证据未通过质量门槛， quality_escalation 可以调用一个已配置的付费提供方；而 paid_first 会在回退到免费选项前先尝试该提供方。

请求预算会限制适配器尝试次数、经过的时间和纳入的结果数。 证据预算会限制完整响应中与查询相关的段落数量。 精简模式会保留前几条结果的完整详情，并将后续条目缩减为保留来源信息的引用。

经测量的令牌缩减

仓库中附带的双语测试样例使用锁定的分词器测量格式化结果：

输出	每次查询的平均令牌数	相较普通模式的节省比例
普通模式	2396.0
精简模式	1650.1	31.1%
精简+模式	1633.0	31.8%

此测试样例用于验证输出格式和证据数据包行为。它不测量实时引擎可用性或搜索质量。请参阅 基准测试方法和限制。

搜索路由器的工作方式

flowchart LR
    A["AI agent"] --> M["MCP search tools"]
    M --> P["Provider and request policy"]
    P --> F["Zero-key sources"]
    P --> O["Optional paid provider"]
    F --> E["Deduplicate, rank, and preserve failures"]
    O --> E
    E --> B["Evidence and token budget"]
    B --> R["Compact multi-source result"]

路由器会根据各自独立的结果、相关性、置信度和提供方系列门槛，评估每一批搜索结果。证据通过这些门槛后，路由器便会停止，并在 meta.execution 中公开这一决策。提供方故障会保留在 partialFailures 中，因此空结果无法掩盖上游错误。

竞争格局（2026-08-07） 梳理了竞争激烈的基线市场和产品缺口。对于可能变化的事实，文档记录了来源日期和固定提交。 2026-08-10 更新 补充了此后竞争对手的动态：直接的本地竞争者处于停滞状态，而高令牌效率的证据正成为业界明确采用的杠杆。较早的 来源级产品对比 包含针对架构的证据。

---

引擎

运行时注册了 16 个适配器：9 个无需密钥的适配器和 7 个可选 API 适配器。

引擎	访问方式	语言	角色
DuckDuckGo	无需密钥	en	通用网络搜索
Sogou Search	无需密钥	zh	中文网络搜索
Bing	无需密钥	en, zh	多语言网络搜索
Baidu	无需密钥	zh	中文网络搜索
Wikipedia	无需密钥	en, zh, ja, de, fr, es, auto	百科参考资料
Startpage	无需密钥	en, auto	注重隐私的网络搜索
Yandex	无需密钥	ru, en, auto	俄语及国际网络搜索
Mojeek	无需密钥	en, auto	独立的注重隐私的索引
Wiby	无需密钥	en	独立的小型网络索引
Brave Search	BRAVE_API_KEY	en, zh	可选的商业网络搜索
Tavily Search	TAVILY_API_KEY	en, zh	可选的面向 Agent 的搜索
Exa Search	EXA_API_KEY	en, zh	可选的神经网络搜索
You.com Search	YDC_API_KEY	en, zh	可选的商业网络搜索
Tencent Web Search API	TENCENT_WSA_API_KEY	zh	可选的官方中文网络搜索
Bocha Web Search	BOCHA_API_KEY	zh, en	可选的中文优先 AI 搜索
Serper Google Search	SERPER_API_KEY	en, zh, auto	可选的 Google SERP 搜索

工具

工具	描述	最适合用于
free_search	带有限回退的多引擎网络搜索	快速查找事实和一般信息
free_search_advanced	带筛选条件的瀑布式搜索和可选增强	域名策略和渐进式验证
free_extract	将 URL 提取为干净的 Markdown	阅读完整的源页面
fetch_github_readme	获取公开的 GitHub 仓库 README	项目文档
fetch_csdn_article	获取 CSDN 文章	中文技术文章
fetch_juejin_article	获取掘金文章	中文开发者文章
search_with_synthesis	搜索证据并提供大模型综合提示	根据引用证据生成由 Agent 撰写的回答

能力控制

环境变量	默认值	用途
ENABLED_TOOLS / DISABLED_TOOLS	all / none	工具注册白名单和黑名单；黑名单优先
ALLOWED_ENGINES / DENIED_ENGINES	all / none	引擎执行白名单和黑名单；黑名单优先
SEARCH_PROVIDER_MODE	free_first	默认路由：free_first、quality_escalation、paid_first 或 free_only
PAID_ENGINE_ORDER	brave,exa,tavily,youcom,tencent_wsa,bocha,serper	选择第一个已配置的可选提供方；这不代表质量评级
SEARCH_BUDGET_MAX_CALLS	16	适配器尝试次数预算
SEARCH_BUDGET_MAX_ELAPSED_MS	30000	端到端耗时预算
SEARCH_BUDGET_MAX_RESULTS	100	接纳的原始结果预算
EVIDENCE_BUDGET_CHARS	1200	证据字符数预算

search_with_synthesis 使用与主要搜索工具相同的规范 structuredContent 证据包， 并添加 prompt_hint；其文本内容仅是精简的兼容性视图。执行元数据区分已计划的 适配器与包含重试的适配器尝试次数。只有当所有适配器传输都能准确报告时， http_requests 才会有值，否则为 null。

Wiby 是真正无需密钥的来源，由其官方 JSON API 提供支持，并在免费瀑布式搜索的 后段作为独立的小型网络补充来源。可选提供方需要用户凭据；任何注册赠金或试用 配额均由提供方控制，不视为永久免费访问。

所有工具均为只读且幂等。搜索取消会传递到限速等待、重试、提供方请求和可选增强。 增强可以改善摘要，但不能提高来源可信度或独立来源数量。

free_search_advanced.time_range 保留在兼容性架构中。由于通用网络提供方没有 共同遵循的可执行时效性约定，服务器会在搜索前返回 UNSUPPORTED_FILTER。

---

配置

上方生成的能力表列出了默认请求预算。这些设置涵盖常见的部署方式：

目标	环境变量
添加可选提供方	BRAVE_API_KEY、TAVILY_API_KEY、EXA_API_KEY、YDC_API_KEY、TENCENT_WSA_API_KEY、BOCHA_API_KEY 或 SERPER_API_KEY
选择支出策略	SEARCH_PROVIDER_MODE、PAID_ENGINE_ORDER
减少响应 token	OUTPUT_STYLE=compact、MAX_FULL_RESULTS、SNIPPET_LENGTH、EVIDENCE_BUDGET_CHARS
限制工具或引擎	ENABLED_TOOLS、DISABLED_TOOLS、ALLOWED_ENGINES、DENIED_ENGINES
使用显式代理	DUCKDUCKGO_PROXY_URL、SOGOU_PROXY_URL、MOJEEK_PROXY_URL、WIBY_PROXY_URL，或将 USE_PROXY=true 与 PROXY_URL 配合使用
使用用户自有的代理池	将 DUCKDUCKGO_PROXY_URLS、SOGOU_PROXY_URLS、MOJEEK_PROXY_URLS 或 WIBY_PROXY_URLS 设为包含 2-16 个 HTTP(S) 代理 URL 的 JSON 数组
持久化精确结果缓存	SEARCH_CACHE_DIRECTORY、SEARCH_CACHE_TTL_MS、SEARCH_CACHE_MAX_ENTRIES
启用可选语义处理	SEMANTIC_DEDUP、SEMANTIC_RERANK、DEDUP_THRESHOLD、RERANK_TOP_K

添加 API 密钥并不代表获准产生付费流量。路由策略控制提供方的使用方式。默认的精确结果缓存保留在内存中；设置 SEARCH_CACHE_DIRECTORY 可启用本地持久化。语义处理是唯一会使用 Python 和 Model2Vec 的可选功能。

代理池会根据逻辑查询选择确定性的首个出口，并保持多步提供方请求使用同一出口。只有传输失败时才会切换到下一个已配置出口；发生传输失败的出口会冷却 60 秒。HTTP 响应（包括 403、429 和质询页面）不会触发代理切换，并继续遵循提供方现有的冷却机制。引擎专用的单代理变量优先于对应的代理池。fasm doctor 绝不会打印代理凭据。

HTTP 部署

HTTP 模式需要设置 HTTP_AUTH_TOKEN，除非设置 HTTP_ALLOW_UNAUTHENTICATED=true。带有 Origin 标头的浏览器请求必须与 ALLOWED_ORIGINS 匹配。TLS 终止、令牌轮换和反向代理示例，请参阅 HTTP 部署指南。

---

命令行界面

此软件包包含 fasm 命令行界面：

fasm search "TypeScript MCP server"
fasm search "query" --count 5 --engines bing,baidu,youcom --json
fasm extract "https://example.com"
fasm extract "https://example.com" --json
fasm doctor
fasm doctor --json
HTTP_AUTH_TOKEN=change-me MODE=http npx agent-search-mcp

fasm doctor 会读取本地配置，不进行网络探测，也绝不会打印凭据或代理值。

---

文档与证据

文档	内容
系统架构	路由、证据、提供方系列和配置
竞争格局（2026-08-10）	截至 2026-08-10 的竞争对手动态、定位和改进优先级
竞争格局（2026-08-07）	基准竞争对手、预期和产品差距快照
产品比较	Agent 搜索产品的源码级审查
基准测试	token 测试夹具、实时运行范围和质量评估方法
v3.2.0 发布说明	提供方策略、预算和迁移说明
较早的发布候选版本证据	扩展前的打包安装矩阵及其局限
MCP 2026 就绪情况	隔离的协议实验及剩余门槛

配套项目：Slim Guard

Agent Search 控制检索工作并压缩搜索证据。 mcp-slim-guard 位于 Agent 与 MCP 服务之间，用于处理工具架构压缩和安全策略。

npm install -g mcp-slim-guard

---

开发

git clone https://github.com/lennney/agent-search-mcp.git
cd agent-search-mcp
npm install
npm run build
npm test
npm run dev        # stdio mode
npm run dev:http   # HTTP mode (port 3000)

稳定版软件包支持 Node.js 18、20 和 22。隔离的 MCP 2026 实验要求 Node.js 20 或更高版本。

---

许可证

Apache 2.0

基于 Aas-ee 开发的 open-websearch。

如果 Agent Search MCP 对你的 Agent 有帮助，请为仓库点亮星标， 让其他开发者也能发现这个项目。