Geo-Explorer

Was ist Geo-Explorer

Geo-Explorer ist eine fiktive Lernplattform, inspiriert von der DIO (Digital Innovation One). Das Projekt simuliert ein System von Lernpfaden mit Code-Herausforderungen und der Ausstellung von Zertifikaten.

Es dient als Studienbasis für:

• Entwicklung von CLI-Tools in TypeScript

• Aufbau eines MCP-Servers, der die Logik der Plattform als Werkzeuge bereitstellt, die von KI-Agenten (Bob, Claude Desktop, Cursor usw.) aufgerufen werden können

• Definition von lokalen Slash-Commands in Bob, um die Werkzeuge direkt im Chat auszulösen

• Übung von Unit-Tests mit 100 % Abdeckung

Related MCP server: MCP Learning Project

Projektstruktur

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

Ausführung

Voraussetzungen

• Node.js ≥ 18

• npm ≥ 9

Installation

# Na raiz do projeto
npm install

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

Build (Typprüfung)

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

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

Der Build des MCP-Servers muss mindestens einmal ausgeführt werden, bevor er registriert wird.

Verwendung der Befehle

Die drei CLI-Befehle werden über npm run im Projektstamm ausgeführt.

/trilha <tecnologia>

Zeigt den vollständigen Studienplan eines Lernpfads anhand des Namens (oder eines Teils des Namens) der Technologie an. Die Suche ist case-insensitive und akzeptiert teilweise Übereinstimmungen.

npm run trilha -- javascript

Ausgabe:

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

