🥋 miyagi

Un tutor de codificación MCP paciente, gamificado y con voz. Tú ejecutas los comandos. Él perfora, corrige, atrapa las caídas y lleva la puntuación.

Cera en, cera fuera. miyagi nunca hace el trabajo por ti. Te entrega el siguiente comando, te lo explica a tu nivel y convierte cada resultado en una lección. Cada ejecución vuelve como una tarjeta didáctica: dónde estás en la hoja de ruta, un desglose de Qué/Cómo/Compensaciones adaptado a tu experiencia, un modelo mental en Mermaid, los errores que muerden a la gente, documentación curada y un cuestionario de recuerdo activo. Todo narrado a través del motor de voz de tu propio sistema operativo.

Por qué es seguro instalarlo

Ejecuta comandos de shell en tu máquina, así que está diseñado para ser leído antes de ser confiado.

• Nada catastrófico se ejecuta. rm -rf, dd of=/dev/*, bombas fork, curl | sh, push forzados y chmod -R 777 se detectan por patrones y se fuerzan a modo de prueba independientemente de lo que afirme el modelo que lo llama. La pantalla defiende contra una IA confundida, no solo contra un usuario descuidado, por eso vuelve a derivar el veredicto en lugar de confiar en la bandera is_dangerous que se le entregó.

• Una lista de denegación es un respaldo, no una caja de arena. El límite real es el propio prompt de aprobación de tu cliente MCP, con tú leyendo el comando antes de que se ejecute. La pantalla existe para el caso más estrecho en que ese prompt maneja mal: algo obviamente destructivo propuesto a alguien que está haciendo clic sin mirar.

• Los fallos enseñan en lugar de estrellarse. Una salida no cero devuelve un Diagnóstico de Hotfix con una escalera de solución de problemas. El servidor nunca lanza excepciones.

• Acotado. Timeout de 60 segundos, límite de salida de 4 MB, sin llamadas de red, sin telemetría, sin claves de API, sin cuentas.

• Lo suficientemente pequeño para auditar. Dos dependencias de ejecución, el SDK de MCP y zod, en un solo archivo fuente que puedes leer en una sentada.

Related MCP server: EduChain MCP Server

Instalación

Apunta tu cliente MCP a npx y lo obtiene en la primera ejecución:

npx -y miyagi-mcp

O instálalo globalmente, lo que te da un comando miyagi:

npm install -g miyagi-mcp

git clone https://github.com/c00p75/miyagi.git
cd miyagi
npm install
npm run build      # emits dist/miyagi.js
npm test

Luego usa "command": "node", "args": ["<ABS_PATH>/dist/miyagi.js"] en la configuración de abajo.

Configura tu cliente MCP

Tres líneas, igual en todas partes. Sin claves, sin cuentas, y todo se ejecuta localmente.

{
  "mcpServers": {
    "miyagi": {
      "command": "npx",
      "args": ["-y", "miyagi-mcp"]
    }
  }
}

Dónde va eso:

Para Claude Code, un comando lo hace:

claude mcp add miyagi -- npx -y miyagi-mcp

Reinicia el cliente, luego prueba: "Pon mi hoja de ruta en Desarrollador Backend y enséñame docker compose config."

Qué contiene

Motores de voz

Usuarios de Linux que quieran audio: sudo apt install speech-dispatcher.

Herramientas

• quick_config: cambia el nivel de habilidad (Junior/Mid/Senior), categoría, pista, tema o voz en una sola llamada. Pasa reset_progress: true para borrar el XP guardado y volver al estado inicial.

• set_active_roadmap: establece categoría, hoja de ruta, tema y contadores de paso

• get_next_roadmap_command: el siguiente comando listo para copiar y pegar, con advance: true para avanzar un paso

• configure_voice: activa o desactiva el audio, establece palabras por minuto, habla una frase de prueba

• get_user_stats: XP, nivel, título, rachas, insignias, escalera de títulos

• run_teaching_command: ejecuta o prueba un comando y devuelve la tarjeta didáctica

• verify_quiz_answer: califica el cuestionario, actualiza racha y XP, habla la retroalimentación

• export_roadmap_notes: escribe ROADMAP_PROGRESS.md

Dónde vive el progreso

~/.miyagi/profile.json, que contiene XP, nivel, rachas, insignias, tu nivel de habilidad, configuración de voz y posición en la hoja de ruta. Sobrescribe el directorio con MIYAGI_HOME, que es también cómo las pruebas se mantienen alejadas de un perfil real.

El archivo se trata como no confiable al volver a entrar, porque es editable a mano y un bloqueo puede truncarlo. Cualquier cosa que no se pueda analizar se descarta en favor de un perfil nuevo en lugar de lanzarse como error, los valores fuera de rango se recortan en lugar de rechazarse, y el nivel se recalcula desde el XP en lugar de leerse, así que un archivo que afirma nivel 99 con 40 XP se corrige. Las escrituras van a un archivo temporal y se renombran, así que una escritura interrumpida deja el perfil anterior intacto.

Desarrollo

npm install
npm run typecheck
npm test           # node:test, no test framework to install
npm run build

CI ejecuta typecheck, pruebas y un apretón de manos stdio real contra Node 18, 20 y 22.

Límites que vale la pena conocer

• Los comandos se ejecutan con tus propios privilegios en tu propio directorio. Sin contenedor, sin usuario restringido, sin filtro de syscall. Eso es correcto para una herramienta de enseñanza local manejada por su dueño, y es lo primero que cambiaría si alguna vez acepta entrada no confiable.

• Los comandos de larga duración o interactivos pertenecen a tu propia terminal. El límite de 60 segundos los cortará.

• Si el XP y las rachas realmente mantienen a alguien en una hoja de ruta es una pregunta abierta. El archivo de progreso es lo que la hace respondible.

Licencia

MIT