folklore-variant-evidence

Evidência de Variante Folklore

Use o Folklore Clinical Variant Interpretation MCP para recuperar evidências públicas estruturadas de variantes, suporte automatizado de decisão ACMG/AMP em nível de variante, proveniência e literatura vinculada a fontes para revisão profissional. Mantenha o fluxo de trabalho limitado a identificadores públicos e preserve todos os estados de resultado explícitos. O adaptador 1.5.0 também fornece asserções de Validade Gene-Doença do ClinGen; a cobertura de fontes é limitada, nem toda associação conhecida está presente.

O Folklore Clinical Variant Interpretation MCP é publicado pela Helena Bioinformatics. Seu endpoint hospedado é:

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

Nenhuma conta ou chave de API é necessária. O adaptador público sob licença Apache-2.0 e o contrato estão disponíveis em https://github.com/helena-bioinformatics/folklore-mcp.

Exemplo mínimo de conexão

Um host sem suporte nativo a MCP pode fazer a mesma chamada JSON-RPC pública:

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"}}}'

Inspecione o resultado retornado antes de continuar. Este exemplo pode retornar ambíguo com múltiplos candidatos: pare e solicite uma notação de variante pública inequívoca em vez de selecionar um candidato automaticamente.

Selecione o skill correto

Use este skill quando a tarefa for uma variante pública para evidência Folklore estruturada, manipulação explícita do estado de resolução, literatura vinculada à variante ou asserções gene-para-doença/doença-para-gene do ClinGen.

• Use database-lookup para consultas diretas amplas em ClinVar, dbSNP, gnomAD, Ensembl VEP, COSMIC ou múltiplos bancos de dados.
• Use genomic-coordinates primeiro quando a montagem, convenção de coordenadas, nome do contig ou representação da variante forem incertos.
• Não use este skill para anotação VCF, processamento em lote, variantes somáticas, variantes estruturais, escores poligênicos ou interpretação específica de paciente.

O Folklore Clinical Variant Interpretation MCP complementa esses skills com um contrato de evidência pública vinculada a fontes. Ele não substitui a revisão direta de bancos de dados ou o julgamento clínico qualificado.

Reforce o limite de entrada

Antes de uma chamada de ferramenta de variante:

1. Extraia exatamente um identificador de variante pública ou notação.
2. Exija GRCh38 e uma variante germinativa nuclear SNV ou indel simples.
3. Remova ou recuse nomes de pacientes, identificadores de caso, fenótipos, histórico familiar, evidências de segregação, registros clínicos, arquivos enviados e outro contexto privado ou específico de paciente.
4. Se a tarefa depender de contexto do paciente, pare e explique que o Folklore Clinical Variant Interpretation MCP não aceita ou avalia esse contexto.
5. Nunca transforme uma solicitação específica de paciente em uma consulta de variante pública enquanto implica que o resultado responde à pergunta específica do paciente.

Formas aceitas de variante pública incluem coordenadas genômicas, HGVS genômico/codificante/proteico, SPDI, rsID ou uma canonical_key retornada pelo Folklore Clinical Variant Interpretation MCP.

Verifique o catálogo ativo de ferramentas

Conecte-se ao endpoint hospedado e chame tools/list. Verifique as ferramentas disponíveis em vez de confiar na memória do modelo. O catálogo público documentado contém:

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

A sétima ferramenta separada support_helena não é evidência científica; use-a apenas quando solicitado explicitamente.

Se a descoberta ou uma chamada de ferramenta falhar, preserve a falha como um problema de disponibilidade. Não a reinterprete como falta de evidência científica.

Leia o contrato MCP público antes de compor chamadas de ferramentas ou interpretar estados de resposta.

Recupere asserções gene-doença

Use get_gene_disease_associations para um símbolo de gene exato ou identificador HGNC, ou search_disease_genes para um identificador MONDO exato ou substring pública de nome de doença. Ambos aceitam limit (padrão 20, 1–50) e offset (padrão 0, 0–1000). Consulte a referência para exemplos de solicitação. Esta é uma consulta de fonte separada e não requer entrada de variante ou montagem.

Preserve cada identidade de doença retornada, herança, avaliação de evidência, URL de origem, data e instantâneo. Não combine doenças distintas ou escolha silenciosamente entre correspondências de nome. A validade gene-doença não classifica uma variante específica. Resultados vazios significam que não há asserção correspondente na fonte ClinGen disponível, não que não haja associação. Nenhum dado de paciente, fenótipo, família, segregação, caso privado ou arquivos de sequenciamento podem ser enviados. A revisão profissional qualificada permanece necessária.

Execute o fluxo de trabalho de evidência de variante

1. Resolva e recupere evidências

