CIViC MCP Server

Un servidor para consultar la API de CIViC, que convierte respuestas GraphQL en tablas SQLite consultables mediante Cloudflare Workers.

GitHubPrueba este MCPPatrocinado

Documentación

Servidor MCP de CIViC

Este es un servidor de Protocolo de Contexto de Modelo (MCP) basado en Cloudflare Workers que proporciona herramientas para consultar la API de CIViC (Interpretación Clínica de Variantes en Cáncer). El servidor convierte respuestas GraphQL en tablas SQLite consultables utilizando Durable Objects para un procesamiento eficiente de datos.

La base de datos CIViC es un repositorio de código abierto colaborativo de interpretaciones clínicas de variantes de cáncer. Este servidor MCP permite consultas estructuradas y análisis de datos de información genómica del cáncer a través de interacciones en lenguaje natural con asistentes de IA.

Cumplimiento de la Especificación MCP

Este servidor implementa MCP 2026-07-28 a través del adaptador SDK v2 sin estado de la flota:

server/discover reemplaza la inicialización y cada solicitud lleva su envoltorio de protocolo/capacidad.
El Worker utiliza HTTP Streamable sin estado sin sesión MCP Durable Object ni Mcp-Session-Id.
El SDK valida Mcp-Method / Mcp-Name, sella resultType y serverInfo, y proporciona sugerencias de caché.
Las listas de herramientas tienen un orden de registro determinista.
Las herramientas devuelven content y structuredContent en éxito y error, con isError: true para errores.
Los resultados estructurados grandes conservan las protecciones de almacenamiento temporal y transporte de 100KB de la flota.

Referencia de Anotaciones de Herramientas

El servidor define anotaciones completas de herramientas para clientes MCP:

// GraphQL Query Tool
annotations: {
  readOnlyHint: false,      // Creates/modifies data in SQLite
  destructiveHint: false,   // Non-destructive data staging
  idempotentHint: false,    // Different queries produce different results
  openWorldHint: true       // Interacts with external CIViC API
}

// SQL Query Tool  
annotations: {
  readOnlyHint: true,       // Only reads data
  destructiveHint: false,   // Cannot modify data (read-only SQL)
  idempotentHint: true,     // Same query produces same results
  openWorldHint: false      // Operates on closed SQLite database
}

Transporte

// MCP 2026-07-28 stateless Streamable HTTP
CivicMCP.serve("/mcp").fetch(request, env, ctx)

Los únicos Durable Objects retenidos son objetos de aplicación/datos utilizados para almacenamiento temporal; no son sesiones de transporte MCP.

Características

Conversión de GraphQL a SQL: Convierte automáticamente las respuestas de la API CIViC en tablas SQLite estructuradas
Almacenamiento Eficiente de Datos: Utiliza Cloudflare Durable Objects con SQLite para el almacenamiento temporal y consulta de datos
Manejo Inteligente de Respuestas: Optimiza el rendimiento omitiendo el almacenamiento temporal para respuestas pequeñas, errores y consultas de introspección de esquema
Pipeline de Herramientas:
1. civic_graphql_query: Ejecuta consultas GraphQL y almacena conjuntos de datos grandes
2. civic_query_sql: Habilita análisis basado en SQL de datos almacenados
3. civic_execute: Modo Código — ejecuta JavaScript en un aislamiento V8 con gql.query() y ayudantes de esquema para acceso completo a GraphQL

Instalación y Configuración

Requisitos Previos

Una cuenta de Cloudflare
CLI de Wrangler instalado
Aplicación Claude Desktop

Desplegar en Cloudflare Workers

Clona este repositorio:

git clone <repository-url>
cd civic-mcp-server

Instala las dependencias:
```
npm install
```
Despliega en Cloudflare Workers:
```
npm run deploy
```
Después del despliegue, obtendrás una URL como: https://civic-mcp-server.YOUR_SUBDOMAIN.workers.dev

Configurar Claude Desktop

Agrega esta configuración a tu archivo claude_desktop_config.json:

{
  "mcpServers": {
    "civic-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://civic-mcp-server.quentincody.workers.dev/mcp"
      ]
    }
  }
}

Reemplaza quentincody con tu subdominio real de Cloudflare Workers.

