Biajin-PKU/topper-mcp · 上手攻略

  • 仓库：Biajin-PKU/topper-mcp
  • 链接：https://github.com/Biajin-PKU/topper-mcp · PyPI：topper-mcp（截至 2026-09 抓取被 PyPI 反爬拦截，版本号待复核）
  • 分类：学术检索 / LLM 工具 / MCP 服务
  • 作者：spark
  • 更新：2026-09-07

⚠️ 存疑/待核：① 仓库 GitHub Releases 页面截至抓取时为空，故无法锚定具体 release tag 版本号；下文安装命令中的版本号一律按"无版本约束"或"PyPI 最新"处理，使用前请 pip index versions topper-mcp 自行确认。② PyPI 详情页因反爬未拿到，只在 README 自述与 GitHub 源文件层面验证过命令格式。

1. 这是什么

topper-mcp（"Top Paper Retriever"）是一个只搜顶刊顶会的学术论文检索器，以三种形态分发：

  1. Python 库：import topper; search(...)
  2. 命令行工具：topper search / topper plan / topper tiers
  3. MCP Server：topper-mcp 可执行文件，可挂到 Claude Desktop / Cursor / Cline / OpenCode 等任意 MCP 客户端

它的核心定位是"档次门"——返回结果先按 CCF 推荐目录 / 中科院分区 / JCR / SCI 收录 / 旗舰刊名单 过滤，再做相关性打分。普通检索器（arXiv 直查、Semantic Scholar、Google Scholar）默认是"全收录然后排序"，噪声大；topper 把"档次"当成一级硬约束，光有声望也未必能进，光相关但发在低档会议也不行。

底层的检索流水线（README 自述）：

研究问题 ──▶ LLM 写检索简报（query families + 领域术语）
       ──▶ 多轮检索（Semantic Scholar + OpenAlex，合并去重）
       ──▶ 档次门（CCF / 中科院 / JCR / WoS / 旗舰刊）
       ──▶ 相关性门（主题契合度）
       ──▶ 打分 + 全景（学派、活跃团队）

引擎本体零运行时依赖（仅标准库），LLM 调用和数据源检索是外部依赖。

2. 解决什么问题

研究生 / 研究员 / 综述作者在做文献综述时常见的三个痛点：

  1. 档次过滤靠记忆：要回答"近三年这个方向有哪些 CCF A 类工作"，正常做法是凭印象 + Google Scholar + 反复核对 CCF 目录。topper 把这件事自动化，且门槛可配置。
  2. 跨数据源去重：一篇论文在 Semantic Scholar 和 OpenAlex 各有 ID，topper 内部合并去重。
  3. 检索简报可复用：检索计划（query families）由 LLM 生成，可独立缓存（"同一个问题再问一次快得多"——README 原话）。

不适用的场景：

  • 需要抓取付费全文（README 明确："只返回元数据和链接，不抓取付费全文"）。
  • 想知道某方向预印本最新进展——topper 走的是已发表工作的索引，不是 arXiv first-look。
  • 想做系统综述（systematic review）级别的 PRISMA 流程——topper 是检索器，不是文献管理软件。

3. 快速安装

3.1 Python 库 + CLI（最常用）

# 仅库和命令行（引擎零依赖，纯标准库）
pip install topper-mcp

# 含 MCP server（额外依赖：mcp SDK）
pip install "topper-mcp[mcp]"

# 可编辑模式 + dev 依赖（含 pytest）
pip install -e ".[dev,mcp]"

# 自检：会逐条告诉你缺什么
topper doctor

⚠️ 待核：PyPI 抓取失败，无法给出当前最新稳定版本号。CI 之前请用 pip index versions topper-mcp 或 pip install topper-mcp== 让 pip 自动选最新。

3.2 必填环境变量

topper doctor 会点名缺失项。两条强必填：

