Skip to main content
Glama
geo-explorer

geo-explorer

by juanidives

Geo-Explorer

什么是 Geo-Explorer

Geo-Explorer 是一个虚构的学习平台,灵感来自 DIO (Digital Innovation One)。该项目模拟了一个学习路径系统,包含代码挑战和证书颁发。

它作为以下内容的学习基础:

  • 使用 TypeScript 开发 CLI 工具

  • 构建一个 MCP Server,将平台逻辑作为可由 AI 代理(Bob、Claude Desktop、Cursor 等)调用的工具暴露出来

  • 在 Bob 中定义本地斜杠命令,以便直接在聊天中触发工具

  • 练习单元测试,覆盖率 100%


Related MCP server: LearnFlow AI

项目结构

geo-explorer/
│
├── commands/               # Comandos CLI executáveis via npm run
│   ├── lib/
│   │   └── trilhas.ts      # Leitura de data/trilhas_dio.json e função findTrilha()
│   ├── trilha.ts           # /trilha <tecnologia>
│   ├── desafio.ts          # /desafio <tecnologia> [nivel]
│   └── certificado.ts      # /certificado --nome "<nome>" --tech "<tecnologia>" (flags) ou posicional
│
├── data/
│   └── trilhas_dio.json    # Base de dados com 35 trilhas DIO
│
├── mcp/                    # MCP Server (pacote independente)
│   ├── src/
│   │   └── index.ts        # Entry-point do servidor MCP (stdio transport)
│   ├── build/              # Saída compilada (gerada por npm run build, não versionada)
│   ├── package.json
│   ├── tsconfig.json
│   └── README.md           # Documentação específica do servidor MCP
│
├── tests/                  # Testes unitários (Vitest)
│   ├── trilha.test.ts
│   ├── desafio.test.ts
│   └── certificado.test.ts
│
├── .bob/
│   ├── commands/           # Slash commands locais do Bob
│   │   ├── trilha.md
│   │   ├── desafio.md
│   │   └── certificado.md
│   ├── mcp.example.json    # Template de registro do MCP Server (versionado)
│   └── mcp.json            # Configuração local do MCP Server (não versionada)
│
├── package.json
├── tsconfig.json
└── vitest.config.mts

如何运行

先决条件

  • Node.js ≥ 18

  • npm ≥ 9

安装

# Na raiz do projeto
npm install

# Para o servidor MCP (pacote separado)
cd mcp
npm install

构建(类型检查)

# Raiz — verifica os tipos sem emitir arquivos
npm run build

# MCP Server — compila TypeScript para JavaScript em mcp/build/
cd mcp
npm run build

在注册 MCP 服务器之前,至少需要执行一次构建。


如何使用命令

三个 CLI 命令通过项目根目录下的 npm run 执行。


/trilha <tecnologia>

根据技术名称(或名称的一部分)显示完整的学习路径计划。搜索是不区分大小写的,并接受部分匹配。

npm run trilha -- javascript

输出:

╔══════════════════════════════════════════════════════╗
  🎯  PLANO DE ESTUDOS — JAVASCRIPT DEVELOPER
╚══════════════════════════════════════════════════════╝

  Tecnologia   : JavaScript
  Nível        : Básico
  Total de XP  : 12.000 XP
  Acesso       : Por período
  Promoção     : ✅ Disponível
  Lives ao vivo: 4

── MÓDULOS ──────────────────────────────────────────
  1. Fundamentos de JavaScript e ambiente de execução
  2. Tipos de dados, variáveis e operadores
  3. Estruturas de controle e funções
  4. Manipulação do DOM e eventos
  5. ES6+: arrow functions, promises e async/await
  6. Projeto final: aplicação web interativa

── BADGES DISPONÍVEIS ───────────────────────────────
  🏅 JS Fundamentals
  🏅 DOM Master
  🏅 ES6+ Hero

  Bons estudos! 🚀

/desafio <tecnologia> [nivel]

生成一个随机的代码挑战。nivel 参数是可选的;省略时,使用路径中注册的级别。级别可接受的值:básico、intermediário、avançado(带或不带重音符号,不区分大小写)。

# Sem nível (usa o nível da trilha)
npm run desafio -- typescript

# Com nível explícito
npm run desafio -- python avançado

输出(示例):

╔══════════════════════════════════════════════════════╗
  ⚔️   DESAFIO DE CÓDIGO — TYPESCRIPT
╚══════════════════════════════════════════════════════╝

  Nível      : Intermediário
  Trilha base: Formação TypeScript Fullstack

── ENUNCIADO ────────────────────────────────────────

  Implemente uma classe Stack (pilha) com os métodos push, pop, peek e isEmpty.

── CRITÉRIOS DE AVALIAÇÃO ───────────────────────────

  ✔  Código legível e bem estruturado
  ✔  Tratamento de casos extremos (edge cases)
  ✔  Complexidade de tempo e espaço adequada ao nível
  ✔  Testes mínimos demonstrando o funcionamento

  Boa sorte! 💪

/certificado

以 Markdown 格式颁发虚构证书。证书 ID 是确定性的——由学生姓名和路径 ID 生成。

该命令接受两种参数传递方式:

# Forma recomendada — flags explícitas; cada flag coleta todos os tokens
# até a flag seguinte, então valores com espaços funcionam normalmente
npm run certificado -- --nome "Maria Silva" --tech "TypeScript"
npm run certificado -- --nome "Ana Lima" --tech "Data Science"

# Forma posicional — o primeiro argumento vira nome e o segundo vira tecnologia;
# aspas fazem o shell entregar cada valor como um único elemento de argv,
# então espaços dentro de cada valor funcionam normalmente
npm run certificado -- "Ana Lima" "TypeScript"
npm run certificado -- "Ana" "Data Science"

在位置形式中,解析器期望恰好两个参数(argv[0] → 姓名,argv[1] → 技术)。如果您更喜欢更明确的语法,或者想避免依赖 shell 引号,请使用 --nome 和 --tech 标志。

输出(Markdown 格式):

# 🎓 CERTIFICADO DE CONCLUSÃO

---

**A Digital Innovation One certifica que**

## Maria Silva

**concluiu com êxito a trilha:**

# Formação TypeScript Fullstack

---

| Campo              | Detalhe                            |
|--------------------|------------------------------------|
| **Tecnologia**     | TypeScript                         |
| **Nível**          | Intermediário                      |
| **Módulos**        | 9 módulos concluídos               |
| **XP conquistado** | 22.000 XP                          |
| **Lives ao vivo**  | 6 aulas                            |
| **Emitido em**     | <data de hoje>                     |
| **Certificado ID** | `DIO-002-XXXXXXXX`                 |

---

### Badges conquistadas

- 🏅 TS Beginner
- 🏅 TS Advanced
- 🏅 Fullstack Badge

重定向到文件: npm run certificado -- --nome "Maria Silva" --tech "TypeScript" > certificado.md


如何在 Bob 的聊天中使用

该项目在 .bob/commands/ 中定义了三个本地斜杠命令。在 Bob 中打开项目后,它们可直接在聊天中使用:

命令

语法

功能

/trilha

/trilha <tecnologia>

执行 commands/trilha.ts 并显示学习计划

/desafio

/desafio <tecnologia> [nivel]

执行 commands/desafio.ts 并显示生成的挑战

/certificado

/certificado "<nome>" "<tecnologia>"

执行 commands/certificado.ts 并渲染证书

聊天中的使用示例:

/trilha react
/desafio java intermediário
/certificado "Ana Lima" "Data Science"

Bob 解释参数,构建正确的命令,并在聊天中显示格式化输出。


如何运行测试

# Executa os testes sem cobertura
npm test

# Executa os testes com relatório de cobertura
npm run test:coverage

当前结果

 ✔ tests/trilha.test.ts        (14 testes)
 ✔ tests/certificado.test.ts   (24 testes)
 ✔ tests/desafio.test.ts       (20 testes)

 Test Files  3 passed (3)
      Tests  58 passed (58)
   Duration  1.71s

 % Coverage report from v8
------------------|---------|----------|---------|---------|
 File             | % Stmts | % Branch | % Funcs | % Lines |
------------------|---------|----------|---------|---------|
 All files        |     100 |      100 |     100 |     100 |
  commands        |     100 |      100 |     100 |     100 |
   certificado.ts |     100 |      100 |     100 |     100 |
   desafio.ts     |     100 |      100 |     100 |     100 |
   trilha.ts      |     100 |      100 |     100 |     100 |
  commands/lib    |     100 |      100 |     100 |     100 |
   trilhas.ts     |     100 |      100 |     100 |     100 |
------------------|---------|----------|---------|---------|

Statements : 100% (49/49) | Branches : 100% (28/28) | Functions : 100% (14/14) | Lines : 100% (43/43)

MCP Server

它暴露了什么

位于 mcp/src/index.ts 的 MCP 服务器直接复用 commands/ 中命令的逻辑,并暴露四个工具:

工具

参数

描述

listar_tecnologias

(无)

列出所有可用技术及其级别和总 XP

buscar_trilha

tecnologia (string)

返回某项技术的完整学习计划

gerar_desafio

