PubMed Search

PubMed Search MCP

面向 AI Agent 的专业文献研究助手——不只是 API 封装

基于领域驱动设计（DDD）的 MCP 服务，作为 AI Agent 的智能研究助手，提供面向任务的文献搜索和分析能力。

✨ 功能一览：

• 🔧 41 个 MCP 工具——精简整合 PubMed、Europe PMC、CORE、NCBI 数据库访问，以及带版本管理的 Research Chronicle
• 🛡️ 多 Agent 服务模式——部署一次，即可服务多个 Agent：按租户隔离会话、缓存和资料，提供 Bearer 令牌身份验证和按租户公平共享的限额。参阅 DEPLOYMENT.md
• 🖼️ 开放获取论文图片提取——从 PMC 开放获取文章中提取图片说明、直接图片 URL 和 PDF 链接
• 📘 文档网站——浏览完整的多语言手册：用户工作流、架构、41 个工具参考、管道教程、数据源／代理契约、集成与运维、安全和部署，访问 u9401066.github.io/pubmed-search-mcp
• 📖 GitHub Wiki——同一套规范文档的 GitHub 原生镜像，访问 github.com/u9401066/pubmed-search-mcp/wiki
• 📚 26 个 Claude Skills——可直接使用的 AI Agent 工作流指南（专为 Claude Code 编写）
• 📖 Copilot 使用说明——VS Code GitHub Copilot 集成指南
• 研究自动化——定时管道差异分析／本地通知、Chronicle 重建摘要、多种子引文雪球式扩展，以及可选的会话去重（使用 options="exclude_seen"）。

🌐 语言：英语 | 繁體中文

📘 文档导航：README 是项目的快速入门入口。推荐使用 文档网站 获得最佳阅读体验，使用 GitHub Wiki 进行 GitHub 原生导航；编辑文档请查看源文件：用户指南 | 高级工作流 | 按能力分类的指南 | 统一搜索架构 | 41 个工具质量审计 | 60 个仓库的学术检索全景 | 提供方数据平面 | BioMCP 架构分析 | 开发者指南 | 完整索引

文档导航 · 维护脚本

---

研究自动化与便携式安装 — v0.8.0

定时流水线会报告范围明确的变更，并保留本地通知摘要。 Chronicle 重建摘要会与上一个版本进行比较；snowball 流水线 会扩展多个引文种子。普通搜索可以选择启用 options="exclude_seen" ，在 limit 生效前过滤本会话中此前返回的 PMID/DOI 标识； 此选项不能与 pipeline= 同时使用。接口仍包含 41 个工具。 请参阅使用指南和 流水线教程。

在上传到 PyPI 前会检查注册表元数据和插件差异。发布冒烟测试会在注册表 环境约定下验证指定 wheel 的所有权标记和全部 41 个已安装工具；随后通过 GitHub OIDC 在 PyPI 发布之后发布到注册表。

真实工作流冒烟测试与本地预检 — v0.7.7

本地 pretest 会在推送前运行完整回归门禁。CI 侧重于 Ubuntu/Windows 已安装构件以及真实的 MCP/提供方工作流；发布流程会验证指定的 wheel/sdist 和正在运行的非 root 容器。移除了 64 项较弱或已过时的测试，并提供了有据可查的 替代覆盖。请参阅测试策略和 分阶段发布审查。

后台全文预取与可靠的章节读取 — v0.7.6

选择启用的 XML 预取会与后续 get_fulltext 调用共享下载内容。请求已排队 的文章时会将其转为前台读取；搜索会返回可直接使用的读取参数。缺失章节会 报告可用标题，不会用摘要替代，也不会重复获取 PDF。预取默认仍处于关闭状态。 请参阅评估和 发布审查。

共享输入规范化 — v0.7.5

全部 41 个工具都支持自动修正 JSON 容器、十进制数字字符串、显式布尔文本、 枚举拼写和生物医学标识符。已发布的架构包含接受的表示形式；执行前错误会提供 精确的字段路径和修正约束。所有工具都会验证原生请求和规范化请求，包括一次 修正后重试。 请参阅输入格式与验证。

提供方安全的调度 — v0.7.4

现在，流水线分支会在依赖完成后立即继续执行，同时 API 请求速率限制保持不变。 共享并发会采用调用方中最保守的限制；429 冷却期会在超时和取消 PubMed 工作线程后 继续保留。历史计划已归档，并附有文档索引。请参阅 发布审查和 离线延迟实验； 固定延迟计时并不代表实时提供方的吞吐量或检索质量。

核心审查与可靠性 — v0.7.3

已完成十阶段核心审查：审查了 223 个源文件和 2,901 项定义，并记录了编写的决策和当前文件哈希。本次发布修复了源故障处理、文章身份识别、持久化、取消、导出和评估检查点，同时保留全部 41 个工具。安装测试工具时会保留用户自定义内容；贡献者须在推送前运行完整本地门禁，普通 CI 中则设有独立的冒烟测试门禁。行为变更请参阅变更日志。本地回归结果并不能证明公开基准测试取得了新的提升。

研究质量与评估 — v0.7.2

此版本改进了查询感知排序与融合、跨来源文章去重、书目核验、章节筛选和并发缓存获取。规范的 41 工具接口保持不变。

基准测试报告 将组件质量与完整 Agent 套件的价值区分开来。在公开的 BEIR NFCorpus 上，早期的 BM25 组件对比将测试集 nDCG@10 从 0.293357 提高到 0.297831。该结果并未衡量此版本完整 Agent 的性能。由 3 个问题组成的原生 Codex／套件试点规模太小，无法证明产品层面的提升；完整的 5,000 题评估已准备就绪，但尚未启动。

请阅读可靠性审计，了解已复现的缺陷、验证边界和修订指纹。参考文献核验会检查书目一致性；要确认论文是否支持某项主张，仍需检查相关段落。

🚀 快速安装

MCP Registry 和 Agent Plugin

对于支持官方 MCP Registry 或 GitHub MCP Registry 的客户端，请在版本发布后查找 io.github.u9401066/pubmed-search-mcp。Registry 元数据会通过 stdio 启动 uvx [email protected]；请在客户端中配置 NCBI_EMAIL 并可选择配置 NCBI_API_KEY。

对于兼容 Agent Plugins 1.0.0 的客户端，请使用客户端的 插件安装程序安装仓库中的 plugins/pubmed-search/ 目录。该目录包含固定版本的 MCP 启动器和研究技能； 客户端对插件的支持及安装界面各不相同。请参阅集成指南。

前置条件

• Python 3.10+ — 下载

• uv（推荐）— 安装 uv

  # macOS / Linux
  curl -LsSf https://astral.sh/uv/install.sh | sh
  # Windows
  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  

• NCBI Email — NCBI API 政策要求提供。可使用任何有效的电子邮件地址。

• NCBI API Key （可选） — 在此获取，以提高请求速率限制（10 req/s，而非 3 req/s）

• OpenAlex API Key （可选） — 设置 OPENALEX_API_KEY 以使用经过身份验证的额度；未设置时，请求将使用 OpenAlex 当前面向匿名用户的常规使用额度。mailto 是联系信息元数据，不用于身份验证。若未提供来源专用电子邮件地址，服务将为 OpenAlex、CrossRef 和 Unpaywall 重用已配置的运行时联系邮箱。

安装并运行

# Option 1: Zero-install with uvx (recommended for trying out)
uvx pubmed-search-mcp

# Option 2: Add as project dependency
uv add pubmed-search-mcp

# Option 3: pip install
pip install pubmed-search-mcp

Python SDK 门面

对于进程内 Python 集成，请使用稳定的 SDK 门面，而不要导入 MCP 工具模块：

from pubmed_search.api import PubMedSearchClient, PubMedSearchConfig

async with PubMedSearchClient(PubMedSearchConfig(email="[email protected]")) as client:
    result = await client.unified_search("remimazolam ICU sedation", limit=20)

    print(result.articles)
    print(result.source_counts)
    print(result.source_errors)
    print(result.result_filter_counts)

使用 uvx pubmed-search-mcp 或 /mcp 来发现 Agent 工具。对于 Python 包／笔记本调用，如果类型化对象比解析 MCP 响应字符串更方便，请使用 SDK。 SDK 会直接执行应用用例，并且有意不包含 MCP 会话日志或工件副作用；当需要持久重放和工件定位符时，请使用 MCP 工具。 异步上下文会负责管理并关闭每个提供方客户端和 HTTP 连接池。如果长时间运行的应用未使用 async with，请在关闭时调用 await client.aclose()。

选择运行时契约

