Tutor — MCP server para Developer Docs de Z2H Academy

Qué es

tutor es un harness/agente que expone los Developer Docs (MDs de los roadmaps) a TUIs agentic (OpenCode hoy; Codex y Claude Code en el futuro) vía el protocolo MCP.

Los MDs viven en un storage S3-compatible (MinIO en la VPS de producción, https://minio.z2h-academy.com). El LLM de la TUI los consume directamente — no las secciones TSX del web, que al contener componentes React consumen más tokens y no son la fuente de verdad operativa.

Related MCP server: MCP Enhanced Data Retrieval System

Por qué existe

La academia tiene dos representaciones del contenido:

El estudiante ejecuta labs en local siguiendo al pie de la letra las instrucciones del MD. tutor es el puente que le da al LLM acceso a ese contenido sin pasar por el pipeline de renderizado.

Estado actual

v0.3.0 — auth por estudiante en producción. Una sola tool (tutor_get_section), MinIO en la VPS (https://minio.z2h-academy.com, bucket roadmaps), auth por estudiante con device flow de GitHub + Edge Function de provisioning en Supabase (service account read-only por estudiante). Flujo end-to-end validado desde el entorno Sysbox canónico (SMOKE PASS).

Arquitectura

OpenCode / Codex / Claude Code
        │
        ▼  MCP (stdio)
      tutor
        │  @aws-sdk/client-s3 (S3-compatible, forcePathStyle)
        ▼
      MinIO (VPS producción, HTTPS vía Caddy)
        │
        ▼
  roadmaps/{roadmap}/{level}/{section}.md

Detalle completo en docs/ARCHITECTURE.md.

Stack

• Node 20 + TypeScript 5 (ESM)

• @modelcontextprotocol/sdk (protocolo MCP)

• @aws-sdk/client-s3 (cliente S3-compatible para MinIO)

• zod (validación de input de tools)

Estructura

tutor/
├── scripts/
│   ├── seed.ts          # crea bucket + sube un MD de prueba (contra VPS)
│   └── smoke.ts         # test JSON-RPC end-to-end del server
└── src/
    ├── index.ts         # entrypoint MCP (stdio transport)
    ├── server.ts        # instancia McpServer
    ├── storage.ts       # cliente S3/MinIO
    └── tools/
        └── get-section.ts  # tool: tutor_get_section

Setup (para un estudiante)

# 1. Dependencias
npm install

# 2. Autenticación (device flow de GitHub, una vez)
npm run build && node dist/cli/login.js
# → abre https://github.com/login/device, ingresá el código, autorizá
# → guarda credenciales en ~/.config/z2h/tutor.env (perms 600)

# 3. Correr el MCP server (stdio)
npm run dev

Para probar el loop completo sin OpenCode:

npm run smoke

Infraestructura: MinIO corre en la VPS de producción (~/tutor-minio/ en 62.238.103.174, ver docs/VPS.md). No hay MinIO local. Para el estudiante, ver docs/STUDENT-SETUP.md.

Tools

Convención de paths en el bucket:

roadmaps/{roadmap}/{level}/{section}.md

Ejemplo: roadmaps/data-engineering/nivel-0/1-section.md

Env vars

Próximos pasos

• Cómo extender el server: docs/DEVELOPMENT.md

• Decisiones tomadas, diferidas y riesgos: docs/DECISIONS.md