Skip to main content
Glama

Geo-Explorer

Geo-Explorer is a learning-track exploration tool that gives you structured study plans, hands-on code challenges, and printable certificates for three technologies: JavaScript, Python, and TypeScript — each at beginner (iniciante) or advanced (avancado) level.

All track data lives in a local JSON file (data/tracks.json). There are no external API calls — everything is static and self-contained.

The project exposes its functionality through two surfaces:

  • CLI — run commands directly from the terminal with npm run cli

  • MCP Server — register it in any MCP-compatible client (e.g. Claude Desktop) and call the same three tools via natural language


Prerequisites

  • Node.js 18+ (tested on v24)

  • npm 8+


Related MCP server: miyagi

Installation

git clone https://github.com/your-username/geo-explorer.git
cd geo-explorer
npm install

CLI Usage

All CLI commands use the npm run cli -- prefix followed by a sub-command and its arguments.

trilha — Study plan

Prints an ordered list of modules for a given technology and level.

npm run cli -- trilha javascript iniciante
npm run cli -- trilha python avancado
npm run cli -- trilha typescript iniciante

desafio — Code challenge

Prints the challenge title, description, and a starter code block for a given track.

npm run cli -- desafio javascript iniciante
npm run cli -- desafio python avancado
npm run cli -- desafio typescript avancado

certificado — Certificate

Generates an ASCII certificate for a learner's name, technology, and level.

npm run cli -- certificado "Maria Silva" javascript iniciante
npm run cli -- certificado "João Costa" python avancado
npm run cli -- certificado "Ana Lima" typescript iniciante

Help

npm run cli -- help

MCP Server

The MCP server exposes the same three commands (trilha, desafio, certificado) as MCP tools over stdio, so any MCP-compatible client can call them.

Build the project first:

npm run build

This compiles TypeScript to dist/ and produces dist/mcp-server.js.

Run the server:

npm start

The server stays running and listens for MCP messages on stdin/stdout. See docs/mcp-setup.md for instructions on registering it in Claude Desktop or another MCP client.


Running Tests

npm test

Runs all 9 Vitest tests across three test files (track, challenge, certificate). Tests run against the real data/tracks.json — no mocking required.

Available Tools

3 tools
certificadoC

Gera um certificado de conclusão para o aprendiz.

Inputs: name (required), level (required), technology (required).

desafioA

Retorna o desafio de código para uma tecnologia e nível.

Inputs: level (required), technology (required).

trilhaB

Retorna o plano de estudos para uma tecnologia e nível.

Inputs: level (required), technology (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool targets a distinct artifact: study plan, code challenge, and certificate. There is no overlap or ambiguity between the three.

    Naming Consistency5/5

    All tool names follow the same pattern: single lowercase Portuguese nouns (trilha, desafio, certificado). The naming is uniform and predictable.

    Tool Count4/5

    Three tools is slightly minimal but appropriate for a focused learning-oriented server. The count is not bloated, though more tools could expand the scope.

    Completeness4/5

    The core journey of study plan, coding challenge, and certificate is covered. Minor gaps exist, such as no tool for listing available technologies/levels or tracking progress, but they are not fatal.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers