smart-search MCP
Integrates with Zhihu as a concurrent search source via the Zhihu Open Platform access secret, contributing results to the multi-engine search, deduplication, reranking, and source-cited output pipeline.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
smart-search MCP
一个 MCP 服务器:多引擎并发搜索 → 合并去重 → 相关性重排 → 站点约束 → 正文补全 → LLM 去噪整理, 对外只暴露一个
smart_search工具,返回带来源编号的整理结果,而不是一堆原始链接。
为什么不是直接调搜索 API
直接调一个搜索 API,拿到的是 10 条带摘要的链接。真用起来会撞上五个问题:
问题 | 这里的处理 |
单一引擎覆盖不全(中文长尾 / 英文技术内容各有偏科) | Tavily + Exa + 知乎并发,配了几个就查几个,单源挂了不拖垮整体 |
同一篇文章被多个站点转载,重复占位 |
|
一个站点霸屏 | 同域名最多保留 3 条(软约束) |
摘要太短,LLM 引用不到关键信息 | 正文不足 300 字的条目,并发抓原页补齐 |
权威源被相关性分数挤掉 | 质量源(gov.cn / edu.cn / cnki.net 等)保底补入 2 条 |
最后交给 LLM 去噪整理成「整理 / 推荐关键词 / 来源」三段,论断后带 [1] 这样的来源编号。
Related MCP server: Agent Search MCP
处理管线
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+)
pip install -r requirements.txt2. 配 key
cp .env.example .env # 至少填 TAVILY_API_KEY也可以不建 .env,直接把变量写进 MCP 客户端的 env 配置里(推荐,见下一步)。
3. 接入 MCP 客户端
客户端配置里加一条(模板见 skill/references/mcp-entry.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 skill/scripts/preflight.sh命令行直接试一次(不需要客户端):
python skill/scripts/call.py "数字乡村治理 最新政策" '{"top_k":5,"days":30}'配置项
全部走环境变量,改完不用动代码。
搜索引擎(至少一个)
变量 | 说明 |
| Tavily,免费额度 1000 次/月,最省事 |
| Exa,英文检索质量好,配了之后英文查询会自动并发走它 |
| 知乎开放平台 access secret。Windows 也可存进凭据管理器(条目 |
没配的源会被自动跳过,不会报错。 但一个都没有就搜不了。
重排服务(可选)
变量 | 默认 | 说明 |
|
| 协议为 llama.cpp |
|
| |
|
| 置 1 则重排不可用时直接报错,不降级 |
不部署也能跑——中文查询会保持引擎原始顺序,只是少了相关性排序。 要部署的话:
llama-server -m bge-reranker-v2-m3-Q8_0.gguf --rerank --port 19002LLM 整理层(可选)
变量 | 默认 | 说明 |
| 空 | 留空则跳过整理,直接返回 JSON 列表 |
|
| 任意 OpenAI 兼容的 chat completions 端点 |
|
| |
|
| 置 1 开启推理模型的思考;整理任务不需要,开着延迟从 ~2s 涨到 ~14s |
工具参数
smart_search(query, max_results=5, top_k=3, days=0, topic="auto", min_score=0.3)参数 | 默认 | 说明 |
| 必填 | 关键词或完整问题 |
| 5 | 每个引擎要多少条,1–20;实际候选池是它的 2 倍(多源合并后粗筛) |
| 3 | 净化后返回几条 |
| 0 | 限定近 N 天,只在 news 模式生效 |
|
|
|
| 0.3 | 相关性门槛。重排分数是 logits 尺度,可为负;结果太少就降到 0.2 |
两个要注意的地方:
days的坑:Tavily 在general模式下会静默忽略days,返回一批没有发布时间的聚合首页。要时效性就显式给days或topic="news"。英文查询会跳过重排:
min_score在这种模式下不生效,结果按引擎原始相关性排序取top_k。原因是本地 BGE 对英文 query 打分系统性偏低,Exa 的排序反而更准。
返回格式
正常是三段纯文本:## 整理、## 推荐关键词、## 来源(只列 LLM 实际引用过的编号)。
LLM 整理失败时降级为紧凑 JSON:
{"query":"…","returned":3,"results":[{"rank":1,"score":0.87,"title":"…","url":"…","content":"…"}],
"cached":false,"llm":"degraded","llm_error":"…"}错误一律以 JSON 返回,不抛异常:
返回 | 含义 |
| 无结果,或全部低于 |
|
|
| 引擎超时 / 断网 / 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。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Web search, Google SERP, page extraction to markdown and cited answers for AI agents.
Web search, fetch, extract, and research for AI agents. Markdown output + AI-synthesized answers.
LLM-ready web search + instant answers + URL-to-clean-text fetch for agents and RAG.
Web search for AI agents: one query across 10 providers, deduplicated, licensed results flagged.
Related MCP Servers
- AlicenseCqualityBmaintenanceEnables unified web search across multiple providers (AnySearch, SearXNG, Tavily) and deep research via DeepSeek's web_search_20250305 tool, with optional OpenRouter reranking for improved result ordering.22MIT
- AlicenseNot gradedqualityAmaintenanceEnables free-first English and Chinese web search through zero-key engines plus optional paid providers, returning compact multi-source evidence with bounded token and request budgets. Each result exposes provenance, independent source counts, routing decisions, and visible provider failures so agents can verify claims rather than receive unexplained empty results.171 npmApache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables parallel web search across Exa, Firecrawl, and context.dev with deduplicated reciprocal-rank-fusion results, plus URL-to-markdown fetching with optional sourced LLM bias scoring.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to run multi-channel searches across GitHub, Hacker News, Bilibili, Juejin, Exa, and optionally arXiv, then fetch and read original sources such as webpages as Markdown, GitHub PR reviews and inline comments, embedded chart data, and Bilibili fallback content. It reports partial results, failed channels, truncation, and coverage so agents can decide whether to search again or paginate.MIT