Geo-Explorer

O que é o Geo-Explorer

Geo-Explorer é uma plataforma de estudos fictícia inspirada na DIO (Digital Innovation One). O projeto simula um sistema de trilhas de aprendizado com desafios de código e emissão de certificados.

Ele serve como base de estudo para:

• Desenvolvimento de ferramentas CLI em TypeScript
• Construção de um MCP Server que expõe a lógica da plataforma como ferramentas invocáveis por agentes de IA (Bob, Claude Desktop, Cursor etc.)
• Definição de slash commands locais no Bob para acionar as ferramentas diretamente no chat
• Prática de testes unitários com cobertura 100%

---

Estrutura do projeto

geo-explorer/
│
├── commands/               # Comandos CLI executáveis via npm run
│   ├── lib/
│   │   └── trilhas.ts      # Leitura de data/trilhas_dio.json e função findTrilha()
│   ├── trilha.ts           # /trilha <tecnologia>
│   ├── desafio.ts          # /desafio <tecnologia> [nivel]
│   └── certificado.ts      # /certificado --nome "<nome>" --tech "<tecnologia>" (flags) ou posicional
│
├── data/
│   └── trilhas_dio.json    # Base de dados com 35 trilhas DIO
│
├── mcp/                    # MCP Server (pacote independente)
│   ├── src/
│   │   └── index.ts        # Entry-point do servidor MCP (stdio transport)
│   ├── build/              # Saída compilada (gerada por npm run build, não versionada)
│   ├── package.json
│   ├── tsconfig.json
│   └── README.md           # Documentação específica do servidor MCP
│
├── tests/                  # Testes unitários (Vitest)
│   ├── trilha.test.ts
│   ├── desafio.test.ts
│   └── certificado.test.ts
│
├── .bob/
│   ├── commands/           # Slash commands locais do Bob
│   │   ├── trilha.md
│   │   ├── desafio.md
│   │   └── certificado.md
│   ├── mcp.example.json    # Template de registro do MCP Server (versionado)
│   └── mcp.json            # Configuração local do MCP Server (não versionada)
│
├── package.json
├── tsconfig.json
└── vitest.config.mts

---

Como executar

Pré-requisitos

• Node.js ≥ 18
• npm ≥ 9

Instalação

# Na raiz do projeto
npm install

# Para o servidor MCP (pacote separado)
cd mcp
npm install

Build (verificação de tipos)

# Raiz — verifica os tipos sem emitir arquivos
npm run build

# MCP Server — compila TypeScript para JavaScript em mcp/build/
cd mcp
npm run build

O build do servidor MCP precisa ser executado ao menos uma vez antes de registrá-lo.

---

Como usar os comandos

Os três comandos CLI são executados via npm run na raiz do projeto.

---

/trilha <tecnologia>

Exibe o plano de estudos completo de uma trilha a partir do nome (ou parte do nome) da tecnologia. A busca é case-insensitive e aceita correspondência parcial.

npm run trilha -- javascript

Saída:

╔══════════════════════════════════════════════════════╗
  🎯  PLANO DE ESTUDOS — JAVASCRIPT DEVELOPER
╚══════════════════════════════════════════════════════╝

  Tecnologia   : JavaScript
  Nível        : Básico
  Total de XP  : 12.000 XP
  Acesso       : Por período
  Promoção     : ✅ Disponível
  Lives ao vivo: 4

── MÓDULOS ──────────────────────────────────────────
  1. Fundamentos de JavaScript e ambiente de execução
  2. Tipos de dados, variáveis e operadores
  3. Estruturas de controle e funções
  4. Manipulação do DOM e eventos
  5. ES6+: arrow functions, promises e async/await
  6. Projeto final: aplicação web interativa

── BADGES DISPONÍVEIS ───────────────────────────────
  🏅 JS Fundamentals
  🏅 DOM Master
  🏅 ES6+ Hero

  Bons estudos! 🚀

---

/desafio <tecnologia> [nivel]

Gera um desafio de código aleatório. O parâmetro nivel é opcional; quando omitido, usa o nível registrado na trilha. Valores aceitos para nível: básico, intermediário, avançado (com ou sem acento, case-insensitive).

# Sem nível (usa o nível da trilha)
npm run desafio -- typescript

# Com nível explícito
npm run desafio -- python avançado

Saída (exemplo):

╔══════════════════════════════════════════════════════╗
  ⚔️   DESAFIO DE CÓDIGO — TYPESCRIPT
╚══════════════════════════════════════════════════════╝

  Nível      : Intermediário
  Trilha base: Formação TypeScript Fullstack

