🌎 Geo-Explorer

Explorador de trilhas de aprendizagem em linha de comando, com servidor MCP integrado. Projeto do desafio "Construindo Seu Primeiro Produto com um Agente de IA" da DIO.

📖 O que é o Geo-Explorer

O Geo-Explorer é uma ferramenta de linha de comando que ajuda alguém a explorar uma trilha de estudos de ponta a ponta:

1. escolhe uma tecnologia e recebe um plano de estudos com módulos, tópicos e carga horária;

2. pede um desafio de código no nível em que está;

3. ao terminar, emite um certificado fictício de conclusão.

Tudo roda sobre uma base de trilhas fictícia (trilhas.json) criada especialmente para o projeto — nenhum dado aqui representa um curso real, e o certificado não tem validade legal.

Além da CLI, o projeto expõe os mesmos três comandos como um servidor MCP, permitindo que ferramentas de IA (Claude Desktop, Claude Code, IDEs compatíveis) usem o Geo-Explorer como fonte de dados sem precisar do terminal.

Base de trilhas

5 trilhas · 15 planos de estudo · 30 desafios de código

Related MCP server: AegisX MCP

🚀 Como executar o projeto

Pré-requisitos

• Python 3.10 ou superior

• Nada além disso: o projeto tem zero dependências externas em runtime

Instalação

# 1. clone o repositório
git clone https://github.com/GuiC1ntra/geo-explorer.git
cd geo-explorer

# 2. (recomendado) crie um ambiente virtual
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

# 3. instale em modo editável, com as dependências de teste
pip install -e ".[dev]"

Depois disso o comando geo-explorer fica disponível no terminal.

Sem instalar nada? Também funciona direto do código-fonte:

PYTHONPATH=src python3 -m geo_explorer listar

🧭 Como usar os comandos

listar — ver todas as trilhas

geo-explorer listar

================================================================
  TRILHAS DISPONIVEIS
================================================================

  devops       DevOps
               Infraestrutura | 156h totais
               niveis: iniciante, intermediario, avancado

  ia           Inteligencia Artificial
               IA | 146h totais
               niveis: iniciante, intermediario, avancado
  ...

trilha — plano de estudos

Apresenta o plano de estudos da tecnologia escolhida.

geo-explorer trilha python
geo-explorer trilha python --nivel intermediario
geo-explorer trilha "Inteligência Artificial" --nivel avancado
geo-explorer trilha frontend            # busca por tag também funciona

================================================================
  TRILHA: PYTHON
================================================================
Categoria......: Backend
Nivel..........: intermediario
Carga horaria..: 60h
Modulos........: 5

PLANO DE ESTUDOS
----------------------------------------------------------------

  1. Programacao orientada a objetos  (12h)
     - Classes e heranca
     - dataclasses
     - Metodos magicos
  ...

Proximo passo: nivel 'avancado' (geo-explorer trilha python --nivel avancado)

desafio — gerar um desafio de código

geo-explorer desafio sql --nivel avancado
geo-explorer desafio ia --nivel intermediario --seed 42

================================================================
  DESAFIO: Carga incremental idempotente
================================================================
Id.............: sql-avc-02
Trilha.........: SQL e Dados
Nivel..........: avancado
Tempo estimado.: 120 min

ENUNCIADO
----------------------------------------------------------------
Monte um MERGE que carregue apenas registros novos ou alterados
e possa ser reexecutado sem duplicar dados.

CRITERIOS DE ACEITE
----------------------------------------------------------------
  [ ] Usar chave de negocio
  [ ] Tratar updates e inserts
  [ ] Ser idempotente

DICA
----------------------------------------------------------------
  Uma coluna updated_at mais MERGE ON chave resolve os dois casos.

certificado — emitir certificado fictício

geo-explorer certificado "Guilherme Cintra" --trilha python --nivel intermediario
geo-explorer certificado "Guilherme Cintra" -t ia -n avancado --data 2026-08-28

+--------------------------------------------------------------+
|                                                              |
|                   CERTIFICADO DE CONCLUSAO                   |
|           (documento ficticio - projeto de estudo)           |
|                                                              |
|                       Certificamos que                       |
|                                                              |
|                       GUILHERME CINTRA                       |
|                                                              |
|         concluiu a trilha de Inteligencia Artificial         |
|             no nivel intermediario, com 50 horas             |
|                  distribuidas em 4 modulos.                  |
|                                                              |
|                    Emitido em 2026-08-28                     |
|           Codigo de validacao: GEO-8028-633F-AD41            |
|                                                              |
+--------------------------------------------------------------+

O código de validação é gerado por um hash SHA-256 dos dados do certificado. Ele é determinístico: os mesmos dados sempre produzem o mesmo código, e qualquer alteração produz um código diferente. Não é uma assinatura criptográfica de verdade — é o que dá cara de documento ao resultado e o torna testável.

Saída em JSON

Qualquer comando aceita --json, o que torna o Geo-Explorer utilizável dentro de scripts:

geo-explorer --json trilha python --nivel avancado | jq '.modulos[].titulo'
geo-explorer --json desafio devops --seed 1 | jq -r '.enunciado'

🔌 Servidor MCP

O MCP (Model Context Protocol) é um protocolo baseado em JSON-RPC 2.0 que permite que ferramentas de IA descubram e chamem funções de um programa externo. Na prática: em vez de você digitar geo-explorer trilha python, o agente de IA chama a ferramenta sozinho durante a conversa.

O servidor foi escrito à mão, sem SDK, para manter o projeto com zero dependências e deixar visível o que acontece em cada mensagem do protocolo.

Ferramentas expostas

Testando manualmente

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | geo-explorer-mcp

Configurando no Claude Desktop / Claude Code

Adicione ao arquivo de configuração MCP:

{
  "mcpServers": {
    "geo-explorer": {
      "command": "geo-explorer-mcp"
    }
  }
}

A documentação completa do protocolo, com exemplos de todas as mensagens, está em docs/mcp.md.

🧪 Como executar os testes

pip install -e ".[dev]"
pytest

74 passed in 0.12s

Outras formas de rodar:

pytest -v                        # saída detalhada
pytest tests/test_mcp_server.py  # só o servidor MCP
pytest -k certificado            # só o que menciona "certificado"

O que é testado

Vale destacar dois testes que pegam problemas de verdade na base de dados:

• test_carga_horaria_do_nivel_bate_com_a_soma_dos_modulos — impede que a carga horária declarada divirja da soma dos módulos ao adicionar uma trilha nova;

• test_toda_trilha_tem_desafio_em_cada_nivel — impede que uma trilha nova entre sem desafio em algum nível, o que quebraria o comando desafio.

🗂️ Estrutura do projeto

geo-explorer/
├── src/geo_explorer/
│   ├── data/trilhas.json      # base fictícia de trilhas e desafios
│   ├── commands/              # um arquivo por comando
│   │   ├── trilha.py
│   │   ├── desafio.py
│   │   └── certificado.py
│   ├── models.py              # dataclasses do domínio
│   ├── repository.py          # única camada que conhece o JSON
│   ├── formatters.py          # dicionário → texto do terminal
│   ├── errors.py              # exceções de domínio
│   ├── cli.py                 # interface de linha de comando
│   └── mcp_server.py          # servidor MCP (JSON-RPC sobre stdio)
├── tests/                     # 74 testes com pytest
├── docs/
│   ├── arquitetura.md
│   ├── mcp.md
│   └── base-de-dados.md
├── examples/                  # exemplos de uso e configuração
├── .claude/commands/          # slash commands para agentes de IA
└── .github/workflows/ci.yml   # testes automáticos a cada push

A decisão de arquitetura mais importante: os comandos devolvem dicionários, não texto. A formatação vive separada, em formatters.py. Foi isso que permitiu que a CLI e o servidor MCP compartilhassem exatamente a mesma lógica — o MCP entrega o texto formatado e o JSON estruturado na mesma resposta, sem duplicar uma linha de regra de negócio.

