# 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+**

---

## Installation

```bash
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.

```bash
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.

```bash
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.

```bash
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

```bash
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:**

```bash
npm run build
```

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

**Run the server:**

```bash
npm start
```

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

---

## Running Tests

```bash
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.