folklore-variant-evidence

Folklore 变异证据

使用 Folklore Clinical Variant Interpretation MCP 获取结构化公共变异证据、自动化变异级 ACMG/AMP 决策支持、溯源信息以及带来源链接的文献，以供专业审查。将工作流限制在公共标识符范围内，并保留每一个明确的结局状态。适配器 1.5.0 还提供 ClinGen 基因-疾病有效性断言；来源覆盖范围是有限的，并非涵盖所有已知关联。

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

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

无需账户或 API key。公共 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"}}}'

路由标头必须与 JSON-RPC 方法和工具名称匹配。HTTP 响应成功并不足够：请检查 JSON-RPC 的 error，然后是 result.structuredContent.adapter_error，再然后是此工具的 result.structuredContent.result.status。其他工具使用不同的响应结构；请使用契约表。

在继续之前检查返回的结局。此示例可能返回带有多个候选的 ambiguous：请停止并请求一个无歧义的公共变异表示法，而不是自动选择一个候选。

选择正确的技能

当任务是以下情况时使用此技能：将一个公共变异转换为结构化 Folklore 证据、显式解析状态处理、变异关联文献，或 ClinGen 基因到疾病/疾病到基因断言。

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

Folklore Clinical Variant Interpretation MCP 通过一个带来源链接的公共证据契约来补充这些技能。它不能替代直接数据库审查或合格的临床判断。

强制执行输入边界

在调用变异工具之前：

1. 仅提取一个公共变异标识符或表示法。
2. 要求 GRCh38 以及胚系核 SNV 或短于 50 个碱基对的简单插入/缺失。不支持的组装版本可能会在任何科学性的 unsupported 状态出现之前就被输入 schema 拒绝。
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

单独的第 7 个工具 support_helena 不是科学证据；仅在明确要求时使用它。

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

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

检索基因-疾病断言

使用 get_gene_disease_associations 查询一个精确的基因符号或 HGNC 标识符，或使用 search_disease_genes 查询一个精确的 MONDO 标识符或公开疾病名称子串。两者都接受 limit（默认 20，1–50）和 offset（默认 0，0–1000）。请求示例见参考文档。这是独立的来源查询，不需要变异输入或组装信息。

保留每个返回的疾病身份、遗传方式、证据评估、来源 URL、日期、source.version 和 source.snapshotSha256。这是本地 ClinGen 快照，不保证是最新的 ClinGen 发布版本。在 pagination.nextOffset 存在时持续跟进；保留分页上限警告。超过总数后的空页面并不意味着初始查询没有匹配项。不要合并不同的疾病，也不要静默地在名称匹配项中做出选择。基因-疾病有效性并不对特定变异进行分类。not_found 响应意味着在可用来源中没有匹配的断言，而不是没有关联。不得发送任何患者、表型、家族、分离、私人病例数据或测序文件。仍需合格的专业人员审核。

运行变异证据工作流

1. 解析并检索证据

调用 search_variant_evidence，参数为：

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

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

2. 根据返回的状态进行分支

首先读取传输/JSON-RPC 错误和 adapter_error。对于 search_variant_evidence，令 envelope = result.structuredContent；仅当 envelope.result 非空时，根据 envelope.result.status 进行分支。invalid_arguments 适配器错误与科学上的 invalid_request 不同。保留 isError 和任何类型化失败，包括 resolution_unavailable。将状态视为控制流值，而非叙述性文本：

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

只有 resolved 结果可以自动进入变异关联的文献工作流。其规范键为 envelope.result.identity.canonical_key。如果 envelope.result.interpretation.status 为 unavailable，保留其类型化错误；身份解析已成功，但分类尚未完成。不要为该结果读取或编造分类。

3. 审查证据，避免过度断言

对于已解析的结果：

• 呈现返回的变异身份和 canonical_key。
• 完全按照返回内容保留自动化变异级 ACMG/AMP 决策支持结果。
• 引用返回的公开来源和来源信息。
• 按照上游解读指南的要求，将提交的 ClinVar 断言与 Folklore 的自动化结果分开。如果两者不一致，分别报告每个断言及其来源/日期，并保留分歧；不要呈现合并后的共识分类。
• 将返回的事实与 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 概念进行发现。将结果视为供专业审查使用的来源关联候选。 零结果响应意味着针对该有界查询未返回任何结果，而非 任何地方都不存在相关出版物。

查询长度为 3–200 个字符，limit 为 1–25，sort 设为 relevance、 newest 或 oldest。要获取另一页，请复用返回的不透明 next_cursor， 并使用相同的查询和排序；不要构造偏移量。将 match_types 和 article_entities 与变异文献匹配类型区分开来。报告 semantic_index_used 和 semantic_degraded_reason；返回的词法匹配 并不能证明语义检索有效。保留实时服务返回的 其他检索元数据。

不要将患者信息放入语料库查询，即使该查询并非 变异特异性查询。

报告可复现的结果

包括：

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.

仅当歧义响应导致工作流停止且不自动选择候选时， 歧义分支才通过。如果实时响应发生变化，请记录 实际状态；已解析的响应不能测试歧义处理。

2026-09-30，实时发现报告 adapter 1.5.0 和 protocol 2026-07-28。 rsID 示例返回 ambiguous；另一个公开 HGVS 查询成功解析， 并通过其返回的 key 链接到文献和一个返回的 PMID。语料库 游标分页和基因-疾病偏移分页均已演练。这些是 有日期的协议检查，而非对临床准确性的验证。有关确切的响应形态和 来源/实时差异，请参阅参考资料。

官方参考资料

• 集成设置：https://folklore.helena.bio/integrations
• 技术指南：https://folklore.helena.bio/docs/folklore-connector
• 公开 adapter 与合约：https://github.com/helena-bioinformatics/folklore-mcp
• 官方 MCP Registry 身份：io.github.helena-bioinformatics/folklore