tecnologia (string), nivel (可选)

生成一个随机的代码挑战

gerar_certificado

nome (string), tecnologia (string)

以 Markdown 格式颁发证书

使用的传输方式是 stdio——服务器由 MCP 客户端作为子进程启动。

如何在 Bob 中注册

  1. 构建服务器(仅需一次):

    cd mcp
    npm install
    npm run build
  2. 复制配置模板:

    cp .bob/mcp.example.json .bob/mcp.json
  3. 编辑 .bob/mcp.json,将路径替换为您机器上的绝对路径:

    {
      "mcpServers": {
        "geo-explorer": {
          "command": "node",
          "args": ["/caminho/absoluto/para/geo-explorer/mcp/build/mcp/src/index.js"]
        }
      }
    }
  4. Bob 会在保存文件时自动重新加载 MCP 服务器。之后,geo-explorer 将作为已连接的服务器出现在 Bob 的 MCP 面板中。

.bob/mcp.json 文件位于 .gitignore 中——每个开发者在本地维护自己的绝对路径。


已完成的改进

手动测试中发现的修复

在验证超出正常路径的命令时,出现了两个初始测试未捕获的缺陷:

  • 当技术名称中包含空格("Data Science")时,/certificado 会卡住。解析依赖于参数的位置,无法区分姓名在哪里结束。已通过显式的 --nome 和 --tech 标志修复,同时保留位置模式作为回退。

  • /trilha 显示 "Módulo 1, Módulo 2..." 而不是真实名称。代码根据 numero_de_modulos 字段生成标签,而忽略了 JSON 中的 modulos 数组——数据是正确的,是消费数据的人没有读取它。

  • findTrilha 对空输入返回目录中的第一条路径,因为 "".includes("") 始终为真。验证存在于 CLI 中,但不存在于 MCP 服务器中,Zod schema 接受空格字符串。已在源头修复。

实测覆盖率而非估算

目标是 70% 的覆盖率。我没有断言一个数字,而是配置了 Vitest 的 v8 provider 来实际测量,报告写入文件,并提供了可复现的 npm 脚本。CLI 入口点以明确的理由被排除在计算之外,剩余发现的分支都得到了测试。结果:可测试逻辑上 100% 覆盖率,59 个测试。

纯逻辑与 I/O 的分离

每个命令都被重构为两层:导出的纯函数和由 require.main === module 守卫隔离的 run() 函数。这使得代码无需 mock process.argv 即可测试,并允许 MCP 服务器导入相同的逻辑而无需重复。

本地配置不纳入版本控制

.bob/mcp.json 需要机器的绝对路径。我没有将只在我电脑上有效的路径纳入版本控制,而是将带占位符的 .bob/mcp.example.json 纳入版本控制,并忽略了实际文件——与 .env.example 相同的模式。

对生成文档的审查

代理生成的文档被逐行审查,其中包含不准确之处:路径数量错误(15 而不是 35)、与代码不符的解析器描述,以及一个将冗余字段合理化而不是承认权衡的建模理由。所有内容都已对照代码进行了修正。


我学到了什么

  • 代理生成速度快,但不会验证。 有效的循环始终相同:请求、阅读输出、测试错误路径、修复。这个项目的三个 bug 都出现在手动测试中,从未出现在代理报告为完成的内容中。它两次错误地描述了自己的解析器——描述的是意图,而不是代码。

  • 声称的数字不是测量的数字。 参考项目声称 100% 覆盖率,却没有安装任何覆盖率工具。这就是说与证明之间的区别,而且只有有人去查才会显现。

  • 默认安全通常是最弱的选择。 原始指令要求使用 credential.helper store,它会将令牌以纯文本形式写入磁盘。我换成了 Git Credential Manager,它以加密存储满足相同要求。GitHub 令牌保存在用户环境变量中,从未出现在项目文件中——这一决定也符合挑战中不向仓库提交凭据的指导。

  • 记录决策不同于记录代码。 ARQUITETURA.md 只有在每个部分都记录问题、被放弃的替代方案和选择理由后才变得有用。描述代码做什么是多余的——代码已经在那里了。

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
      D
      maintenance
      A comprehensive learning platform for Model Context Protocol development that teaches MCP concepts through hands-on modules including text processing, file operations, and database integration. Designed as an educational tool with progressive difficulty levels from basic to advanced MCP server development.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      AI-powered MCP server that transforms learning by finding best YouTube tutorials, generating personalized learning paths, and tracking progress for any tech skill.
      11
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that exposes certifications, projects, and an AI engineering learning roadmap as callable tools for MCP clients like Claude Desktop.
      4
      1
      MIT