Mais detalhes em docs/arquitetura.md.

✨ Melhorias que eu fiz

Além do fluxo pedido no desafio (trilha, desafio, certificado e servidor MCP):

1. Comando listar — o desafio original não previa uma forma de descobrir o que existe na base. Sem ele, a pessoa precisa adivinhar o nome da trilha.

2. Busca tolerante — python, Python, PYTHON, Inteligência Artificial, inteligencia artificial e a tag frontend chegam à trilha certa. Normalizo removendo acento e caixa antes de comparar.

3. Mensagens de erro que ensinam — errar o nome da trilha devolve a lista das trilhas disponíveis, em vez de um "não encontrado" seco.

4. Flag --json global — todo comando pode ser consumido por script, jq ou outro programa.

5. Desafio reprodutível com --seed — sem isso, um comando que sorteia é impossível de testar de forma determinística.

6. Código de certificado determinístico — SHA-256 dos dados, no formato GEO-XXXX-XXXX-XXXX, com teste garantindo que muda se qualquer campo mudar.

7. Sugestão de próximo nível — ao final do plano de estudos, o comando indica qual é o passo seguinte e como pedi-lo.

8. Testes de consistência da base — não testam só o código, testam os dados: carga horária coerente, ids únicos, todo nível com desafio.

9. Zero dependências em runtime — o servidor MCP foi escrito à mão sobre JSON-RPC. Clona e roda, sem instalar nada.

10. CI no GitHub Actions — os testes rodam em Python 3.10, 3.11 e 3.12 a cada push.

11. Slash commands em .claude/commands/ — atalhos para usar o projeto de dentro de um agente de IA.

12. Três trilhas a mais que o mínimo — SQL, DevOps e IA, cada uma com 3 níveis e 6 desafios.

🎓 O que eu aprendi

Separar dados de apresentação vale mais do que parece. Comecei fazendo os comandos imprimirem direto na tela. Quando cheguei no servidor MCP, percebi que teria de reescrever tudo — o MCP precisa de dados estruturados, não de texto formatado. Refiz para que cada comando devolvesse um dicionário e a formatação virasse uma camada separada. A partir daí, adicionar o MCP custou quase nada: ele chama a mesma função da CLI.

Testar aleatoriedade exige projetar para isso. O comando desafio sorteia. Não dava para testar até eu adicionar o parâmetro seed e usar random.Random(seed) em vez do random global. Foi a primeira vez que mudei uma assinatura de função por causa do teste — e o resultado ficou melhor também para quem usa, porque agora dá para repetir um desafio específico.

MCP é mais simples do que o nome sugere. É JSON-RPC 2.0 sobre stdin/stdout: uma mensagem JSON por linha. Implementar initialize, tools/list e tools/call à mão me fez entender o protocolo de verdade, em vez de só configurar um SDK. Aprendi também uma distinção importante: erro de domínio (trilha inexistente) volta como resultado com isError: true, para o agente ler e corrigir; erro de protocolo (método desconhecido) volta como erro JSON-RPC.

Teste de dados pega o que teste de código não pega. O test_carga_horaria_do_nivel_bate_com_a_soma_dos_modulos falhou de verdade enquanto eu montava a base — eu tinha digitado uma carga horária que não batia com a soma dos módulos. O código estava certo; os dados é que estavam errados.

Revisar o que o agente escreve é parte do trabalho. Usei IA como apoio o tempo todo, mas cada arquivo passou por leitura minha. O ponto do desafio não é gerar muitos arquivos — é conseguir explicar cada escolha. Escrever este README foi o teste final disso: o que eu não conseguia explicar, eu não tinha entendido.

🤝 Créditos

Projeto desenvolvido por Guilherme Cintra para o desafio Construindo Seu Primeiro Produto com um Agente de IA da Digital Innovation One.

• GitHub: @GuiC1ntra

• LinkedIn: guilherme-cintr4

📄 Licença

MIT — use, estude e adapte à vontade.