folklore-variant-evidence

Folklore Variant Evidence

Usa Folklore Clinical Variant Interpretation MCP para recuperar evidencia estructurada pública de variantes, soporte automatizado de decisiones ACMG/AMP a nivel de variante, procedencia y literatura vinculada a fuentes para revisión profesional. Mantén el flujo de trabajo limitado a identificadores públicos y preserva cada estado explícito de resultado. El adaptador 1.5.0 también proporciona afirmaciones de validez gen-enfermedad de ClinGen; la cobertura de fuentes es limitada, no todas las asociaciones conocidas.

Folklore Clinical Variant Interpretation MCP es publicado por Helena Bioinformatics. Su endpoint alojado es:

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

No se requiere cuenta ni clave API. El adaptador público con licencia Apache-2.0 y el contrato están disponibles en https://github.com/helena-bioinformatics/folklore-mcp.

Ejemplo mínimo de conexión

Un host sin soporte nativo MCP puede realizar la misma llamada 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"}}}'

Inspecciona el resultado devuelto antes de continuar. Este ejemplo puede devolver ambiguous con múltiples candidatos: detente y solicita una notación de variante pública inequívoca en lugar de seleccionar un candidato automáticamente.

Selecciona la habilidad correcta

Usa esta habilidad cuando la tarea sea una variante pública hacia evidencia Folklore estructurada, manejo explícito del estado de resolución, literatura vinculada a la variante o afirmaciones ClinGen de gen-a-enfermedad/enfermedad-a-gen.

• Usa database-lookup para consultas directas amplias en ClinVar, dbSNP, gnomAD, Ensembl VEP, COSMIC o múltiples bases de datos.
• Usa genomic-coordinates primero cuando el ensamblaje, la convención de coordenadas, el nombre del contig o la representación de la variante sean inciertos.
• No uses esta habilidad para anotación VCF, procesamiento por lotes, variantes somáticas, variantes estructurales, puntuaciones poligénicas o interpretación específica de paciente.

Folklore Clinical Variant Interpretation MCP complementa esas habilidades con un contrato de evidencia pública vinculada a fuentes. No reemplaza la revisión directa de bases de datos ni el juicio clínico calificado.

Aplica el límite de entrada

Antes de una llamada de herramienta de variante:

1. Extrae exactamente un identificador o notación de variante pública.
2. Exige GRCh38 y una variante SNV germinal nuclear o indel simple.
3. Elimina o rechaza nombres de pacientes, identificadores de casos, fenotipos, historial familiar, evidencia de segregación, registros clínicos, archivos subidos y cualquier otro contexto privado o específico de paciente.
4. Si la tarea depende del contexto del paciente, detente y explica que Folklore Clinical Variant Interpretation MCP no lo acepta ni evalúa.
5. Nunca transformes una solicitud específica de paciente en una consulta de variante pública implicando que el resultado responde a la pregunta específica del paciente.

Las formas aceptadas de variante pública incluyen coordenadas genómicas, HGVS genómico/codificante/proteico, SPDI, rsID o una canonical_key devuelta por Folklore Clinical Variant Interpretation MCP.

Verifica el catálogo de herramientas activo

Conéctate al endpoint alojado y llama a tools/list. Verifica las herramientas disponibles en lugar de confiar en la memoria del modelo. El catálogo público documentado contiene:

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

La séptima herramienta separada support_helena no es evidencia científica; úsala solo cuando se solicite explícitamente.

Si el descubrimiento o una llamada de herramienta falla, preserva el fallo como un problema de disponibilidad. No lo reinterpretes como falta de evidencia científica.

Lee el contrato MCP público antes de componer llamadas de herramienta o interpretar estados de respuesta.

Recupera afirmaciones gen-enfermedad

Usa get_gene_disease_associations para un símbolo de gen exacto o identificador HGNC, o search_disease_genes para un identificador MONDO exacto o subcadena de nombre de enfermedad pública. Ambos aceptan limit (predeterminado 20, 1–50) y offset (predeterminado 0, 0–1000). Consulta la referencia para ejemplos de solicitud. Esta es una búsqueda de fuente separada y no requiere entrada de variante ni ensamblaje.

Preserva cada identidad de enfermedad devuelta, herencia, evaluación de evidencia, URL de fuente, fecha e instantánea. No combines enfermedades distintas ni elijas silenciosamente entre coincidencias de nombre. La validez gen-enfermedad no clasifica una variante particular. Resultados vacíos significan que no hay una afirmación coincidente en la fuente ClinGen disponible, no que no haya asociación. No se pueden enviar datos de paciente, fenotipo, familia, segregación, datos de caso privados ni archivos de secuenciación. La revisión profesional calificada sigue siendo necesaria.

Ejecuta el flujo de trabajo de evidencia de variante

1. Resuelve y recupera evidencia

Llama a search_variant_evidence con:

