Geo-Explorer

Qué es Geo-Explorer

Geo-Explorer es una plataforma de estudios ficticia inspirada en DIO (Digital Innovation One). El proyecto simula un sistema de rutas de aprendizaje con desafíos de código y emisión de certificados.

Sirve como base para:

• Desarrollo de herramientas CLI en TypeScript

• Construcción de un MCP Server que expone la lógica de la plataforma como herramientas invocables por agentes de IA (Bob, Claude Desktop, Cursor, etc.)

• Definición de slash commands locales en Bob para accionar las herramientas directamente en el chat

• Práctica de pruebas unitarias con cobertura 100%

Related MCP server: MCP Learning Project

Estructura del proyecto

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

Cómo ejecutar

Requisitos previos

• Node.js ≥ 18

• npm ≥ 9

Instalación

# Na raiz do projeto
npm install

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

Build (verificación 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

El build del servidor MCP debe ejecutarse al menos una vez antes de registrarlo.

Cómo usar los comandos

Los tres comandos CLI se ejecutan vía npm run en la raíz.

/trilha <tecnologia>

Muestra el plan de estudios completo de una ruta a partir del nombre (o parte del nombre) de la tecnología. La búsqueda es case-insensitive y acepta correspondencia parcial.

npm run trilha -- javascript

Salida:

╔══════════════════════════════════════════════════════╗
  🎯  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]

Genera un desafío de código aleatorio. El parámetro nivel es opcional; cuando se omite, usa el nivel registrado en la ruta. Valores aceptados para nivel: básico, intermediário, avançado (con o sin 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

Salida (ejemplo):

╔══════════════════════════════════════════════════════╗
  ⚔️   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 un certificado ficticio en Markdown. El ID del certificado es determinístico — generado a partir del nombre del estudiante y del ID de la ruta.

El comando acepta dos formas de pasar 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"

En la forma posicional el parser espera exactamente dos argumentos (argv[0] → nombre, argv[1] → tecnología). Usa las flags --nome y --tech si prefieres una sintaxis más explícita o si quieres evitar depender de las comillas del shell.

Salida (en 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

Redirigiendo a archivo: npm run certificado -- --nome "Maria Silva" --tech "TypeScript" > certificado.md

Cómo usar en el chat de Bob

El proyecto define tres slash commands locales en .bob/commands/. Después de abrir el proyecto en Bob, quedan disponibles directamente en el chat:

Ejemplos de uso en el chat:

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

Bob interpreta los argumentos, monta el comando correcto y muestra la salida formateada en el propio chat.

Cómo ejecutar las pruebas

# Executa os testes sem cobertura
npm test

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

Resultado actual

 ✔ 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

Qué expone

El servidor MCP en mcp/src/index.ts reutiliza directamente la lógica de los comandos en commands/ y expone cuatro herramientas:

El transporte usado es stdio — el servidor se inicia como proceso hijo por el cliente MCP.

Cómo registrarlo en Bob

1. Haz el build del servidor (necesario solo una vez):

   cd mcp
   npm install
   npm run build

2. Copia el template de configuración:

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

3. Edita .bob/mcp.json sustituyendo la ruta por la absoluta de tu máquina:

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

4. Bob recarga los servidores MCP automáticamente al guardar el archivo. Después de eso, geo-explorer aparecerá como servidor conectado en el panel MCP de Bob.

El archivo .bob/mcp.json está en el .gitignore — cada desarrollador mantiene su propia ruta absoluta localmente.

Mejoras realizadas

Correcciones encontradas en prueba manual

Al validar los comandos más allá del camino feliz, aparecieron dos defectos que las pruebas iniciales no detectaban:

• El /certificado se trababa cuando la tecnología tenía espacio en el nombre ("Data Science"). El parsing dependía de la posición de los argumentos y no distinguía dónde terminaba el nombre. Corregido con flags explícitas --nome y --tech, manteniendo el modo posicional como fallback.

• El /trilha mostraba "Módulo 1, Módulo 2..." en lugar de los nombres reales. El código generaba las etiquetas a partir del campo numero_de_modulos e ignoraba el array modulos del JSON — el dato estaba correcto, quien lo consumía no lo leía.

• El findTrilha retornaba la primera ruta del catálogo para entrada vacía, porque "".includes("") siempre es verdadero. La validación existía en la CLI, pero no en el servidor MCP, donde el schema Zod acepta string de espacios. Corregido en el origen.

Cobertura medida en lugar de estimada

La meta era 70% de cobertura. En lugar de afirmar un número, configuré el provider v8 de Vitest para medir de hecho, con informe guardado en archivo y script npm reproducible. Los entrypoints CLI fueron excluidos del cálculo con justificativa explícita, y las branches descubiertas que sobraron recibieron prueba. Resultado: 100% sobre la lógica testeable, 59 pruebas.

Separación entre lógica pura e I/O

Cada comando fue refactorizado en dos capas: funciones puras exportadas y una función run() aislada por el guard require.main === module. Eso hizo el código testeable sin mock de process.argv, y permitió que el servidor MCP importara la misma lógica sin duplicación.

Configuración local fuera del versionado

El .bob/mcp.json exige ruta absoluta de la máquina. En lugar de versionar una ruta que solo funciona en mi computador, versioné .bob/mcp.example.json con placeholder e ignoré el archivo real — mismo patrón del .env.example.

Revisión de la documentación generada

La documentación producida por el agente fue revisada línea a línea y contenía imprecisiones: conteo erróneo de rutas (15 en lugar de 35), descripción del parser que no correspondía al código, y una justificativa de modelado que racionalizaba un campo redundante en lugar de admitir el trade-off. Todas fueron corregidas contra el código.

Lo que aprendí

• El agente genera rápido, pero no verifica. El ciclo que funcionó fue siempre el mismo: pedir, leer lo que salió, probar el camino de error, corregir. Los tres bugs de este proyecto aparecieron en prueba manual, nunca en lo que el agente reportó como listo. Describió su propio parser de forma incorrecta dos veces — describía la intención, no el código.

• Número afirmado no es número medido. El proyecto de referencia declaraba 100% de cobertura sin tener ninguna herramienta de cobertura instalada. Es la diferencia entre decir y demostrar, y solo aparece si alguien busca.

• Seguridad por defecto suele ser la opción más débil. La instrucción original mandaba usar credential.helper store, que graba el token en texto plano en el disco. Lo cambié por Git Credential Manager, que cumple el mismo requisito con almacenamiento cifrado. El token de GitHub quedó en variable de entorno de usuario, nunca en archivo del proyecto — decisión que también atiende la orientación del desafío de no enviar credenciales al repositorio.

• Documentar decisión es diferente de documentar código. El ARQUITETURA.md solo fue útil cuando cada sección pasó a registrar el problema, la alternativa descartada y el motivo de la elección. Describir lo que el código hace es redundante — el código ya está ahí.