契约	命令	网络与信任边界
本地 stdio	uvx pubmed-search-mcp	推荐用于单个本地 AI 客户端；没有正在监听的 MCP 端口
本地 loopback HTTP	pubmed-search-mcp-http --mode local --host 127.0.0.1	受信任的单用户集成；MCP 请求共享持久化的 default 租户，且绝不能公开此端口
多用户服务	pubmed-search-mcp-http --mode service	通过 HTTPS 提供远程/团队使用；必须启用 Bearer 身份验证、允许的主机/来源和按主体隔离的存储

本地部署和服务部署是有意区分的契约。不要只更改绑定地址， 就把本地 HTTP 命令变成公共服务。 显式本地配置会在 MCP 请求和重新连接之间，于持久化的 default 租户中保留 pmids="last"、会话、缓存和导出；这只有在强制执行的 loopback/Host/Origin 边界内才安全。服务模式绝不 继承此信任：没有 Bearer 主体时会默认拒绝请求。 服务环境和 Compose 配置请参阅 DEPLOYMENT.md。 当前服务配置支持在一个服务进程中处理多个已验证身份的主体；在会话、锁、 工件和订阅拥有共享后端之前，请保持单个副本。

协议基线为 MCP SDK v2（mcp>=2.0,<3）。现代 2026-07-28 客户端 会直接发送 tools/list 和 tools/call，不进行 initialize 握手，也不使用 Mcp-Session-Id。本地模式保留文件系统功能。经过身份验证的服务调用方 无法加载 file: 管道、无法选择笔记的 output_dir/template_file，也无法继承进程级管道工作区。 笔记响应使用相对于租户的逻辑定位符，绝不会暴露服务器文件系统路径。服务 Compose 调度器已 禁用。能力矩阵请参阅集成与运维指南。

---

⚙️ 配置

此 MCP 服务适用于任何兼容 MCP 的 AI 工具。选择你偏好的客户端：

VS Code / Cursor（.vscode/mcp.json）

{
  "servers": {
    "pubmed-search": {
      "type": "stdio",
      "command": "uvx",
      "args": ["pubmed-search-mcp"],
      "env": {
        "NCBI_EMAIL": "[email protected]"
      }
    }
  }
}

可选：启用浏览器会话 PDF 回退功能一次，让工具自动使用：

{
  "servers": {
    "pubmed-search": {
      "type": "stdio",
      "command": "uvx",
      "args": ["pubmed-search-mcp"],
      "env": {
        "NCBI_EMAIL": "[email protected]",
        "BROWSER_FETCH_CONFIG": "{\"enabled\":true,\"auto_enabled\":true,\"broker_url\":\"http://127.0.0.1:8766/fetch\",\"token\":\"<random-32-byte-token>\",\"allowed_hosts\":[\"jamanetwork.com\",\"*.jamanetwork.com\",\"nejm.org\",\"*.nejm.org\"]}"
      }
    }
  }
}

启用此设置后，get_fulltext 会自动尝试通过本地代理获取机构或出版商落地页。仅当你想在特定调用中禁用此功能时，才传入 allow_browser_session=false。

运行启用了下载拦截的本地代理：

uv sync --extra browser-broker
uv run playwright install chromium
uv run python -c "import secrets; print(secrets.token_urlsafe(32))"
uv run pubmed-browser-fetch-broker --token "<same-random-32-byte-token>"

将生成的值复制到两条命令/配置中；切勿重复使用 已公开的示例令牌。必须提供 --token、BROWSER_FETCH_BROKER_TOKEN 或 共享的 BROWSER_FETCH_TOKEN；代理会默认拒绝请求，而不是 生成或记录密钥。代理会启动一个启用了下载拦截的持久化浏览器 配置文件。在这个由代理控制的浏览器窗口中登录一次，之后的 PDF 下载就会 自动捕获，无需使用原生的“另存为”对话框。

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "pubmed-search": {
      "command": "uvx",
      "args": ["pubmed-search-mcp"],
      "env": {
        "NCBI_EMAIL": "[email protected]"
      }
    }
  }
}

配置文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

Claude Code

claude mcp add pubmed-search -- uvx pubmed-search-mcp

或者，将内容添加到项目根目录下的 .mcp.json：

{
  "mcpServers": {
    "pubmed-search": {
      "command": "uvx",
      "args": ["pubmed-search-mcp"],
      "env": {
        "NCBI_EMAIL": "[email protected]"
      }
    }
  }
}

Zed AI（settings.json）

Zed 编辑器（z.ai）原生支持 MCP 服务。将内容添加到 Zed 的 settings.json：

{
  "context_servers": {
    "pubmed-search": {
      "command": "uvx",
      "args": ["pubmed-search-mcp"],
      "env": {
        "NCBI_EMAIL": "[email protected]"
      }
    }
  }
}

提示：打开命令面板 → zed: open settings 进行编辑，或前往 Agent 面板 → 设置 →“添加自定义服务”。

OpenClaw 🦞（~/.openclaw/openclaw.json）

OpenClaw 通过 mcp-adapter 插件使用 MCP 服务。请先安装适配器：

openclaw plugins install mcp-adapter

然后将内容添加到 ~/.openclaw/openclaw.json：

{
  "plugins": {
    "entries": {
      "mcp-adapter": {
        "enabled": true,
        "config": {
          "servers": [
            {
              "name": "pubmed-search",
              "transport": "stdio",
              "command": "uvx",
              "args": ["pubmed-search-mcp"],
              "env": {
                "NCBI_EMAIL": "[email protected]"
              }
            }
          ]
        }
      }
    }
  }
}

配置完成后，重启网关：

openclaw gateway restart
openclaw plugins list  # Should show: mcp-adapter | loaded

Cline（cline_mcp_settings.json）

