OpenGenes

opengenes-mcp

Servidor MCP (Model Context Protocol) para o banco de dados OpenGenes

Este servidor implementa o Model Context Protocol (MCP) para o OpenGenes, fornecendo uma interface padronizada para acesso a dados de pesquisa sobre envelhecimento e longevidade. O MCP permite que assistentes de IA e agentes consultem conjuntos de dados biomédicos abrangentes por meio de interfaces estruturadas.

O servidor baixa automaticamente o banco de dados e a documentação mais recentes do OpenGenes do Hugging Face Hub (especificamente da pasta opengenes), garantindo que você sempre tenha acesso aos dados mais atualizados sem gerenciamento manual de arquivos.

O banco de dados OpenGenes contém:

• lifespan_change: Dados experimentais sobre intervenções genéticas e seus efeitos na longevidade em organismos modelo
• gene_criteria: Classificações de critérios para genes relacionados ao envelhecimento (12 categorias diferentes)
• gene_hallmarks: Marcadores do envelhecimento associados a genes específicos
• longevity_associations: Variantes genéticas associadas à longevidade a partir de estudos populacionais

Se você quiser entender mais sobre o que é o Model Context Protocol e como usá-lo de forma mais eficiente, você pode fazer o Curso de IA do DeepLearning ou pesquisar vídeos sobre MCP no YouTube.

🏆 Parte do Holy Bio MCP Framework

Este servidor MCP faz parte do projeto Holy Bio MCP - um framework unificado para pesquisa em bioinformática que venceu o Bio x AI Hackathon 2025 e continua sendo ativamente desenvolvido e expandido após a vitória.

O framework Holy Bio MCP reúne vários servidores MCP especializados em um ecossistema coeso para pesquisa biológica avançada:

• gget-mcp - Kit de ferramentas para genômica e análise de sequências
• opengenes-mcp - Genética do envelhecimento e longevidade (este servidor)
• synergy-age-mcp - Interações genéticas sinérgicas na longevidade
• biothings-mcp - Dados biológicos fundamentais do BioThings.io
• pharmacology-mcp - Dados de fármacos, alvos e ligantes

Juntos, esses servidores fornecem mais de 50 funções especializadas de bioinformática que podem trabalhar de forma integrada em fluxos de pesquisa orientados por IA. Saiba mais sobre o framework completo em github.com/longevity-genie/holy-bio-mcp.

Exemplo de Uso

Veja como o servidor MCP OpenGenes funciona na prática com assistentes de IA:

Exemplo mostrando como consultar o banco de dados OpenGenes por meio de um assistente de IA usando linguagem natural, que é traduzida em consultas SQL via servidor MCP. Você pode usar este banco de dados tanto em interfaces de chat para perguntas de pesquisa quanto em ferramentas de desenvolvimento baseadas em IA (como Cursor, Windsurf, VS Code com Copilot) para melhorar significativamente sua produtividade em bioinformática, tendo acesso direto a dados de pesquisa sobre envelhecimento e longevidade enquanto codifica.

Sobre MCP (Model Context Protocol)

MCP é um protocolo que preenche a lacuna entre sistemas de IA e conhecimento especializado de domínio. Ele permite:

• Acesso Estruturado: Conexão direta com dados autoritativos de pesquisa sobre envelhecimento e longevidade
• Consultas em Linguagem Natural: Interação simplificada com bancos de dados especializados via SQL
• Segurança de Tipos: Tipagem forte e validação via FastMCP
• Integração com IA: Integração perfeita com assistentes e agentes de IA

Fonte de Dados e Atualizações

O servidor MCP OpenGenes baixa automaticamente dados do repositório longevity-genie/bio-mcp-data no Hugging Face Hub. Isso garante:

• Sempre Atualizado: Acesso automático ao banco de dados OpenGenes mais recente sem atualizações manuais
• Distribuição Confiável: Hospedagem centralizada de dados com controle de versão e rastreamento de alterações
• Cache Eficiente: Arquivos baixados são armazenados em cache localmente para minimizar solicitações de rede
• Suporte a Fallback: Arquivos de fallback locais são suportados para desenvolvimento e uso offline

Os arquivos de dados são armazenados na subpasta opengenes do repositório Hugging Face e incluem:

• open_genes.sqlite - O banco de dados OpenGenes completo
• prompt.txt - Documentação do esquema do banco de dados e diretrizes de uso

Ferramentas Disponíveis

Este servidor fornece três ferramentas principais para interagir com o banco de dados OpenGenes:

1. opengenes_db_query(sql: str) - Executar consultas SQL somente leitura no banco de dados OpenGenes
2. opengenes_get_schema_info() - Obter informações detalhadas do esquema, incluindo tabelas, colunas e enumerações
3. opengenes_example_queries() - Obter uma lista de consultas SQL de exemplo com descrições

Recursos Disponíveis

1. resource://db-prompt - Documentação completa do esquema do banco de dados e diretrizes de uso
2. resource://schema-summary - Resumo formatado das tabelas e suas finalidades

Início Rápido

Instalando uv

# Download and install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify installation
uv --version
uvx --version

uvx é uma ferramenta muito útil que pode executar um pacote Python instalando-o se necessário.

Executando com uvx

Você pode executar o servidor opengenes-mcp diretamente usando uvx sem clonar o repositório:

# Run the server in streamed http mode (default)
uvx opengenes-mcp

# Or explicitly specify stdio mode
uvx opengenes-mcp stdio

# Run the server in streamable HTTP mode on default (3001) port
uvx opengenes-mcp server

# Run on a specific port
uvx opengenes-mcp server --port 8000

# Run the server in SSE mode
uvx opengenes-mcp sse

Em casos em que há problemas com uvx, eles geralmente podem ser causados pela limpeza do cache do uv:

uv cache clean

O modo HTTP iniciará um servidor web que você pode acessar em http://localhost:3001/mcp (com documentação em http://localhost:3001/docs). O modo STDIO é projetado para clientes MCP que se comunicam via entrada/saída padrão, enquanto o modo SSE usa Server-Sent Events para comunicação em tempo real.

Nota: Atualmente, não temos uma interface Swagger/OpenAPI, então acessar o servidor diretamente no seu navegador não mostrará muitas informações úteis. Para explorar as ferramentas e capacidades disponíveis, você deve usar o MCP Inspector (veja abaixo) ou conectar-se por meio de um cliente MCP para ver as ferramentas disponíveis.

Configurando seu Cliente de IA (Anthropic Claude Desktop, Cursor, Windsurf, etc.)

Exemplo Rápido de Configuração

Aqui está o que você pode copiar diretamente para a configuração MCP do seu Claude Desktop ou Cursor:

{
  "mcpServers": {
    "opengenes-mcp": {
      "command": "uvx",
      "args": ["opengenes-mcp"],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Alternativa: Usando Arquivos Pré-configurados

Também fornecemos arquivos JSON pré-configurados para diferentes casos de uso:

• Para modo STDIO (recomendado): Use mcp-config-stdio.json
• Para modo HTTP: Use mcp-config.json
• Para desenvolvimento local: Use mcp-config-stdio-debug.json

Tutorial em Vídeo de Configuração

Para um guia visual sobre como configurar servidores MCP com clientes de IA, confira nosso vídeo tutorial de configuração para nosso servidor MCP irmão (biothings-mcp). Os princípios de configuração são exatamente os mesmos para o servidor MCP OpenGenes - basta usar os arquivos de configuração JSON apropriados fornecidos acima.

Inspecionando o servidor MCP OpenGenes

npx @modelcontextprotocol/inspector --config mcp-config-stdio.json --server opengenes-mcp

npx @modelcontextprotocol/inspector --config mcp-config.json --server opengenes-mcp

npx @modelcontextprotocol/inspector --config mcp-config-stdio-debug.json --server opengenes-mcp

npx @modelcontextprotocol/inspector

Integração com Sistemas de IA

Basta apontar seu cliente de IA (como Cursor, Windsurf, ClaudeDesktop, VS Code com Copilot, ou outros) para usar o arquivo de configuração apropriado do repositório.

Configuração do Repositório

# Clone the repository
git clone https://github.com/longevity-genie/opengenes-mcp.git
cd opengenes-mcp
uv sync

Executando o Servidor MCP

Se você já clonou o repositório, pode executar o servidor com uv:

# Start the MCP server locally (HTTP mode)
uv run server

# Or start in STDIO mode  
uv run stdio

# Or start in SSE mode
uv run sse

Esquema do Banco de Dados

Consultas de Exemplo

-- Get top genes with most lifespan experiments
SELECT HGNC, COUNT(*) as experiment_count 
FROM lifespan_change 
WHERE HGNC IS NOT NULL 
GROUP BY HGNC 
ORDER BY experiment_count DESC 
LIMIT 10;

-- Find genes that increase lifespan in mice
SELECT DISTINCT HGNC, effect_on_lifespan 
FROM lifespan_change 
WHERE model_organism = 'mouse' 
AND effect_on_lifespan = 'increases lifespan' 
AND HGNC IS NOT NULL;

-- Get hallmarks of aging for genes
SELECT HGNC, "hallmarks of aging" 
FROM gene_hallmarks 
WHERE "hallmarks of aging" LIKE '%mitochondrial%';

-- Find longevity associations by ethnicity
SELECT HGNC, "polymorphism type", "nucleotide substitution", ethnicity 
FROM longevity_associations 
WHERE ethnicity LIKE '%Italian%';

-- Find genes with both lifespan effects and longevity associations
SELECT DISTINCT lc.HGNC 
FROM lifespan_change lc 
INNER JOIN longevity_associations la ON lc.HGNC = la.HGNC 
WHERE lc.HGNC IS NOT NULL;

Recursos de Segurança

• Acesso somente leitura: Apenas consultas SELECT são permitidas
• Validação de entrada: Bloqueia operações INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE
• Tratamento de erros: Tratamento abrangente de erros com mensagens informativas

Testes e Verificação

O servidor MCP é fornecido com testes abrangentes, incluindo testes LLM-como-juiz que avaliam a qualidade das respostas a consultas complexas. No entanto, os testes baseados em LLM são desabilitados por padrão no CI para economizar custos.

Configuração do Ambiente para Testes de Agente LLM

Se você quiser executar testes de agente LLM que usam funções MCP com modelos Gemini, você precisa configurar um arquivo .env com sua chave de API Gemini:

# Create a .env file in the project root
echo "GEMINI_API_KEY=your-gemini-api-key-here" > .env

Nota: O arquivo .env e a chave de API Gemini são necessários apenas para executar testes de agente LLM. Todos os outros testes e a funcionalidade básica do servidor MCP funcionam sem nenhuma chave de API.

Executando Testes

Execute testes para o servidor MCP:

uv run pytest -vvv -s

Você também pode executar testes manuais:

uv run python test/manual_test_questions.py

Você pode usar o MCP inspector com o servidor MCP construído localmente da mesma forma que com uvx.

Nota: Usar o MCP Inspector é opcional. A maioria dos clientes MCP (como Cursor, Windsurf, etc.) exibirá automaticamente as ferramentas disponíveis deste servidor uma vez configurado. No entanto, o Inspector pode ser útil para testes detalhados e exploração.

Se você escolher usar o Inspector via npx, certifique-se de ter Node.js e npm instalados. Usar nvm (Node Version Manager) é recomendado para gerenciar versões do Node.js.

Exemplos de perguntas que o MCP ajuda a responder

Contribuindo

Aceitamos contribuições da comunidade! 🎉 Seja você pesquisador, desenvolvedor ou entusiasta interessado em pesquisa sobre envelhecimento e longevidade, há muitas maneiras de se envolver:

Encorajamos especialmente você a experimentar nosso servidor MCP e compartilhar seu feedback conosco! Sua experiência usando o servidor, quaisquer problemas que encontrar e sugestões de melhoria são incrivelmente valiosas para tornar esta ferramenta melhor para toda a comunidade de pesquisa.

Maneiras de Contribuir

• 🐛 Relatórios de Bugs: Encontrou um problema? Abra uma issue no GitHub com informações detalhadas
• 💡 Solicitações de Recursos: Tem ideias para novas funcionalidades? Adoraríamos ouvi-las!
• 📝 Documentação: Ajude a melhorar nossa documentação, exemplos ou tutoriais
• 🧪 Testes: Adicione casos de teste, especialmente para casos extremos ou novos padrões de consulta
• 🔍 Qualidade de Dados: Ajude a identificar e relatar inconsistências de dados ou sugerir melhorias
• 🚀 Desempenho: Otimize consultas, melhore o cache ou aprimore o desempenho do servidor
• 🌐 Integração: Crie exemplos para novos clientes MCP ou sistemas de IA
• 🎥 Tutoriais e Vídeos: Crie tutoriais, guias em vídeo ou conteúdo educacional mostrando como usar servidores MCP
• 📖 Histórias de Usuários: Compartilhe seus fluxos de trabalho de pesquisa e histórias de sucesso usando nossos servidores MCP
• 🤝 Alcance Comunitário: Ajude-nos a promover a adoção de MCP na comunidade de bioinformática

Tutoriais, vídeos e histórias de usuários são especialmente valiosos para nós! Estamos trabalhando para impulsionar a comunidade de bioinformática em direção à adoção de IA, e exemplos do mundo real de como pesquisadores usam nossos servidores MCP (este e outros que desenvolvemos) ajudam a demonstrar os benefícios práticos e incentivam uma adoção mais ampla.

Começando

1. Faça um fork do repositório
2. Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
3. Faça suas alterações e adicione testes
4. Execute a suíte de testes (uv run pytest)
5. Faça commit das suas alterações (git commit -m 'Add amazing feature')
6. Envie para o seu branch (git push origin feature/amazing-feature)
7. Abra um Pull Request

Diretrizes de Desenvolvimento

• Siga o estilo de código existente (usamos black para formatação)
• Adicione testes para novas funcionalidades
• Atualize a documentação conforme necessário
• Mantenha os commits focados e escreva mensagens de commit claras

Perguntas ou Ideias?

Não hesite em abrir uma issue para discussão! Somos amigáveis e sempre felizes em ajudar iniciantes a começar. Suas contribuições ajudam a avançar a ciência aberta e a pesquisa sobre longevidade para todos. 🧬✨

Problemas Conhecidos

Cobertura do Banco de Dados

Atualmente, este servidor MCP usa apenas um subconjunto do banco de dados completo do OpenGenes. O banco de dados completo do OpenGenes contém tabelas e dados adicionais que ainda não estão incluídos em nossa implementação MCP. Precisamos de contribuidores para ajudar a estender o suporte ao banco de dados completo! Se você está interessado em ajudar a expandir a cobertura do banco de dados, consulte nossa seção Contribuindo.

Cobertura de Testes

Embora forneçamos testes abrangentes, incluindo avaliações LLM-como-juiz, nem todos os casos de teste foram verificados manualmente contra a interface web real do OpenGenes. Alguns resultados de testes automatizados podem precisar de validação manual para garantir precisão. Contribuições para melhorar a cobertura de testes e validação são bem-vindas.

Licença

Este projeto é licenciado sob a Licença MIT.

Agradecimentos

• Banco de Dados OpenGenes pelos dados abrangentes de pesquisa sobre envelhecimento
  • Rafikova E, Nemirovich-Danchenko N, Ogmen A, Parfenenkova A, Velikanova A, Tikhonov S, Peshkin L, Rafikov K, Spiridonova O, Belova Y, Glinin T, Egorova A, Batin M. Open Genes-a new comprehensive database of human genes associated with aging and longevity. Nucleic Acids Res. 2024 Jan 5;52(D1):D950-D962. doi: 10.1093/nar/gkad712. PMID: 37665017; PMCID: PMC10768108.
• Model Context Protocol pela especificação do protocolo
• FastMCP pelo framework do servidor MCP

Este projeto faz parte da organização Longevity Genie, que desenvolve assistentes de IA e bibliotecas de código aberto para pesquisa em saúde, genética e longevidade.

Outros Servidores MCP no Framework Holy Bio MCP

Este servidor faz parte do framework completo Holy Bio MCP, que inclui:

• gget-mcp - Kit de ferramentas poderoso de bioinformática para consultas e análises genômicas
• synergy-age-mcp - Banco de dados de interações genéticas sinérgicas e antagônicas em longevidade
• biothings-mcp - Acesso às APIs do BioThings.io para dados abrangentes de genes, variantes, produtos químicos e taxonômicos
• pharmacology-mcp - Acesso ao banco de dados Guide to PHARMACOLOGY para informações sobre drogas, alvos e ligantes

O framework fornece arquivos de configuração unificados que habilitam todos os servidores de uma vez, facilitando o acesso a mais de 50 funções especializadas de bioinformática através de uma única configuração. Este projeto premiado continua evoluindo como uma plataforma abrangente para pesquisa biológica impulsionada por IA.

Somos apoiados por:

HEALES - Healthy Life Extension Society

e

IBIMA - Institute for Biostatistics and Informatics in Medicine and Ageing Research