miyagi
This server is a gamified, voice-enabled MCP coding tutor: it teaches shell commands through lessons, quizzes, checkpoints, and spaced repetition while safely executing or dry-running commands on your machine.
Configure learning preferences with
quick_config: skill level, category, roadmap, topic, voice on/off, words per minute, session mode (drill / ride-along / focus), and progress reset.Manage roadmaps: list tracks, set the active roadmap, and get the next copy-pasteable command with optional step advancement.
Run or dry-run shell commands through
run_teaching_command, returning a full teaching card (What/How/Trade-offs, diagram, pitfalls, docs, quiz) or a hotfix diagnostic on failure.Verify read-only checkpoints: prove a step's outcome exists, credit it once, advance the roadmap, and award XP.
Grade quiz answers by letter or text, updating streaks, XP, mastery, and spaced-repetition schedules.
Review due items: spaced-repetition sessions over learned questions and commands.
Get player stats: XP, level, title, streaks, badges, per-command mastery, weak spots, review queue, and lifetime totals, optionally spoken aloud.
Export roadmap notes to
ROADMAP_PROGRESS.md, session-scoped or lifetime, append or overwrite.Configure voice/audio settings (including a test phrase) through
quick_configor the legacyconfigure_voicetool.Read progress via resources like
miyagi://profile,miyagi://roadmap,miyagi://review,miyagi://history,miyagi://insights, and use prompts likedrill,review,explain-last-error, andprogress.Safety controls: catastrophic commands are refused, destructive commands need human confirmation, interactive/opaque commands are flagged or refused, with timeouts and output caps.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@miyagi Set my level to Junior and teach me `git rebase` with a quiz."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
๐ฅ miyagi
A patient, gamified, voice-enabled MCP coding tutor. You run the commands. It drills, corrects, catches the falls, and keeps score.
Overview and setup guide ยท How it was built ยท npm
Wax on, wax off. miyagi never does the work for you. It hands you the next command,
explains it at your level, and turns every result into a lesson. The default session mode
is ride-along: a short card, no inline quiz, no voice. Switch to drill when you want
the full teaching card โ What/How/Trade-offs, a mental model diagram, pitfalls, docs, an
active-recall quiz, and narration through your OS's own speech engine. What you get wrong
comes back on a spaced-repetition schedule until it sticks.
XP is for outcomes, not for tool calls. Most steps carry a checkpoint: a read-only probe that looks at your machine and confirms the thing you were asked to do actually exists. Running a command is worth 10 XP in drill (3 in ride-along, nothing in focus); a verified outcome is worth 30, once. You cannot farm a title by asking an assistant to call a tool.
Why it's safe to install
It runs shell commands on your machine, so it's built to be read before it's trusted.
Nothing catastrophic executes.
rm -rf /,mkfs,dd of=/dev/*, fork bombs,curl | shand history-wiping are pattern-matched and refused regardless of what the calling model claims. The screen defends against a confused AI, not just a careless user, which is why it re-derives the verdict instead of trusting theis_dangerousflag it was handed.A human confirms destructive commands, not a model.
confirm_dangerousused to be a flag the assistant filled in, which is not confirmation: a prompt-injected assistant sets it as easily as a careful one. Where your client supports elicitation, the server asks you, shows you the command, and requires you to typeRUN. The flag survives only as the fallback for clients that cannot prompt, and a failed or cancelled prompt means no.A denylist is a backstop, not a sandbox. The real boundary is your MCP client's own approval prompt, with you reading the command before it runs. The screen exists for the narrower case that prompt handles badly: something obviously destructive proposed to someone who is clicking through.
Failures teach instead of crashing. A non-zero exit returns a Hotfix Diagnostic with a troubleshooting ladder. The server never throws.
Bounded. 60-second timeout (raise it per call if you know better), 4 MB output cap, no network calls, no telemetry, no API keys, no accounts.
Interactive commands are refused, not timed out.
vim,npm run dev,tail -fand friends are recognised up front and handed back to you, rather than sitting in the queue until the timeout makes the tool look broken.Two tiers, not one. Catastrophic shapes (
rm -rf /,mkfs,curl | sh, fork bombs, wiping your shell history) never execute, with or without confirmation. Merely destructive ones (rm -rf build,git push --force,terraform destroy) are explained, dry-run, and executed only if you passconfirm_dangerous: true. One tier had a cost: a learner who genuinely needed to practiserm -rf buildhad to leave the tutor to do it, which teaches working around your own safety rail.It admits what it cannot see.
sh -c,evaland decoded payloads hide the real command from any pattern match, so they are flagged as opaque rather than waved through.Nothing is truncated silently. Output over the cap, a killed process, and a trimmed display all say so on the card. "That is all the output there was" is the one wrong conclusion a learner must never be led to.
Small enough to audit. Two runtime dependencies, the MCP SDK and zod. The MCP surface, the safety screen, the content pack, the quiz bank, scheduling, persistence, execution, speech, rendering and session modes are separate modules.
Related MCP server: geo-explorer
Install
Point your MCP client at npx and it fetches on first run:
npx -y miyagi-mcpOr install it globally, which gives you a miyagi command:
npm install -g miyagi-mcpgit clone https://github.com/c00p75/miyagi.git
cd miyagi
npm install
npm run build # emits dist/miyagi.js
npm testThen use "command": "node", "args": ["<ABS_PATH>/dist/miyagi.js"] in the config below.
Configure your MCP client
Three lines, the same everywhere. No keys, no accounts, and it all runs locally.
{
"mcpServers": {
"miyagi": {
"command": "npx",
"args": ["-y", "miyagi-mcp"]
}
}
}Where that goes:
Client | File |
Claude Desktop (macOS) |
|
Claude Desktop (Windows) |
|
Cursor |
|
AntiGravity / Windsurf |
|
For Claude Code, one command does it:
claude mcp add miyagi -- npx -y miyagi-mcpRestart the client, then try: "Set my roadmap to Backend Developer and teach me
docker compose config."
What's in it
Engine | What it does |
Teaching | A content pack with per-command lessons at three depths for 33 commands, so |
Checkpoints | Steps carry a read-only probe and a stated pass criterion, shown before you start. |
Spaced repetition | Every question you see and every command you run is scheduled on a Leitner ladder โ 10 minutes, 1, 3, 7, 16, 35 days. A correct answer promotes it; a slow-but-correct answer holds its box, because hesitant recall is weaker recall; a miss drops it to the front, not to zero. |
Model assistance | Optional, and strictly additive. If your client offers sampling, a prose answer that means the right thing is graded on meaning rather than string comparison โ and a model can only ever upgrade a verdict, never take away an answer that already matched. For a command the bank has never heard of, it writes a question, validates it as hard as a hand-written one, and caches it so the bank grows towards what you actually practise. |
Insights |
|
Streaks | Two of them. The quiz streak drives the XP multiplier; the practice-day streak counts consecutive calendar days, which is the habit hook a per-session number cannot be. The card tells you when today is the day you lose it. |
Mastery | Per-command attempt and success counts, so stats can say "you are 40% on |
Audio | A non-blocking FIFO queue, so lines never talk over each other. Markdown, URLs and emoji are stripped before anything is spoken, and the OS engine is probed before it's called, so a missing binary goes quiet instead of taking the server down. On Windows one PowerShell is kept alive rather than paying ~1s of |
Roadmap | Six built-in tracks with 26 checkpointed steps, plus your own: any JSON file in |
Windows | Tracks declare |
Gamification | Attempt XP follows the session mode (10 in drill, 3 in ride-along, 0 in focus), 30 for a verified outcome, 25 per correct quiz (30 for a review โ cold recall is the harder skill) with streak multipliers, |
Progress |
|
Safety | Two tiers, screened independently of the caller: catastrophic shapes never run, destructive ones need a human's confirmation. Checkpoint probes are screened too โ a "probe" that deletes something is not a probe, and a track file is where one would hide. |
Notes |
|
Speech engines
Platform | Engine |
macOS |
|
Windows | PowerShell |
Linux |
|
Linux users who want audio: sudo apt install speech-dispatcher.
Tools
quick_config: skill level (Junior/Mid/Senior), category, track, topic, voice on/off, words per minute, a test phrase, and session mode (drill/ride-along/focus), in one call.reset_progress: truewipes XP, streaks, mastery and the review queue back to first-run state. Call it with no arguments to read the current configuration. The default mode is ride-along: a short card, no inline quiz, no voice. Intensity is opted into withmode: "drill".list_roadmaps: every track, built-in and yours, with step counts and the JSON schema for authoring your own. Worth calling before you set a track name.set_active_roadmap: category, track, topic and step counters. An unknown name is reported with suggestions rather than substituted.get_next_roadmap_command: the next copy-pasteable command, withadvance: trueto step forward.run_teaching_command: execute or dry-run a command and return the teaching card. If the command is the current step and that step has a checkpoint, the outcome is verified afterwards and credited.timeout_msraises the 60-second cap;confirm_dangerousis the fallback for clients that cannot prompt you directly.verify_step: run the current step's read-only probe. Passing credits the outcome once and advances; failing says what is missing and leaves the step where it is.verify_quiz_answer: grade an answer by letter or by text, update streaks, XP, mastery and the review schedule. Takes thequiz_idfrom the card, or defaults to the most recent question.review_due_items: the spaced-repetition session โ everything whose interval has elapsed, most overdue first.get_user_stats: XP, level, title, both streaks, badges, per-command mastery, weak spots, review queue and lifetime totals.export_roadmap_notes: writeROADMAP_PROGRESS.md, session-scoped or lifetime.
All ten tools carry MCP annotations (readOnlyHint, destructiveHint, idempotentHint),
so a client can tell get_user_stats apart from run_teaching_command when it decides
what to prompt about.
Upgrading from 1.x:
configure_voiceis gone โ its three fields duplicatedquick_config, and two ways to set one value is one of them drifting. Voice settings, includingtest_phrase, now live inquick_config.Upgrading from 2.x: XP moved to outcomes. Drill still pays 10 XP for running a command (was 15); ride-along pays 3; a verified checkpoint is 30. The default mode is ride-along. Old profiles are migrated, not discarded.
Resources and prompts
Progress is readable without spending a tool call, so a client can render it in a sidebar:
Resource | What |
| XP, level, badges, both streaks, mastery, review queue |
| Active track, position, next command, full step list |
| Every scheduled item with its box, due date and lapses |
| The durable practice log, most recent 200 events |
| One track as markdown; the name autocompletes |
| Cadence by week, review accuracy, checkpoint pass rate, verdict |
| How the tutor works, and the order to do things in |
Subscribed clients get notifications/resources/updated when saved state moves, so a
sidebar is never showing a level you passed twenty minutes ago.
And four prompts, so nobody has to know tool names to start: drill (a guided session on
a track), review (spaced repetition over what is due), explain-last-error (teach from
a failure instead of fixing it), and progress (where am I, what is weak, what next).
Authoring your own track
Drop a JSON file in ~/.miyagi/roadmaps/. A step can be a bare command string or an
object with its own topic and note:
{
"name": "My Python Track",
"category": "Skill Based",
"description": "What this track teaches, in one line.",
"shell": "posix",
"steps": [
"python3 --version",
{
"command": "python3 -m venv .venv && . .venv/bin/activate",
"topic": "Isolated environments",
"note": "Never install into the system interpreter.",
"windows": "python -m venv .venv; .venv\\Scripts\\Activate.ps1",
"verify": {
"command": "test -x .venv/bin/python",
"describe": "a virtualenv exists at .venv"
}
}
]
}verifyis what makes a step earnable. It must be read-only: a probe that the danger screen objects to is dropped when the file is loaded, because a track file is exactly where somebody would hide one.containsadditionally requires a string in its output.windowsis the PowerShell equivalent, used automatically when aposixtrack is walked on Windows.shelldeclares what the commands are written for:posix,powershellorany.
list_roadmaps with reload: true picks up edits without a restart, and names any file
it had to skip โ a track silently ignored is worse than one that fails loudly.
Where progress lives
~/.miyagi/profile.json holds XP, level, both streaks, badges, per-command mastery, the
review queue, your skill level, voice settings and roadmap position. ~/.miyagi/history.jsonl
is the append-only practice log: one line per event, so a crash costs at most the line
being written and one corrupt line costs only itself. Override the directory with
MIYAGI_HOME, which is also how the tests keep away from a real profile.
The file is treated as untrusted on the way back in, because it's hand-editable and a crash can truncate it. Anything that fails to parse is discarded in favour of a fresh profile rather than raised as an error, values out of range are clamped instead of rejected, and level is recomputed from XP rather than read, so a file claiming level 99 at 40 XP gets corrected. A review item with an unreadable due date is treated as due now, which fails safe towards revision, and a streak nobody can date is not counted as a streak. Writes go to a temp file and are renamed, so an interrupted write leaves the previous profile intact. A 1.x profile is migrated rather than discarded: losing a learner's XP on upgrade would be the worse bug.
When something looks wrong
npx miyagi-mcp --doctorChecks the Node version, that commands can actually be executed, that the profile directory is writable, that a saved profile parses, which track files were skipped and why, whether any track is written for the wrong shell for this host, and whether a speech engine exists. Plain text on stdout โ the one mode where that is safe, because there is no protocol to corrupt. A warning is a working install; only a real failure exits non-zero.
Development
npm install
npm run typecheck
npm test # node:test, no test framework to install
npm run buildnpm run eval # the content rubric, the learner journey, and coverage parity
npm run doctor # after a buildnpm test runs 230-odd node:test cases. Three layers, and the top two are the ones that
find real bugs:
Unit โ persistence, scheduling, safety tiers, quiz selection, platform resolution.
End-to-end โ a test client that speaks real MCP over stdio, including answering elicitation prompts and serving sampling requests, so the human-confirmation and model-grading paths are exercised the way a client exercises them. It also throws on any non-JSON byte on stdout, which is how a stray
console.loggets caught.Eval โ a rubric over everything a learner can see: every lesson at every depth (boilerplate, specificity, does depth change anything), every question (does the answer leak, can it be won by picking the longest choice, does grading round-trip), every card every track can render, every diagram, plus a fuzz pass over malformed command lines.
That last layer earns its keep. It found a signed-integer bug in the choice shuffler that
rendered B. undefined for some seeds and not others โ intermittent by construction,
invisible to a single example, and caught immediately by sweeping the whole bank. It also
found that 29 of 35 questions could be answered by picking the longest choice.
CI runs typecheck, tests, a stdio handshake, --doctor, and an install-from-tarball check
against Node 18, 20 and 22.
Limits worth knowing
Commands run with your own privileges in your own directory. No container, no restricted user, no syscall filter. That's right for a local teaching tool driven by its owner, and it's the first thing to change if it ever accepts untrusted input.
Long-running or interactive commands belong in your own terminal. The common ones are recognised and refused; anything else meets the 60-second cap.
The pattern-based safety screen is a speed bump, not a sandbox.
sh -c "$(...)"defeats any denylist, which is why those shapes are flagged as opaque rather than trusted. The real boundary is your client's approval prompt with you reading the command.The content pack covers the commands the built-in tracks teach, enforced by a test. Everything else leans on the tutor brief and the model reading the card, which is honest but not offline.
A checkpoint proves the outcome exists, not that you produced it. Someone determined to cheat can create the directory by hand โ but at that point they have run a command, which was the entire objective.
Model-assisted grading and question generation need a client that offers sampling. Without one, grading is a string comparison and questions come from the bank.
Whether XP, streaks and spaced repetition actually keep someone on a roadmap is still an open question โ but it is now a measured one. Read
miyagi://insights: review accuracy against first-sight accuracy is the number that matters, and the report says so, including when there is not yet enough evidence to say anything at all.
Learn more
Overview and setup guide walks through what a teaching card contains, the config for each client, and where the safety model stops.
How it was built is the engineering write-up: why the danger screen ignores its caller, why it uses a transport that cannot be hosted, and what the design gives up.
Issues and pull requests are welcome. If you use it and it teaches you nothing, that is a bug worth reporting.
License
MIT
Available Tools
8 toolsconfigure_voiceConfigure VoiceA
Toggle tutor audio on/off and adjust the speech rate in words per minute.
Inputs: enabled, test_phrase, words_per_minute.
export_roadmap_notesExport Roadmap NotesA
Write a clean ROADMAP_PROGRESS.md summary of the session: roadmap position, player stats, and every concept and command covered.
Inputs: append, output_path.
get_next_roadmap_commandGet Next Roadmap CommandB
Suggest the next copy-pasteable terminal command for the active roadmap milestone. Optionally advance the step counter.
Inputs: advance.
get_user_statsGet User StatsA
Return the current player profile: XP, level, title, quiz streak, unlocked badges, and roadmap progress.
Inputs: speak.
quick_configQuick ConfigC
Instantly switch the target skill level (Junior/Mid/Senior), roadmap category, roadmap track, or topic via simple key-value parameters.
Inputs: category, skill_level, roadmap_name, current_topic, +3 more.
run_teaching_commandRun Teaching CommandA
Execute (or dry-run) a shell command and return a full teaching card: roadmap alignment, level-appropriate What/How/Trade-offs, a Mermaid flowchart, pitfalls, curated docs, and an active-recall quiz. Errors return a Tutor Hotfix Diagnostic instead of throwing.
Inputs: command (required), cwd, concept, dry_run, +1 more.
set_active_roadmapSet Active RoadmapC
Configure the active roadmap: category, roadmap name, current topic node, and progress step counters.
Inputs: category (required), roadmap_name (required), current_topic (required), step_index, +1 more.
verify_quiz_answerVerify Quiz AnswerA
Evaluate the learner's answer to the most recent active-recall quiz. Updates streak, XP and badges, and speaks feedback.
Inputs: answer (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 8 tools
Tools are mostly distinct, but quick_config and set_active_roadmap both handle roadmap configuration, which could cause confusion about which to use for what. Other tools like verify_quiz_answer and run_teaching_command have clear, separate purposes.
Most tools follow a verb_noun snake_case pattern (verify_quiz_answer, set_active_roadmap, get_user_stats), but 'quick_config' deviates with an adjective prefix and lacks a clear noun, breaking the pattern slightly.
Eight tools is well within the ideal range for a focused tutoring server. Each tool covers a distinct aspect of the tutor workflowโconfig, teaching, quiz, stats, exportโwith no redundancy or excessive bloat.
The tool set covers core tutor functions: configuration, teaching, assessment, progress tracking, and export. Minor gaps exist, such as no explicit tool to list available topics or manage user preferences beyond voice, but agents can work around these.
Maintenance
Related MCP Connectors
Open-source AI courses taught by your AI tutor in conversation, with progress saved by MCP tools.
Let your coding agent read your GameSalad projects, and edit them live in Creator on Pro and Edu.
Language coaching in Codex with durable per-account memory on en-ai.ru.
Remote MCP learning coach for coding agents.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables interactive LeetCode practice with AI-guided authentication, problem solving, solution submission, and learning mode.2471 npm12MIT
- AlicenseAqualityCmaintenanceEnables querying structured study plans, code challenges, and ASCII certificates for JavaScript, Python, and TypeScript tracks at beginner or advanced levels via natural language.3MIT
- FlicenseNot gradedqualityCmaintenanceEnables an active learning tutor that runs in MCP clients like Codex or Claude Code, letting the AI create and manage lessons, read student attempts, and give feedback while the student practices in a local browser panel.-
- AlicenseAqualityBmaintenanceEnables chat assistants to insert graded coding exercises (Python, JavaScript, TypeScript, SQL) with hidden tests, and returns failed attempts to the conversation so the tutor can explain the learner's specific mistake.17 npmMIT