项目定位与核心价值

agent-search-mcp 是一个面向 LLM Agent 的开源搜索/抽取 MCP (Model Context Protocol) 服务器，目标是在不依赖付费 API（如 Tavily、SerpAPI、Bing Search API）的前提下，为 Agent 提供可直接调用的网页搜索与内容抽取工具。资料来源：README.md:1-40 该项目同时强调 "free" 与 "fast"：内置 8 个无需密钥的搜索引擎（包括 DuckDuckGo、Bing News、Brave、Baidu、Wikipedia、arxiv、CrossRef、Yahoo），并通过 Node.js HTML 引擎（cheerio）作为自动回退方案，实现 "DDGS Independence"，使 DuckDuckGo 搜索不再依赖 Python 环境。资料来源：README_zh.md:10-60

项目的最新稳定版为 v3.1.2，于 2026-07-22 发布，定位从单纯 "MCP 搜索服务器" 演化为 "Agent 友好的检索与合成引擎"，强调 Glama 质量评级（MCP 注册表）从 B 提升至 A，并完成 npm 发行与 CI 徽章整合。资料来源：docs/index.md:1-30

设计理念与架构原则

项目的架构原则可以概括为三点：

1. 零密钥优先（Keyless-first）：默认情况下不要求用户配置任何 API Key，所有内置引擎都支持匿名/公开访问；这显著降低 LLM Agent 接入门槛。资料来源：README.md:60-120
2. 冗余与降级（Waterfall & Fallback）：在搜索与抽取两个环节都采用 waterfall 模式——按优先级依次尝试多个引擎，直到返回足够结果或达到超时；同时 cheerio 作为 Python DDGS 不可用时的兜底实现。资料来源：docs/research/2026-07-26-agent-search-product-architecture.md:40-90
3. 工具粒度可控（Tool Visibility）：通过 ENABLED_TOOLS / DISABLED_TOOLS 环境变量让宿主控制哪些 MCP 工具被暴露，避免在资源受限的客户端上注册过多 Tool。资料来源：README.md:120-160

核心能力与技术特性

v3.0.0 引入了 Synthesis Engine（search_with_synthesis 工具），其思路是 waterfall 搜索 + prompt_hint 提示词，由 Agent 自身的 LLM 完成答案合成，而无需调用外部摘要 API，从而避免二次计费与数据外泄。资料来源：docs/index.md:30-80 同期新增的 free_search_news 工具聚合 DuckDuckGo News 与 Bing News，无需密钥即可检索新闻流。资料来源：README_zh.md:60-110

下表概括当前主要 MCP 工具与其设计意图：

资料来源：README.md:80-140

双模式部署与可扩展性

自 v2.1.0 起，项目以双模式运行：作为 MCP Server（stdio/SSE）被 Claude Desktop、Cursor、Cline 等客户端直接调用；或作为 CLI 二进制 fasm 在终端独立使用。资料来源：docs/research/2026-07-26-agent-search-product-architecture.md:90-140 Docker 镜像也得到同步精简——npm install 即可获得完整功能，不再需要 Python 运行时。资料来源：README.md:160-200

版本演进显示项目持续向 "Agent 原生" 收敛：v3.1.0 引入 Tool Visibility Control；v3.1.1 完成 MCP 2025 规范合规并补充 DDG News 的 HTML 回退；v3.1.2 则聚焦注册表质量、元数据与 CI 流程。资料来源：docs/index.md:1-50

总体而言，agent-search-mcp 的设计哲学是：在不牺牲隐私与成本的前提下，把搜索与抽取能力以最小摩擦暴露给 Agent。所有能力均围绕 "免费、可降级、可裁剪" 三个属性展开，使开发者能在 Claude、Cursor、自建 Agent 框架之间无缝复用同一套检索后端。资料来源：README_zh.md:1-60

概述

agent-search-mcp 是一个基于 Model Context Protocol (MCP) 的搜索聚合服务器，提供无需 API Key 的「自由搜索」能力。其核心设计目标是：多引擎聚合 + 自动降级 + 工具粒度可控。当前版本（v3.1.2）已经实现了 8 个免费搜索引擎、Synthesis 合成引擎，并完成了 DDGS Independence（不再依赖 Python）等重要演进 资料来源：README.md:1-40。

总体分层架构