── ENUNCIADO ────────────────────────────────────────

  Implemente uma classe Stack (pilha) com os métodos push, pop, peek e isEmpty.

── CRITÉRIOS DE AVALIAÇÃO ───────────────────────────

  ✔  Código legível e bem estruturado
  ✔  Tratamento de casos extremos (edge cases)
  ✔  Complexidade de tempo e espaço adequada ao nível
  ✔  Testes mínimos demonstrando o funcionamento

  Boa sorte! 💪

---

/certificado

Emite um certificado fictício em Markdown. O ID do certificado é determinístico — gerado a partir do nome do estudante e do ID da trilha.

O comando aceita duas formas de passagem de argumentos:

# Forma recomendada — flags explícitas; cada flag coleta todos os tokens
# até a flag seguinte, então valores com espaços funcionam normalmente
npm run certificado -- --nome "Maria Silva" --tech "TypeScript"
npm run certificado -- --nome "Ana Lima" --tech "Data Science"

# Forma posicional — o primeiro argumento vira nome e o segundo vira tecnologia;
# aspas fazem o shell entregar cada valor como um único elemento de argv,
# então espaços dentro de cada valor funcionam normalmente
npm run certificado -- "Ana Lima" "TypeScript"
npm run certificado -- "Ana" "Data Science"

Na forma posicional o parser espera exatamente dois argumentos (argv[0] → nome, argv[1] → tecnologia). Use as flags --nome e --tech se preferir uma sintaxe mais explícita ou se quiser evitar depender das aspas do shell.

Saída (em Markdown):

# 🎓 CERTIFICADO DE CONCLUSÃO

---

**A Digital Innovation One certifica que**

## Maria Silva

**concluiu com êxito a trilha:**

# Formação TypeScript Fullstack

---

| Campo              | Detalhe                            |
|--------------------|------------------------------------|
| **Tecnologia**     | TypeScript                         |
| **Nível**          | Intermediário                      |
| **Módulos**        | 9 módulos concluídos               |
| **XP conquistado** | 22.000 XP                          |
| **Lives ao vivo**  | 6 aulas                            |
| **Emitido em**     | <data de hoje>                     |
| **Certificado ID** | `DIO-002-XXXXXXXX`                 |

---

### Badges conquistadas

- 🏅 TS Beginner
- 🏅 TS Advanced
- 🏅 Fullstack Badge

Redirecionando para arquivo: npm run certificado -- --nome "Maria Silva" --tech "TypeScript" > certificado.md

---

Como usar no chat do Bob

O projeto define três slash commands locais em .bob/commands/. Após abrir o projeto no Bob, eles ficam disponíveis diretamente no chat:

Comando	Sintaxe	O que faz
/trilha	/trilha <tecnologia>	Executa commands/trilha.ts e exibe o plano de estudos
/desafio	/desafio <tecnologia> [nivel]	Executa commands/desafio.ts e exibe o desafio gerado
/certificado	/certificado "<nome>" "<tecnologia>"	Executa commands/certificado.ts e renderiza o certificado

Exemplos de uso no chat:

/trilha react
/desafio java intermediário
/certificado "Ana Lima" "Data Science"

O Bob interpreta os argumentos, monta o comando correto e exibe a saída formatada no próprio chat.

---

Como executar os testes

# Executa os testes sem cobertura
npm test

# Executa os testes com relatório de cobertura
npm run test:coverage

Resultado atual

 ✔ tests/trilha.test.ts        (14 testes)
 ✔ tests/certificado.test.ts   (24 testes)
 ✔ tests/desafio.test.ts       (20 testes)

 Test Files  3 passed (3)
      Tests  58 passed (58)
   Duration  1.71s

 % Coverage report from v8
------------------|---------|----------|---------|---------|
 File             | % Stmts | % Branch | % Funcs | % Lines |
------------------|---------|----------|---------|---------|
 All files        |     100 |      100 |     100 |     100 |
  commands        |     100 |      100 |     100 |     100 |
   certificado.ts |     100 |      100 |     100 |     100 |
   desafio.ts     |     100 |      100 |     100 |     100 |
   trilha.ts      |     100 |      100 |     100 |     100 |
  commands/lib    |     100 |      100 |     100 |     100 |
   trilhas.ts     |     100 |      100 |     100 |     100 |
------------------|---------|----------|---------|---------|

Statements : 100% (49/49) | Branches : 100% (28/28) | Functions : 100% (14/14) | Lines : 100% (43/43)

---

MCP Server

O que expõe

O servidor MCP em mcp/src/index.ts reutiliza diretamente a lógica dos comandos em commands/ e expõe quatro ferramentas:

