Skip to main content
Glama
Geo-Explorer MCP Server

Geo-Explorer MCP Server

by henda07

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

Node.js ES Modules Tests MCP License: MIT DIO IBM Bob


📑 Sumário


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

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

  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

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to programmatically interact with Coursera, including enrolling in courses, completing lectures, solving quizzes, submitting assignments, earning certificates, and pushing them to LinkedIn.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for a fictional learning platform, providing tools to list technologies, search learning tracks, generate coding challenges, and issue certificates.
      MIT