CIViC MCP Server

Um servidor para consultar a API do CIViC, convertendo respostas GraphQL em tabelas SQLite consultáveis usando Cloudflare Workers.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP CIViC

Este é um servidor de Protocolo de Contexto de Modelo (MCP) baseado em Cloudflare Workers que fornece ferramentas para consultar a API CIViC (Interpretação Clínica de Variantes em Câncer). O servidor converte respostas GraphQL em tabelas SQLite consultáveis usando Durable Objects para processamento eficiente de dados.

O banco de dados CIViC é um repositório crowdsourced de interpretações clínicas de variantes de câncer. Este servidor MCP permite consultas estruturadas e análise de dados de informações genômicas de câncer por meio de interações em linguagem natural com assistentes de IA.

Conformidade com a Especificação MCP

Este servidor implementa MCP 2026-07-28 por meio do adaptador SDK v2 sem estado da frota:

  • server/discover substitui a inicialização e cada requisição carrega seu envelope de protocolo/capacidade.
  • O Worker usa Streamable HTTP sem estado, sem Durable Object de sessão MCP ou Mcp-Session-Id.
  • O SDK valida Mcp-Method / Mcp-Name, carimba resultType e serverInfo, e fornece dicas de cache.
  • As listas de ferramentas têm ordem de registro determinística.
  • As ferramentas retornam content e structuredContent em caso de sucesso e erro, com isError: true para erros.
  • Resultados estruturados grandes mantêm as proteções de staging e transporte de 100KB da frota.

Referência de Anotações de Ferramentas

O servidor define anotações abrangentes de ferramentas 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)

Os únicos Durable Objects mantidos são objetos de aplicação/dados usados para staging; eles não são sessões de transporte MCP.

Recursos

  • Conversão GraphQL para SQL: Converte automaticamente respostas da API CIViC em tabelas SQLite estruturadas
  • Armazenamento Eficiente de Dados: Usa Cloudflare Durable Objects com SQLite para staging e consulta de dados
  • Manipulação Inteligente de Respostas: Otimiza o desempenho ignorando o staging para respostas pequenas, erros e consultas de introspecção de esquema
  • Pipeline de Ferramentas:
    1. civic_graphql_query: Executa consultas GraphQL e faz staging de grandes conjuntos de dados
    2. civic_query_sql: Permite análise baseada em SQL de dados em staging
    3. civic_execute: Modo Código — executa JavaScript em um isolado V8 com gql.query() e auxiliares de esquema para acesso completo ao GraphQL

Instalação e Configuração

Pré-requisitos

  • Uma conta Cloudflare
  • CLI Wrangler instalado
  • Aplicativo Claude Desktop

Implantar no Cloudflare Workers

  1. Clone este repositório:

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

  2. Instale as dependências:

    npm install

  3. Implante no Cloudflare Workers:

    npm run deploy

  4. Após a implantação, você receberá uma URL como: https://civic-mcp-server.YOUR_SUBDOMAIN.workers.dev

Configurar o Claude Desktop

Adicione esta configuração ao seu arquivo claude_desktop_config.json:

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

Substitua quentincody pelo seu subdomínio real do Cloudflare Workers.

Uso

Após a configuração, reinicie o Claude Desktop. O servidor fornece três ferramentas principais:

  1. civic_graphql_query: Executa consultas GraphQL contra a API CIViC
  2. civic_query_sql: Consulta dados em staging usando SQL
  3. civic_execute: Modo Código — escreva JavaScript contra a API GraphQL CIViC em um isolado V8

Prompts

Este servidor expõe três Prompts MCP que orientam o modelo a usar a ferramenta civic_graphql_query com sintaxe GraphQL correta e estratégias robustas de busca:

Prompts Individuais por Tipo de Dado

  • get-variant-evidence — Gera GraphQL apenas para Itens de Evidência (sem filtro variantName - não suportado pelo esquema CIViC)
  • get-variant-assertions — Gera GraphQL apenas para Assertions com estratégias sistemáticas de fallback

Prompt Combinado de Dados

  • get-variant-data — Executa consultas de Itens de Evidência E Assertions para análise abrangente de variantes

Exemplos (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"

Principais Recursos dos Prompts

  • Geração GraphQL à Prova de Falhas: Consultas completas e validadas que nunca falham
  • Estratégias Inteligentes de Busca: Abordagens automáticas de fallback para encontrar dados relevantes
  • Resultados Abrangentes: Itens de evidência incluem descrições clínicas; assertions fornecem resumos de alto nível
  • Filtragem Otimizada: O status padrão é "ALL" para evitar filtragem excessiva; parâmetros nulos são automaticamente excluídos
  • Geração Adequada de URLs: Links canônicos para verificação (evidência: /evidence/{id}, assertions: /assertions/{id})

Esses prompts fornecem consultas GraphQL completas com conformidade adequada ao esquema CIViC v2 e metodologias sistemáticas de busca que garantem a descoberta de dados mesmo quando os usuários fornecem parâmetros imperfeitos.

Exemplos de Consultas

Você pode fazer perguntas ao Claude como:

  • "Quais são os itens de evidência mais recentes para mutações BRAF?"
  • "Mostre-me todas as interpretações terapêuticas para variantes de câncer de pulmão"
  • "Encontre genes com mais itens de evidência no banco de dados CIViC"

O Claude usará o servidor (e sua ferramenta civic_graphql_query) para buscar os dados relevantes do banco de dados CIViC e apresentá-los a você. O servidor foi projetado para consultar a versão 2 da API CIViC, garantindo que você obtenha informações atualizadas.

Se você encontrar problemas ou o Claude não parecer estar usando os dados CIViC, verifique novamente as etapas de configuração acima.

Manipulação de Respostas

O servidor otimiza inteligentemente o uso de contexto armazenando resultados grandes em um banco de dados SQLite temporário. Quando as respostas GraphQL atendem a certos critérios, a resposta bruta é retornada diretamente em vez de criar um banco de dados:

  • Respostas pequenas (< 1500 caracteres): Retornadas diretamente para evitar sobrecarga desnecessária
  • Respostas de erro: Passadas diretamente para facilitar a solução de problemas
  • Respostas vazias/nulas: Ignoradas para evitar a criação de bancos de dados vazios
  • Consultas de introspecção de esquema: Consultas contendo __schema, __type ou outros padrões de introspecção são retornadas diretamente, pois contêm metadados em vez de dados adequados para conversão SQL

Essa otimização torna o servidor mais eficiente e fornece melhor visibilidade de erros, ao mesmo tempo que permite análise poderosa baseada em SQL para conjuntos de dados substanciais.

Licença

Licença MIT com Requisito de Citação Acadêmica - consulte LICENSE.md