SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场folklore-variant-evidence

folklore-variant-evidence

数据与分析

查看项目

更新于 10-15 17:04

技能介绍

用途

Folklore Variant Evidence 用于将单个公开变异标识符转换为结构化的 Folklore 证据，处理明确的解析状态，检索变异关联文献，并获取 ClinGen 基因-疾病或疾病-基因有效性断言。它面向专业审查场景，提供来源可追溯的公开证据与自动化变异级 ACMG/AMP 决策支持。

该技能由 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。

主要能力

  • 检索单个公开变异的结构化证据，包括变异身份、canonical_key、自动化变异级 ACMG/AMP 决策支持结果、来源链接与限制说明。
  • 检索变异关联文献，区分 exact_variant、variant_alias、gene_association 三种匹配类型。
  • 通过 PMID 获取出版物详情，保留 PubMed URL、DOI/PMCID、撤稿状态，并区分基因提及与变异提及。
  • 对公开自然语言科学问题进行语义语料检索，支持按出版物标识符、基因、变异、表型、HPO 或 OMIM 概念发现。
  • 使用 get_gene_disease_associations 按精确基因符号或 HGNC 标识符检索 ClinGen 基因-疾病有效性断言；使用 search_disease_genes 按精确 MONDO 标识符或公开疾病名称子串检索。

使用方式

连接托管端点后，应先调用 tools/list 验证实时工具目录，而非依赖模型记忆。文档记录的公开目录包含：search_variant_evidence、search_variant_literature、get_publication_details、search_literature_corpus、get_gene_disease_associations、search_disease_genes。第七个工具 support_helena 不属于科学证据，仅在明确要求时使用。

不支持原生 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 错误、result.structuredContent.adapter_error，以及该工具的 result.structuredContent.result.status。其他工具使用不同的响应结构，应参考契约表。

变异证据工作流：

  1. 调用 search_variant_evidence，参数为 assembly: GRCh38 和单个公开变异标识符或记法。不要添加表型、疾病、患者、家族或治疗背景。
  2. 根据返回状态分支处理：resolved 可复用返回的 canonical_key 并审查结构化解读、溯源、来源链接与限制；ambiguous 应展示候选并要求明确选择，绝不自动选择；not_found 报告在该服务与查询范围内未找到结果，不声称普遍不存在；invalid_request 报告验证问题并要求更正后的公开变异；unsupported 说明服务边界并停止；resolution_unavailable 报告临时解析或可用性故障，不视为证据缺失。
  3. 仅 resolved 结果可自动进入变异关联文献工作流，其 canonical key 为 envelope.result.identity.canonical_key。若 envelope.result.interpretation.status 不可用，保留其类型化错误，不读取或编造分类。
  4. 审查证据时，保留返回的变异身份与 canonical_key，原样保留自动化 ACMG/AMP 决策支持结果，引用公开来源与溯源，将提交的 ClinVar 断言与 Folklore 自动化结果分开，若不一致则分别报告并保留分歧，不呈现合并共识分类。区分返回事实与代理综合，说明需要合格专业审查。

文献链式调用：resolved 证据调用后，将 canonical_key 传给 search_variant_literature，assembly 保持 GRCh38。可选 question 可缩小文献焦点，但必须是公开科学问题且不含患者背景。get_publication_details 仅使用文献工具返回的 PMID。search_literature_corpus 用于公开自然语言科学问题或按标识符、基因、变异、表型、HPO、OMIM 概念发现，查询长度 3–200 字符，limit 1–25，sort 为 relevance、newest 或 oldest；翻页时复用返回的 opaque next_cursor，不要构造 offset。

基因-疾病断言：get_gene_disease_associations 接受精确基因符号或 HGNC 标识符；search_disease_genes 接受精确 MONDO 标识符或公开疾病名称子串。两者均接受 limit（默认 20，1–50）和 offset（默认 0，0–1000）。需保留返回的疾病身份、遗传方式、证据评估、来源 URL、日期、source.version 与 source.snapshotSha256。这是本地 ClinGen 快照，不保证为最新版本。存在 pagination.nextOffset 时应继续翻页，并保留分页上限警告。

适用场景

  • 将单个公开变异映射为结构化 Folklore 证据。
  • 处理明确的解析状态（resolved、ambiguous、not_found、invalid_request、unsupported、resolution_unavailable）。
  • 检索变异关联文献与出版物详情。
  • 获取 ClinGen 基因-疾病或疾病-基因有效性断言。

限制

  • 仅接受 GRCh38 与胚系核 SNV 或短于 50 碱基对的简单插入/缺失。不支持的组装可能在输入模式阶段被拒绝。
  • 不接受患者姓名、病例标识符、表型、家族史、分离证据、临床记录、上传文件或其他私有或患者特定背景。若任务依赖患者背景，应停止并说明该服务不接受也不评估此类数据。
  • 不得将患者特定请求转换为公开变异查询并暗示结果回答了患者特定问题。
  • 不适用于 VCF 注释、批处理、体细胞变异、结构变异、多基因评分或患者特定解读。
  • 基因-疾病有效性不分类特定变异；not_found 表示可用来源中无匹配断言，而非无关联。
  • 文献关联不改变返回的 ACMG/AMP 分类。
  • 结果不构成诊断、个体风险估计、治疗建议或独立临床报告，需要合格专业审查。
  • 来源覆盖有限，并非所有已知关联都包含在内。

可复现报告与冒烟测试

报告应包含：精确公开查询与 GRCh38 组装；返回状态及 resolved 时的 canonical_key；未改变含义的结构化证据或文献结果；来源链接与出版物标识符；文献结果的匹配类型；访问日期与任何可用性限制。并附边界声明：这是面向合格专业审查的公开变异级决策支持，不评估患者、表型、家族、分离或私有病例数据，不是诊断或治疗建议。

可证伪冒烟测试：使用公开 rsID rs80357914，以 assembly GRCh38 调用 search_variant_evidence。若结果为 ambiguous，列出返回候选并停止等待明确选择，不选择候选也不调用下游文献工具。仅当 ambiguous 响应导致工作流停止且无自动候选选择时，该分支通过。若实时响应变化，记录实际状态；resolved 响应不测试歧义处理。

2026-09-30 的实时发现报告适配器 1.5.0 与协议 2026-07-28。rsID 示例返回 ambiguous；另一公开 HGVS 查询解析成功并通过返回键链式调用文献与返回的 PMID。语料游标分页与基因-疾病 offset 分页均已演练。这些是带日期的协议检查，不是临床准确性验证。

官方参考

  • 集成设置：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