mcp server

Geo-Explorer

Explorador interativo de trilhas de aprendizagem - desafio DIO / IBM Bob (CLI + MCP)

henda07/Geo-Explorercommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

This project does not publish an install method we can turn into a config. Follow the README instead.

README

synced Oct 26, 2026

🌍 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

🧭 Visão geral

O Geo-Explorer é uma experiência de exploração de trilhas de aprendizagem executada no terminal. A pessoa usuária pode:

Consultar uma trilha — plano de estudos por tecnologia e nível, com módulos, tópicos e duração estimada.
Receber um desafio de código — enunciado + dica, conforme tecnologia e nível.
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).

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/index.js`
Comando Desafio — desafio de código por tecnologia e nível	`src/commands/desafio.js` + `src/index.js`
Comando Certificado — certificado fictício de trilha concluída	`src/commands/certificado.js` + `src/index.js`
Base com trilhas fictícias (tecnologias, níveis, módulos)	`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/` — 23 testes Jest (detalhes)
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` — tools `get_trilha`, `get_desafio`, `get_certificado`

✨ 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

Requisito	Versão mínima	Verificação
Node.js (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

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]

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

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

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

npm test

Framework: Jest 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).

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; 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

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; 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

Fork o repositório e crie uma branch (git checkout -b feat/minha-melhoria).
Siga o padrão existente: lógica pura em buscar*/gerar*, formatação em exibir*, testes no arquivo correspondente em tests/.
Garanta npm test verde antes do PR.
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.