内容
# 代理搜索 MCP
> 🔍 免费的多源搜索 AI 代理 — 多源验证、令牌节省、瀑布式搜索、MCP 原生。
[](LICENSE)
[](https://www.npmjs.com/package/agent-search-mcp)
[](https://www.npmjs.com/package/agent-search-mcp)
[](package.json)
[](https://modelcontextprotocol.io)
[](https://github.com/lennney/agent-search-mcp)
**与 Hermes、Claude Code、Cursor、Windsurf、OpenClaw、Codex 及任何 MCP 兼容的客户端兼容。**
---
[English](#why-agent-search-mcp) · [中文](README_zh.md) · [安装](#quick-start) · [工具文档](#tools) · [竞品对比](#competitor-comparison)
---
## 为什么选择 Agent Search MCP
**AI 代理需要搜索互联网。但现有方案都有问题：**
| 方案 | 价格 | 问题 |
|------|------|------|
| **Tavily** | $0.01/次 | 搜索多了成本高，月费 $20-50+ |
| **Exa** | $50/月起 | 语义搜索强但太贵 |
| **Brave Search** | 2000 次/月免费，之后 $3/1000 | 免费额度不够 |
| **Firecrawl** | $83/10万页 | 搜索+抓取一体，但量大了贵 |
| **Perplexity Sonar** | $5/千次 + token | 答案引擎，无法评估原始来源 |
| **Serper** | $0.30/千次 | 谷歌 SERP，无内容提取 |
| **DDG MCP** | 免费 | 单源、无验证、无去重、结果不稳定 |
**Agent Search MCP 的差异化：**
- **默认免费** — DuckDuckGo + Sogou + Bing + Baidu 为核心引擎，无需 API Key，开箱即用。Brave + Tavily 作为可选付费 fallback。
- **瀑布式渐进搜索** — 分阶段调用引擎，置信度达标即停，节省 50-75% 引擎调用。
- **多源验证** — 跨引擎交叉验证，每个结果有置信度评分（1-3），置信度 ≥2 的结果经过至少 2 个引擎验证。
- **内容丰富化** — 低置信度结果自动通过 Jina Reader 提取全文回填。
- **域名权威评分** — `.edu`/`.gov`/`.ac.xx` 域名加分，高质量站点加权，低质域名扣分。
- **自适应查询扩展** — 置信度不足时自动生成备选查询重搜，无需 LLM 参与。
- **Token 优化** — 标题 ≤100 字符，摘要 ≤200 字符，URL + 标题去重。节省 ~40-50% token 消耗。
- **渐进式披露** — 3 个工具按复杂度递增：`free_search` 快速问答、`free_search_advanced` 过滤搜索+瀑布流程、`free_extract` 页面提取。Agent 按需发现。
- **Fallback 机制** — 免费引擎优先，付费引擎备用。自动合并、去重、评分。
- **健康监控** — 实时追踪 Provider 健康状态，失败 Provider 自动过滤。
- **内置安全** — Prompt 注入检测、输出边界标记、钓鱼 URL 过滤、安全元数据。
---
## 竞品对比
| 功能 | Agent Search MCP | Tavily | Exa | Brave Search | Firecrawl | Perplexity Sonar | Serper | DDG MCP |
|---------|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| **价格** | 免费 | $0.01/次 | $50/月起 | $3/1000 | $83/10万页 | $5/千次 + token | $0.30/千次 | 免费 |
| **API Key** | 不需要 | 需要 | 需要 | 需要 | 需要 | 需要 | 需要 | 需要 |
| **免费额度** | 无限 | 1K/月 | $10 积分 | 2K/月 | 有限 | 无 | 2.5K/月 | 无限 |
| **多源验证** | ✅ 4+ 引擎 | ❌ 单源 | ❌ 单源 | ❌ 单源 | ❌ 单源 | ❌ 单源 | ❌ 单源 | ❌ 单源 |
| **瀑布式搜索** | ✅ 置信度分级 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| **内容丰富化** | ✅ 自动提取 | ✅ (内置) | ✅ (内置) | ❌ | ✅ (内置) | ✅ (合成) | ❌ | ❌ |
| **查询扩展** | ✅ 基于规则 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| **置信度评分** | ✅ 1-3 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| **域名权威** | ✅ Edu/Gov 加分 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| **去重** | ✅ URL + 标题 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| **Token 优化** | ✅ ~40-50% | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| **中文搜索** | ✅ Sogou + Baidu | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| **语义搜索** | ❌ | ❌ | ✅ 神经网络 | ❌ | ❌ | ❌ | ❌ | ❌ |
| **答案引擎** | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ 合成 | ❌ | ❌ |
| **人员/公司搜索** | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| **MCP 原生** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| **可自托管** | ✅ | ❌ 仅云端 | ❌ 仅云端 | ❌ 仅云端 | ❌ 仅云端 | ❌ 仅云端 | ❌ 仅云端 | ✅ |
| **安全性** | ✅ 注入保护 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| **依赖项** | 4 | 12+ | 15+ | 8 | 10+ | 8+ | 5 | 3 |
**关键差异：**
1. **默认免费** — 无需 API Key，无需信用卡，无限制。DuckDuckGo + Sogou + Bing + Baidu 开箱即用。
2. **多源验证** — 跨引擎交叉验证。置信度评分告诉您结果的可靠性。
3. **瀑布式搜索** — 独特的置信度分级多阶段搜索。在质量足够时停止，节省引擎调用和令牌。
4. **Token 优化** — 智能截断和去重减少令牌消耗 ~40-50%。
5. **中文支持** — Sogou + Baidu 提供原生中文网络搜索。不是翻译层。
6. **安全性** — 内置保护，防止 Prompt 注入、钓鱼 URL 和输出边界标记。
7. **渐进式披露** — 3 个工具在不同复杂度级别。Agent 按需发现功能。
---
## 快速开始
### 前置条件
- Node.js >= 18
- Python 3 并安装 `ddgs` 库：
```bash
pip install ddgs
```
### 安装
```bash
# 选项 1：npx（推荐）
npx agent-search-mcp
# 选项 2：全局安装
npm install -g agent-search-mcp
```
### 平台设置
<details>
<summary><b>Hermes</b></summary>
```yaml
# ~/.hermes/config.yaml
mcp_servers:
agent-search:
command: npx
args: ["agent-search-mcp"]
```
</details>
<details>
<summary><b>Claude Code</b></summary>
```json
// ~/.claude/mcp.json
{
"mcpServers": {
"agent-search": {
"command": "npx",
"args": ["agent-search-mcp"]
}
}
}
</details>
<details>
<summary><b>Cursor</b></summary>
```json
// .cursor/mcp.json
{
"mcpServers": {
"agent-search": {
"command": "npx",
"args": ["agent-search-mcp"]
}
}
}
</details>
<details>
<summary><b>Windsurf</b></summary>
```json
// ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"agent-search": {
"command": "npx",
"args": ["agent-search-mcp"]
}
}
}
</details>
<details>
<summary><b>OpenClaw</b></summary>
```typescript
// openclaw.config.ts
{
mcpServers: {
"agent-search": {
command: "npx",
args: ["agent-search-mcp"]
}
}
}
</details>
<details>
<summary><b>Codex</b></summary>
```json
// ~/.codex/mcp.json
{
"mcpServers": {
"agent-search": {
"command": "npx",
"args": ["agent-search-mcp"]
}
}
}
</details>
---
## 功能
### 核心搜索
- **免费默认** — DuckDuckGo + Sogou + Bing + Baidu 作为核心引擎，无需 API Key。
- **瀑布式渐进搜索** — 3 阶段置信度分级搜索：(1) DDG+Sogou → 检查置信度 → (2) Bing+Baidu → 检查 → (3) Brave+Tavily+Exa（付费）。
- **多源验证** — 跨引擎交叉验证，每个结果置信度评分（1-3）。
- **内容丰富化** — 低置信度结果自动通过 Jina Reader 提取全文回填。
- **域名权威评分** — `.edu`/`.gov`/`.ac.xx` 域名 +0.12；已知高质量站点加权；低质域名扣分。
- **自适应查询扩展** — 置信度不足时自动生成备选查询重搜。
### Token & 成本优化
- **Token 优化** — 标题 ≤100 字符，摘要 ≤200 字符，URL + 标题去重。节省 ~40-50% Token。
- **渐进式披露** — 3 个工具在不同复杂度级别。`free_search` 快速问答，`free_search_advanced` 过滤搜索+瀑布流程，`free_extract` 页面提取。
### 可靠性
- **Fallback 链** — 免费引擎优先，付费引擎作为备份。自动合并、去重和评分。
- **健康监控** — 实时追踪 Provider 健康状态。健康状况不佳的 Provider 自动过滤。
- **限率** — 每个提供商每秒 1 分钟间隔。
- **智能缓存** — LRU 缓存，60 秒 TTL（最多 1000 条记录）。
### 安全
- **Prompt 注入检测** — 阻止搜索查询中的注入模式。
- **输出边界标记** — 系统输出与搜索结果的清晰分隔符。
- **钓鱼 URL 过滤** — 检测并标记可疑 URL。
-` — 阻止私密 IP、localhost 和元数据端点。
- **安全元数据** — 每个响应都包含安全上下文。
### 附加功能
- **CLI 工具** — 作为终端搜索、网页提取和 HTTP 服务器的命令行工具。
- **HTTP/SSE 模式** — 作为 HTTP 服务器运行，带有 SSE 流（设置 `MODE=http`）。
- **上下文管理器** — 持续研究中的长运行自主会话管理。
---
## CLI 用法
agent-search-mcp 也可用作 CLI 工具。
### 安装
```bash
npm install -g agent-search-mcp
```
### 搜索
```bash
# 基本搜索
fasm search "TypeScript MCP 服务器"
# 带选项
fasm search "查询" --count 5 --engines bing,baidu
# JSON 输出
fasm search "查询" --json
```
### 提取网页内容
```bash
fasm extract "https://example.com"
fasm extract "https://example.com" --json
```
### 启动 HTTP 服务器
```bash
fasm serve --port 8080
```
### 帮助
```bash
fasm --help
```
---
## 工具
### `free_search`
基本网络搜索，多源验证。
```json
{
"query": "TypeScript MCP 服务器",
"count": 5
}
```
**返回：** 带有置信度评分（1-3）的搜索结果数组。
### `free_search_advanced`
高级搜索，瀑布式渐进搜索、过滤和丰富。
```json
{
"query": "MCP 服务器",
"count": 10,
"min_confidence": 2,
"time_range": "week",
"language": "zh",
"include_domains": ["github.com"],
"exclude_domains": ["reddit.com"]
}
```
**参数：**
- `min_confidence`（1-3）：仅返回结果由 N+ 个来源验证
- `time_range`：day, week, month, year
- `language`：auto, en, zh
- `include_domains`：仅搜索这些域名
- `exclude_domains`：排除这些域名
**瀑布式行为（默认启用）：**
1. 阶段 1：DDG + Sogou → 检查置信度篮
2. 阶段 2（如果需要）：Bing + Baidu → 检查篮
3. 阶段 3（如果需要）：Brave + Tavily + Exa（仅付费）
4. 内容丰富化：低置信度结果通过 Jina Reader 自动提取
5. 查询扩展（如果篮子仍然不足）：自动生成替代查询
### `free_extract`
从 URL 提取网页内容为 Markdown。
```json
{
"url": "https://example.com/article",
"max_length": 5000
}
```
**返回：** 带有元数据的 Markdown 内容。页面超过 `max_length` 时，完整文本存储在磁盘上。
### `search_with_synthesis`
深度搜索，多引擎验证。返回结构化结果和 `prompt_hint`，适用于 LLM 驱动的合成 - 无需外部 LLM API 调用。
```json
{
"query": "TypeScript MCP 服务器",
"count": 10,
"language": "auto",
"min_confidence": 1
}
```
**返回：** `{ results, prompt_hint, meta }` — `prompt_hint` 字段包含一个格式化的提示，适用于 LLM 合成带有引用的答案。
**行为：**
- 运行瀑布式搜索（DDG+Sogou → Bing+Baidu → Brave+Tavily+Exa）
- 自动丰富低置信度结果通过 Jina Reader
- 生成带有置信度评分和引用指南的 `prompt_hint`
### `free_search_news`
搜索最近的新闻文章，跨多个免费引擎。
```json
{
"query": "AI 监管",
"count": 10,
**time_range**: "week"
}
```
**来源：** DuckDuckGo News + Bing News（免费，无需 API Key）。
---
## 资源
### `search://capabilities`
返回一个 Markdown 文档，描述所有可用的工具和功能。Agent 可以按需发现功能。
### `search://health`
返回 JSON 数据，其中包含每个搜索提供商的健康状态。有助于监控和调试。
---
## 配置
### 环境变量
| 变量 | 描述 | 必需 |
|----------|-------------|----------|
| `BRAVE_API_KEY` | Brave Search API 密钥（每月 2000 次免费） | 否 |
| `TAVILY_API_KEY` | Tavily API 密钥（每月 1000 次免费） | 否 |
| `EXA_API_KEY` | Exa API 密钥（每月 1000 次免费） | 否 |
| `LOG_LEVEL` | 日志级别（info, debug） | 否 |
**零配置有效** — DDG + Sogou + Bing + Baidu 的基本搜索无需 API 密钥。
### 付费引擎
设置环境变量以启用备用付费引擎，当免费结果不足时使用：
```bash
export BRAVE_API_KEY=your_key_here
export TAVILY_API_KEY=your_key_here
export EXA_API_KEY=your_key_here
```
---
## 依赖项
| 依赖项 | 许可证 | 用途 |
|------------|---------|---------|
| @modelcontextprotocol/sdk | MIT | MCP 协议 |
| zod | MIT | 模式验证 |
| pino | MIT | 日志记录 |
| yaml | ISC | 配置解析 |
| ddgs (Python) | MIT | DuckDuckGo 搜索后端（绕过反机器人） |
**注意：** `ddgs` 是一个 Python 库，通过子进程调用。必须单独安装：
```bash
pip install ddgs
```
## 架构
```
代理
↓ MCP 协议（stdio / HTTP）
MCP 服务器
├── 工具层
│ ├── free_search（快速查询）
│ ├── free_search_advanced（瀑布式 + 过滤）
│ └── free_extract（页面内容）
├── 聚合层
│ ├── 瀑布式搜索引擎 ← 新增
│ │ ├── 阶段 1：DDG + Sogou
│ │ ├── 阶段 2：Bing + Baidu
│ │ └── 阶段 3：Brave + Tavily + Exa（付费）
│ ├── 内容丰富器（Jina） ← 新增
│ ├── 域名权威评分器 ← 新增
│ ├── 查询扩展器（规则引擎） ← 新增
│ ├── 置信度篮检查器 ← 新增
│ ├── 顶部 1 个摘要合并
│ ├── URL + 标题重复检查
│ ├── 评分 + 置信度
│ └── 输出截断
├── 安全层
│ ├── Prompt 注入检测
│ ├── 输出边界标记
│ ├── 钓鱼 URL 过滤
│ └── 安全元数据
├── Fallback 链
│ ├── 阶段 1：免费引擎（DDG + Sogou + Bing + Baidu）
│ └── 阶段 2：付费引擎（Brave + Tavily + Exa）
└── 基础设施
├── 缓存（LRU，60 秒 TTL）
├── 速率限制器（每提供商 1 秒）
├── 健康跟踪器
└── SSRF 防护
```
---
## 统计
| 指标 | 值 |
|--------|-------|
| 测试次数 | **149**（跨 13 个文件） |
| 源文件 | ~2,500 行 TypeScript |
| 免费引擎 | 4（DDG + Sogou + Bing + Baidu） |
| 付费引擎 | 3（Brave + Tavily + Exa） |
| npm 依赖项 | 4 个生产环境依赖项 |
| 总引擎 | 7 |
---
## 文档 / 文档
| 文档 | 描述 |
|----------|-------------|
| [PRD](docs/prd.md) | 产品需求文档 |
| [架构](docs/architecture.md) | 技术架构 |
| [计划](docs/plan.md) | 实现计划 |
| [审查结果](docs/review-results.md) | 5 支团队审查结果 |
| [分叉计划](docs/fork-plan.md) | 分叉和修改计划 |
| [CHANGELOG](CHANGELOG.md) | 版本历史 |
---
## 开发
```bash
# 克隆
git clone https://github.com/lennney/agent-search-mcp.git
cd agent-search-mcp
# 安装
npm install
# 构建
npm run build
# 测试
npm test
# 运行
npm start
```
---
## 路线图
- [x] DDG + Sogou 免费引擎，多源验证，去重，评分
- [x] Bing + Baidu 引擎，HTTP/SSE 模式，安全层，配置模块
- [x] CLI 二进制文件（`fasm`），上下文管理器，双模式服务器
- [x] **瀑布式搜索，内容丰富化，域名权威，查询扩展** ← 你在这里
- [ ] 语义/神经搜索（基于嵌入的概念匹配）
- [ ] 答案引擎模式（多源结果上的 LLM 合成）
- [ ] 实体特定搜索（人员，公司，代码）
- [ ] 自定义引擎的插件系统
- [ ] 浏览器端提取（Playwright）
---
## 许可证
[Apache License 2.0](LICENSE)
基于 [open-websearch](https://github.com/Aas-ee/open-websearch) 由 Aas-ee 构建。
```
Copyright 2025 Open-WebSearch MCP 服务器贡献者
基于 open-websearch 由 Aas-ee 构建（Apache 2.0）。
由 Agent Search MCP 贡献者修改。
Copyright 2026 Agent Search MCP 贡献者
```
---
## 贡献
欢迎贡献！请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器