Skip to main content
Glama
smart-search MCP

smart-search MCP

README.md
# smart-search MCP

> 一个 MCP 服务器:**多引擎并发搜索 → 合并去重 → 相关性重排 → 站点约束 → 正文补全 → LLM 去噪整理**,
> 对外只暴露一个 `smart_search` 工具,返回带来源编号的整理结果,而不是一堆原始链接。

## 为什么不是直接调搜索 API

直接调一个搜索 API,拿到的是 10 条带摘要的链接。真用起来会撞上五个问题:

| 问题 | 这里的处理 |
|------|-----------|
| 单一引擎覆盖不全(中文长尾 / 英文技术内容各有偏科) | Tavily + Exa + 知乎并发,配了几个就查几个,单源挂了不拖垮整体 |
| 同一篇文章被多个站点转载,重复占位 | `difflib` 内容相似度 > 0.95 视为转载,只留一条 |
| 一个站点霸屏 | 同域名最多保留 3 条(软约束) |
| 摘要太短,LLM 引用不到关键信息 | 正文不足 300 字的条目,并发抓原页补齐 |
| 权威源被相关性分数挤掉 | 质量源(gov.cn / edu.cn / cnki.net 等)保底补入 2 条 |

最后交给 LLM 去噪整理成「整理 / 推荐关键词 / 来源」三段,论断后带 `[1]` 这样的来源编号。

## 处理管线

```
query
  │
  ├─ 语言分流:中文走重排,英文直搜(BGE 对英文 query 打分系统性偏低)
  │
  ├─ 多引擎并发:Tavily / Exa / 知乎(按配置自动启用,单源失败只记 warning)
  │     └─ 逐源去重 → 轮转交错(防止单源霸屏)→ 全局去重 → 候选池
  │
  ├─ 相关性重排(可选,bge-reranker-v2-m3;未部署则保持引擎原始顺序)
  │
  ├─ 净化:内容级去重 → 同站点限流 → 质量源保底
  │
  ├─ 正文补全(只补 content 太短的,最多 3 条并发)
  │
  └─ LLM 整理(可选,失败自动降级为 JSON 列表)
       └─ 输出:## 整理 / ## 推荐关键词 / ## 来源
```

缓存两层,都是进程内 LRU 128 / TTL 300 秒:引擎结果一层、LLM 整理结果一层,键相同。
所以同一个 query 在 5 分钟内重复问不重复付费。

## 快速开始

**1. 装依赖**(Python 3.10+)

```bash
pip install -r requirements.txt
```

**2. 配 key**

```bash
cp .env.example .env      # 至少填 TAVILY_API_KEY
```

也可以不建 `.env`,直接把变量写进 MCP 客户端的 `env` 配置里(推荐,见下一步)。

**3. 接入 MCP 客户端**

客户端配置里加一条(模板见 [`skill/references/mcp-entry.json`](skill/references/mcp-entry.json)):

```json
{
  "mcpServers": {
    "smart-search": {
      "command": "python",
      "args": ["/path/to/smart-search-mcp/smart_search_server.py"],
      "env": {
        "TAVILY_API_KEY": "tvly-xxxxxxxx",
        "SMART_SEARCH_LLM_API_KEY": "sk-xxxxxxxx",
        "SMART_SEARCH_LLM_THINKING": "0"
      },
      "timeout": 180
    }
  }
}
```

**`timeout` 要给足 180 秒。** 最坏情况是 Tavily 30s×2 + 重排 120s×2 + 正文补全 6s×3 + LLM 60s,
留默认的 60 秒,慢查询会被客户端掐断,报的是「工具超时」而不是服务器错误,很容易误判。

跑一下体检,确认环境没问题:

```bash
bash skill/scripts/preflight.sh
```

命令行直接试一次(不需要客户端):

```bash
python skill/scripts/call.py "数字乡村治理 最新政策" '{"top_k":5,"days":30}'
```

## 配置项

全部走环境变量,改完不用动代码。

### 搜索引擎(至少一个)