变量 必填 说明
TOPPER_LLM_API_KEY 是 任何 OpenAI 兼容端点（OpenAI 官方 / 本地 vLLM / Ollama 网关 / 中转）
TOPPER_LLM_MODEL 是 例如 gpt-4o-mini，无默认值，必须显式指定
TOPPER_LLM_BASE_URL 否 默认 https://api.openai.com/v1
TOPPER_LLM_FALLBACK_MODELS 否 逗号分隔，主模型不可用时依次回退
SEMANTIC_SCHOLAR_API_KEY 否 不填也能跑，会被限流到几秒一次
OPENALEX_MAILTO 否 OpenAlex 礼貌策略；不填走慢速公共池
TOPPER_DATA_DIR 否 档次表位置，详见 topper/data/README.md

.env 模板：

cp .env.example .env
# 编辑 .env，填两项强必填

3.3 MCP 客户端配置

把下面这段塞到 Claude Desktop / Cursor / Cline 的 MCP 配置（一般是 ~/.config/claude/mcp.json 或客户端 UI 里）：

{
  "mcpServers": {
    "topper": {
      "command": "topper-mcp",
      "env": {
        "TOPPER_LLM_API_KEY": "sk-...",
        "TOPPER_LLM_MODEL": "gpt-4o-mini",
        "SEMANTIC_SCHOLAR_API_KEY": "..."
      }
    }
  }
}

服务器暴露三个工具（README 自述）：

工具 作用
search_top_papers 检索
explain_venue 查一个期刊/会议的档次标签
preview_search_plan 只生成检索计划，不打数据源（成本/延迟都更低）

4. 核心用法

4.1 CLI

# 完整检索：一次 LLM 调用 + 若干数据源往返，通常 30–120 秒
topper search "钙钛矿太阳能电池的稳定性衰减机理与界面钝化策略"

# 只出检索计划（query families + 领域术语），不打数据源
topper plan "双重差分 多期处理 异质性"

# 查一个刊/会的档次标签
topper tiers "Journal of Econometrics"

4.2 Python

from topper import search, SearchPolicy

hits = search(
    "graph neural networks",
    policy=SearchPolicy(
        ccf_levels=("A", "B"),
        cas_zones=(1, 2),
        max_age_years=5,
    ),
    limit=20,
)

SearchPolicy 的主要参数（README 提到，按命名推断）：

  • ccf_levels：CCF A/B/C 等级白名单
  • cas_zones：中科院分区 1–4 区白名单
  • max_age_years：时间窗
  • limit：返回条数上限

⚠️ 待核：SearchPolicy 的完整参数列表未在 README 详尽列出，建议读 topper/__init__.py 源码或 help(SearchPolicy) 获取。

4.3 MCP 客户端

配好 §3.3 之后，对话里直接说："用 topper 帮我找近三年 SIGMOD 上图数据库索引相关的论文"——客户端会调 search_top_papers。

想"先看检索计划再决定要不要花 token 检索"：让客户端调 preview_search_plan，返回的 query families 可以人工审核，再决定是否升级到 search_top_papers。

5. 典型适用场景

  1. 综述写作前的"档次核查"：写 Related Work 时，担心引了一篇 C 类甚至非 CCF 工作被审稿人挑刺，先用 search_top_papers 限定 ccf_levels=("A",) 跑一遍。
  2. 跨学科入门：新方向不熟，让 topper 先出一份"检索计划 + 全景"，看 query families 比直接读综述更省时间。
  3. 导师/合作者问"这个方向谁在发顶会"：topper search ... 返回结果里通常带活跃团队（README 提到"打分 + 全景"环节）。
  4. MCP 工作流嵌入研究助手：Claude Desktop / Cursor 配好 topper-mcp 后，写作过程中随时可以问"这个引用够不够顶"。
  5. 本地 LLM 网关用户：因 TOPPER_LLM_BASE_URL 可改 + 兼容 OpenAI 协议，vLLM / Ollama / LM Studio 用户可以把"档次检索"完全本地化。

