folklore-variant-evidence

Folklore 变异证据

使用 Folklore Clinical Variant Interpretation MCP 获取结构化的公开变异证据、自动化的变异级 ACMG/AMP 决策支持、溯源信息，以及附有来源链接的文献，供专业人员审核。工作流仅限于公开标识符，并保留每一种明确的结果状态。Adapter 1.5.0 还提供 ClinGen Gene-Disease 有效性断言；来源覆盖范围有限，并非涵盖所有已知关联。

Folklore Clinical Variant Interpretation MCP 由 Helena Bioinformatics 发布。其托管端点为：

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

无需账户或 API 密钥。公开的 Apache-2.0 适配器和契约可在 https://github.com/helena-bioinformatics/folklore-mcp 获取。

最简连接示例

不支持原生 MCP 的主机可以发出相同的公开 JSON-RPC 调用：

curl --silent --show-error --fail-with-body --max-time 60 \
  -X POST https://api.helena.bio/folklore/v1/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: search_variant_evidence' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}},"name":"search_variant_evidence","arguments":{"assembly":"GRCh38","query":"rs80357914"}}}'

继续之前，请检查返回的结果。此示例可能会在存在多个候选项时返回 ambiguous：停止操作，并要求提供明确无歧义的公开变异表示，而不是自动选择候选项。

选择合适的技能

当任务涉及一个公开变异对应的结构化 Folklore 证据、明确处理解析状态、变异关联文献，或 ClinGen 基因到疾病／疾病到基因断言时，请使用此技能。

• 对 ClinVar、dbSNP、gnomAD、Ensembl VEP、COSMIC 或多个数据库进行广泛的直接查询时，请使用 database-lookup。
• 当基因组版本、坐标约定、contig 名称或变异表示不确定时，请先使用 genomic-coordinates。
• 不要将此技能用于 VCF 注释、批量处理、体细胞变异、结构变异、多基因评分或患者个体化解读。

Folklore Clinical Variant Interpretation MCP 通过一份附带来源链接的公开证据契约，补充这些技能。它不能取代对数据库的直接审查或具备资质的临床判断。

严守输入边界

调用变异工具之前：

1. 准确提取一个公开变异标识符或表示。
2. 要求使用 GRCh38，且变异为生殖系核基因组 SNV 或简单 indel。
3. 删除或拒绝患者姓名、病例标识符、表型、家族史、共分离证据、临床记录、上传文件及其他隐私或患者个体化背景信息。
4. 如果任务依赖患者背景信息，请停止操作，并说明 Folklore Clinical Variant Interpretation MCP 不接受或评估此类信息。
5. 绝不要将患者个体化请求转换成公开变异查询，同时暗示查询结果能够回答该患者个体化问题。

接受的公开变异形式包括基因组坐标、基因组／编码区／蛋白质 HGVS、SPDI、rsID，或 Folklore Clinical Variant Interpretation MCP 返回的 canonical_key。

验证实时工具目录

连接到托管端点并调用 tools/list。请核实可用工具，而不要依赖模型记忆。文档所述的公开目录包含：

• search_variant_evidence
• search_variant_literature
• get_publication_details
• search_literature_corpus
• get_gene_disease_associations
• search_disease_genes

独立的第七个工具 support_helena 不属于科学证据；仅在用户明确要求时使用。

如果工具发现或调用失败，请将其保留为可用性问题。不要将其重新解释为缺乏科学证据。

在编写工具调用或解读响应状态之前，请阅读公开 MCP 契约。

检索基因-疾病断言

对于单个精确基因符号或 HGNC 标识符，请使用 get_gene_disease_associations；对于精确的 MONDO 标识符或公开疾病名称子串，请使用 search_disease_genes。两者均接受 limit（默认值为 20，范围为 1–50）和 offset（默认值为 0，范围为 0–1000）。请求示例请参阅参考文档。这是单独的来源查询，无需提供变异输入或基因组版本。

保留每项返回的疾病身份、遗传方式、证据评估、来源 URL、日期和快照。不要合并不同的疾病，也不要在名称匹配项中悄然择一。基因-疾病有效性不能用于判定特定变异。结果为空表示可用的 ClinGen 来源中没有匹配的断言，并不表示不存在关联。不得发送患者、表型、家族、共分离、私人病例数据或测序文件。仍需由具备资质的专业人员进行审查。