| 变量 | 说明 |
|------|------|
| `TAVILY_API_KEY` | [Tavily](https://app.tavily.com),免费额度 1000 次/月,最省事 |
| `EXA_API_KEY` | [Exa](https://exa.ai),英文检索质量好,配了之后英文查询会自动并发走它 |
| `ZHIHU_ACCESS_SECRET` | 知乎开放平台 access secret。Windows 也可存进凭据管理器(条目 `zhihu-cli:access-secret`),其它平台只能用这个变量 |

**没配的源会被自动跳过,不会报错。** 但一个都没有就搜不了。

### 重排服务(可选)

| 变量 | 默认 | 说明 |
|------|------|------|
| `SMART_SEARCH_RERANK_URL` | `http://127.0.0.1:19002/v1/rerank` | 协议为 llama.cpp `/v1/rerank` |
| `SMART_SEARCH_RERANK_MODEL` | `bge-reranker-v2-m3` | |
| `SMART_SEARCH_RERANK_REQUIRED` | `0` | 置 1 则重排不可用时直接报错,不降级 |

**不部署也能跑**——中文查询会保持引擎原始顺序,只是少了相关性排序。
要部署的话:

```bash
llama-server -m bge-reranker-v2-m3-Q8_0.gguf --rerank --port 19002
```

### LLM 整理层(可选)

| 变量 | 默认 | 说明 |
|------|------|------|
| `SMART_SEARCH_LLM_API_KEY` | 空 | 留空则跳过整理,直接返回 JSON 列表 |
| `SMART_SEARCH_LLM_API_URL` | `https://api.deepseek.com/chat/completions` | 任意 OpenAI 兼容的 chat completions 端点 |
| `SMART_SEARCH_LLM_MODEL` | `deepseek-chat` | |
| `SMART_SEARCH_LLM_THINKING` | `0` | 置 1 开启推理模型的思考;整理任务不需要,开着延迟从 ~2s 涨到 ~14s |

## 工具参数

```
smart_search(query, max_results=5, top_k=3, days=0, topic="auto", min_score=0.3)
```

| 参数 | 默认 | 说明 |
|------|:---:|------|
| `query` | 必填 | 关键词或完整问题 |
| `max_results` | 5 | 每个引擎要多少条,1–20;实际候选池是它的 2 倍(多源合并后粗筛) |
| `top_k` | 3 | 净化后返回几条 |
| `days` | 0 | 限定近 N 天,**只在 news 模式生效** |
| `topic` | `auto` | `auto`(有 days 就走 news)/ `general` / `news` |
| `min_score` | 0.3 | 相关性门槛。重排分数是 logits 尺度,可为负;结果太少就降到 0.2 |

两个要注意的地方:

- **`days` 的坑**:Tavily 在 `general` 模式下会**静默忽略** `days`,返回一批没有发布时间的聚合首页。要时效性就显式给 `days` 或 `topic="news"`。
- **英文查询会跳过重排**:`min_score` 在这种模式下不生效,结果按引擎原始相关性排序取 `top_k`。原因是本地 BGE 对英文 query 打分系统性偏低,Exa 的排序反而更准。

## 返回格式

正常是三段纯文本:`## 整理`、`## 推荐关键词`、`## 来源`(只列 LLM 实际引用过的编号)。

LLM 整理失败时降级为紧凑 JSON:

```json
{"query":"…","returned":3,"results":[{"rank":1,"score":0.87,"title":"…","url":"…","content":"…"}],
 "cached":false,"llm":"degraded","llm_error":"…"}
```

错误一律以 JSON 返回,不抛异常:

| 返回 | 含义 |
|------|------|
| `搜索工具无该结果` | 无结果,或全部低于 `min_score` |
| `重排服务不可用或无有效结果` | `SMART_SEARCH_RERANK_REQUIRED=1` 且 `:19002` 没起 |
| `网络请求失败: …` | 引擎超时 / 断网 / key 失效 |
| `参数错误: …` | 参数类型不对 |

## 目录结构

```
smart-search-mcp/
├── smart_search_server.py        # 唯一入口,单文件
├── requirements.txt
├── .env.example
├── skill/                        # 以 pi 为例的接入与运维说明
│   ├── SKILL.md
│   ├── references/
│   │   ├── mcp-entry.json        # 客户端配置模板
│   │   ├── operations.md         # 排障、常量、备份回滚
│   │   └── pi-mcp.md             # pi 侧 exposure / timeout 细节
│   └── scripts/
│       ├── call.py               # 命令行直连,验证服务器可用
│       └── preflight.sh          # 环境体检
└── docs/运维手册-smart-search-MCP.md
```

## 已知限制

- 服务器会把 query 和抓到的网页正文发给 LLM 做整理。**敏感查询请自己权衡**,或置空 `SMART_SEARCH_LLM_API_KEY` 关掉整理层。
- 知乎源的 key 在非 Windows 平台只能走环境变量;凭据管理器读取是 Windows 专属实现。
- 去重靠 `difflib` 文本相似度,对「同一事件不同写法」的报道无效(那是聚类问题,不是去重问题)。
- 质量源名单是按社科场景写死的(`QUALITY_SITES`),换领域要自己改。
- 正文补全只处理前 3 条短摘要,不做全量抓取。
- 缓存是进程内内存,宿主重启即清空。

## License

MIT,见 [LICENSE](LICENSE)。