6. 坑与注意

  1. 两次抓取失败：本次写攻略时，PyPI 详情页被反爬拦截，GitHub Releases 页面为空 → 无法给出锚定版本号。安装前自行验证 PyPI 上的最新版。
  2. 强必填两项：少填 TOPPER_LLM_API_KEY 或 TOPPER_LLM_MODEL 会直接报错。topper doctor 是唯一自检入口，养成跑它的习惯。
  3. 慢：README 自述"30–120 秒一次检索"——LLM 生成检索简报 + 多轮数据源查询是主因。缓存命中时快得多，但首次必然慢。MCP 客户端配 timeout 时建议 ≥180s。
  4. 不抓全文：免费档（不填 Semantic Scholar key）会被限速到几秒一次；填了 key 会更快，但仍只返回元数据 + 链接，付费墙之后的全文别想。
  5. CCF 目录是 2026 版：README 写"CCF 推荐目录 2026"（670 条：A 87 / B 234 / C 349）；中科院分区、JCR 等多份名录共存于 topper/data/，各自的"使用条款"以原始来源为准，仓库不二次分发——按 README 说法，把这些名录放进 TOPPER_DATA_DIR 才能生效。
  6. 缺表不致命：topper doctor 会报告缺哪几张表，但不会因此拒绝运行——只是某些门控失效（例如缺 CCF 表则 ccf_levels 过滤退化为空操作）。
  7. 隐私：检索问题会发送给 LLM 网关（OpenAI 兼容端点）。涉及未公开研究方向/敏感术语时，用本地 vLLM 网关 + 关掉 OpenAlex MAILTO。
  8. 品牌 vs 代码双许可：代码 MIT，但仓库 assets/、TOPPER 名称与标识不在 MIT 范围内——fork 用没问题，发布同名/同标识产品会侵权。

7. 与同类对比

工具 档次门 数据源 MCP 离线 LLM 备注
topper-mcp CCF / 中科院 / JCR / WoS / 旗舰刊 5 重 Semantic Scholar + OpenAlex ✅ ✅（OpenAI 兼容协议） 本篇主角
直接用 Semantic Scholar API 无 Semantic Scholar 需自己包装 任意 噪声大
Google Scholar 无 Google 需自己包装 任意 反爬严格、限速重
arXiv 检索 仅 pre-print arXiv 需自己包装 任意 不含已发表顶刊
OpenAlex 直接调用 可自己写过滤 OpenAlex 需自己包装 任意 "礼貌策略"需要 mailto
文献管理软件（Zotero / Connected Papers） 看导入源 视具体工具而定 部分支持 — 主要做组织/可视化，非检索

定位总结：topper 是"档次过滤 + LLM 检索简报 + MCP 三栖"的窄而深工具。如果你只想做"找最近 arXiv 论文"或"导入到 Zotero"，它不划算；如果你的痛点是"找顶会顶刊上的某方向论文"，它最对口。

8. 一句话推荐

想让 LLM 帮你找只来自顶会顶刊的论文、并且要挂到 Claude/Cursor 上用——pip install "topper-mcp[mcp]" + 填两项环境变量 = 30 分钟上手，别忘了先跑 topper doctor。

事实核查表（⚠️ 标 = 数据来自 README 自述，未二次验证）：

数据 出处 状态
CCF 推荐目录 670 条（A 87 / B 234 / C 349） README ⚠️ 待 CCF 官网复核
旗舰刊 38 本（含 Nature/Science/Cell 等） README ⚠️ 待人工核对清单
pip install topper-mcp 与 topper-mcp[mcp] 命令 README ✅ 与 PyPI 项目名一致
三个 MCP 工具名（search_top_papers / explain_venue / preview_search_plan） README ⚠️ 待源码复核
Semantic Scholar key 不填会被限速 README ⚠️ 待实测
检索耗时 30–120 秒 README ⚠️ 待实测
GitHub Releases 为空 抓取时确认 ✅

本次攻略未做事项：未跑 topper search 实测（避免消耗 LLM token）；未 clone 仓库验证目录结构；未做 SearchPolicy 全字段源码核对。下一棒若需复核，从这三个入口入手最快。