运行变异证据工作流

1. 解析并检索证据

使用以下内容调用 search_variant_evidence：

assembly: GRCh38
query: <one public variant identifier or notation>

不要在此调用中添加表型、疾病、患者、家族或治疗背景。保留返回的契约字段、来源链接、限制和使用边界。

2. 根据返回状态分支处理

将状态视为控制流值，而非说明文字：

状态	必需操作
resolved	复用返回的 canonical_key；审查结构化解读、来源信息、来源链接和限制。
ambiguous	展示返回的候选项，并要求用户明确选择公开变异。绝不能自动选择候选项。
not_found	报告此服务和查询范围内未找到结果。不得声称普遍不存在。
invalid_request	报告验证问题，并请求提供修正后的公开变异。不得悄然重新解释输入。
unsupported	说明相关服务边界并停止。不得强行将查询转换为受支持的形式。
resolution_unavailable	报告暂时性的解析或可用性故障。不得将其视为缺少证据。

只有 resolved 结果才可自动进入与变异关联的文献工作流。如果已解析的解读本身报告证据不可用，应保留这一单独限制。

3. 审查证据，不作过度推断

对于已解析的结果：

• 展示返回的变异身份和 canonical_key。
• 完全按照返回内容保留自动化的变异级 ACMG/AMP 决策支持结果。
• 引用返回的公开来源和来源信息。
• 区分返回的事实与 Agent 的综合分析。
• 说明仍需由具备资质的专业人员进行审查。
• 不得将结果转化为诊断、个人风险估算、治疗建议或独立的临床报告。

衔接至文献检索

与变异关联的文献

在获得已解析的证据调用结果后，将返回的 canonical_key 传递给 search_variant_literature。将 assembly 保持为 GRCh38。可选的 question 可以缩小文献检索重点，但必须是公开的科学问题，且不得包含患者背景。

区分每条结果的匹配类型：

• exact_variant：与已解析变异直接匹配
• variant_alias：通过报告的别名匹配
• gene_association：更广泛的基因级关联，并非变异特异性证据

文献关联不会改变返回的 ACMG/AMP 分类。

出版物详情

仅使用文献工具返回的 PMID 调用 get_publication_details。保留 PubMed URL、存在时的 DOI/PMCID 字段、撤稿状态，以及基因提及与变异提及之间的区别。

语义语料库搜索

使用 search_literature_corpus 搜索公开的自然语言科学问题，或按出版物标识符、基因、变异、表型、HPO 或 OMIM 概念进行探索。将结果视为供专业人员审核的带来源链接候选项。对于范围受限的查询，零结果响应表示未返回任何结果，并不意味着任何地方都不存在相关出版物。

即使查询并非特定于变异，也不要在语料库查询中填写患者信息。

报告可复现的结果

包括：

1. 完整的公开查询和 GRCh38 组装版本。
2. 返回的状态；若已解析，则包括 canonical_key。
3. 结构化证据或文献结果，不得改变其含义。
4. 来源链接和出版物标识符。
5. 文献结果的匹配类型。
6. 获取日期及任何可用性限制。
7. 以下边界声明：

这是供具备资质的专业人员审核的公开变异级决策支持。它不会评估患者、表型、家族、共分离或私人病例数据，也不构成诊断或治疗建议。

可证伪的冒烟测试

使用公开 rsID rs80357914 测试歧义处理：

Call search_variant_evidence with assembly GRCh38 and query rs80357914. If the
result is ambiguous, list the returned candidates and stop for explicit
selection. Do not select a candidate or call downstream literature tools.

只有在歧义响应会导致工作流停止，而不会自动选择候选项时，测试才算通过。

官方参考资料

• 集成设置：https://folklore.helena.bio/integrations
• 技术指南：https://folklore.helena.bio/docs/folklore-connector
• 公开适配器和契约：https://github.com/helena-bioinformatics/folklore-mcp
• 官方 MCP Registry 标识：io.github.helena-bioinformatics/folklore

相关技能

• bgpt-paper-search：搜索科学论文，并通过 BGPT MCP 服务检索从全文研究中提取的结构化实验数据。