Erzeugt eine zufällige Code-Herausforderung. Der Parameter nivel ist optional; wenn er weggelassen wird, wird der im Lernpfad registrierte Level verwendet. Akzeptierte Werte für den Level: básico, intermediário, avançado (mit oder ohne Akzent, 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

Ausgabe (Beispiel):

╔══════════════════════════════════════════════════════╗
  ⚔️   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

Stellt ein fiktives Zertifikat in Markdown aus. Die ID des Zertifikats ist deterministisch — generiert aus dem Namen des Studierenden und der ID des Lernpfads.

Der Befehl akzeptiert zwei Formen der Argumentübergabe:

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

In der positionellen Form erwartet der Parser genau zwei Argumente (argv[0] → Name, argv[1] → Technologie). Verwenden Sie die Flags --nome und --tech, wenn Sie eine explizitere Syntax bevorzugen oder nicht von den Shell-Anführungszeichen abhängig sein möchten.

Ausgabe (in 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

In Datei umleiten: npm run certificado -- --nome "Maria Silva" --tech "TypeScript" > certificado.md

Verwendung im Bob-Chat

Das Projekt definiert drei lokale Slash-Commands in .bob/commands/. Nach dem Öffnen des Projekts in Bob sind sie direkt im Chat verfügbar:

Beispiele für die Verwendung im Chat:

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

Bob interpretiert die Argumente, setzt den korrekten Befehl zusammen und zeigt die formatierte Ausgabe direkt im Chat an.

Ausführen der Tests

# Executa os testes sem cobertura
npm test

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

Aktuelles Ergebnis

 ✔ 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

Was er bereitstellt

Der MCP-Server in mcp/src/index.ts verwendet direkt die Logik der Befehle in commands/ und stellt vier Werkzeuge bereit:

Der verwendete Transport ist stdio — der Server wird als untergeordneter Prozess vom MCP-Client gestartet.

Registrierung in Bob

1. Erstellen Sie den Build des Servers (nur einmal erforderlich):

   cd mcp
   npm install
   npm run build

2. Kopieren Sie die Konfigurationsvorlage:

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

3. Bearbeiten Sie .bob/mcp.json und ersetzen Sie den Pfad durch den absoluten Pfad Ihrer Maschine:

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

4. Bob lädt die MCP-Server beim Speichern der Datei automatisch neu. Danach erscheint geo-explorer als verbundener Server im MCP-Panel von Bob.

Die Datei .bob/mcp.json steht in der .gitignore — jeder Entwickler pflegt seinen eigenen absoluten Pfad lokal.

Durchgeführte Verbesserungen

Bei manuellen Tests gefundene Korrekturen

Bei der Validierung der Befehle über den Happy Path hinaus traten zwei Fehler auf, die die ersten Tests nicht erfassten:

• Der /certificado hing, wenn die Technologie ein Leerzeichen im Namen hatte ("Data Science"). Das Parsing hing von der Position der Argumente ab und unterschied nicht, wo der Name endete. Mit expliziten Flags --nome und --tech korrigiert, wobei der positionelle Modus als Fallback erhalten bleibt.

• Der /trilha zeigte "Módulo 1, Módulo 2..." anstelle der tatsächlichen Namen. Der Code generierte die Bezeichnungen aus dem Feld numero_de_modulos und ignorierte das Array modulos aus dem JSON — die Daten waren korrekt, nur der Konsument las sie nicht.

• Der findTrilha gab für leere Eingabe den ersten Lernpfad des Katalogs zurück, weil "".includes("") immer wahr ist. Die Validierung existierte in der CLI, aber nicht im MCP-Server, wo das Zod-Schema eine Zeichenkette mit Leerzeichen akzeptiert. An der Quelle korrigiert.

Gemessene statt geschätzte Abdeckung

Das Ziel war 70 % Abdeckung. Anstatt eine Zahl zu behaupten, habe ich den v8-Provider von Vitest konfiguriert, um tatsächlich zu messen, mit Bericht in Datei und reproduzierbarem npm-Skript. Die CLI-Entrypoints wurden mit expliziter Begründung von der Berechnung ausgeschlossen, und die verbleibenden entdeckten Branches erhielten Tests. Ergebnis: 100 % auf der testbaren Logik, 59 Tests.

Trennung zwischen reiner Logik und I/O

Jeder Befehl wurde in zwei Schichten refaktoriert: exportierte reine Funktionen und eine run()-Funktion, die durch den Guard require.main === module isoliert ist. Dadurch wurde der Code ohne Mock von process.argv testbar, und der MCP-Server konnte dieselbe Logik ohne Duplizierung importieren.

Lokale Konfiguration außerhalb der Versionskontrolle

Die .bob/mcp.json erfordert den absoluten Pfad der Maschine. Anstatt einen Pfad zu versionieren, der nur auf meinem Computer funktioniert, habe ich .bob/mcp.example.json mit Platzhalter versioniert und die echte Datei ignoriert — dasselbe Muster wie bei .env.example.

Überprüfung der generierten Dokumentation

Die vom Agenten erstellte Dokumentation wurde Zeile für Zeile überprüft und enthielt Ungenauigkeiten: falsche Anzahl der Lernpfade (15 statt 35), eine Beschreibung des Parsers, die nicht dem Code entsprach, und eine Modellierungsbegründung, die ein redundantes Feld rationalisierte, anstatt den Trade-off zuzugeben. Alle wurden gegen den Code korrigiert.

Was ich gelernt habe

• Agenten generieren schnell, aber sie verifizieren nicht. Der funktionierende Zyklus war immer derselbe: anfordern, lesen, was herauskam, den Fehlerpfad testen, korrigieren. Die drei Bugs dieses Projekts traten bei manuellen Tests auf, nie in dem, was der Agent als fertig meldete. Er beschrieb den eigenen Parser zweimal falsch — er beschrieb die Absicht, nicht den Code.

• Eine behauptete Zahl ist keine gemessene Zahl. Das Referenzprojekt deklarierte 100 % Abdeckung, ohne ein einziges Abdeckungswerkzeug installiert zu haben. Das ist der Unterschied zwischen Behaupten und Demonstrieren, und er zeigt sich nur, wenn jemand danach sucht.

• Sicherheit als Standard ist oft die schwächste Option. Die ursprüngliche Anweisung verlangte die Verwendung von credential.helper store, das den Token im Klartext auf der Festplatte speichert. Ich habe es durch den Git Credential Manager ersetzt, der dieselbe Anforderung mit verschlüsselter Speicherung erfüllt. Der GitHub-Token blieb in einer Benutzerumgebungsvariable, nie in einer Projektdatei — eine Entscheidung, die auch der Anweisung der Herausforderung entspricht, keine Anmeldedaten an das Repository zu senden.

• Entscheidungen zu dokumentieren ist etwas anderes als Code zu dokumentieren. Die ARQUITETURA.md wurde erst nützlich, als jeder Abschnitt das Problem, die verworfenen Alternative und den Grund für die Wahl festhielt. Zu beschreiben, was der Code tut, ist redundant — der Code ist bereits da.