gget-mcp

👤 Usuário: "Analise o gene TP53 - encontre seus detalhes e sequência de proteína, depois verifique mutações de câncer"

🤖 Assistente de IA: Vou ajudá-lo a analisar o TP53 passo a passo:

[Usa gget_search] → Encontrou TP53 (ENSG00000141510) no cromossomo 17
[Usa gget_info] → TP53 é um gene supressor de tumor codificador de proteínas
[Usa gget_seq com translate=True] → Recuperou sequência de proteína de 393 aminoácidos
[Usa gget_cosmic] → Encontrou mutações hotspot R175H, R248Q, R273H em múltiplos cânceres

👤 Usuário: "Agora prediga a estrutura 3D desta sequência de proteína: MSKGEELFTGVVPILVEL..."

🤖 Assistente de IA: Deixe-me analisar esta sequência:

[Usa gget_blast] → Identificada como Green Fluorescent Protein (GFP)
[Usa gget_alphafold] → Predita estrutura clássica de barril beta com confiança de 90%+

👤 Usuário: "Realize enriquecimento de vias para genes de reparo de DNA: TP53, BRCA1, BRCA2, ATM"

🤖 Assistente de IA: [Usa gget_enrichr] → Principais vias: Resposta a Danos no DNA, Recombinação Homóloga, Checkpoints do Ciclo Celular, Sinalização p53

Viu como isso é poderoso? Agora você pode fazer perguntas em linguagem natural sobre genes, sequências, mutações e vias - a IA faz o trabalho complexo de bioinformática para você!

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

• Acesso Estruturado: Conexão direta com ferramentas e bancos de dados de bioinformática
• Consultas em Linguagem Natural: Interação simplificada com fluxos de trabalho genômicos complexos
• Segurança de Tipos: Tipagem forte e validação através do FastMCP
• Integração com IA: Integração perfeita com assistentes e agentes de IA

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 DeepLearning AI ou pesquisar vídeos sobre MCP no YouTube.

Informação de Genes e Busca

• gget_search: Encontre IDs Ensembl associados a termos de busca
• gget_info: Obtenha informações detalhadas para IDs Ensembl
• gget_seq: Recupere sequências de nucleotídeos ou aminoácidos
• gget_ref: Obtenha informações do genoma de referência do Ensembl

Análise de Sequências

• gget_blast: BLAST de sequências de nucleotídeos ou aminoácidos
• gget_blat: Encontre localizações genômicas de sequências
• gget_muscle: Alinhe múltiplas sequências

Análise de Expressão e Funcional

• gget_archs4: Obtenha dados de expressão gênica do ARCHS4
• gget_enrichr: Realize análise de enriquecimento de conjuntos de genes

Estrutura e Função de Proteínas

• gget_pdb: Obtenha dados de estrutura de proteínas do PDB
• gget_alphafold: Prediga estrutura de proteínas usando AlphaFold

Análise de Câncer e Mutações

• gget_cosmic: Pesquise no banco de dados COSMIC por mutações de câncer

Análise de Célula Única

• gget_cellxgene: Consulte dados de RNA-seq de célula única do CellxGene

# 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.

Modo STDIO (para clientes MCP que exigem stdio)

# Run the server in stdio mode
uvx gget-mcp stdio

Modo HTTP (Servidor Web)

# Run the server in streamable HTTP mode on default (3002) port
uvx gget-mcp http

# Run on a specific port
uvx gget-mcp http --port 8000

Modo SSE (Server-Sent Events)

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

Se você quiser inspecionar os métodos fornecidos pelo servidor MCP, use npx (você pode precisar instalar nodejs e npm):

Para o modo STDIO com uvx:

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

Você também pode executar o inspector manualmente e configurá-lo através da interface:

npx @modelcontextprotocol/inspector

Depois disso, você pode explorar as ferramentas e recursos com o MCP Inspector, que geralmente está na porta 6274 (nota: se você executar o inspector várias vezes, a porta pode mudar)

Visão Geral

Este guia o orientará na configuração do Claude Desktop com a extensão gget_mcp e integração com Google Drive no Windows. Ao final, você poderá usar o Claude para buscar dados biológicos (como sequências de genes) e salvá-los diretamente na sua pasta do Google Drive com acesso offline.

Pré-requisitos

• PC com Windows e acesso de administrador
• Conta do Google
• Conexão de internet estável

Passo 1: Configurar o Google Drive para Desktop com Acesso Offline

1. Baixe e instale o Google Drive para Desktop

2. Inicie o aplicativo e faça login com sua conta de usuário

3. Conecte a conta Google compartilhada do seu projeto (se aplicável)

4. Configure o acesso offline para sua pasta de trabalho:

   • Navegue até a pasta com a qual deseja trabalhar no Google Drive
   • Clique com o botão direito na pasta (por exemplo, "work" ou sua pasta de projeto)
   • Selecione "Disponível offline" no menu de contexto
   • Isso torna a pasta acessível em um caminho como C:\GDrive\holy-bio-mcp\My Disk\work

   Importante: Isso é diferente de apenas sincronizar - o acesso offline garante que os arquivos estejam disponíveis localmente enquanto ainda fazem parte da sua estrutura do Google Drive.

Passo 2: Instalar o Claude Desktop

1. Baixe o Claude Desktop para Windows
2. Execute o instalador e siga o assistente de configuração
3. Faça login com sua conta Anthropic/Claude
4. Complete a configuração inicial

Passo 3: Instalar o Gerenciador de Pacotes uv

1. Instale o uv usando um destes métodos:

   Opção A: Usando winstall

   • Visite https://winstall.app/apps/astral-sh.uv
   • Siga as instruções de instalação

   Opção B: Usando PowerShell

   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   

2. Reinicie seu terminal após a instalação

Passo 4: Instalar o Node.js

Você pode instalar o Node.js usando qualquer um dos métodos:

Opção A: Instalador Nativo

1. Visite https://nodejs.org/en/download
2. Baixe o instalador do Windows (versão LTS recomendada)
3. Execute o instalador com as configurações padrão

Opção B: Usando Chocolatey

choco install nodejs

Ambos os métodos funcionam igualmente bem - escolha o que preferir.

Passo 5: Verificar a Instalação e Cache de Pacotes

Abra o Prompt de Comando ou PowerShell e execute:

uvx --from gget-mcp@latest stdio

Comportamento esperado:

• O comando deve iniciar sem erros
• Os pacotes serão baixados e armazenados em cache
• Se for executado com sucesso, tudo está configurado corretamente
• Você pode pressionar Ctrl+C para interrompê-lo

Passo 6: Configurar o Claude Desktop

6.1: Habilitar a Extensão Filesystem

1. Abra o Claude Desktop
2. Vá para Configurações (ícone de engrenagem)
3. Navegue até a aba "Extensions" na barra lateral esquerda
4. Habilite a extensão Filesystem
5. Adicione sua pasta offline do Google Drive aos diretórios permitidos (por exemplo, C:\GDrive\holy-bio-mcp\My Disk\work)

Nota: A extensão Filesystem está integrada ao Claude Desktop e usa MCP internamente, mas é gerenciada diretamente pelo aplicativo. Você não precisa configurá-la no arquivo JSON.

6.2: Adicionar o Servidor gget_mcp

1. Da mesma forma, vá para Configurações, navegue até a aba "Developer" na barra lateral esquerda
2. Na aba de configurações Developer, clique no botão "Edit Config"
3. Isso abrirá o arquivo claude_desktop_config.json
4. Edite-o e adicione a configuração do servidor gget_mcp:

{
  "mcpServers": {
    "gget": {
      "command": "uvx",
      "args": [
        "--from",
        "gget-mcp@latest",
        "stdio"
      ]
    }
  }
}

5. Salve o arquivo de configuração

Passo 7: Reiniciar o Claude Desktop

1. Feche completamente o Claude Desktop (verifique a bandeja do sistema)
2. Reinicie o aplicativo
3. Nota: No primeiro início, você pode experimentar um timeout - isso é normal
4. Se necessário, reinicie o Claude Desktop uma segunda vez

Passo 8: Verificar se as Extensões Estão Ativas

1. Abra as Configurações do Claude Desktop
2. Vá para a aba Developer
3. Confirme que ambos os componentes estão habilitados:
   • ✅ Filesystem Extension - deve mostrar seu caminho configurado do Google Drive e status "Running"
   • ✅ gget MCP Server - deve mostrar status "Running"

Passo 9: Testar a Configuração

Agora vamos verificar se tudo funciona! No Claude Desktop, crie um novo chat. Clique no ícone "Search and tools", selecione e habilite tanto gget_mcp quanto filesystem

Tente este prompt:

Please search for the COL1A1 gene, retrieve its protein sequence, 
and save it to C:\GDrive\holy-bio-mcp\My Disk\work\test_sequences\ as a FASTA file.

Resultado esperado:

• Claude usará gget_mcp para buscar o gene
• Ele buscará os dados da sequência
• Ele salvará o arquivo na sua pasta especificada
• O arquivo será sincronizado com o Google Drive automaticamente
• Claude poderá lê-lo usando a Filesystem Extension.

Solução de Problemas

Servidor MCP Não Conectando

• Certifique-se de que uv e node estão no PATH do seu sistema
• Tente executar o comando de verificação novamente do Passo 5
• Reinicie o Claude Desktop completamente

Erros de Permissão do Filesystem

• Verifique se a Extensão do Filesystem tem acesso à sua pasta do Google Drive
• Confirme que a pasta tem acesso offline habilitado no Google Drive
• Tente executar o Claude Desktop como administrador
• Garanta que o caminho está correto (use o caminho exato mostrado no File Explorer)

Tempo Limite no Primeiro Início

• Isso é normal - basta reiniciar o Claude Desktop
• Aguarde 10-15 segundos antes de fazer solicitações

Comandos gget Não Funcionando

• Garanta que a conexão com a internet esteja estável (o gget busca em bancos de dados online)
• Verifique se o servidor gget_mcp aparece como "Ativo" nas configurações
• Tente o comando de verificação da Etapa 5 novamente

Problemas de Acesso Offline no Google Drive

• Confirme que a pasta mostra uma marca de verificação verde no Google Drive para Desktop
• Se os arquivos não estiverem sincronizando, clique com o botão direito na pasta e reative "Disponível offline"
• Verifique se você tem espaço em disco local suficiente para arquivos offline

Sucesso! 🎉

Se tudo funcionar corretamente, agora você tem:

• ✅ Claude Desktop com recursos MCP
• ✅ Acesso a bancos de dados biológicos via gget_mcp
• ✅ Operações diretas de arquivos na sua pasta offline do Google Drive
• ✅ Sincronização automática em nuvem de todos os resultados

Agora você pode pedir ao Claude para buscar sequências de genes, dados de proteínas, realizar buscas BLAST e salvar tudo diretamente na sua pasta do Google Drive com acesso offline!

Exemplos de Casos de Uso

• Buscar sequências de genes: "Obtenha a sequência de DNA do BRCA1 e salve no meu Drive"
• Análise de proteínas: "Encontre a sequência de proteína do TP53 e crie um relatório em markdown"
• Operações em lote: "Pesquise todos os genes relacionados à apoptose e crie uma tabela resumo"
• Referência cruzada: "Obtenha informações sobre COL1A1 do Ensembl e UniProt"

Recursos Adicionais

• Documentação do gget
• Documentação do Model Context Protocol
• Suporte do Claude Desktop

Guia atualizado: 13 de outubro de 2025

# Clone the repository
git clone https://github.com/longevity-genie/gget-mcp.git
cd gget-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

O servidor MCP é fornecido com testes abrangentes, incluindo testes unitários e testes de integração para operações dependentes de rede.

Executando Testes

Execute testes para o servidor MCP:

# Run all tests (excluding expensive judge tests)
uv run pytest -vvv -m "not judge"

# Run only fast tests (skip slow, integration, and judge tests)
uv run pytest -vvv -m "not slow and not integration and not judge"

# Run only integration tests
uv run pytest -vvv -m integration

# Run judge tests (expensive LLM tests - requires API keys and may cost money)
uv run pytest test/test_judge.py -vvv

# Run tests with coverage (excluding judge tests)
uv run pytest -vvv --cov=src/gget_mcp --cov-report=term-missing -m "not judge"

Nota sobre Testes de Avaliação: Os testes de avaliação (test_judge.py) usam modelos de linguagem grandes para avaliar o desempenho do agente de IA com as ferramentas do gget. Esses testes:

• São automaticamente excluídos do CI/CD para evitar custos
• Exigem chaves de API (GEMINI_API_KEY ou similar)
• Podem gerar cobranças dos provedores de API de LLM
• São projetados para desenvolvimento local e avaliação manual
• Fornecem insights valiosos sobre como as ferramentas funcionam com agentes de IA

Fluxos de Trabalho do GitHub Actions

Este projeto inclui vários fluxos de trabalho do GitHub Actions:

• CI (.github/workflows/ci.yml): Executa em cada push/PR com linting básico e testes rápidos
• Testes (.github/workflows/test.yml): Testes abrangentes em vários sistemas operacionais e versões do Python
  • Testes rápidos em todas as plataformas
  • Testes de integração (podem exigir acesso à rede)
  • Testes lentos (como operações BLAST) - executam apenas no Ubuntu com Python 3.11
  • Relatórios de cobertura de código
  • Verificações de segurança com bandit e safety
• Publicação (.github/workflows/publish.yml): Publica no PyPI quando tags são enviadas

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

Dependências Externas

Algumas funções do gget dependem de serviços web externos e bancos de dados que podem ocasionalmente estar indisponíveis ou ter limite de taxa. O servidor implementa tratamento adequado de erros e tentativas quando apropriado.

Cobertura de Testes

Embora forneçamos testes abrangentes, incluindo testes de integração para operações dependentes de rede, alguns casos de teste podem ser sensíveis à disponibilidade de serviços externos. Alguns resultados de testes automatizados podem precisar de validação manual.