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.

Três ferramentas expostas:

Tool	O que faz
get_github_profile	Retorna dados públicos de um usuário/organização do GitHub
list_top_repos	Lista os repositórios mais estrelados de um usuário
get_language_stats	Calcula a distribuição de linguagens usadas pelo usuário

---

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

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. 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     # código-fonte do servidor MCP (comentado)
├── build/            # gerado pelo `npm run build`
├── package.json
├── tsconfig.json
└── 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.