🌍 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).

📑 Sumário

• Visão geral

• Contexto do desafio

• Demonstração

• Arquitetura

• Pré-requisitos

• Instalação

• Guia de uso (CLI)

• Referência de comandos

• Catálogo de trilhas

• Qualidade & testes

• Servidor MCP

• Decisões técnicas

• Melhorias implementadas

• Aprendizados

• Roadmap

• Contribuindo

• Segurança

• Suporte

• Autores & créditos

• Licença

Related MCP server: BNCC MCP Server

🧭 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

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

O que o desafio solicitou — e onde está

✨ Demonstração

# 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

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

# 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

Nenhuma variável de ambiente, banco de dados ou serviço externo é necessário.

📦 Instalação

git clone https://github.com/henda07/Geo-Explorer.git
cd Geo-Explorer
npm install

Verifique a instalação:

node src/index.js ajuda   # deve exibir o menu de ajuda
npm test                  # deve reportar 23 testes passando

Repo: github.com/henda07/Geo-Explorer.

🛠️ Guia de uso (CLI)

node src/index.js <comando> [argumentos]

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

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

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

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: cada trilha tem id, tecnologia, nivel, descricao, duracao_semanas, modulos[] (ordem, titulo, topicos[]) e desafios[] (nivel, titulo, descricao, dica).

Nova trilha = novo objeto no array em data/trilhas.json seguindo o schema — nenhum código precisa mudar.

✅ Qualidade & testes

npm test

• Framework: Jest 29 com ES Modules (node --experimental-vm-modules).

• Resultado: 23 testes, 3 suites — todos passando.

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

npm run mcp

Schemas Zod; níveis aceitam acentos/maiúsculas (normalização na busca, igual à CLI).

Configurar no IBM Bob — .bob/mcp.json (não versionado):

{
  "mcpServers": {
    "geo-explorer": {
      "command": "node",
      "args": ["mcp/server.js"],
      "cwd": "<caminho-absoluto-para-o-projeto>"
    }
  }
}

🧠 Decisões técnicas

✨ 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.

• 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 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 com comando executado, saída e node --version.

👥 Autores & créditos

Henda Carlos Pires Jorge — autor e mantenedor

• 📧 hendacarlos707@gmail.com

• 🐙 @henda07

Créditos: DIO pelo desafio; IBM Bob (bootcamp "IA de Nível Empresarial para Desenvolvedores e Tech Leaders") pelo apoio com IA; comunidade Model Context Protocol pelo SDK.

📄 Licença

Distribuído sob a licença MIT — ver LICENSE (ou o campo license em package.json) para detalhes. Uso livre com atribuição.