Geo-Explorer MCP Server
by henda07
README.md
# 🌍 Geo-Explorer
> Explorador interativo de trilhas de aprendizagem — consulte planos de estudo, receba desafios de código e emita certificados fictícios, via CLI ou via agente de IA (MCP).
[](https://nodejs.org/)
[](https://nodejs.org/api/esm.html)
[](#-qualidade--testes)
[](https://modelcontextprotocol.io/)
[](LICENSE)
[](https://www.dio.me/)
[](https://www.dio.me/)
---
## 📑 Sumário
- [Visão geral](#-visão-geral)
- [Contexto do desafio](#-contexto-do-desafio)
- [Demonstração](#-demonstração)
- [Arquitetura](#-arquitetura)
- [Pré-requisitos](#-pré-requisitos)
- [Instalação](#-instalação)
- [Guia de uso (CLI)](#-guia-de-uso-cli)
- [Referência de comandos](#-referência-de-comandos)
- [Catálogo de trilhas](#-catálogo-de-trilhas)
- [Qualidade & testes](#-qualidade--testes)
- [Servidor MCP](#-servidor-mcp-model-context-protocol)
- [Decisões técnicas](#-decisões-técnicas)
- [Melhorias implementadas](#-melhorias-implementadas)
- [Aprendizados](#-aprendizados)
- [Roadmap](#-roadmap)
- [Contribuindo](#-contribuindo)
- [Segurança](#-segurança)
- [Suporte](#-suporte)
- [Autores & créditos](#-autores--créditos)
- [Licença](#-licença)
---
## 🧭 Visão geral
O **Geo-Explorer** é uma experiência de exploração de trilhas de aprendizagem executada no terminal. A pessoa usuária pode:
1. **Consultar uma trilha** — plano de estudos por tecnologia e nível, com módulos, tópicos e duração estimada.
2. **Receber um desafio de código** — enunciado + dica, conforme tecnologia e nível.
3. **Gerar um certificado fictício** — confirmação simbólica de conclusão de trilha, com código rastreável.
Os mesmos recursos são expostos como **ferramentas MCP (Model Context Protocol)**, de modo que assistentes de IA — como o **IBM Bob** — possam consultar trilhas, desafios e certificados em nome do usuário.
**Stack:** Node.js 18+ · ES Modules · Jest · MCP SDK (`@modelcontextprotocol/sdk`) · Zod · zero dependências de runtime para a CLI.
**Status:** ✅ Funcional — 23 testes automatizados passando, CLI validada, servidor MCP operacional.
---
## 🎓 Contexto do desafio
| Item | Detalhe |
|---|---|
| **Programa** | Bootcamp DIO **"IBM Bob: IA de Nível Empresarial para Desenvolvedores e Tech Leaders"** |
| **Desafio** | **Geo-Explorer** — projeto de portfólio com apoio do IBM Bob |
| **Proposta** | Criar, testar e documentar uma solução completa de exploração de trilhas de aprendizagem |
| **Papel do IBM Bob** | Apoio como agente de IA: criação assistida, revisão de código, organização dos próximos passos e revisão da documentação — **sem substituir** as decisões, revisões e aprendizados do desenvolvedor |
| **Tipo de entrega** | Repositório público no GitHub com dados, comandos, testes, documentação e integração MCP |
> **Nota de autoria:** todo o código gerado com assistência de IA foi revisado, testado e adaptado manualmente. Nenhuma credencial, token ou dado privado é versionado (ver [Segurança](#-segurança)).
### O que o desafio solicitou — e onde está
| Requisito do enunciado | Implementação neste repositório |
|---|---|
| Comando **Trilha** — plano de estudos por tecnologia | [`src/commands/trilha.js`](src/commands/trilha.js) + [`src/index.js`](src/index.js) |
| Comando **Desafio** — desafio de código por tecnologia e nível | [`src/commands/desafio.js`](src/commands/desafio.js) + [`src/index.js`](src/index.js) |
| Comando **Certificado** — certificado fictício de trilha concluída | [`src/commands/certificado.js`](src/commands/certificado.js) + [`src/index.js`](src/index.js) |
| Base com trilhas fictícias (tecnologias, níveis, módulos) | [`data/trilhas.json`](data/trilhas.json) — 7 trilhas, 5–6 módulos cada, 2 desafios por trilha |
| Pastas para dados, comandos, documentação, testes e recursos | `data/` · `src/commands/` · `tests/` · `mcp/` · `README.md` |
| Testes automatizados | [`tests/`](tests/) — 23 testes Jest ([detalhes](#-qualidade--testes)) |
| Documentação (este README) | `README.md` — o que é, como executar, como usar, como testar, melhorias, aprendizados |
| Servidor MCP para integração com outras ferramentas | [`mcp/server.js`](mcp/server.js) — tools `get_trilha`, `get_desafio`, `get_certificado` |
---
## ✨ Demonstração
```bash
# Plano de estudos
$ node src/index.js trilha JavaScript iniciante
🗺️ TRILHA: JAVASCRIPT — INICIANTE
Aprenda os fundamentos do JavaScript e comece a criar scripts interativos para a web.
⏱ Duração estimada: 6 semanas
MÓDULOS
1. Fundamentos da Linguagem · 2. Funções e Escopo · 3. Arrays e Objetos
4. DOM e Eventos · 5. Assincronismo · 6. Projeto Final
```
```bash
# Desafio de código
$ node src/index.js desafio Python avancado
💻 DESAFIO: PYTHON — AVANCADO
📌 API REST com FastAPI
Implemente uma API REST com autenticação JWT, CRUD completo de usuários e testes automatizados.
💡 Dica: Use Depends() para injeção de dependências e pytest-asyncio para testar endpoints.
```
```bash
# Certificado fictício
$ node src/index.js certificado "Maria Silva" React
★ GEO-EXPLORER ACADEMY — CERTIFICADO FICTÍCIO ★
🎓 MARIA SILVA — 📚 Trilha de React
Código: GEO-REAC-202610-XXXX · Geo-Explorer Academy
```
> Saídas acima simplificadas para leitura. Execute os comandos para ver a formatação completa no terminal.
---
## 🏗️ Arquitetura
```
Geo-Explorer/
├── data/
│ └── trilhas.json # Base fictícia: tecnologias, níveis, módulos, desafios
├── src/
│ ├── index.js # CLI — roteamento, validação de args, exit codes
│ └── commands/
│ ├── trilha.js # buscarTrilha() + exibirTrilha()
│ ├── desafio.js # buscarDesafio() + exibirDesafio()
│ └── certificado.js # gerarCertificado() + exibirCertificado()
├── tests/ # 23 testes Jest (trilha · desafio · certificado)
├── mcp/
│ └── server.js # MCP (STDIO): get_trilha, get_desafio, get_certificado
├── package.json # Scripts: start · test · mcp
└── README.md
```
**Fluxo de dados:** `data/trilhas.json` → funções puras `buscar*`/`gerar*` (retornam objetos, testáveis) → funções `exibir*` (formatação de terminal) → CLI (`src/index.js`) ou MCP (`mcp/server.js`). Essa separação permite testar a lógica sem capturar saída de console.
---
## 💻 Pré-requisitos
| Requisito | Versão mínima | Verificação |
|---|---|---|
| [Node.js](https://nodejs.org/) (LTS recomendado) | **18.x** | `node --version` |
| npm (acompanha o Node) | 9.x | `npm --version` |
| Git (para clonar) | qualquer recente | `git --version` |
> Nenhuma variável de ambiente, banco de dados ou serviço externo é necessário.
---
## 📦 Instalação
```bash
git clone https://github.com/henda07/Geo-Explorer.git
cd Geo-Explorer
npm install
```
**Verifique a instalação:**
```bash
node src/index.js ajuda # deve exibir o menu de ajuda
npm test # deve reportar 23 testes passando
```
> Repo: [github.com/henda07/Geo-Explorer](https://github.com/henda07/Geo-Explorer).
---
## 🛠️ Guia de uso (CLI)
```bash
node src/index.js <comando> [argumentos]
```
| Comando | Argumentos | Descrição |
|---|---|---|
| `trilha` | `<tecnologia> [nivel]` | Plano de estudos (filtro de nível opcional) |
| `desafio` | `<tecnologia> <nivel>` | Desafio de código para tecnologia + nível |
| `certificado` | `"<nome>" <tecnologia>` | Certificado fictício de conclusão |
| `ajuda` (ou `help`, ou sem args) | — | Menu de ajuda |
**Normalização de entrada:**
- Buscas **case-insensitive** e **sem acentos**: `python`, `PYTHON`, `avançado`/`avancado`.
- Espaços extras removidos; nome do certificado aceita **com ou sem aspas**.
- Entradas inválidas exibem uso e retornam **exit code `1`** (pronto para scripts/CI).
---
## 📖 Referência de comandos
### `trilha` — Plano de estudos
```bash
node src/index.js trilha <tecnologia> [nivel]
node src/index.js trilha JavaScript
node src/index.js trilha Python iniciante
node src/index.js trilha "Node.js" intermediario
```
Exibe descrição, duração em semanas e módulos numerados com tópicos. Tecnologia inexistente (ex: `COBOL`) → lista as disponíveis + exit `1`.
### `desafio` — Desafio de código
```bash
node src/index.js desafio <tecnologia> <nivel>
node src/index.js desafio JavaScript iniciante
node src/index.js desafio Python avancado
node src/index.js desafio React iniciante
```
Exibe título, enunciado e dica. Combinação inexistente (ex: `Python intermediario` — Python só tem `iniciante`/`avancado`) → mensagem orientativa + exit `1`.
### `certificado` — Certificado fictício
```bash
node src/index.js certificado "<nome>" <tecnologia>
node src/index.js certificado "Maria Silva" React
node src/index.js certificado "João Santos" Python
```
Emite moldura com nome, trilha, data (pt-BR), código único `GEO-XXXX-YYYYMM-NNNN` e `Geo-Explorer Academy`. Campos ausentes → uso + exit `1`.
---
## 🗺️ Catálogo de trilhas
Base fictícia em [`data/trilhas.json`](data/trilhas.json): cada trilha tem `id`, `tecnologia`, `nivel`, `descricao`, `duracao_semanas`, `modulos[]` (`ordem`, `titulo`, `topicos[]`) e `desafios[]` (`nivel`, `titulo`, `descricao`, `dica`).
| Tecnologia | Iniciante | Intermediário | Avançado | Módulos | Desafios |
|---|:---:|:---:|:---:|:---:|:---:|
| JavaScript | ✅ | ✅ | — | 6 + 6 | 2 + 2 |
| Python | ✅ | — | ✅ | 6 + 6 | 2 + 2 |
| React | ✅ | — | — | 6 | 2 |
| Node.js | — | ✅ | — | 6 | 2 |
| SQL | ✅ | — | — | 5 | 2 |
| **Total** | | | | **7 trilhas** | **14 desafios** |
> Nova trilha = novo objeto no array em `data/trilhas.json` seguindo o schema — nenhum código precisa mudar.
---
## ✅ Qualidade & testes
```bash
npm test
```
- **Framework:** [Jest](https://jestjs.io/) 29 com ES Modules (`node --experimental-vm-modules`).
- **Resultado:** **23 testes, 3 suites — todos passando.**
| Suite | Testes | Valida |
|---|---|---|
| `tests/trilha.test.js` | 7 | Carga da base, campos obrigatórios, busca tecnologia/nível, `null` p/ inexistentes, acentos |
| `tests/desafio.test.js` | 9 | Busca tecnologia/nível, campos do desafio, `null` p/ ausentes/inexistentes, case-insensitive, acentos |
| `tests/certificado.test.js` | 7 | Campos, padrão `GEO-XXXX-YYYYMM-NNNN`, mensagem nome/tecnologia, `null` p/ ausentes, unicidade |
Validação manual: 3 comandos (válidos + inválidos, exit `0`/`1`), `node --check` nos módulos e no MCP.
---
## 🔌 Servidor MCP (Model Context Protocol)
Expõe a lógica via STDIO para agentes de IA (ex: IBM Bob).
```bash
npm run mcp
```
| Ferramenta | Parâmetros | Retorno |
|---|---|---|
| `get_trilha` | `tecnologia`, `nivel` (opcional) | JSON da trilha ou erro `isError` |
| `get_desafio` | `tecnologia`, `nivel` | JSON do desafio ou erro `isError` |
| `get_certificado` | `nome`, `tecnologia` | JSON do certificado ou erro `isError` |
Schemas [Zod](https://zod.dev/); níveis aceitam acentos/maiúsculas (normalização na busca, igual à CLI).
**Configurar no IBM Bob** — `.bob/mcp.json` (não versionado):
```json
{
"mcpServers": {
"geo-explorer": {
"command": "node",
"args": ["mcp/server.js"],
"cwd": "<caminho-absoluto-para-o-projeto>"
}
}
}
```
---
## 🧠 Decisões técnicas
| Decisão | Motivo |
|---|---|
| ES Modules nativo (`"type": "module"`) | Padrão moderno do Node, `import`/`export` sem transpilação |
| CLI sem dependências externas | `process.argv` basta para 3 comandos; zero superfície de ataque/quebra |
| Lógica pura separada da formatação (`buscar*` vs `exibir*`) | Testabilidade: Jest testa objetos, não saída de console |
| JSON como base de dados | Suficiente para conteúdo fictício; schema documentado no README |
| Normalização NFD + case-insensitive | UX: acentos e maiúsculas não devem quebrar buscas em pt-BR |
| MCP sobre STDIO + Zod | Padrão do [Model Context Protocol](https://modelcontextprotocol.io/); validação na borda |
---
## ✨ Melhorias implementadas
- **Normalização de acentos e case-insensitive** em todas as buscas (`avançado` ≡ `avancado`).
- **Catálogo de 7 trilhas** — JavaScript (2), Python (2), React, Node.js e SQL, com módulos detalhados.
- **2 desafios por trilha** (14 no total), cada um com enunciado e dica de implementação.
- **Código de certificado rastreável** no padrão `GEO-XXXX-YYYYMM-NNNN` (sigla sanitizada, ex: `Node.js` → `NODE`).
- **Robustez de CLI**: guards contra `undefined`/não-string, `trim()` de entradas, nome com espaços sem aspas, exit codes `1` em erro.
- **Servidor MCP** com validação de schema via Zod e paridade de normalização com a CLI.
---
## 📚 Aprendizados
> Reflexão do desafio — o que este projeto ensinou:
- **Estrutura Node.js com ES Modules** — `"type": "module"`, `__dirname` via `import.meta.url`, camadas `data` → lógica → apresentação.
- **CLI sem frameworks** — roteamento com `process.argv`, validação de args e exit codes, zero dependências de runtime.
- **Testes Jest em ESM** — suites por comando, `null` para casos ausentes, flag `--experimental-vm-modules`.
- **Servidor MCP** — tools com SDK oficial, validação Zod, respostas `content[]`/`isError` sobre STDIO.
- **Normalização de entrada (i18n)** — `String.normalize("NFD")` + remoção de diacríticos para buscas tolerantes em pt-BR.
- **IA como par, não piloto** — IBM Bob acelera e revisa; decisão, teste e documentação seguem humanas.
---
## 🗺️ Roadmap
Melhorias futuras (alinhadas às sugestões do enunciado — "Evolua Com Suas Ideias"):
- [ ] Novas trilhas (ex: TypeScript, Java, DevOps) — só estender `data/trilhas.json`
- [ ] Desafios com níveis de dificuldade e testes de solução
- [ ] Exportação do certificado (HTML/PDF) além do terminal
- [ ] Internacionalização (EN/ES) das mensagens da CLI
- [ ] Cobertura de testes + lint no CI (GitHub Actions)
> Escopo atual propositalmente enxuto: fluxo principal funcionando e bem explicado, conforme o enunciado.
---
## 🤝 Contribuindo
1. Fork o repositório e crie uma branch (`git checkout -b feat/minha-melhoria`).
2. Siga o padrão existente: lógica pura em `buscar*`/`gerar*`, formatação em `exibir*`, testes no arquivo correspondente em `tests/`.
3. Garanta `npm test` verde antes do PR.
4. Descreva **o quê**, **por quê** e **como testar**.
---
## 🔒 Segurança
- Nenhuma credencial, token ou dado pessoal é versionado. `.env`, `node_modules/` e `coverage/` estão no [`.gitignore`](.gitignore).
- Antes de publicar, revise diffs gerados com assistência de IA (regra do desafio).
- Para reportar vulnerabilidades, abra uma issue privada ou contate o autor — não exponha detalhes publicamente.
---
## 🆘 Suporte
- **Dúvidas sobre o desafio?** Use o [DIO Agent](https://github.com/digitalinnovationone/dio-agent) com este modelo:
```
Estou desenvolvendo o Geo-Explorer.
Repositório do meu projeto: <cole aqui o link>
Estou trabalhando nesta etapa: <explique a etapa ou a dificuldade>
Ajude-me a entender o próximo passo sem entregar a solução completa.
```
- **Bugs neste repo?** Abra uma [issue](https://github.com/henda07/Geo-Explorer/issues) com comando executado, saída e `node --version`.
---
## 👥 Autores & créditos
**Henda Carlos Pires Jorge** — autor e mantenedor
- 📧 hendacarlos707@gmail.com
- 🐙 [@henda07](https://github.com/henda07)
**Créditos:** [DIO](https://www.dio.me/) pelo desafio; **IBM Bob** (bootcamp *"IA de Nível Empresarial para Desenvolvedores e Tech Leaders"*) pelo apoio com IA; comunidade [Model Context Protocol](https://modelcontextprotocol.io/) pelo SDK.
---
## 📄 Licença
Distribuído sob a licença **MIT** — ver [LICENSE](LICENSE) (ou o campo `license` em [`package.json`](package.json)) para detalhes. Uso livre com atribuição.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues