mcp-github-explorer-server — PoC de Agente de IA com MCP

Servidor MCP (Model Context Protocol) que expõe dados públicos do GitHub como ferramentas que qualquer agente de IA compatível com MCP pode descobrir e invocar dinamicamente — sem nenhuma integração hardcoded.

Este documento é o mini-tutorial de reprodução: qualquer colega da turma consegue rodar esta PoC do zero em ~10 minutos.

1. O que esta PoC demonstra

• Como um MCP Server anuncia suas capacidades (tools) a um host de IA.

• Como o host descobre essas ferramentas (tools/list) e as invoca (tools/call) via JSON-RPC 2.0 sobre o transporte stdio.

• Como o modelo decide sozinho, a partir da linguagem natural do usuário, quais ferramentas chamar e com quais parâmetros — sem o desenvolvedor escrever nenhum "if/else" de roteamento de intenção.

Quatro ferramentas expostas:

A quarta tool é o elo entre os três blocos do tutorial: ela faz a etapa de recuperação do RAG (busca por palavra-chave nos arquivos em corpus/) e devolve os trechos mais relevantes para o host — é o modelo do lado do host (Claude) quem lê esses trechos e gera a resposta final. Ou seja, a tool nunca chama nenhum LLM internamente; ela só recupera. Isso é uma demonstração ao vivo de RAG agentic: em vez de um pipeline fixo, a recuperação é uma decisão que o próprio agente toma durante a conversa.

Related MCP server: github-mcp

2. Pré-requisitos

• Node.js 18 ou superior (node --version)

• Um host MCP para testar. Recomendamos dois caminhos, do mais simples ao mais completo:

  • MCP Inspector (não exige instalar nada além do Node — ótimo para validar rápido)

  • Claude Desktop ou Claude Code (para a demonstração "de verdade", com o modelo decidindo quando chamar as tools)

3. Instalação e build

# dentro da pasta do projeto
npm install
npm run build

Isso compila src/index.ts (TypeScript) para build/index.js (JavaScript), que é o arquivo que qualquer host vai executar como subprocesso.

4. Teste rápido com o MCP Inspector (sem precisar do Claude Desktop)

npm run inspect

Isso abre uma interface web local onde dá pra ver as 4 tools registradas, chamar cada uma manualmente (ex: get_github_profile com username: torvalds) e inspecionar a troca de mensagens JSON-RPC em tempo real. É o jeito mais rápido de provar pro professor/turma que o protocolo está funcionando, mesmo sem um modelo de IA no meio.

Nota sobre rate limit: a API pública do GitHub sem autenticação permite 60 requisições/hora por IP. Se aparecer esse erro, é isso — normal em redes compartilhadas (ex: Wi-Fi da faculdade), não é bug. Na sua máquina pessoal costuma funcionar sem problema. A tool ask_knowledge_base não é afetada por isso — ela não faz nenhuma chamada de rede, então funciona mesmo sem internet.

Bônus didático: o arquivo test-client.mjs na raiz do projeto é um cliente MCP mínimo, escrito à mão (sem SDK de cliente), que faz o handshake initialize → tools/list → tools/call e imprime as mensagens JSON-RPC cruas. Rode com node test-client.mjs para mostrar na apresentação exatamente o que trafega "por baixo do capô" do protocolo, sem a camada visual do Inspector.

5. Conectando ao Claude Desktop

1. Abra o arquivo de configuração do Claude Desktop:

   • Linux: ~/.config/Claude/claude_desktop_config.json

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Adicione (use o caminho absoluto do build/index.js compilado):

{
  "mcpServers": {
    "github-explorer": {
      "command": "node",
      "args": ["/caminho/absoluto/para/mcp-github-poc/build/index.js"]
    }
  }
}

3. Feche o Claude Desktop completamente (não só a janela) e reabra.

4. Verifique o ícone de ferramentas (martelo 🔨) na caixa de mensagem — ele confirma que pelo menos um MCP server está ativo.

5. Teste com um prompt em linguagem natural, por exemplo:

   "Usa o github-explorer pra ver o perfil do usuário torvalds e me diz quais são as 3 linguagens que ele mais usa."

   O modelo vai decidir sozinho chamar get_github_profile e depois get_language_stats — essa decisão automática é o ponto central da demonstração.

6. Para demonstrar a tool de RAG, pergunte algo como:

   "Usa a base de conhecimento pra me explicar o que é RAG agentic e como isso se conecta com MCP."

   O modelo vai chamar ask_knowledge_base, receber os trechos mais relevantes (recuperados via BM25, sem nenhuma chamada de rede) e sintetizar a resposta final usando esse contexto — a etapa de geração acontece inteiramente do lado do host, não dentro do servidor.

6. Alternativa: conectando ao Claude Code (CLI)

claude mcp add github-explorer -- node /caminho/absoluto/para/mcp-github-poc/build/index.js
claude mcp list        # confirma que o servidor foi registrado

Dentro de uma sessão do Claude Code, use /mcp para checar o status da conexão a qualquer momento.

7. Estrutura do projeto

mcp-github-poc/
├── src/
│   ├── index.ts     # servidor MCP: registra as 4 tools
│   └── rag.ts        # indexação e busca BM25 (a etapa de recuperação do RAG)
├── corpus/            # base de conhecimento (markdown) indexada pelo rag.ts
│   ├── agentes.md
│   ├── mcp.md
│   └── rag.md
├── build/             # gerado pelo `npm run build`
├── package.json
├── tsconfig.json
├── test-client.mjs    # cliente MCP mínimo p/ testar via terminal
└── README.md          # este arquivo

8. Possíveis extensões (para quem quiser ir além)

• Trocar o transporte stdio por Streamable HTTP, permitindo que o servidor rode remotamente e sirva vários clientes ao mesmo tempo.

• Adicionar um Resource (ex: expor o README.md de um repo como contexto navegável, em vez de só uma tool).

• Adicionar autenticação via GITHUB_TOKEN para elevar o rate limit de 60 para 5.000 requisições/hora.

• Trocar a recuperação BM25 (esparsa) por embeddings (densa) — ex: gerar vetores com um modelo local ou via API e comparar por similaridade de cosseno — ou combinar as duas em uma busca híbrida, como no projeto rag-docs-api.

• Adicionar mais documentos ao corpus/ e observar como o BM25 se comporta com uma base maior (é o momento de discutir os limites da recuperação puramente léxica, sem sinônimos).