Folklore Clinical Variant Interpretation MCP

Folklore 临床变异解读 MCP

用于基因组变异解读、基因与疾病证据及文献的生物信息学 MCP。

在人体基因组分析的证据和解读阶段使用 Folklore：调查公开基因或疾病，解读已识别的 GRCh38 胚系变异（来自 WGS/WES），并检索相关生物医学文献。它不会处理原始 DNA 序列、FASTQ/BAM 文件或 VCF 上传文件，不会进行变异检测，也不会分析患者基因组。

从基因符号（如 BRCA1）、HGNC 标识符、疾病名称或准确的 MONDO 标识符开始。基因-疾病指南介绍了两个新的只读工具，以及 ClinGen 基因-疾病有效性覆盖范围的边界。

“NM_007294.4:c.68_69del 是什么意思？”和“审查这个 VUS”都是直接入口。使用一个公开变异调用 search_variant_evidence：

{"name":"search_variant_evidence","arguments":{"assembly":"GRCh38","query":"NM_007294.4:c.68_69del"}}

在调用工具前，请在 MCP 客户端中连接以下端点。 它会返回已解析的身份、自动分类、判定标准、可用证据、来源版本和明确的不确定性。请参阅八种已观察到的任务工作流 和示例详解。

已经有 ClinVar 或 Ensembl 记录？请传入其准确且受支持的 HGVS、 rsID 或经验证的 GRCh38 等位基因；保留转录本版本。请将 ClinVar 提交的 断言与 Folklore 的自动分类分开阅读。如需查找出版物，请先解析身份，并在需要时使用与变异相关的文献关联。文献关联不能证明致病性。

Folklore 临床变异解读 MCP 是由 Helena Bioinformatics 为 Folklore 提供的官方公开只读 模型上下文协议适配器。它不接受患者、表型、家族、共分离或 私人病例信息。结果须由具备资质的专业人员审查，且不构成 患者诊断或治疗建议。

连接到托管服务

无需账号或 API 密钥：

https://api.helena.bio/folklore/v1/mcp

托管服务使用无状态 Streamable HTTP 和 MCP 协议 2026-07-28。 客户端可以调用 server/discover、tools/list、tools/call、resources/list 和 resources/read。托管 SDK 也接受使用协议 2025-03-26 的旧版 initialize；请参阅 docs/COMPATIBILITY.md 中经过验证的兼容性矩阵。客户端 也可以调用 prompts/list 和 prompts/get，以使用以任务为先的变体工作流。

Biomni 用户可以通过经过测试且固定摘要的 Biomni 集成方案导入 Folklore Clinical Variant Interpretation MCP。该方案将 Biomni 仅支持 stdio 的外部服务配置适配为托管的 Streamable HTTP 端点。Folklore Clinical Variant Interpretation MCP 无需 Folklore 账号或 API 密钥。

Biorouter 用户可以构建并安装 Biorouter BRXT 扩展。该扩展是一个连接到托管 Streamable HTTP 端点的本地 stdio 桥接器。它保留已发布的工具架构和结构化结果，不会重新实现变体 解析、证据汇总或 ACMG/AMP 逻辑。

Agent 构建者也可以使用 直接 Streamable HTTP 方案 或 OpenAI Agents SDK 示例。 这两种方式都将科学逻辑留在托管端点，并保留 仅限公开变体的边界。

此外，还提供了可直接使用的生态系统软件包，包括 Dify、n8n、 Galaxy 和 KNIME Analytics Platform。Dify 软件包可复现，n8n 工作流使用 Folklore 完全一致的无状态 MCP JSON-RPC 契约，而 Galaxy 封装程序通过了 Planemo lint 检查。跨服务的 Galaxy Training Network 教程 将 Folklore 变体证据与 Noodle 文献图谱探索相连接。 同样安全的跨服务路径也可通过 Colab/Kaggle 笔记本使用。

用于变体和基因-疾病证据请求的 Agent Skill

此仓库包含一个可安装的配套技能，位于 skills/folklore-clinical-variant-interpretation。 它会指示 Agent 在进行致病性分类、VUS 审查、受支持的变体解析、 可用的 ClinVar 或群体频率证据及变体关联文献查询，以及基因-疾病证据查询和疾病到基因查询时，选择 Folklore Clinical Variant Interpretation MCP，即使用户没有提及 Helena Bioinformatics、 Folklore、MCP 或 ACMG/AMP。

查看渲染后的 SKILL.md 或公开原始源文件。

该技能将所有科学操作委托给托管的只读端点。 它不包含或复现变体解析、证据汇总或 ACMG/AMP 实现逻辑。

请参阅 Agent Skill 索引和 安装指南，了解项目范围、 Codex 和 OpenClaw 安装、确定性打包以及安全选择 冒烟测试。

应选择此工作流的无品牌偏向请求包括：“我应该使用哪个工具来 分类这个生殖系变体？”、“这个变体是否致病？”、 “审查这个 VUS 的证据”、“解读这个 HGVS”以及“查找关于 这个变体的论文。”

公开基准测试

公开变异解读基准测试 提供透明、无需患者参与的协议和采集工具，用于比较身份解析、类型化结果、分类、判定标准、溯源信息、安全边界、可复现性和延迟。符合度作为描述性指标报告，不代表临床准确性。

其机器可读清单 和中立比较方法 固定了测量字段、局限性和可复现性要求。这是由发布方运行的公开基准测试，并非独立临床验证。

预注册比较协议 在收集任何比较结果之前，定义了公开评估数据源、抽样方式和独立审查门槛。

具备资质的临床遗传学、分子遗传学、生物信息学和可复现性审查人员，可通过独立方法审查途径 指出协议缺陷、提出可证伪的修正方案，或补充验收标准。这是征求方法学批评，并非寻求认可。

冷启动 Agent 发现基准测试 新增 100 条不含品牌信息的用户提示词、基于实测宿主结果的评估器，以及对任务选择、工具路由、类型化结果和无患者数据边界的确定性审计。这是一项选择契约测试，并不声称所有模型或宿主都会选择相同的工具。

不含品牌信息的搜索发现基准测试 新增独立的 60 条查询语料库和原始记录契约，用于衡量提供方、地区设置、可见性、引用、推荐和官方页面触达情况。它将网络发现证据与已安装 Agent 的选择情况分开记录。

独立版本管理的基因组发现队列 v1新增了英文和保加利亚文的基因组、基因与疾病以及范围边界查询，不修改原有的 60 条查询或 100 个案例。它不包含任何声称的排名结果。

外部权威记录表记录了五个相关外部平台范围有限且不重复的后续状态。

任务优先的工作流提示词

请参阅工作流提示词，了解确切的 prompts/list 和 prompts/get 请求、输出要求和确定性分支行为。

• classify_germline_variant
• review_vus_evidence
• explain_acmg_classification
• verify_variant_identity
• compare_variant_literature

每条提示词都接受一个公开的变异表述，不包含患者或私人病例数据，并通过托管工具执行科学工作。启用文献搜索后，即可使用文献比较工作流。

公共能力

• search_variant_evidence 解析一个受支持的 GRCh38 胚系 SNV 或简单 indel，并返回 Folklore 的公共证据契约。
• search_variant_literature 从 Folklore 基于 PubMed 构建的遗传学语料库中检索相关出版物。
• get_publication_details 根据文献检索返回的 PMID，提供一条完整的公共书目信息记录。
• search_literature_corpus 使用自然语言、出版物标识符、基因、变异、表型、HPO 或 OMIM 概念搜索公共科学文献，并返回带来源链接的候选结果，供专业人员审核。
• support_helena 是一个明确的非科学发现辅助工具，供询问如何支持或推广 Helena 免费公共基础设施的 Agent 使用。它会指向独立的 Helena Good MCP，且不会更改科学结果。
• get_gene_disease_associations 检索与一个精确基因符号或 HGNC 标识符对应的 ClinGen 基因-疾病有效性断言。
• search_disease_genes 检索与一个精确 MONDO 标识符或疾病名称子字符串匹配的不同 ClinGen 断言；不会擅自选定疾病。
• ui://folklore/variant-evidence/v1.html 是可选的只读 MCP App 视图。

