如何为BioMCP添加新的生物医学数据源?完整开发指南
如何为BioMCP添加新的生物医学数据源?完整开发指南
📌 本文带你完整走一遍 BioMCP 数据源集成 流程:BioMCP 是一个统一的生物医学数据查询工具(CLI + MCP Server),它把 UniProt、KEGG、gnomAD、ClinicalTrials.gov 等 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,避免阻塞异步运行时。
三、第一步:创建你的源模块
这是整个开发流程中最关键的一步,规则非常清晰:
-
一个上游一个模块:在 src/sources/ 下新建
<source>.rs。例如 KEGG 客户端在 src/sources/kegg.rs#L12-L23,结构一目了然:pub struct KeggClient { client: reqwest_middleware::ClientWithMiddleware, // 共享中间件客户端 base: Cow<'static, str>, // 可用环境变量覆盖的基础 URL } -
复用共享工具:src/sources/mod.rs 提供了
shared_client()、env_base()、read_limited_body()、body_excerpt()、retry_send()等辅助函数——统一处理 30 秒请求超时、指数退避重试、8 MiB 响应体上限和磁盘缓存。不要为同一个 provider 发明第二个限流器或客户端。 -
注册模块:新模块必须在 src/sources/mod.rs 中声明,否则不会被编译进项目。
-
新源 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是正确设计而非偷懒。
如上图所示,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(若涉及密钥)。
当你把新数据源接入完毕,用户就能像上图那样,一条命令拿到从原始数据到图表的完整链路——这就是集成工作的最终回报。
九、常见问题 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+ 来源完全一致的体验,融入这条统一的命令语法之中 🎯