Uso

Una vez configurado, reinicia Claude Desktop. El servidor proporciona tres herramientas principales:

civic_graphql_query: Ejecuta consultas GraphQL contra la API CIViC
civic_query_sql: Consulta datos almacenados usando SQL
civic_execute: Modo Código — escribe JavaScript contra la API GraphQL de CIViC en un aislamiento V8

Prompts

Este servidor expone tres Prompts MCP que guían al modelo para usar la herramienta civic_graphql_query con sintaxis GraphQL correcta y estrategias de búsqueda robustas:

Prompts de Tipos de Datos Individuales

get-variant-evidence — Genera GraphQL solo para Elementos de Evidencia (sin filtro variantName - no compatible con el esquema CIViC)
get-variant-assertions — Genera GraphQL solo para Afirmaciones con estrategias de respaldo sistemáticas

Prompt de Datos Combinados

get-variant-data — Ejecuta consultas tanto de Elementos de Evidencia COMO de Afirmaciones para un análisis integral de variantes

Ejemplos (VS Code Copilot Chat / comandos de barra):

/get-variant-evidence molecularProfileName:"TP53 Mutation" diseaseName:"Lung Adenocarcinoma" evidenceType:"PROGNOSTIC" first:"200"
/get-variant-assertions molecularProfileName:"TPM3-NTRK1 Fusion" therapyName:"Larotrectinib" status:"ALL"
/get-variant-data molecularProfileName:"BRAF V600E" diseaseName:"Melanoma" therapyName:"Trametinib" status:"ALL"

Características Clave de los Prompts

Generación GraphQL a Prueba de Fallos: Consultas completas y validadas que nunca fallan
Estrategias de Búsqueda Inteligentes: Enfoques de respaldo automáticos para encontrar datos relevantes
Resultados Integrales: Los elementos de evidencia incluyen descripciones clínicas; las afirmaciones proporcionan resúmenes de alto nivel
Filtrado Óptimo: El estado predeterminado es "ALL" para evitar sobre-filtrado; los parámetros nulos se excluyen automáticamente
Generación Adecuada de URLs: Enlaces canónicos para verificación (evidencia: /evidence/{id}, afirmaciones: /assertions/{id})

Estos prompts proporcionan consultas GraphQL completas con cumplimiento adecuado del esquema CIViC v2 y metodologías de búsqueda sistemáticas que aseguran el descubrimiento de datos incluso cuando los usuarios proporcionan parámetros imperfectos.

Consultas de Ejemplo

Puedes hacer preguntas a Claude como:

"¿Cuáles son los elementos de evidencia más recientes para mutaciones BRAF?"
"Muéstrame todas las interpretaciones terapéuticas para variantes de cáncer de pulmón"
"Encuentra genes con más elementos de evidencia en la base de datos CIViC"

Claude utilizará el servidor (y su herramienta civic_graphql_query) para obtener los datos relevantes de la base de datos CIViC y presentártelos. El servidor está diseñado para consultar la versión 2 de la API CIViC, asegurando que obtengas información actualizada.

Si encuentras problemas o Claude no parece estar usando los datos de CIViC, verifica nuevamente los pasos de configuración anteriores.

Manejo de Respuestas

El servidor optimiza inteligentemente el uso de contexto almacenando resultados grandes en una base de datos SQLite temporal. Cuando las respuestas GraphQL cumplen ciertos criterios, la respuesta cruda se devuelve directamente en lugar de crear una base de datos:

Respuestas pequeñas (< 1500 caracteres): Se devuelven directamente para evitar sobrecarga innecesaria
Respuestas de error: Se pasan directamente para facilitar la resolución de problemas
Respuestas vacías/nulas: Se omiten para evitar crear bases de datos vacías
Consultas de introspección de esquema: Las consultas que contienen __schema, __type u otros patrones de introspección se devuelven directamente ya que contienen metadatos en lugar de datos adecuados para conversión SQL

Esta optimización hace que el servidor sea más eficiente y proporciona mejor visibilidad de errores mientras aún permite un potente análisis basado en SQL para conjuntos de datos sustanciales.

Licencia

Licencia MIT con Requisito de Citación Académica - ver LICENSE.md