assembly: GRCh38
query: <un identificador o notación de variante pública>

No agregues fenotipo, enfermedad, paciente, familia o contexto de tratamiento a esta llamada. Preserva los campos del contrato devueltos, los enlaces a fuentes, las limitaciones y el límite de uso.

2. Ramifica según el estado devuelto

Trata el estado como un valor de control de flujo, no como prosa:

Estado	Acción requerida
resolved	Reutiliza la canonical_key devuelta; revisa la interpretación estructurada, procedencia, enlaces a fuentes y limitaciones.
ambiguous	Muestra los candidatos devueltos y solicita una selección explícita de variante pública. Nunca elijas un candidato automáticamente.
not_found	Informa que no se encontró ningún resultado dentro de este servicio y alcance de consulta. No afirmes ausencia universal.
invalid_request	Informa el problema de validación y solicita una variante pública corregida. No reinterpretes silenciosamente la entrada.
unsupported	Indica el límite de servicio relevante y detente. No fuerces la consulta a una forma soportada.
resolution_unavailable	Informa una falla temporal de resolución o disponibilidad. No lo trates como ausencia de evidencia.

Solo un resultado resolved puede proceder automáticamente a un flujo de trabajo de literatura vinculada a variante. Si una interpretación resuelta en sí misma informa evidencia no disponible, preserva esa limitación separada.

3. Revisa la evidencia sin exagerar

Para un resultado resuelto:

• Presenta la identidad de variante devuelta y la canonical_key.
• Preserva el resultado de soporte automatizado de decisiones ACMG/AMP a nivel de variante exactamente como se devolvió.
• Cita las fuentes públicas y la procedencia devueltas.
• Separa los hechos devueltos de la síntesis del agente.
• Indica que se requiere revisión profesional calificada.
• No conviertas el resultado en un diagnóstico, estimación de riesgo individual, recomendación de tratamiento o informe clínico independiente.

Encadena a literatura

Literatura vinculada a variante

Después de una llamada de evidencia resuelta, pasa la canonical_key devuelta a search_variant_literature. Mantén assembly como GRCh38. Una question opcional puede acotar el enfoque de la literatura, pero debe seguir siendo una pregunta científica pública y no debe contener contexto de paciente.

Distingue el tipo de coincidencia de cada resultado:

• exact_variant: coincidencia directa con la variante resuelta
• variant_alias: coincidencia a través de un alias reportado
• gene_association: asociación más amplia a nivel de gen, no prueba específica de variante

Las asociaciones de literatura no alteran la clasificación ACMG/AMP devuelta.

Detalles de publicación

Llama a get_publication_details solo con un PMID devuelto por las herramientas de literatura. Preserva las URLs de PubMed, los campos DOI/PMCID cuando estén presentes, el estado de retractación y la distinción entre menciones de gen y menciones de variante.

Búsqueda semántica en corpus

Usa search_literature_corpus para una pregunta científica pública en lenguaje natural o para descubrimiento por identificador de publicación, gen, variante, fenotipo, HPO o concepto OMIM. Trata los resultados como candidatos vinculados a fuentes para revisión profesional. Una respuesta de cero resultados significa que no se devolvió ningún resultado para esa consulta limitada, no que no exista ninguna publicación relevante en ningún lugar.

No coloques información de paciente en una consulta de corpus, incluso si la consulta no es específica de variante.

Informa un resultado reproducible

Incluye:

1. La consulta pública exacta y el ensamblaje GRCh38.
2. El estado devuelto y, si está resuelto, la canonical_key.
3. La evidencia estructurada o el resultado de literatura sin cambiar su significado.
4. Enlaces a fuentes e identificadores de publicación.
5. Tipo de coincidencia para resultados de literatura.
6. Fecha de acceso y cualquier limitación de disponibilidad.
7. Esta declaración de límite:

Esto es soporte de decisiones a nivel de variante pública para revisión profesional calificada. No evalúa datos de paciente, fenotipo, familia, segregación o casos privados y no es un diagnóstico o recomendación de tratamiento.

Prueba de humo falsificable

Usa el rsID público rs80357914 para probar el manejo de ambigüedad:

Llama a search_variant_evidence con assembly GRCh38 y query rs80357914. Si el
resultado es ambiguo, lista los candidatos devueltos y detente para selección
explícita. No selecciones un candidato ni llames a herramientas de literatura
descendentes.

La prueba pasa solo si una respuesta ambigua hace que el flujo de trabajo se detenga sin selección automática de candidatos.

Referencias oficiales

• Configuración de integración: https://folklore.helena.bio/integrations
• Guía técnica: https://folklore.helena.bio/docs/folklore-connector
• Adaptador y contrato público: https://github.com/helena-bioinformatics/folklore-mcp
• Identidad oficial en el Registro MCP: io.github.helena-bioinformatics/folklore