项目采用「CLI/Server 双入口 + 引擎注册表 + MCP 工具层」的三层结构。从 v2.1.0 起引入了 CLI 二进制 fasm 与双模式服务器（stdio/HTTP），并通过 ContextManager 统一管理请求上下文 资料来源：CHANGELOG.md:60-90。

flowchart TB
    A[MCP Client / Claude / IDE] -->|JSON-RPC| B[src/server.ts<br/>MCP Server]
    B --> C[Tool Layer<br/>free_search / free_extract<br/>search_with_synthesis / free_search_news]
    B --> D[Engine Registry<br/>src/engines/index.ts]
    D --> E1[duckduckgo-html.ts<br/>cheerio HTML 引擎]
    D --> E2[duckduckgo-web.ts<br/>Web API 引擎]
    D --> E3[duckduckgo.ts<br/>DDGS Python 封装]
    D --> E4[其他 5+ 引擎<br/>Bing/Brave/Startpage...]
    E1 -.失败降级.-> E2
    E2 -.失败降级.-> E3

CLI 入口与 MCP 服务器共享同一份引擎实现，避免逻辑分裂 资料来源：docs/architecture.md:1-50。

搜索引擎注册与路由

引擎注册表

src/engines/index.ts 是路由中枢，它以有序数组的形式注册所有引擎，并暴露统一的 search(query, options) 接口。每个引擎实现只需满足同一签名即可被插入到瀑布流中 资料来源：src/engines/index.ts:1-60。

Waterfall 搜索策略

v3.0.0 引入的 Synthesis Engine (search_with_synthesis) 采用瀑布搜索：按数组顺序依次调用每个引擎，首个返回非空结果即停止，保证在任意上游限流或宕机时仍能返回数据 资料来源：CHANGELOG.md:30-55。该策略同时复用于 free_search 与 free_search_news（后者串联 DDG News 与 Bing News） 资料来源：docs/architecture.md:80-120。

引擎实现与降级

DDGS Independence（v3.1.0 重大演进）

在 v3.1.0 之前，DDG 搜索依赖 Python 的 ddgs 包；之后项目通过 Node.js 的 cheerio 直接解析 HTML，实现了纯 Node 运行时，Docker 镜像不再需要 Python 资料来源：CHANGELOG.md:1-25。

• duckduckgo-html.ts：使用 cheerio 抓取 html.duckduckgo.com，作为零依赖的首选入口 资料来源：src/engines/duckduckgo-html.ts:1-80。
• duckduckgo-web.ts：调用 duckduckgo.com 的 Web 接口，作为 HTML 抓取失败时的二级回退 资料来源：src/engines/duckduckgo-web.ts:1-60。
• duckduckgo.ts：保留对官方 ddgs Python 包的封装，作为最终保底；环境检测失败时该引擎会被自动跳过 资料来源：src/engines/duckduckgo.ts:1-50。

8 个免费引擎

v3.0.0 起注册表中已包含 DDG（含三档）、Bing、Brave、Startpage、Mojeek、Yandex 等无 Key 引擎 资料来源：CHANGELOG.md:30-55。v3.1.1 进一步为 DDG News 增加了 HTML 抓取回退，以应对官方接口调整 资料来源：CHANGELOG.md:1-15。

工具暴露与可见性控制

src/server.ts 通过 MCP SDK 注册工具定义，调用引擎注册表完成实际搜索。v3.1.0 引入的工具可见性机制允许运维通过环境变量裁剪工具列表：

资料来源：CHANGELOG.md:1-25。该机制常用于 Glama 等托管平台的资源隔离——v3.1.2 进一步按 TDQS 框架优化了 free_search 与 free_extract 的描述 资料来源：CHANGELOG.md:1-10。

总结

