Skip to content
Styling
miyagi

Model Context Protocol server · MIT

Miyagi

Wax on. Wax off.

A coding tutor that lives in your editor and refuses to do the work for you. It hands you the next command, explains it at your level, and turns every result into a lesson, narrated aloud by your own machine.

$ npx -y miyagi-mcp
Install from npmRead the source

The ladder

Commands earn 15 XP, correct quiz answers 25 with a streak multiplier, and level is simply XP over 100. Titles unlock on the way up. Progress is saved, so a restart costs nothing.

  • Terminal Novice

    Level 1

  • Shell Apprentice

    Level 3

  • CLI Artisan

    Level 6

  • Terminal Wizard

    Level 10

A real session

Watch it drill

Captured output, replayed. It runs a command, hands back a card, marks a quiz, then refuses to delete anything.

miyagi · live session

Example session. Command: echo drill. Output: # Miyagi · `echo drill` ## Roadmap Absolute Beginners → Command Line Basics Progress: [█░░░░░░░░░░░] step 1/10 ## Execution EXECUTED. Exit code 0 ✅ drill ## Quiz Which shell variable holds the exit code of the command that just finished? A. $? B. $! C. $0 D. $#

01

Setup

Three lines, any client

No API keys, no account, no sign-up. It runs entirely on your machine, so the only thing your client needs is permission to start it.

{
  "mcpServers": {
    "miyagi": {
      "command": "npx",
      "args": ["-y", "miyagi-mcp"]
    }
  }
}
ClientWhere it goes
Claude Desktop (macOS)~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)%APPDATA%\Claude\claude_desktop_config.json
Cursor.cursor/mcp.json, or ~/.cursor/mcp.json
AntiGravity / Windsurf~/.codeium/windsurf/mcp_config.json
Claude Codeclaude mcp add miyagi -- npx -y miyagi-mcp

Restart the client, then ask it something like “set my roadmap to Backend Developer and teach me docker compose config”.

02

What you get

Every command comes back as a lesson

Running the command is the cheap part. The card around it is the point: the same command at the depth you asked for, with the failure modes it actually invites.

  1. 01

    Roadmap alignment

    Where the command sits on your track, and which step you are on.

  2. 02

    What / How / Trade-offs

    The same command explained three ways, pitched at Junior, Mid or Senior.

  3. 03

    Mental model

    A Mermaid flowchart of what the shell actually does with it.

  4. 04

    Pitfalls

    The mistakes this command specifically invites, not generic advice.

  5. 05

    Curated docs

    A short set including the man page, rather than a search link.

  6. 06

    Active recall quiz

    One question you answer back, which is where the XP comes from.

03

Before you install it

It runs shell commands. Here is the honest version.

Anything that executes commands on your machine should be read before it is trusted, so this says what the protection is and, more usefully, where it stops.

Nothing catastrophic executes

Nine classes are pattern-matched and forced into dry-run: recursive delete, raw device writes, filesystem formats, fork bombs, disk overwrites, host power state, world-writable recursion, piping remote code into a shell, and history-rewriting force pushes.

The screen does not trust its caller

The tool accepts an is_dangerous flag but re-derives the verdict itself, then ORs the two. The threat model is a model reaching for a vivid example mid-lesson, not a careless human, so a flag the caller supplies cannot be the thing protecting you from the caller.

A denylist is a backstop, not a sandbox

The real boundary is your client’s own approval prompt, with you reading the command first. Commands run with your privileges in your directory: no container, no restricted user, no syscall filter.

Failures teach instead of crashing

A non-zero exit returns a diagnostic with a troubleshooting ladder rather than a thrown error. Commands cap at 60 seconds and 4 MB. No network calls, no telemetry, no keys.

Two runtime dependencies, the MCP SDK and zod, in one source file you can read in a sitting. Sixteen tests cover the danger screen and the saved-profile parser, and CI drives a real handshake on Node 18, 20 and 22.

04

Surface

Eight tools

Progress lives in ~/.miyagi/profile.json, so XP, streaks, badges and your position on a track survive a client restart.

  • run_teaching_command

    Execute or dry-run a command and return the full teaching card.

  • verify_quiz_answer

    Grade the quiz, update your streak and XP, speak the feedback.

  • get_next_roadmap_command

    The next copy-pasteable command for where you are.

  • set_active_roadmap

    Set category, roadmap, topic and step counters.

  • quick_config

    Switch skill level, track or voice in one call. Also resets progress.

  • configure_voice

    Toggle audio and set words per minute.

  • get_user_stats

    XP, level, title, streaks, badges and the title ladder.

  • export_roadmap_notes

    Write a ROADMAP_PROGRESS.md summary of the session.

05

Ask it yourself

Questions before you install

Ask Miyagi

Answers from the written record

It answers from what is actually written about this server and the rest of the site. If something is not in the record it says so rather than inventing it, which is the part worth testing.