{
  "mcpServers": {
    "pubmed-search": {
      "command": "uvx",
      "args": ["pubmed-search-mcp"],
      "env": {
        "NCBI_EMAIL": "[email protected]",
        "SEMANTIC_SCHOLAR_API_KEY": "your_semantic_scholar_key",
        "PUBMED_SEARCH_DISABLED_SOURCES": ""
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

其他 MCP 客户端

任何兼容 MCP 的客户端都可以通过 stdio 传输使用此服务：

# Command
uvx pubmed-search-mcp

# With environment variable
[email protected] uvx pubmed-search-mcp

注意：根据 NCBI API 政策，必须设置 NCBI_EMAIL。可选设置 NCBI_API_KEY 以提高速率限制（10 req/s，而非 3 req/s）。 📖 详细集成指南：有关所有环境变量、Copilot Studio 设置、Docker 部署、代理配置和故障排除，请参阅 docs/guides/INTEGRATIONS.md。

---

🎯 设计理念

核心定位：AI Agent 与学术搜索引擎之间的智能中间件。

为什么选择此服务？

其他工具提供原始 API 访问能力，而我们提供词汇转换 + 智能路由 + 研究分析：

挑战	我们的解决方案
Agent 使用 ICD 编码，而 PubMed 需要 MeSH	✅ 自动 ICD→MeSH 转换
多个数据库，各有不同 API	✅ 统一搜索单一入口
临床问题需要结构化搜索	✅ PICO 移交 + 流水线（validate_pico_plan 验证 Agent 提供的 P/I/C/O，并返回可运行的 template: pico 流水线）
医学术语中有拼写错误	✅ ESpell 自动纠正
单一来源返回的结果过多	✅ 并行多源并去重
需要追踪研究演进	✅ 研究编年史与树状图，提供里程碑检测、诊断、子主题分支和版本化修订
引文上下文不明确	✅ 引文树，支持前向／后向／网络分析
无法访问全文	✅ 多源全文（Europe PMC XML、Unpaywall OA 位置、机构直接访问／EZproxy、CORE，以及下载器回退方案）
基因／药物信息散布于多个数据库	✅ NCBI 扩展（Gene、PubChem、ClinVar）
需要搜索前沿预印本	✅ 预印本搜索（arXiv、medRxiv、bioRxiv），支持筛选检测到的预印本；但不验证同行评审状态
导出到文献管理工具	✅ 一键导出（官方 RIS／MEDLINE／CSL JSON；本地 RIS／BibTeX／CSV／MEDLINE／JSON）

主要差异化优势

1. 词汇转换层——Agent 使用自然语言表达，我们将其转换为各数据库的术语（MeSH、ICD-10、文本挖掘实体）
2. 统一搜索网关——一次 unified_search() 调用，即可根据功能在 PubMed、Europe PMC、CORE、OpenAlex、Semantic Scholar 及已启用的预印本／商业来源之间进行分发
3. PICO 移交 + 流水线——Agent 提取 P/I/C/O，validate_pico_plan() 验证结构化移交内容，后端 template: pico 流水线执行面向 O 的精确率／召回率搜索
4. 研究编年史与谱系树——通过策略驱动的启发式方法检测里程碑，通过多信号评分识别里程碑论文，呈现诊断信息，持久化可供比较的版本化修订，并按子主题以分支树的形式呈现研究演进
5. 引文网络分析——构建多层级引文树，从单篇论文映射完整的研究领域
6. 完整研究生命周期——从搜索 → 发现 → 全文 → 分析 → 导出，全部集成于一个服务中
7. Agent 优先设计——输出针对机器决策进行优化，而非面向人类阅读

---

📡 外部 API 与数据源

此 MCP 服务集成了多个学术数据库和 API：

核心数据源

来源	覆盖范围	词汇体系	自动转换	说明
NCBI PubMed	3,600 多万篇文章	MeSH	✅ 原生支持	主要生物医学文献
NCBI Entrez	多数据库	MeSH	✅ 原生支持	基因、PubChem、ClinVar
Europe PMC	3,300 多万篇	文本挖掘	✅ 提取	全文 XML 访问
CORE	2 亿多篇	无	➡️ 自由文本	开放获取聚合器
Semantic Scholar	持续扩展的图谱 + 算子数据集	S2 字段 / 批量语法	✅ 经 Broker 编译的模式	相关性、受限批量查询、批处理、引文图谱，以及仅元数据的发布/差异平面；不支持分区下载
OpenAlex	持续扩展的开放研究图谱	主题 / 关键词	✅ 关键词 + 受限原生语义查询	游标、成本溯源、实体图谱，以及声明式算子快照路径；尚无本地索引
NIH iCite	PubMed	不适用	不适用	引文指标（RCR）

🔑 图例：✅ = 完整词汇支持 | ➡️ = 查询直通（无受控词汇）

ICD 代码：自动检测，并在 PubMed 搜索前转换为 MeSH

环境变量

# Required
[email protected]          # Required by NCBI policy

# Optional - For higher rate limits
NCBI_API_KEY=your_ncbi_api_key     # Get from: https://www.ncbi.nlm.nih.gov/account/settings/
CORE_API_KEY=your_core_api_key     # Get from: https://core.ac.uk/services/api
[email protected]      # Optional override; defaults to server/NCBI email
[email protected]     # Optional override; defaults to server/NCBI email
SEMANTIC_SCHOLAR_API_KEY=your_semantic_scholar_key # https://www.semanticscholar.org/product/api
OPENALEX_API_KEY=your_openalex_key # Raises the OpenAlex credit budget; actual grant is response-driven
PUBMED_SEARCH_DISABLED_SOURCES=    # Example: semantic_scholar

# Optional - Pipeline run-wide safety budgets
PUBMED_PIPELINE_RUN_TIMEOUT_SECONDS=120 # Shared end-to-end deadline (max 3600)
PUBMED_PIPELINE_MAX_EXTERNAL_CALLS=40   # Shared across sequential/parallel steps (max 1000)

# Optional - Network settings
HTTP_PROXY=http://proxy:8080       # HTTP proxy for API requests
HTTPS_PROXY=https://proxy:8080     # HTTPS proxy for API requests

# Optional - Institutional fulltext access
INSTITUTIONAL_DIRECT_FETCH=true    # Try DOI publisher pages before CORE fallback
EZPROXY_ENABLED=false              # Enable only after configuring EZPROXY_HOST + cookie
EZPROXY_HOST=ezproxy.example.edu
EZPROXY_COOKIE_FILE=/path/to/cookies.json

# Optional - Local note export
PUBMED_NOTES_DIR=/path/to/wiki/references  # save_literature_notes target folder
PUBMED_WORKSPACE_DIR=/path/to/project       # fallback: references/ under this workspace
PUBMED_DATA_DIR=~/.pubmed-search-mcp        # fallback: references/ under this data dir

除非配置了源专用电子邮件地址，否则 CrossRef 和 Unpaywall 会复用运行时服务联系邮箱（NCBI_EMAIL、CLI --email 或检测到的 git 邮箱）。OpenAlex 支持日常匿名使用，也可使用可选 API 密钥；Broker 会读取其响应中的额度/速率元数据，而不会假设存在永久的“礼貌使用池”配额。

本地笔记导出会按以下顺序确定目录：output_dir 参数、PUBMED_NOTES_DIR、PUBMED_WORKSPACE_DIR/references、PUBMED_DATA_DIR/references，然后是 ~/.pubmed-search-mcp/references。 此路径/模板选择仅适用于可信本地模式。经过身份验证的服务笔记始终使用内置格式，并存储在当前租户隔离的 references/ 目录下。 为兼容大模型知识库，wiki 和 foam 导出会使用基于 PMID、DOI、PMCID 或备用标识符的稳定链接目标；标题仍用作别名/显示标签，响应中还会包含 wiki_validation，用于检查未解析的维基链接。

🔄 工作原理：中间件架构

┌─────────────────────────────────────────────────────────────────────────────┐
│                              AI AGENT                                        │
│                                                                              │
│   "Find papers about I10 hypertension treatment in diabetic patients"       │
│                                                                              │
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                     🔄 PUBMED SEARCH MCP (MIDDLEWARE)                        │
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │  1️⃣ VOCABULARY TRANSLATION                                              ││
│  │     • ICD-10 "I10" → MeSH "Hypertension"                                ││
│  │     • "diabetic" → MeSH "Diabetes Mellitus"                             ││
│  │     • ESpell: "hypertention" → "hypertension"                           ││
│  └─────────────────────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │  2️⃣ INTELLIGENT ROUTING                                                 ││
│  │     ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐             ││
│  │     │ PubMed   │  │Europe PMC│  │   CORE   │  │ OpenAlex │             ││
│  │     │  36M+    │  │   33M+   │  │  200M+   │  │  250M+   │             ││
│  │     │  (MeSH)  │  │(fulltext)│  │  (OA)    │  │(metadata)│             ││
│  │     └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘             ││
│  │          └──────────────┴──────────────┴──────────────┘                 ││
│  │                              ▼                                          ││
│  │  3️⃣ RESULT AGGREGATION: Dedupe + Rank + Enrich                         ││
│  └─────────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         UNIFIED RESULTS                                      │
│   • 150 unique papers (deduplicated from 4 sources)                          │
│   • Ranked by relevance + citation impact (RCR)                              │
│   • Full text links enriched from Europe PMC                                 │
└─────────────────────────────────────────────────────────────────────────────┘

---

🛠️ MCP 工具概览

如果你想将工具集理解为一个可用的系统，不要从记忆 41 个工具名称开始。

请先阅读工具使用指南：它将当前的 41 个工具归纳为 8 个能力类别，解释理论下限，并为人类和 Agent 提供基于意图的路由方式。

🔍 搜索与查询智能

┌─────────────────────────────────────────────────────────────────┐
│                      SEARCH ENTRY POINT                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   unified_search()          ← 🌟 Single entry for all sources    │
│        │                                                         │
│        ├── Quick search     → Direct multi-source query          │
│        ├── Native semantic → Bounded OpenAlex semantic mode    │
│        ├── Systematic       → Bounded provider bulk/cursor mode  │
│        ├── PICO hints       → Detects comparison, shows P/I/C/O  │
│        └── ICD expansion    → Auto ICD→MeSH conversion           │
│                                                                  │
│   Sources: PubMed · Europe PMC · CORE · OpenAlex · S2            │
│   Auto: Deduplicate → Rank → Enrich full-text links              │
│                                                                  │
├─────────────────────────────────────────────────────────────────┤
│   QUERY INTELLIGENCE                                             │
│                                                                  │
│   generate_search_queries() → MeSH expansion + synonym discovery │
│   validate_pico_plan()              → Agent-provided PICO handoff        │
│   analyze_search_query()    → Query analysis without execution   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

一个搜索入口，三种检索策略

通用文献发现有意通过且仅通过一个 MCP 工具公开：unified_search。提供方专属 API 仍作为内部代理功能：

# Default relevance/keyword routing across enabled sources
unified_search(query="treatment resistance")

# OpenAlex native semantic search (provider maximum 50 results)
unified_search(
    query="mechanisms of treatment resistance",
    sources="openalex",
    options="native_semantic",
)

# Deterministic/bounded retrieval: OpenAlex cursor and S2 bulk where selected
unified_search(
    query="melanoma AND immunotherapy",
    sources="openalex,semantic_scholar",
    options="systematic",
)

native_semantic 和 systematic 互斥，且会停用多策略深度搜索扩展。如果明确选择的来源不支持所请求的检索模式，系统会在发起网络调用前报错；自动选择来源时则仅保留具备相应能力的提供方。每个来源的 limit 仍不超过 100，因此 systematic 表示确定性、有界的提供方执行，并不保证穷尽式系统综述。结构化输出和工件会记录 retrieval_mode 以及每个来源的 source_metadata（请求／提供方模式、规范化或编译后的查询、是否可继续获取、成本／速率元数据，以及可用时的警告）。

公共请求边界采用失败即关闭策略。limit 必须是 1 至 100 的整数；未知或格式错误的 filters／options、年份范围颠倒或超出范围，以及不受支持的排序或输出模式，都会在执行提供方 I/O 前返回验证错误。在默认的深度搜索策略中，limit 是每个来源的总预算，会分配给该来源的各项查询策略，而不是每项策略各返回 limit 条结果。策略调用采用有界的全局／每来源并发和超时设置；即使某个来源超时、受到速率限制或发生故障，其他成功的来源仍可使用。

本版本中的 PubMed、Europe PMC、Scopus 和 Web of Science 仍仅支持关键词检索；对这些来源明确请求系统检索时，会在执行 I/O 前报错，而不会把单页结果错误标记为系统综述覆盖。

有关提供方限制和运营方数据平面边界，请参阅来源契约、Semantic Scholar 和 OpenAlex。

🔬 发现工具（找到关键论文后）

                        Found important paper (PMID)
                                   │
           ┌───────────────────────┼───────────────────────┐
           │                       │                       │
           ▼                       ▼                       ▼
    ┌─────────────┐        ┌─────────────┐        ┌─────────────┐
    │  BACKWARD   │        │  SIMILAR    │        │  FORWARD    │
    │  ◀──────    │        │  ≈≈≈≈≈≈     │        │  ──────▶    │
    │             │        │             │        │             │
    │ get_article │        │find_related │        │find_citing  │
    │ _references │        │ _articles   │        │ _articles   │
    │             │        │             │        │             │
    │ Foundation  │        │  Similar    │        │ Follow-up   │
    │  papers     │        │   topic     │        │  research   │
    └─────────────┘        └─────────────┘        └─────────────┘

    fetch_article_details()   → Detailed article metadata
    get_citation_metrics()    → iCite RCR, citation percentile
    build_citation_tree()     → Full network visualization (6 formats)

📚 全文、图表提取与导出

对于搜索后需要细读的场景，unified_search(..., fulltext="prefetch") 会在后台预取最多 3 篇符合条件的 PMC XML 文章。之后调用 get_fulltext 时，会共享已就绪或正在获取的 XML。默认关闭；不会轮询，也不会推测性访问 PDF／浏览器。权衡与限制。

类别	工具
全文	get_fulltext → 有 PMCID 时使用 Europe PMC XML；必要时使用基于 DOI 的 Unpaywall、机构直连／EZproxy、CORE 和下载器作为备用来源
图表	get_article_figures → 从 PMC 开放获取文章中提取图表标签、说明文字、图像 URL 和 PDF 链接
支持图表的全文	get_fulltext(include_figures=True) → 在结构化全文中嵌入图表元数据
文本挖掘	get_text_mined_terms → 提取基因、疾病、化学物质
导出	prepare_export → 官方 RIS／MEDLINE／CSL JSON，或本地 RIS／BibTeX／CSV／MEDLINE／JSON；save_literature_notes → 本地 wiki／Foam 兼容／Markdown／MedPaper 风格笔记，以及集合级 CSL JSON

get_fulltext 会报告 coverage_status、确切的 sources_tried／sources_completed，以及经过净化的 source_errors。因此，一个来源返回可用文章或链接、另一个来源发生故障时，结果会标记为 partial，而不是误报为完全成功或空结果。扩展的 PDF 发现流程会在发现、下载、提取、工具输出和工件各阶段沿用相同的不可变类型化覆盖范围封装。

🖼️ OA 图优先探索

当 Agent 需要证据图而不只是文章正文时，请使用 PMC 开放获取路径：

• get_article_figures(source={"kind":"pmcid","value":"PMC12086443"}) → 图编号、图注、图片 URL 以及 PDF/文章链接
• get_fulltext(source={"kind":"pmcid","value":"PMC7096777"}, include_figures=True) → 内嵌图片的结构化全文
• 图像输出保留文章上下文，因此 Agent 可以将每张图与提及它的章节关联起来

🧬 NCBI 扩展数据库

工具	描述
search_gene	搜索 NCBI Gene 数据库
get_gene_details	根据 NCBI Gene ID 获取基因详情
get_gene_literature	与基因关联的 PubMed 文章
search_compound	搜索 PubChem 化合物
get_compound_details	根据 PubChem CID 获取化合物详情
get_compound_literature	与化合物关联的 PubMed 文章
search_clinvar	搜索 ClinVar 临床变异

🕰️ 研究编年史与谱系树

工具	描述
build_research_chronicle	构建持久化、带版本的编年史，并检测里程碑。输出：summary、chronicle_map、timeline、tree、graph、evidence、milestones、mermaid、narrative、json
read_research_chronicle	加载、列出、比较修订版本、撰写带引用的叙述、分析里程碑分布，或比较最多五个主题

# 1. Build from topic (retrieves PubMed, scores landmarks, clusters lineages)
build_research_chronicle(topic="remimazolam intraoperative", output="mermaid", max_events=30)

# 2. Continue an existing chronicle (inherits stored topic and filters to produce Revision N+1)
build_research_chronicle(chronicle_id="remimazolam-intraoperative-08c229f3")

# 3. Read revision diff, milestone analytics, or cross-topic comparison
read_research_chronicle(request={"action":"diff","chronicle_id":"remimazolam-intraoperative-08c229f3","from_revision":1})
read_research_chronicle(request={"action":"milestones","chronicle_id":"remimazolam-intraoperative-08c229f3"})
read_research_chronicle(request={"action":"compare","selection":{"kind":"topics","values":["remimazolam intraoperative","propofol intraoperative"]}})

mermaid 是规范的综合视图：一条水平年份主轴（X 轴），每条 观测到的研究脉络（Y 轴）都从其在检索范围内最早发表的论文处分支。此分组 便于解释，但并非因果谱系，也不表示对该领域真正首篇论文的判断。谱系优先采用 多篇论文共有的 MeSH 描述词和作者关键词；如果只有单篇论文的信号，或信号不足， 则会带警告地回退到研究阶段。相同年份的显示顺序稳定，但当出版日期精度无法证明 先后关系时，不表示优先顺序。请参阅 高级研究工作流（docs/guides/ADVANCED_RESEARCH_WORKFLOWS.md） 和 docs/design/RESEARCH_CHRONICLE_REFACTOR_SPEC.md。

编年史的 Mermaid 输出由结构化节点和边构建，并具有安全的 标签转义、环路／孤立节点修复、抗碰撞 ID 和有界图规模。它会从丰富语法回退到 安全语法，再回退到最简语法，而不会导致整个编年史生成失败。mermaid_validation.json 会记录每项修正、回退和省略的可视元素；chronicle.mmd 保持为纯 Mermaid 源码。

编年史修订版本不可变，并以原子方式追加。启用会话 制品持久化时，制品保存失败会明确报告，但已保存的编年史修订版本仍然可用。

主题构建会先将年份限制发送给 PubMed，再进行有界检索；随后保留最早和最晚的 观测论文，并用里程碑和时间跨度填满上限。审计会记录 PubMed 的 returned / available 数量， 并在可用数量未知或任何检索／筛选上限导致视图并非穷尽时发出警告。PubMed 出错或 范围内没有文章证据时，不会发布空修订版本。

检索来源信息会将 ranking_requested 与实际生效的 ranking 区分开来。只有实际应用了 经过验证的引文计数时，才会声称按 iCite 排序。带版本的引文指标覆盖情况会记录 complete、 partial、empty、error 和 not-requested 结果，并提供安全计数和错误信息； 审计会发出警告或报错，而不会将服务中断视为零条引文。

显式 PMID 输入采用严格格式（12345678 或 PMID:12345678，仅限正数 ASCII 数字，最多 20 位）；DOI 或混合文本会被拒绝，而不会被强制转换。没有可靠发表日期的 记录会显示在已标注日期的条目之后，标为 Undated，且不会纳入显示的年份跨度。条目 ID 会根据 PMID／DOI 证据 身份保持稳定，不受日期或分类器修正影响；主题连续性使用统一的 Unicode／大小写／空白规范化键。包含多个信号的论文会保留一个主分支， 并设置明确的交叉链接；重叠达到 20% 或以上时，审计会发出 警告。在修订版本差异中，缺失表示 not_observed_in_revision，绝不表示 已确定退役。

🏥 机构访问与 ICD 转换

工具	描述
configure_institutional_access	配置机构的链接解析器
get_institutional_link	生成 OpenURL 访问链接
list_resolver_presets	列出解析器预设
test_institutional_access	测试解析器配置
diagnose_institutional_access	诊断直接 DOI、EZproxy 和 OpenURL 移交路径
convert_icd_mesh	在 ICD 代码与 MeSH 术语之间进行双向转换
unified_search	自动检测查询中的 ICD 代码并扩展为 MeSH

解析器基址必须是无凭据、不带查询或片段的 HTTP(S) URL。PMID 诊断会针对 PubMed 到 DOI 的步骤报告 resolved、not_found 或 error，因此上游服务中断绝不会被描述为 DOI 缺失。

💾 会话管理

工具	描述
read_session	按操作严格区分的读取器，可读取 PMID、缓存文章、摘要、日志、持久化搜索运行、重放参数和持久化工件

还提供动态 MCP 资源，供可直接读取资源的 Agent 使用：

• session://context — 当前会话状态
• session://last-search — 最新搜索元数据
• session://last-search/pmids — 最新 PMID 列表及 CSV 格式
• session://last-search/results — 最新搜索的缓存文章负载

持久化工件

配置会话持久化后，可为可复用的 unified_search 和 get_fulltext 响应保存持久化 MCP 输出工件。工具响应类似索引卡：其中包含 足够的计数、来源警告和工件提示，便于 Agent 立即作答；完整的证据负载则保留在 可反复读取的文件中。精简的 artifact 定位信息包含 artifact_id、artifact_uri、primary_file、summary、文件清单、 read_order、审计状态，以及精确的 read_session(...) 检索提示。仅当 本地 MCP 客户端也应直接收到 local_path 和 manifest_path 时，才设置 PUBMED_ARTIFACT_INCLUDE_LOCAL_PATHS=true。

无法读取服务端文件系统的远程客户端可通过会话门面检索相同内容：

read_session(request={"action":"list_artifacts"})
read_session(request={"action":"artifact","locator":{"kind":"artifact_id","value":"..."}})
read_session(request={"action":"artifact","locator":{"kind":"artifact_uri","value":"artifact://..."}})
read_session(request={"action":"artifact","locator":{"kind":"artifact_uri","value":"artifact://..."},"artifact_file":"audit.json"})
read_session(request={"action":"artifact","locator":{"kind":"artifact_uri","value":"artifact://..."},"artifact_file":"query_strategy.json"})
read_session(request={"action":"artifact","locator":{"kind":"artifact_uri","value":"artifact://..."},"artifact_file":"results.json","offset":0,"max_chars":200000})
read_session(request={"action":"list_artifacts","include_local_paths":true})

可恢复的搜索运行

启用会话管理后，每次 unified_search 调用都会获得一个稳定的运行 ID。这包括常规搜索、验证／规划失败，以及内联、saved:<name> 或 dry_run=true 流水线执行。结构化结果和错误会附带 search_run 移交信息；Markdown 则会以精简的恢复说明返回相同的运行 ID。常规文献结果封装包含两个独立的机器可读契约：

• search_status 描述有界检索结果：state （completed、empty、partial 或 failed）、bounded=true、 exhaustive=false、返回数量、尝试成功／失败／可重试的来源，以及用于延续检索／完整性未知的来源列表。
• search_run 是恢复移交信息：稳定的 run_id、日志状态、 recoverable、精确的 read_session 检查／重放参数，以及已提交时的工件 URI。 租户范围的 search-run/v1 日志会在调用提供方或返回终止验证响应之前发布，并记录经过清理的请求、计划、按来源或流水线步骤划分的实际尝试、计数、安全失败信息、结果引用，以及适用时的工件定位信息。日志最终会进入 completed、partial、failed 或 cancelled 状态；有效的零结果搜索是一条 completed 运行，其 search_status.state 为 empty。重启时，未完成的 started / planned / running 条目会被恢复一次，标记为 interrupted，而不会消失。非试运行的已保存流水线还会保留其 PipelineStore 报告/运行历史；这是对调用级搜索日志的补充，而非替代。

流水线重放会保留原始内联参数或 saved:<name> 参数，以及 dry_run / stop_at。包含密钥、令牌、Cookie、密码或其他凭据内容的流水线文本会被拒绝，并记录为失败运行；提供方凭据应放在服务环境/配置中，绝不能写入流水线 YAML 或 JSON。

read_session(request={"action":"search_runs"})
read_session(request={"action":"search_runs","status":"partial"})
read_session(request={"action":"search_run","run_id":"..."})
read_session(request={"action":"replay_search","run_id":"..."})

replay_search 只会返回原始且不含凭据的 unified_search kwargs。它绝不会自动执行网络调用；Agent 或用户必须先审核并明确提交这些参数。提供方游标/令牌值会作为不透明来源信息保留在 source_metadata 和 query_strategy.json 中，但目前尚无公开的游标续传参数，因此重放会启动新的有限搜索。

如果无法恢复终止日志写入，响应会报告 search_run.status="history_unavailable"、history_available=false、预期的终止状态以及一条警告。由于无法保证持久化恢复，响应会有意省略检查/重放操作；搜索结果本身仍可能可用。

unified_search 工件使用研究信封。先查看 audit.json，了解来源数量和完整性警告；然后查看 query_strategy.json，了解实际执行计划；最后查看 results.json / results.toon，获取完整文章列表。这样可以减少 MCP 响应令牌，同时保留学术追溯能力。

工件由已计算出的结果对象生成，因此读取工件不会重新执行搜索或全文检索。 如果在工件目录以原子方式发布后、会话索引更新前发生崩溃，会话重新加载时只会发现完整且已建立校验和索引的清单，并通过 search_run_id 将孤立工件重新关联到其搜索运行（对于较旧的工件，则使用保守的查询匹配）。 read_session 默认会隐去本地文件系统路径；local_path 和 manifest_path 是服务端本地路径，并非可移植的客户端路径。get_fulltext 生成的工件可能包含文章正文，包括订阅或通过机构访问的内容。请根据出版方许可和机构访问条款存储和分享这些内容。 如果有工件可用，较大的 get_fulltext 响应会以内联预览形式返回；请使用工件定位信息获取保存的完整内容。

当某个来源失败但整体搜索仍可继续时，JSON 响应可能会包含 source_errors；Markdown 响应会显示一行 Source warnings。对于 Semantic Scholar HTTP 429 错误，请设置 SEMANTIC_SCHOLAR_API_KEY，稍后重试，或通过 sources="auto,-semantic_scholar" 或 PUBMED_SEARCH_DISABLED_SOURCES=semantic_scholar 暂时将其排除。

流水线管理

流水线管理使用 7 个用途单一、架构精确的工具。每个工具只接受与相应操作相关的字段，因此拼写错误或无关的参数会被拒绝，而不会被默默忽略。

工具	描述
save_pipeline	保存流水线配置以供日后复用（YAML/JSON，自动验证）
list_pipelines	列出已保存的流水线（按标签/范围筛选）
load_pipeline	按已保存的名称加载；受信任的本地调用方也可以加载文件
delete_pipeline	删除流水线及其执行历史
get_pipeline_history	查看执行历史及文章差异分析
schedule_pipeline	创建或更新定期运行的流水线计划
unschedule_pipeline	移除定期运行的流水线计划

经过身份验证的服务调用方使用其租户派生存储中的命名流水线；workspace 和 file: 访问仅限本地。服务 Compose 配置不会执行计划任务，除非另行设计单一领导者机制。流水线历史采用失败即关闭策略：如果某次已持久化运行的数据格式错误，系统会返回明确且安全的错误，而不会返回不完整列表或错误地显示“没有历史记录”。

分步教程：

• English：docs/guides/PIPELINE_MODE_TUTORIAL.en.md
• 繁體中文：docs/guides/PIPELINE_MODE_TUTORIAL.md

👁️ 视觉与图像搜索

工具	描述
prepare_figure_search	将上传的图像、图像 URL 或数据 URI 交给 Agent 视觉功能，以提取搜索词
search_biomedical_images	在 Open-i 中搜索生物医学图像（X 光片、显微图像、照片、示意图）

当用户提供图像且 Agent 必须先解读其含义时，请使用 prepare_figure_search。该工具会返回 MCP ImageContent，并提供指示，让大模型 Agent 提取英文生物医学术语，然后继续使用 search_biomedical_images 搜索相似的 Open-i 图像，或使用 unified_search 搜索相关论文。

Open-i 结果包含按来源分类的类型化覆盖状态。有效的 total=0 和空列表表示没有匹配项；格式错误的响应或来源不可用表示 failed；有效行和无效行混杂则表示 partial。失败的来源会从 sources_used 中排除，其总数仍为未知；Markdown 会显示经过净化的覆盖状态，而不是声称“没有图像”。

📄 预印本搜索

通过 unified_search 的 options 标志搜索 arXiv、medRxiv 和 bioRxiv 预印本服务：

来源、筛选条件和选项标记必须使用准确的规范拼写。逗号分隔的标记之间不要添加 空格，也不要重复标记；别名和大小写变体均会被拒绝。

• preprints：搜索预印本服务，并将预印本作为 article_type=PREPRINT 合并到主要聚合结果集中。
• include_detected_preprints：在已选学术来源中保留通过预印本启发式识别的记录，但不添加预印本服务爬取。

预印本来源元数据会报告提供方的查询／时间窗口、结果上限、 未知的语料库总数以及本地年份筛选计数。指定严格年份范围时， 年份未知的记录会被排除。medRxiv/bioRxiv 使用有界日期信息流并按所有词项进行字面筛选，因此布尔或分组查询语法会在网络 I/O 发生前失败，而不会被静默地重新解释。

推荐组合：

• 空 options：会筛除被识别为预印本的记录。此启发式不能证明剩余的每条记录都经过了同行评审。
• options="preprints"：搜索 arXiv、medRxiv 和 bioRxiv，然后将这些预印本与主要结果一起排序并去重。
• options="include_detected_preprints"：不爬取预印本服务；保留已选来源返回的、已识别的预印本。

预印本检测——通过以下方式将文章识别为预印本：

• 来源 API 提供的文章类型（OpenAlex、CrossRef、Semantic Scholar）
• 存在 arXiv ID，但没有 PubMed ID
• 已知的预印本服务来源或期刊名称
• DOI 前缀与预印本服务相匹配（例如，10.1101/ → bioRxiv/medRxiv，10.48550/ → arXiv）

如需研究的时间脉络，请使用 build_research_chronicle；这是唯一提供研究时间线的功能，并会提供经审计的时间线、 分支图、叙述和修订历史。

🧪 临床试验注册库补充查询

系统不会隐式查询 ClinicalTrials.gov。当需要有界的注册库补充查询时，可在搜索中添加 options="clinical_trials"。它与文献来源计划、文章排序和来源计数保持独立。Markdown 最多呈现三条记录；JSON/TOON 会以结构化数据形式返回相同的所需补充查询。版本化的 clinical-trials-adjunct/v1 覆盖信息会在响应和持久化产物中以一致的方式记录检索和格式状态、返回数量、完整性、警告及经过清理的失败信息。

unified_search(query="remimazolam ICU sedation", options="clinical_trials")

📊 优先显示计数

对于希望在阅读排序列表前获得路由指引的 Agent，unified_search 也可以优先提供现有的来源覆盖信息和决策提示：

选项标志	说明
counts_first	在响应中添加来源计数表、覆盖摘要和下一步工具建议

示例：

unified_search(query="remimazolam ICU sedation", options="counts_first")

当 Agent 需要决定是否扩展来源、检查首位 PMID、获取全文、提取图表或转向时间线探索时，此模式很有用。

⏱️ MCP 进度报告

当 MCP 客户端提供进度令牌时，unified_search、build_research_chronicle、get_fulltext 和 get_text_mined_terms 会针对各自的主要阶段发送进度更新。 这可以减少 Agent 在较长时间搜索中的“黑箱”等待时间。 进度回调尽力执行，并设有 100 ms 的硬截止时间。卡住的 回调会被取消；如果有问题的宿主抑制了取消操作，其任务会被隔离在 由服务端管理、最多容纳 32 个条目的池中，以确保核心工具保持响应，且不会产生无界的后台任务。

---

📋 Agent 用法示例

1️⃣ 快速搜索（最简单）

# Agent just asks naturally - middleware handles everything
unified_search(query="remimazolam ICU sedation", limit=20)

# Or with clinical codes - auto-converted to MeSH
unified_search(query="I10 treatment in E11.9 patients")
#                     ↑ ICD-10           ↑ ICD-10
#                     Hypertension       Type 2 Diabetes

2️⃣ PICO 临床问题

简单路径 — unified_search 可直接搜索（无需进行 PICO 分解）：

# unified_search searches as-is; detects "A vs B" pattern and shows PICO hints in metadata
unified_search(query="Is remimazolam better than propofol for ICU sedation?")
# → Multi-source keyword search + PICO hint metadata in output
# ⚠️ This does NOT auto-decompose PICO or expand MeSH!
# For structured PICO search, use the Agent workflow below

Agent 工作流 — Agent 提供 PICO + 后端管道搜索（推荐用于临床问题）：

┌─────────────────────────────────────────────────────────────────────────┐
│  "Is remimazolam better than propofol for ICU sedation?"                │
└─────────────────────────────────┬───────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         validate_pico_plan()                                     │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐                     │
│  │    P    │  │    I    │  │    C    │  │    O    │                     │
│  │  ICU    │  │remimaz- │  │propofol │  │sedation │                     │
│  │patients │  │  olam   │  │         │  │outcomes │                     │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘                     │
└───────┼────────────┼────────────┼────────────┼──────────────────────────┘
        │            │            │            │
        ▼            ▼            ▼            ▼
┌─────────────────────────────────────────────────────────────────────────┐
│              generate_search_queries() × 4 (parallel)                    │
│                                                                          │
│  P → "Intensive Care Units"[MeSH]                                        │
│  I → "remimazolam" [Supplementary Concept], "CNS 7056"                   │
│  C → "Propofol"[MeSH], "Diprivan"                                        │
│  O → "Conscious Sedation"[MeSH], "Deep Sedation"[MeSH]                   │
└─────────────────────────────────┬───────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│              Agent combines with Boolean logic                           │
│                                                                          │
│  (P) AND (I) AND (C) AND (O)  ← High precision                           │
│  (P) AND (I OR C) AND (O)     ← High recall                              │
└─────────────────────────────────┬───────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│              unified_search() (auto multi-source + dedup)                │
│                                                                          │
│  PubMed + Europe PMC + CORE + OpenAlex → Auto deduplicate & rank         │
└─────────────────────────────────────────────────────────────────────────┘

# Step 1: Agent extracts P/I/C/O, then validates the structured handoff
pico = validate_pico_plan(
    description="Is remimazolam better than propofol for ICU sedation?",
    p="ICU patients requiring sedation",
    i="remimazolam",
    c="propofol",
    o="sedation efficacy, delirium, hypotension"
)
# Returns validation plus a ready-to-run `template: pico` pipeline.

# Step 2: Get MeSH for each element (parallel!)
generate_search_queries(topic="ICU patients")   # P
generate_search_queries(topic="remimazolam")    # I
generate_search_queries(topic="propofol")       # C
generate_search_queries(topic="sedation")       # O

# Step 3: Either pass expanded fragments back as p_query/i_query/c_query/o_query
# or let the backend pipeline use the structured P/I/C/O labels.

# Step 4: Search (backend runs O-aware precision/recall searches, dedup, rank)
unified_search(
    query="Is remimazolam better than propofol for ICU sedation?",
    pipeline=pico["pipeline"]
)

3️⃣ 从关键论文开始探索

# Found landmark paper PMID: 33475315
find_related_articles(pmid="33475315")   # Similar methodology
find_citing_articles(pmid="33475315")    # Who built on this?
get_article_references(pmid="33475315")  # What's the foundation?

# Build complete research map
build_citation_tree(pmid="33475315", depth=2, output_format="mermaid")

4️⃣ 基因/药物研究

# Research a gene
search_gene(query="BRCA1", organism="human")
get_gene_literature(gene_id="672", limit=20)

# Research a drug compound
search_compound(query="propofol")
get_compound_literature(cid="4943", limit=20)

5️⃣ 导出结果

# Export last search results
prepare_export(pmids="last", format="ris")      # → EndNote/Zotero
prepare_export(pmids="last", format="bibtex", source="local")  # → LaTeX
prepare_export(pmids="last", format="csl")      # → CSL JSON from the official NCBI Citation API
save_literature_notes(pmids="last")              # → local wiki note + Foam-compatible wikilinks + CSL JSON
save_literature_notes(pmids="last", note_format="medpaper", output_dir="./references")
save_literature_notes(pmids="last", template_file="./reference-template.md")

# Retrieve full text for a selected paper from the last search
get_fulltext(source={"kind":"pmid","value":"12345678"}, extended_sources=True)

6️⃣ 预印本搜索

# Search preprint sources alongside the regular scholarly-source set
unified_search(query="COVID-19 vaccine efficacy", options="preprints")
# → Main aggregated results include labelled arXiv, medRxiv, and bioRxiv preprints

# Retain preprints detected in otherwise selected sources without adding a crawl
unified_search(query="CRISPR gene therapy", options="include_detected_preprints")

# Default heuristic policy
unified_search("diabetes treatment")
# → Detected preprints are filtered; remaining peer-review status is not proven

7️⃣ 管道（可复用的搜索计划）

# Save a template-based pipeline through the primary facade
save_pipeline(
    name="icu_sedation_weekly",
    config="template: pico\ntemplate_params:\n  P: ICU patients\n  I: remimazolam\n  C: propofol\n  O: delirium",
    tags=["anesthesia","sedation"],
    description="Weekly ICU sedation monitoring"
)

# Save a custom DAG pipeline
save_pipeline(
    name="brca1_comprehensive",
    config="""
steps:
  - id: expand
    action: expand
    params: { topic: BRCA1 breast cancer }
  - id: pubmed
    action: search
    params: { query: BRCA1, sources: [pubmed], limit: 50 }
  - id: expanded
    action: search
    inputs: [expand]
    params: { strategy: mesh, sources: [pubmed, openalex], limit: 50 }
  - id: merged
    action: merge
    inputs: [pubmed, expanded]
    params: { method: rrf }
  - id: enriched
    action: metrics
    inputs: [merged]
output:
  limit: 30
  ranking: quality
"""
)

# Execute a saved pipeline
unified_search(pipeline="saved:icu_sedation_weekly")

# List & manage
list_pipelines(tag="anesthesia")
load_pipeline(source="brca1_comprehensive")  # Review YAML
get_pipeline_history(name="icu_sedation_weekly")  # View past runs

---

🔍 搜索模式对比

┌─────────────────────────────────────────────────────────────────────────┐
│                        SEARCH MODE DECISION TREE                         │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   "What kind of search do I need?"                                       │
│         │                                                                │
│         ├── Know exactly what to search?                                 │
│         │   └── unified_search(query="topic keywords")                   │
│         │       → Quick, auto-routing to best sources                    │
│         │                                                                │
│         ├── Have a clinical question (A vs B)?                           │
│         │   └── Agent P/I/C/O → validate_pico_plan() handoff                  │
│         │       → unified_search(template:pico) or expanded Boolean    │
│         │                                                                │
│         ├── Need comprehensive systematic coverage?                      │
│         │   └── generate_search_queries() → parallel search              │
│         │       → MeSH expansion, multiple strategies, merge             │
│         │                                                                │
│         └── Exploring from a key paper?                                  │
│             └── find_related/citing/references → build_citation_tree     │
│                 → Forward/backward citation network                      │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

模式	入口	适用场景	自动功能
快速	unified_search()	快速主题搜索	ICD→MeSH、多源、去重
PICO	Agent P/I/C/O -> validate_pico_plan()	临床问题	验证交接 -> template:pico 后端搜索
系统综述	generate_search_queries() → unified_search(options="systematic")	可复现的综述初始搜索	MeSH/同义词及有界批量/游标执行；不代表穷尽所有结果
原生语义	unified_search(options="native_semantic")	标题/摘要空间中的概念相似性	能力验证；OpenAlex 语义模式，最多 50 条
探索	find_*_articles()	从关键论文开始	引文网络、相关文章

---

🤖 Claude 技能（AI Agent 工作流）

.claude/skills/ 中预先构建的工作流指南，分为使用技能（用于使用 MCP 服务）和开发技能（用于维护项目）：

📚 使用技能（11 项）— 供使用此 MCP 服务的 AI Agent 使用

技能	描述
pubmed-quick-search	基本搜索与筛选条件
pubmed-systematic-search	MeSH 扩展，全面搜索
pubmed-pico-search	临床问题分解
pubmed-paper-exploration	引文树、相关文章
pubmed-research-chronicle	持久化、版本化的研究演进记录
pubmed-gene-drug-research	基因/PubChem/ClinVar
pubmed-fulltext-access	Europe PMC、CORE 全文
pubmed-export-citations	RIS/BibTeX/CSV/CSL 导出指南
pubmed-multi-source-search	跨数据库统一搜索
pubmed-mcp-tools-reference	完整的工具参考指南
pipeline-persistence	保存、加载和复用搜索计划

🔧 开发技能（15 项）——面向项目贡献者

技能	描述
changelog-updater	自动更新 CHANGELOG.md
code-refactor	DDD 架构重构
code-reviewer	代码质量与安全审查
ddd-architect	为新功能搭建 DDD 脚手架
git-doc-updater	提交前同步文档
git-precommit	协调提交前工作流
memory-checkpoint	将上下文保存到 Memory Bank
memory-updater	更新 Memory Bank 文件
pdf-asset-extractor	提取并整理可用于引用的 PDF 资源
project-init	初始化新项目
readme-i18n	同步多语言 README
readme-updater	根据代码变更同步 README
roadmap-updater	更新 ROADMAP.md 状态
test-generator	生成测试套件
tool-sync	保持 MCP 注册表与生成的工具文档一致

📁 位置：.claude/skills/*/SKILL.md（Claude Code 专用，也是仓库技能的唯一事实来源） 不要将仓库技能镜像或拆分到 .github/skills/ 中。 这些仓库技能属于项目，应继续纳入版本控制。个人跨项目技能应放在 ~/.copilot/skills/ 或 ~/.claude/skills/ 等用户目录中，而非此仓库。

研究技能安装会保留现有自定义内容。请参阅安装和升级策略。贡献者在推送前运行完整本地门禁；常规 CI 则运行规模较小、独立的冒烟门禁。

已完成的十阶段核心审查涵盖 src/pubmed_search/ 中的全部 223 个 Python 文件：456 个类，以及 2,445 个函数、方法和嵌套函数。2,901 个定义均已记录审查决定、依据和当前文件的 SHA-256；没有待审或过期项。这是作者编写的自审，与测试结果相互独立。使用 uv run python scripts/perf/symbol_inventory.py --require-reviewed src/ 对当前代码树重新检查；后续源代码变更会使受影响的审查失效。测试和脚本也已列入清单，但不在此处“完整核心审查”声明的范围内。

真实 MCP 回归门禁

41 个公开工具中的每一个，都会通过 MCP 协议分别经由源码树 stdio、Streamable HTTP，以及从全新安装的 wheel 启动的 stdio 调用。 wheel 路径仅从空白虚拟环境导入服务端代码；外部 fixture 仅提供确定性的 provider 接缝。 确定性子服务端会替换外部 provider 边界；注册表、架构、应用服务、持久化、产物、Chronicle 修订版本、管道和调度均使用真实实现。 选择启用的扩展 CI 还会使用固定版本 Mermaid 11.16.1，渲染通过 MCP 返回的精确 Chronicle 和引用 Mermaid 源码，因此展示层语法损坏会导致 门禁失败。 额外的真实 stdio 拒绝测试会确认：已停用的工具名称、 旧版扁平请求格式、含义不明确的标量值以及格式错误的容器仍会被拒绝。

uv run pytest -q tests/test_all_tools_mcp_acceptance.py

请参阅开发者指南， 了解测试架构、CI 门禁和实时 provider 边界。

---

🏗️ 架构（DDD）

本项目采用**领域驱动设计（DDD）**架构，以文献研究领域知识作为核心模型。

src/pubmed_search/
├── domain/                     # Core business logic
│   └── entities/article.py     # UnifiedArticle, Author, etc.
├── application/                # Use cases
│   ├── search/                 # QueryAnalyzer, ResultAggregator
│   ├── export/                 # Citation export (RIS, BibTeX...)
│   └── session/                # SessionManager
├── infrastructure/             # External systems
│   ├── ncbi/                   # Entrez, iCite, Citation Exporter
│   ├── sources/                # Europe PMC, CORE, CrossRef...
│   └── http/                   # HTTP clients
├── presentation/               # User interfaces
│   ├── mcp_server/             # MCP tools, prompts, resources
│   │   ├── tools/              # discovery, strategy, pico, export...
│   │   └── http_cli.py         # Canonical Streamable HTTP/SSE launcher
│   └── browser_fetch_broker.py # Optional isolated browser-fetch service
└── shared/                     # Cross-cutting concerns
    ├── exceptions.py           # Unified error handling
    └── async_utils.py          # Rate limiter, retry, circuit breaker

内部机制（对 Agent 透明）

机制	说明
Session	自动创建、自动切换
Cache	自动缓存搜索结果，避免重复调用 API
Rate Limit	自动遵守 NCBI API 限制（0.34s/0.1s）
MeSH Lookup	generate_search_queries() 自动查询 NCBI MeSH 数据库
ESpell	自动拼写纠正（remifentanyl → remifentanil）
Query Analysis	显示 PubMed 实际如何解析每条建议的查询

词汇转换层（核心功能）

我们的核心价值：我们是 Agent 与搜索引擎之间的智能中间件，自动处理词汇标准化，让 Agent 无需了解各数据库的术语。

不同数据源使用不同的受控词汇系统。本服务提供自动转换：

API / 数据库	词汇系统	自动转换
PubMed / NCBI	MeSH（医学主题词）	✅ 通过 expand_with_mesh() 提供完整支持
ICD Codes	ICD-10-CM / ICD-9-CM	✅ 自动检测并转换为 MeSH
Europe PMC	文本挖掘实体（基因、疾病、化学物质）	✅ get_text_mined_terms() 提取
OpenAlex	主题 / 关键词（模型推断）	✅ Broker 关键词模式；选定时使用受限的原生语义模式
Semantic Scholar	S2 字段 / 批量查询语法	✅ Broker 选择相关性模式或受限的批量模式；提供方标注保留来源信息
CORE	无	❌ 仅支持自由文本
CrossRef	无	❌ 仅支持自由文本

ICD → MeSH 自动转换

使用 ICD 代码搜索时（例如，用 I10 表示高血压），unified_search() 会自动：

1. 通过 detect_and_expand_icd_codes() 检测 ICD-10/ICD-9 模式
2. 从内部映射（ICD10_TO_MESH、ICD9_TO_MESH）查找对应的 MeSH 术语
3. 使用 MeSH 同义词扩展查询，实现全面搜索

# Agent calls unified_search with clinical terminology
unified_search(query="I10 treatment outcomes")

# Server auto-expands to PubMed-compatible query
"(I10 OR Hypertension[MeSH]) treatment outcomes"

📖 完整架构文档：ARCHITECTURE.md

MeSH 自动扩展 + 查询分析

调用 generate_search_queries("remimazolam sedation") 时，内部会执行：

1. ESpell 纠正 - 修正拼写错误
2. MeSH 查询 - 使用 Entrez.esearch(db="mesh") 获取标准词汇
3. 同义词提取 - 从 MeSH Entry Terms 获取同义词
4. 查询分析 - 分析 PubMed 如何解析每条查询

{
  "mesh_terms": [
    {
      "input": "remimazolam",
      "preferred": "remimazolam [Supplementary Concept]",
      "synonyms": ["CNS 7056", "ONO 2745"]
    }
  ],
  "all_synonyms": ["CNS 7056", "ONO 2745", ...],
  "suggested_queries": [
    {
      "id": "q1_title",
      "query": "(remimazolam sedation)[Title]",
      "purpose": "Exact title match - highest precision",
      "estimated_count": 8,
      "pubmed_translation": "\"remimazolam sedation\"[Title]"
    },
    {
      "id": "q3_and",
      "query": "(remimazolam AND sedation)",
      "purpose": "All keywords required",
      "estimated_count": 561,
      "pubmed_translation": "(\"remimazolam\"[Supplementary Concept] OR \"remimazolam\"[All Fields]) AND (\"sedate\"[All Fields] OR ...)"
    }
  ]
}

查询分析的价值：Agent 认为 remimazolam AND sedation 只会搜索这两个词，但 PubMed 实际会将其扩展为补充概念 + 同义词，结果从 8 条增至 561 条。这有助于 Agent 理解意图与实际搜索之间的差异。

---

🔒 本地 HTTPS 演示与服务部署

捆绑的自签名证书和 curl -k 流程是本地 TLS 演示， 并非生产环境的安全配置文件。对于共享服务，请使用经过身份验证的 服务 Compose 文件和可信证书，具体说明见 DEPLOYMENT.md。

本地 HTTPS 冒烟测试

# Step 1: Generate SSL certificates
./scripts/generate-ssl-certs.sh

# Step 2: Start HTTPS service (Docker)
./scripts/start-https-docker.sh up

# Verify deployment
curl -k https://localhost/

HTTPS 端点

服务	URL	说明
MCP	https://localhost/mcp	Streamable HTTP MCP 端点
健康状态	https://localhost/health	健康检查
就绪状态	https://localhost/ready	就绪检查
信息	https://localhost/info	运行时传输和端点元数据
导出	https://localhost/exports	本地已准备好的导出列表；服务模式要求提供 bearer 身份验证和租户范围

远程 MCP 客户端配置

{
  "mcpServers": {
    "pubmed-search": {
      "url": "https://localhost/mcp"
    }
  }
}

---

🏢 Microsoft Copilot Studio 集成

将 PubMed Search MCP 与 Microsoft 365 Copilot（Word、Teams、Outlook）集成！

快速入门

# Unpublished local schema/protocol smoke only; never tunnel local mode
pubmed-search-mcp-http --mode local --transport streamable-http \
  --copilot-compatible --host 127.0.0.1 --port 8765

# Public Copilot endpoint: authenticated service mode is mandatory
export PUBMED_AUTH_TOKENS="copilot:$(openssl rand -hex 32)"
export NGROK_DOMAIN="your-assigned-domain.ngrok.dev"
./scripts/start-copilot-studio.sh --with-ngrok

Copilot Studio 配置

字段	值
服务名称	PubMed Search
服务 URL	https://your-server.com/mcp
身份验证	服务模式使用 Bearer 令牌；仅未发布的本地演示可使用 None

📖 完整文档：copilot-studio/README.md

使用 pubmed-search-mcp-http --copilot-compatible 以采用打包后的 Copilot HTTP 语义。run_server.py 仍是源代码树中的开发包装器；run_copilot.py 是仅限环回地址的冒烟测试启动器，使用同一规范的 41 工具严格注册表，而不是第二套兼容接口。隧道脚本要求已分配 NGROK_DOMAIN，会拒绝使用中的后端端口，并且只有在 --mode service 通过就绪检查和未授权请求拒绝检查后才会发布。

⚠️ 注意：SSE 传输自 2025 年 8 月起已弃用。请使用 streamable-http。

---

📖 更多文档：

• 架构 → ARCHITECTURE.md
• 流水线教程（英语）→ docs/guides/PIPELINE_MODE_TUTORIAL.en.md
• 流水线教程（繁体中文）→ docs/guides/PIPELINE_MODE_TUTORIAL.md
• 部署指南 → DEPLOYMENT.md
• Copilot Studio → copilot-studio/README.md

---

🔐 安全

安全功能

层级	功能	描述
HTTPS	TLS 终止	远程凭据必须使用；捆绑的自签名配置仅限本地使用
Bearer 身份验证	稳定主体标识	服务模式下为必需，并用于租户授权
租户存储	文件系统隔离	会话、制品、导出内容、编年记录和流水线均存储在已验证身份的主体目录下
公平性与速率策略	租户并发数 + 共享上游预算	防止单个调用方扩大上游 API 配额
安全标头	点击劫持/MIME 加固	反向代理标头可补充身份验证，但不承担 CSRF 授权功能
密钥处理	运行时密钥注入	API 密钥和 Bearer 令牌必须来自部署密钥/环境变量，且不得提交或记录到日志中

详细部署说明请参阅 DEPLOYMENT.md。

---

📤 导出格式

以兼容主流参考文献管理器的格式导出搜索结果：

格式	来源	兼容工具	用例
RIS	官方或本地	EndNote、Zotero、Mendeley	通用导入
MEDLINE	官方或本地	PubMed 工具	PubMed 原生风格的归档
CSL JSON	官方	引文处理器	以编程方式设置引文样式
BibTeX	本地	LaTeX、Overleaf、JabRef	学术写作
CSV	本地	Excel、Google Sheets	数据分析
JSON	本地	程序化访问	自定义处理

导出字段

• 核心：PMID、标题、作者、期刊、年份、卷、期、页码
• 标识符：DOI、PMC ID、ISSN
• 内容：摘要（已清理 HTML 标记）
• 元数据：语言、出版类型、关键词
• 访问：DOI URL、PMC URL、全文可用性

特殊字符处理

• BibTeX 导出使用 pylatexenc 进行正确的 LaTeX 编码
• 北欧字符（ø、æ、å）、变音符号（ü、ö、ä）和重音符号均可正确转换
• 示例：Søren Hansen → S{\o}ren Hansen

---

📚 引用

出版工作区包含重写后的手稿、经审阅的参考文献、证据图谱，以及本地 PDF/arXiv 源码构建版本。这是一份工作草稿，尚无 arXiv 标识符；请引用下方发布的软件。作者：高子平（高雄医学大学附设中和纪念医院）。

GitHub 会根据 CITATION.cff 显示引用此仓库。如果你在研究、方法部分或内部技术报告中使用 PubMed Search MCP，请优先使用 GitHub 生成的引用，或直接复用仓库元数据。

@software{pubmed_search_mcp,
  title = {PubMed Search MCP},
  author = {Gau, Tz-Ping},
  version = {0.8.0},
  year = {2026},
  url = {https://github.com/u9401066/pubmed-search-mcp}
}

---

📄 许可证

Apache License 2.0 - 参见 LICENSE

---

🔗 链接

• GitHub 仓库
• PyPI 软件包
• NCBI Entrez 编程工具