整个系统围绕「注册表 + 瀑布流 + 降级链」展开：上层 MCP 工具暴露给客户端，中层引擎注册表负责路由与降级，下层多个独立实现保证零 API Key 也能完成搜索。理解这三层关系是后续扩展新引擎或定制工具行为的前提 资料来源：docs/architecture.md:120-160`。

概述与设计目标

agent-search-mcp 是一个基于 MCP（Model Context Protocol）协议的搜索服务器，其核心能力围绕三个相互协作的子系统展开：工具注册（Tool Registry）、搜索聚合（Aggregation）以及综合引擎（Synthesis Engine）。工具层负责把 MCP 客户端可见的能力以最小可发现单元暴露出来；聚合层负责在多个搜索源之间做并联或级联调度；综合引擎则在无需外部 LLM API 的前提下，通过 prompt_hint 把多源结果合成可读答案。社区关注的核心问题（v3.0.0、v3.1.0、v3.1.2）也集中在这三者的协同上。

工具注册与可见性控制

registry.ts 是所有工具的统一注册中心，决定哪些 MCP 工具会在握手阶段暴露给客户端。注册表读取环境变量 ENABLED_TOOLS 与 DISABLED_TOOLS，按照用户策略动态裁剪工具列表——这是 v3.1.0 引入的"工具可见性控制"能力的关键实现点。

// src/tools/registry.ts（示意）
const ENABLED = (process.env.ENABLED_TOOLS ?? "").split(",").filter(Boolean);
const DISABLED = (process.env.DISABLED_TOOLS ?? "").split(",").filter(Boolean);
function isVisible(name: string) {
  if (ENABLED.length && !ENABLED.includes(name)) return false;
  if (DISABLED.includes(name)) return false;
  return true;
}

资料来源：src/tools/registry.ts:1-40

注册表还统一维护工具的输入 schema 与描述文案。v3.1.2 依据 TDQS 框架优化了 free_search 与 free_extract 的描述，使 LLM 客户端能够更稳定地选择正确的工具。

资料来源：src/tools/free-search.ts:1-30，src/tools/free-extract.ts:1-30

搜索聚合：Free Search 与 Free Search Advanced

free-search.ts 与 free-search-advanced.ts 是聚合层的主入口。前者面向通用查询，瀑布式（waterfall）尝试多个免费引擎；后者提供时区、语言、来源白名单等高级过滤。两者都遵循同一聚合模式：

flowchart LR
  Q[用户查询] --> A[free-search 主调用]
  A --> B{DDG Node 引擎}
  B -- 命中 --> R[返回结果]
  B -- 失败 --> C[Bing HTML 引擎]
  C -- 命中 --> R
  C -- 失败 --> D[Startpage 兜底]
  D --> R

资料来源：src/tools/free-search.ts:40-120，src/tools/free-search-advanced.ts:40-140

v3.1.0 之后，DDG 引擎不再强依赖 Python 的 duckduckgo-search 包，Node.js 的 cheerio HTML 解析器会自动接管，从而让 Docker 镜像只需 npm install 即可运行。free_extract 与 fetch-tools.ts 共同负责把聚合得到的 URL 列表进一步抓取正文、提炼摘要，弥补纯搜索结果信息密度不足的问题。

资料来源：src/tools/free-extract.ts:1-80，src/tools/fetch-tools.ts:1-60

综合引擎：search_with_synthesis

search-with-synthesis.ts 是 v3.0.0 引入的标志性能力，名字即语义：它把"搜索"与"综合"两步合并成一次 MCP 调用。其工作流由三段组成：

1. 瀑布搜索：复用聚合层调用 free-search，收集多引擎结果并去重。
2. 结果排序：按来源可信度与查询相关度打分，截取前 N 条作为证据集。
3. prompt_hint 综合：把证据集注入到内嵌提示词模板中，由调用方 LLM 直接产出答案，避免再调用外部综合 API。

资料来源：src/tools/search-with-synthesis.ts:1-120

prompt_hint 字段允许调用者传入额外的引导语（例如"只引用前三条证据"或"用中文回答"），综合引擎会把它拼接到模板头部，从而在零外部依赖的情况下完成"搜索 → 合成"的闭环。这种设计是社区最关心的差异化能力之一，因为它让 MCP 客户端在不暴露密钥的前提下获得"问答级"输出。

资料来源：src/tools/search-with-synthesis.ts:120-220

协作模式与选型建议

资料来源：src/tools/registry.ts:40-120，src/tools/free-search-advanced.ts:140-220

如果客户端已经具备强 LLM 能力，优先选择 free_search + free_extract 以保留最大可控性；如果客户端是轻量代理或希望一次调用得到结论，使用 search_with_synthesis 收益更高。无论选择哪条路径，都应在部署时通过 ENABLED_TOOLS 明确开放的能力，避免在握手阶段泄露未使用的工具元数据——这也是 v3.1.2 在 Glama 质量评审中得到 A 级评分的合规要点。

资料来源：src/tools/registry.ts:1-80

部署形态与运行模式

项目在 src/server.ts 中注册 MCP 工具并以双模式启动，由 src/cli.ts 的 CLI 解析 --transport stdio|http 等参数决定监听方式 资料来源：src/cli.ts:1-80。HTTP 模式下服务监听 PORT（默认 3000）并暴露 POST /mcp、GET /mcp、DELETE /mcp 端点，鉴权由 AUTH_TOKEN 头承载 资料来源：docs/http-deployment.md:1-60。

Docker 镜像通过根目录 Dockerfile 构建，自 v3.1.0 起不再依赖 Python（DDG 检索改用 Node + cheerior 回退），仅需 npm install 即可运行 资料来源：Dockerfile:1-30。编排示例见 examples/docker-compose.yml，通常映射 3000:3000 并注入环境变量 资料来源：examples/docker-compose.yml:1-40。

flowchart LR
  A[客户端<br/>Claude Code / Cursor] -->|stdio| B[fasm CLI]
  A -->|HTTP+SSE| C[HTTP Server :3000]
  B --> D[MCP Tools]
  C --> D
  D --> E[Search Engines<br/>DDG/Bing/Brave…]

客户端接入配置

stdstdio 模式由宿主直接拉起 fasm，配置示例集中在 examples/：

• Claude Code：在 examples/claude-code-setup.md 中给出 claude_desktop_config.json 片段，命令为 fasm 或 npx -y agent-search-mcp，env 注入 API Key 资料来源：examples/claude-code-setup.md:1-40。
• Cursor：examples/cursor-setup.md 演示在 Cursor 的 MCP 设置中填入同一命令行 资料来源：examples/cursor-setup.md:1-30。
• HTTP 模式：宿主以 http://host:3000/mcp 形式连接，并在请求头携带 AUTH_TOKEN 资料来源：docs/http-deployment.md:20-50。

环境变量与工具可见性

src/config.ts 统一读取并校验上述变量，校验失败抛出结构化错误（v3.1.1 引入）资料来源：src/config.ts:1-90。自 v3.1.0 起，运维人员可通过 ENABLED_TOOLS/DISABLED_TOOLS 在不改代码的前提下控制 MCP 工具的可见集合，常用于最小权限发布 资料来源：docs/conventions.md:1-40。

运维要点

• npm 分发：v3.1.2 在 package.json 中补全 9 个 npm 关键词并接入发布流水线，可通过 npm i -g agent-search-mcp 安装 CLI 资料来源：package.json:1-50。
• CI/CD：仓库合并了 CI 工作流与发布流水线，README 顶部展示 CI 徽章，PR 自动跑构建与 lint 资料来源：docs/conventions.md:40-70。
• Glama 注册：glama.json 维护 maintainer 与相关 server 元数据，供 Glama 目录抓取，是 v3.1.2 质量从 B 升至 A 的关键文件之一 资料来源：glama.json:1-20。
• 健康检查：HTTP 模式下可访问 GET /health（由 src/server.ts 提供）判断进程存活；Docker 编排建议将其写入 healthcheck 字段 资料来源：examples/docker-compose.yml:20-40。
• 日志与错误：v3.1.1 起所有工具返回结构化错误对象（含 code 与 message），便于在客户端聚合与告警 资料来源：src/server.ts:40-90。
• 升级注意：跨大版本升级（如 v2 → v3）需关注 CLI 参数（--transport、--port）及工具签名（如新增 search_with_synthesis、free_search_news）的变更 资料来源：docs/conventions.md:70-100。

运维侧建议在容器化部署时固定镜像 tag、配合 ENABLED_TOOLS 做最小暴露，并把 AUTH_TOKEN 注入到宿主机的密钥管理系统中，避免明文落盘。

Pitfall Log / 踩坑日志

项目：lennney/agent-search-mcp

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/lennney/agent-search-mcp | host_targets=mcp_host, claude, cursor, claude_code

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/lennney/agent-search-mcp | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/lennney/agent-search-mcp | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/lennney/agent-search-mcp | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/lennney/agent-search-mcp | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/lennney/agent-search-mcp | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/lennney/agent-search-mcp | release_recency=unknown