Ferramenta	Parâmetros	Descrição
listar_tecnologias	(nenhum)	Lista todas as tecnologias disponíveis com nível e XP total
buscar_trilha	tecnologia (string)	Retorna o plano de estudos completo de uma tecnologia
gerar_desafio	tecnologia (string), nivel (opcional)	Gera um desafio de código aleatório
gerar_certificado	nome (string), tecnologia (string)	Emite um certificado em Markdown

O transporte usado é stdio — o servidor é iniciado como processo filho pelo cliente MCP.

Como registrar no Bob

1. Faça o build do servidor (necessário apenas uma vez):

   cd mcp
   npm install
   npm run build
   

2. Copie o template de configuração:

   cp .bob/mcp.example.json .bob/mcp.json
   

3. Edite .bob/mcp.json substituindo o caminho pelo absoluto da sua máquina:

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

4. O Bob recarrega os servidores MCP automaticamente ao salvar o arquivo. Após isso, geo-explorer aparecerá como servidor conectado no painel MCP do Bob.

O arquivo .bob/mcp.json está no .gitignore — cada desenvolvedor mantém seu próprio caminho absoluto localmente.

---

Melhorias realizadas

Correções encontradas em teste manual

Ao validar os comandos além do caminho feliz, apareceram dois defeitos que os testes iniciais não pegavam:

• O /certificado travava quando a tecnologia tinha espaço no nome ("Data Science"). O parsing dependia da posição dos argumentos e não distinguia onde terminava o nome. Corrigido com flags explícitas --nome e --tech, mantendo o modo posicional como fallback.
• O /trilha exibia "Módulo 1, Módulo 2..." em vez dos nomes reais. O código gerava os rótulos a partir do campo numero_de_modulos e ignorava o array modulos do JSON — o dado estava correto, quem o consumia é que não lia.
• O findTrilha retornava a primeira trilha do catálogo para entrada vazia, porque "".includes("") é sempre verdadeiro. A validação existia na CLI, mas não no servidor MCP, onde o schema Zod aceita string de espaços. Corrigido na origem.

Cobertura medida em vez de estimada

A meta era 70% de cobertura. Em vez de afirmar um número, configurei o provider v8 do Vitest para medir de fato, com relatório gravado em arquivo e script npm reproduzível. Os entrypoints CLI foram excluídos do cálculo com justificativa explícita, e as branches descobertas que sobraram receberam teste. Resultado: 100% sobre a lógica testável, 59 testes.

Separação entre lógica pura e I/O

Cada comando foi refatorado em duas camadas: funções puras exportadas e uma função run() isolada pelo guard require.main === module. Isso tornou o código testável sem mock de process.argv, e permitiu que o servidor MCP importasse a mesma lógica sem duplicação.

Configuração local fora do versionamento

O .bob/mcp.json exige caminho absoluto da máquina. Em vez de versionar um caminho que só funciona no meu computador, versionei .bob/mcp.example.json com placeholder e ignorei o arquivo real — mesmo padrão do .env.example.

Revisão da documentação gerada

A documentação produzida pelo agente foi revisada linha a linha e continha imprecisões: contagem errada de trilhas (15 em vez de 35), descrição do parser que não correspondia ao código, e uma justificativa de modelagem que racionalizava um campo redundante em vez de admitir o trade-off. Todas foram corrigidas contra o código.

---

O que aprendi

• Agente gera rápido, mas não verifica. O ciclo que funcionou foi sempre o mesmo: pedir, ler o que saiu, testar o caminho de erro, corrigir. Os três bugs deste projeto apareceram em teste manual, nunca no que o agente relatou como pronto. Ele descreveu o próprio parser de forma incorreta duas vezes — descrevia a intenção, não o código.

• Número afirmado não é número medido. O projeto de referência declarava 100% de cobertura sem ter nenhuma ferramenta de cobertura instalada. É a diferença entre dizer e demonstrar, e ela só aparece se alguém procurar.

• Segurança por padrão costuma ser a opção mais fraca. A instrução original mandava usar credential.helper store, que grava o token em texto puro no disco. Troquei pelo Git Credential Manager, que cumpre o mesmo requisito com armazenamento criptografado. O token do GitHub ficou em variável de ambiente de usuário, nunca em arquivo do projeto — decisão que também atende à orientação do desafio de não enviar credenciais ao repositório.

• Documentar decisão é diferente de documentar código. O ARQUITETURA.md só ficou útil quando cada seção passou a registrar o problema, a alternativa descartada e o motivo da escolha. Descrever o que o código faz é redundante — o código já está lá.