如何为BioMCP添加新的生物医学数据源?完整开发指南

原创2026-11-05 19:36:401,995 阅读

如何为BioMCP添加新的生物医学数据源?完整开发指南

📌 本文带你完整走一遍 BioMCP 数据源集成 流程:BioMCP 是一个统一的生物医学数据查询工具(CLI + MCP Server),它把 UniProt、KEGG、gnomAD、ClinicalTrials.gov 等 20 多个上游 API 整合在一条命令之下。为它添加新的生物医学数据源,只需要一个模块、一份契约和一轮测试。

BioMCP 数据源架构:单二进制并行调用 20+ 上游 API

BioMCP 的核心卖点之一就是「Knows Every API」——内置缓存、限流、重试,让 Agent 不用逐个学习每个 API 的怪癖(见上图右下角卡片)。新增一个数据源,意味着这个能力再覆盖一个领域。

一、先看懂 BioMCP 的 Source 分层

动手之前,先理解一条查询在 BioMCP 内部经过的四层,这样你就知道数据源要"插"在哪里:

CLI 命令 → 实体层 (src/entities/) → 数据源客户端 (src/sources/) → 上游 API
                ↑ 渲染层 (src/render/) 把结果变成 Markdown / JSON
层 目录 职责
数据源客户端 src/sources/ 每个上游一个模块,负责 HTTP、重试、缓存、错误
实体 src/entities/ 把多个来源的数据组装成 gene / drug / variant 等实体卡片
渲染 src/render/ 输出 Markdown/JSON,并保留数据来源标注
CLI src/cli/ 命令语法、帮助文本、health 目录

完整契约定义在 architecture/technical/source-integration.md,这是官方给实现者和评审者的"持久契约",建议通读一遍。

二、选对集成模式:JSON / GraphQL / 非 JSON

BioMCP 已经覆盖了几种典型的上游形态,先判断你的数据源属于哪一类,可以少走很多弯路:

集成模式 仓库中的例子 说明
REST JSON UniProt、ChEMBL、OpenFDA 最主流,直接复用共享客户端
GraphQL gnomAD、OpenTargets、CIViC 单端点多查询路径,通常扩展已有模块
自定义 REST MyGene.info、PubMed 非标准 JSON,自定义反序列化
纯文本 / XML KEGG(TSV 风格)、HPA(XML) 传输格式不同,但安全边界约定一致

参考 docs/technical/overview 中的 "Source Integration Patterns" 一节。非 JSON 源也有明确的写法约定:小体量行式文本可以内联解析;重量级解析要放到 tokio::task::spawn_blocking,避免阻塞异步运行时。

三、第一步:创建你的源模块

这是整个开发流程中最关键的一步,规则非常清晰:

  1. 一个上游一个模块:在 src/sources/ 下新建 <source>.rs。例如 KEGG 客户端在 src/sources/kegg.rs#L12-L23,结构一目了然:

    pub struct KeggClient {
        client: reqwest_middleware::ClientWithMiddleware, // 共享中间件客户端
        base: Cow<'static, str>,                          // 可用环境变量覆盖的基础 URL
    }
    
  2. 复用共享工具:src/sources/mod.rs 提供了 shared_client()、env_base()、read_limited_body()、body_excerpt()、retry_send() 等辅助函数——统一处理 30 秒请求超时、指数退避重试、8 MiB 响应体上限和磁盘缓存。不要为同一个 provider 发明第二个限流器或客户端。

  3. 注册模块:新模块必须在 src/sources/mod.rs 中声明,否则不会被编译进项目。

  4. 新源 vs 扩展:如果仓库里已有该上游的客户端(比如 src/sources/opentargets.rs 已拥有多条 OpenTargets 查询路径),就在原模块上扩展,而不是建"兄弟客户端"。

四、把数据接到实体上:Section 优先原则

⚠️ 这是很多新手容易走偏的地方:BioMCP 不喜欢为每个数据源新建顶层命令,而是偏好"实体 + 分区"(section-first)模式。

新数据源应该扩展 src/entities/ 里已有的实体,把网络数据挂在具名 section 后面,而不是塞进默认卡片。

举个真实例子:architecture/technical/source-integration.md 中的状态注册表定义了 gene pathways 同时由 Reactome 和 KEGG 提供、variant population 由 gnomAD 提供。用户执行 biomcp get gene <id> pathways 时,按解析出的来源能力返回数据。

这样做的好处是:

  • 默认输出保持简洁可靠,重数据按需展开;
  • all 的含义是"当前来源支持的全部 section",而不是所有来源的并集;
  • 来源身份(provenance)在 Markdown 和 JSON 中始终可见,用户知道每条数据从哪里来。