Chame search_variant_evidence com:

assembly: GRCh38
query: <um identificador de variante pública ou notação>

Não adicione fenótipo, doença, paciente, família ou contexto de tratamento a esta chamada. Preserve os campos de contrato retornados, links de fontes, limitações e limite de uso.

2. Ramifique com base no status retornado

Trate o status como um valor de fluxo de controle, não como prosa:

Status	Ação necessária
resolved	Reutilize a canonical_key retornada; revise a interpretação estruturada, proveniência, links de fontes e limitações.
ambiguous	Mostre os candidatos retornados e peça uma seleção explícita de variante pública. Nunca escolha um candidato automaticamente.
not_found	Relate que nenhum resultado foi encontrado neste serviço e escopo de consulta. Não afirme ausência universal.
invalid_request	Relate o problema de validação e solicite uma variante pública corrigida. Não reinterprete silenciosamente a entrada.
unsupported	Declare o limite de serviço relevante e pare. Não force a consulta a uma forma suportada.
resolution_unavailable	Relate uma falha temporária de resolução ou disponibilidade. Não trate como ausência de evidência.

Apenas um resultado resolved pode prosseguir automaticamente para um fluxo de trabalho de literatura vinculada à variante. Se uma interpretação resolvida em si relatar evidência indisponível, preserve essa limitação separada.

3. Revise a evidência sem exageros

Para um resultado resolvido:

• Apresente a identidade da variante retornada e a canonical_key.
• Preserve o resultado de suporte automatizado de decisão ACMG/AMP em nível de variante exatamente como retornado.
• Cite as fontes públicas retornadas e a proveniência.
• Separe os fatos retornados da síntese do agente.
• Declare que a revisão profissional qualificada é necessária.
• Não transforme o resultado em um diagnóstico, estimativa de risco individual, recomendação de tratamento ou relatório clínico independente.

Encadeie com literatura

Literatura vinculada à variante

Após uma chamada de evidência resolvida, passe a canonical_key retornada para search_variant_literature. Mantenha assembly como GRCh38. Uma question opcional pode restringir o foco da literatura, mas deve permanecer uma pergunta científica pública e não pode conter contexto de paciente.

Distinga o tipo de correspondência de cada resultado:

• exact_variant: correspondência direta à variante resolvida
• variant_alias: correspondência através de um alias relatado
• gene_association: associação mais ampla em nível de gene, não prova específica de variante

As associações de literatura não alteram a classificação ACMG/AMP retornada.

Detalhes de publicação

Chame get_publication_details apenas com um PMID retornado pelas ferramentas de literatura. Preserve URLs do PubMed, campos DOI/PMCID quando presentes, status de retratação e a distinção entre menções de gene e menções de variante.

Pesquisa semântica no corpus

Use search_literature_corpus para uma pergunta científica em linguagem natural pública ou para descoberta por identificador de publicação, gene, variante, fenótipo, HPO ou conceito OMIM. Trate os resultados como candidatos vinculados a fontes para revisão profissional. Um resultado de zero respostas significa que nenhum resultado foi retornado para aquela consulta limitada, não que nenhuma publicação relevante existe em lugar algum.

Não coloque informações de paciente em uma consulta de corpus, mesmo que a consulta não seja específica de variante.

Relate um resultado reproduzível

Inclua:

1. A consulta pública exata e a montagem GRCh38.
2. O status retornado e, se resolvido, a canonical_key.
3. A evidência estruturada ou resultado de literatura sem alterar seu significado.
4. Links de fontes e identificadores de publicação.
5. Tipo de correspondência para resultados de literatura.
6. Data de acesso e qualquer limitação de disponibilidade.
7. Esta declaração de limite:

Este é suporte público de decisão em nível de variante para revisão profissional qualificada. Ele não avalia dados de paciente, fenótipo, família, segregação ou caso privado e não é um diagnóstico ou recomendação de tratamento.

Teste de fumaça falseável

Use o rsID público rs80357914 para testar a manipulação de ambiguidade:

Chame search_variant_evidence com assembly GRCh38 e query rs80357914. Se o
resultado for ambíguo, liste os candidatos retornados e pare para seleção
 explícita. Não selecione um candidato nem chame ferramentas de literatura subsequentes.

O teste passa apenas se uma resposta ambígua fizer o fluxo de trabalho parar sem seleção automática de candidato.

Referências oficiais

• Configuração de integração: https://folklore.helena.bio/integrations
• Guia técnico: https://folklore.helena.bio/docs/folklore-connector
• Adaptador e contrato públicos: https://github.com/helena-bioinformatics/folklore-mcp
• Identidade oficial no Registro MCP: io.github.helena-bioinformatics/folklore