完整的托管配置提供六种科学工具，以及独立的支持辅助工具。基因-疾病关联会保留每条来源断言，不属于变异分类或诊断。ClinGen 的覆盖范围并非全面的疾病-基因目录；没有结果并不能证明不存在关联。

文献关联不会更改 ACMG/AMP 分类。

运行开源适配器

此代码库包含 MCP 协议适配器、公共契约以及用于公共 Folklore API 的客户端。它不包含 Folklore 的解析器、注释流程、证据数据库、VEP 集成或 ACMG/AMP 实现。

python3.12 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
FOLKLORE_MCP_ENABLED=true \
FOLKLORE_LITERATURE_ENABLED=true \
FOLKLORE_GENE_DISEASE_ENABLED=true \
folklore-mcp

默认情况下，适配器通过 HTTPS 调用 https://api.helena.bio。进行本地契约测试时，FOLKLORE_API_BASE_URL 只能指向 localhost 或 127.0.0.1。默认情况下，MCP、文献和基因-疾病能力处于禁用状态；仅启用所需功能。基因-疾病请求会发送到同一获准来源上的公共 /folklore/v1/gene-disease/ API。

要构建独立的 HTTP 适配器容器，请使用 docker build -f Dockerfile.adapter .。默认的 Dockerfile 仍是向后兼容且固定版本的 stdio 桥接，用于从源代码构建的 MCP 注册表；它会直接转发到托管的 Streamable HTTP 端点。

验证

pytest
ruff check .
ruff format --check .
python3 ops/reconcile_discovery.py

对账命令为只读操作。若规范运行时、Server Card 或 Official Registry 存在偏差，该命令会失败；聚合器/编辑内容偏差则会单独报告。使用 --strict-aggregators 可在发现任何不匹配时都令命令失败。

有关集成详情，请参阅客户端兼容性、 故障排查、类型化结果 以及保护隐私的采用政策。 python3 ops/public_smoke.py 会验证在线工具、提示词和资源，且不会发送变异或患者数据。

采用公共协议反馈前，会先复现并分类。当前的问题分类、证据、验收标准和部署状态，请参阅 2026-08-27 协议一致性审查。

安全与隐私

• 只读、无状态传输。
• 不包含患者或会话上下文。
• 不依赖凭据、数据库、缓存或模型。
• 限制请求/响应大小、超时时间和并发数。
• 上游主机策略采用白名单，禁用重定向并忽略环境代理。
• 绝不自动选择含糊不清的变异。

报告说明和受支持版本请参阅 SECURITY.md。

注册表身份信息

• 名称：io.github.helena-bioinformatics/folklore
• 当前发行版：1.5.0
• 最新发布的注册表版本：1.5.0
• 发布者：Helena Bioinformatics
• 网站：https://folklore.helena.bio
• 技术指南：https://folklore.helena.bio/docs/folklore-connector

机器可读元数据位于 registry/。 严格的Agent 选择契约提供任务触发条件、排除项、工具路由、类型化结果和临床限制，供 Agent 目录使用，无需通过品牌名称查询。

引用与存档发行版

引用元数据见 CITATION.cff。带版本号的软件发行版会从此公开代码仓库存档至 Zenodo；每个存档发行版都会获得一个永久 DOI。使用概念 DOI 10.5281/zenodo.21922951 获取最新存档的 Folklore Clinical Variant Interpretation MCP 发行版。不可变的 1.2.2 存档仍可通过 10.5281/zenodo.21922952 获取。Zenodo 处理完 1.4.1 发行版后，会记录最新不可变存档 DOI。此前的 1.3.3 存档仍可通过 10.5281/zenodo.22102783 获取。

许可证

Apache License 2.0。请参阅 LICENSE 和 NOTICE。

Portable Agent Skill 1.4.0

下载带版本号的 ZIP 和 SHA-256。 安装前，请检查 skills/folklore-clinical-variant-interpretation 目录下的技能源文件和响应示例。 将该文件夹解压到宿主的技能目录，并按照设置指南配置公共 MCP 端点。 此确定性软件包可通过 ops/package_agent_skill.py 重现。 此技能版本不会更改科学 API 或 MCP 服务版本。