如果确实需要新的命令行修饰符,也要遵守 get <entity> <id> <a href="https://link.gitcode.com/i/e5d510f0aa1ff99d0e36be69353d95f6" target="_blank">section...] 语法,并同步更新 [src/cli/commands.rs 和 src/cli/list/。

五、处理三种"缺失":unsupported / empty / unavailable

接入数据源时,必须明确区分三种用户可见状态(官方称之为"三种不可协商的语义"):

状态 含义 正确做法
unsupported 该来源不提供此 section 快速失败,给出带来源信息的错误和恢复提示
empty 调用成功但无数据 如实返回空形状
unavailable 上游失败或超时 优雅降级为 unavailable,绝不伪装成"不支持"

同时遵守全局运行时边界:

  • 可选增强绝不允许拖垮整个命令,跟随所属实体已有的超时风格(gene/disease/variant 约 8 秒,PGx 约 10 秒);
  • 多源搜索(如 pathway 的 Reactome + KEGG 并行)要按"标题匹配分层 → 上游位置 → 稳定 ID"排序,且不允许固定来源优先级;
  • 联邦查询的总计数是近似的,total=None 是正确设计而非偷懒。

集成 cBioPortal 数据源后:研究队列下载、生存分析与共现图表

如上图所示,BioMCP 把 Agent 技能也按域组织——你新增的数据源最终会以 SKILL.md 工作流、JSON schema 和命令示例的形式暴露给 AI Agent,所以文档与代码同步很重要。

六、认证、缓存与版本登记

如果你的数据源需要 API key(类似 DISGENET_API_KEY、ONCOKB_TOKEN),要满足这些硬性要求:

  • 必需凭据缺失时,明确报 BioMcpError::ApiKeyRequired,并在错误信息中指向文档页(但绝不回显密钥值);
  • 可选凭据只应提升配额,不破坏无 key 基线;
  • 认证请求必须走 no-store 缓存路径,私有响应不能和公共响应混在同一个缓存里;
  • 密钥只放环境变量,同步登记到 docs/getting-started/api-keys.md。

另外别忘了在 docs/reference/source-versioning.md 的矩阵中登记你的端点:是 v2 这种版本化路径、无版本稳定路径,还是"文件就地刷新"型导出——每个来源都要写明理由和评审日期。

七、非运行时源:本地文件也是一种数据源

如果上游只提供批量文件(CSV/JSON 导出)而不是 API,BioMCP 有一套成熟的"本地运行时源"模式(DDInter、EMA、WHO、GTR 都这样做):

  • 通过 BIOMCP_*_DIR 环境变量或平台数据目录解析路径,首次使用时自动下载;
  • 定义过期窗口(如 72 小时 / 7 天 / 30 天)并提供 biomcp <source> sync 强制刷新命令;
  • biomcp health 中显示 configured、available (stale)、not configured 等状态行。

这类源不进入 --apis-only 健康检查,因为它们不是上游 API,但同样要写入 docs/reference/sources.json 机器可读清单。

八、测试与交付清单:不齐全就不算完成

官方在 architecture/technical/source-integration.md#L639-L677 给出了 Source Addition Checklist,精简后如下:

交付面 何时必需 契约
针对性 Rust 测试 所有源新增 靠近 src/sources/、src/entities/、src/render/ 编写
spec/ BDD 更新 任何用户可见的 CLI 契约变化 覆盖新 section、新 flag、输出结构变化
scripts/contract-smoke.sh 端点稳定、探测形状确定 添加或更新存活探针
src/cli/health/catalog.rs 运维需要直接检查就绪度的源 参与 health 可见性,key 门槛源可显示为 excluded
CHANGELOG.md 用户可见的源新增 记录交付面变化

以及文档三件套:docs/reference/data-sources.md(来源矩阵:Base URL、是否要认证、注意事项)、docs/reference/source-versioning.md(版本矩阵)、docs/getting-started/api-keys.md(若涉及密钥)。

BioMCP 数据源支撑的研究分析:TP53 生存曲线、共现矩阵与柱状图

当你把新数据源接入完毕,用户就能像上图那样,一条命令拿到从原始数据到图表的完整链路——这就是集成工作的最终回报。

九、常见问题 FAQ

Q1:我的上游没有 JSON API,能集成吗? 能。仓库约定明确:非 JSON 传输(纯文本、XML)完全可行,只要遵守有限响应体、可读错误、共享客户端优先这几条约定。KEGG 和 HPA 就是活例子。

Q2:能不能给数据源单独写一个 HTTP 客户端? 可以,但不建议轻易这么做。共享客户端统一了超时、重试、缓存和 8 MiB 响应体上限;只有当你的超时/重试/流式/请求构造需求与中间件栈确实冲突时(如 cBioPortal 大文件下载用专用客户端),才走独立路径。

Q3:新数据源会出现在 biomcp health 里吗? 如果它对基线可用性有实质影响,就应该加入 src/cli/health/catalog.rs。key 门槛的来源在未配置时显示为 excluded。

Q4:数据源失败了会报错吗? 取决于它在默认路径还是可选 section。默认路径的必需源失败会抛出带恢复建议的 BioMcpError;可选增强则降级为 unavailable,并在 Markdown、JSON 的 _meta.source_status 中如实记录,绝不静默丢弃。

结语

为 BioMCP 添加生物医学数据源,本质上是回答四个问题:放哪里(src/sources/ 一个模块)、接哪里(实体 section)、怎么降级(三种缺失状态)、怎么证明(测试 + spec + health + 文档清单)。遵循 architecture/technical/source-integration.md 的契约,你的新数据源就能以和现有 20+ 来源完全一致的体验,融入这条统一的命令语法之中 🎯

登录后查看全文
biomcp