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

| 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 |
| `ask_knowledge_base` | **RAG**: busca (BM25, local/offline) nos materiais teóricos do tutorial sobre Agentes de IA, MCP e RAG |

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.

---

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

```bash
# 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)

```bash
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):

```json
{
  "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)

```bash
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).