Skip to main content
Glama
deenesjakoruzh
c00p75

miyagi

by c00p75
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

🥋 miyagi

A patient, gamified, voice-enabled MCP coding tutor. You run the commands. It drills, corrects, catches the falls, and keeps score.

CI npm license

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 | sh and 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 the is_dangerous flag it was handed.

  • A human confirms destructive commands, not a model. confirm_dangerous used 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 type RUN. 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 -f and 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 pass confirm_dangerous: true. One tier had a cost: a learner who genuinely needed to practise rm -rf build had to leave the tutor to do it, which teaches working around your own safety rail.

  • It admits what it cannot see. sh -c, eval and 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: MCP Walkthrough

Install

Point your MCP client at npx and it fetches on first run:

npx -y miyagi-mcp

Or install it globally, which gives you a miyagi command:

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

Then 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)

~/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 globally

AntiGravity / Windsurf

~/.codeium/windsurf/mcp_config.json

For Claude Code, one command does it:

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

Restart 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 pwd, git rebase and terraform apply get three different lessons rather than the same boilerplate. A test walks every track step and fails the build if a taught command has no lesson. Anything genuinely uncovered comes with a tutor brief: the card tells the model what to teach, with the command, the real output and your depth already in hand.

Checkpoints

Steps carry a read-only probe and a stated pass criterion, shown before you start. verify_step runs it, credits the outcome once, and advances. A near-miss command does not claim the XP, and re-passing pays nothing.

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. review_due_items is what turns the XP into retention.

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

miyagi://insights answers the question the README used to ask rhetorically: practice cadence by week, first-sight accuracy against review accuracy, checkpoint pass rates, and a verdict that refuses to claim anything on thin evidence.

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 git rebase over 8 attempts" rather than just showing a level. Weaknesses need three attempts before they are called weaknesses; two attempts at 50% is noise.

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 Add-Type startup per line.

Roadmap

Six built-in tracks with 26 checkpointed steps, plus your own: any JSON file in ~/.miyagi/roadmaps/ becomes a track, and one named after a built-in shadows it. An unknown track name is reported, not silently swapped for Command Line Basics. Every track declares the shell it was written for.

Windows

Tracks declare posix or powershell. On a mismatched host, a step with a PowerShell equivalent is substituted and labelled, then executed through powershell.exe — not cmd.exe. Checkpoints have PowerShell probes too. A step without an alternative gets an explicit warning instead of a command line that is known to fail. Silence was the bug.

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, Level = floor(XP/100) + 1, four titles, streak and practice-day badges.

Progress

~/.miyagi/profile.json for state, plus an append-only history.jsonl for the practice log, so a note export after a restart describes what you actually did instead of an empty session. Saves merge with what is on disk, so two clients cannot roll each other's XP backwards: counters take the higher total, badges union, and verified checkpoints are never dropped. Parallel sessions that each earn XP from the same baseline keep the larger score, not the sum.

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

ROADMAP_PROGRESS.md export with quiz accuracy, weak spots, what is due for review, and the full log — session-scoped or lifetime.

Speech engines

Platform

Engine

macOS

say -r <wpm>

Windows

PowerShell System.Speech.Synthesis.SpeechSynthesizer

Linux

spd-say, falling back to espeak-ng, espeak then festival

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: true wipes 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 with mode: "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, with advance: true to 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_ms raises the 60-second cap; confirm_dangerous is 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 the quiz_id from 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: write ROADMAP_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_voice is gone — its three fields duplicated quick_config, and two ways to set one value is one of them drifting. Voice settings, including test_phrase, now live in quick_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

miyagi://profile

XP, level, badges, both streaks, mastery, review queue

miyagi://roadmap

Active track, position, next command, full step list

miyagi://review

Every scheduled item with its box, due date and lapses

miyagi://history

The durable practice log, most recent 200 events

miyagi://roadmaps/{name}

One track as markdown; the name autocompletes

miyagi://insights

Cadence by week, review accuracy, checkpoint pass rate, verdict

miyagi://getting-started

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"
      }
    }
  ]
}

  • verify is 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. contains additionally requires a string in its output.

  • windows is the PowerShell equivalent, used automatically when a posix track is walked on Windows.

  • shell declares what the commands are written for: posix, powershell or any.

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 --doctor

Checks 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 build
npm run eval        # the content rubric, the learner journey, and coverage parity
npm run doctor      # after a build

npm 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.log gets 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 tools
configure_voiceConfigure VoiceA

Toggle tutor audio on/off and adjust the speech rate in words per minute.

ParametersJSON Schema
NameRequiredDescriptionDefault
enabledNo
test_phraseNoSpeak this immediately to test the setup.
words_per_minuteNo

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

There are no annotations, so the description carries the full burden. It says the tool toggles audio and adjusts speech rate, but it does not disclose whether settings persist, whether permissions are needed, or what side effects occur. The test_phrase behavior is only in the schema, not the description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One efficient sentence with no fluff. The core actions are front-loaded and every word contributes meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, low-complexity configuration tool with zero required parameters and no output schema, the description is mostly sufficient. But it lacks context about persistence, prerequisites, or the full role of test_phrase, and no output schema means the agent is given no clue about the result of calling the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 33%, but the description compensates partially by mapping 'toggle on/off' to enabled and 'speech rate in WPM' to words_per_minute. test_phrase is covered by the schema's own description. The added meaning is useful but modest.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Toggle'/'adjust') and names the exact resource ('tutor audio' and 'speech rate'). This clearly separates it from siblings like quick_config and run_teaching_command, which are not voice-specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: use this when the user wants to enable/disable tutor audio or change speech rate. However, there is no explicit 'when not to use' statement or mention of alternatives like quick_config, leaving some ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
appendNoAppend instead of overwriting.
output_pathNoFile path (relative paths resolve against the server's cwd).ROADMAP_PROGRESS.md

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does say 'Write', which implies a file mutation, but it does not disclose that the default behavior overwrites an existing ROADMAP_PROGRESS.md, that the file is written to the server's cwd, or any other side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single focused sentence with no filler words. It front-loads the primary verb and deliverable, then specifies the content requirements. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with two optional, fully documented parameters and no output schema, so the description covers the core purpose well. However, it omits important behavioral context such as the overwrite-by-default behavior and appropriate invocation timing, leaving mild gaps for an agent deciding when and how to call it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters ('append' and 'output_path') are already documented in the schema. The description does not add parameter-specific meaning beyond the schema, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Write'), a specific deliverable ('clean ROADMAP_PROGRESS.md summary'), and the exact content to include ('roadmap position, player stats, and every concept and command covered'). This clearly differentiates it from the sibling tools, none of which are export/summary tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'summary of the session' implies it should be used after a teaching session to persist progress, but there is no explicit guidance on when to invoke it versus alternatives or whether it should be run at the end of every session. Usage is inferred rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_next_roadmap_commandGet Next Roadmap CommandB

Suggest the next copy-pasteable terminal command for the active roadmap milestone. Optionally advance the step counter.

ParametersJSON Schema
NameRequiredDescriptionDefault
advanceNoAdvance step_index by one before suggesting.

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavioral traits clearly. It does disclose the optional side effect ('Optionally advance the step counter') and implies the command is not executed directly ('copy-pasteable'). However, it does not elaborate on other state changes, error conditions (e.g., missing active roadmap), or the nature of the return value beyond 'suggest a command'. Basic transparency is present but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no wordiness. The primary purpose is front-loaded in the first sentence, and the brief second sentence covers the optional parameter. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional parameter and no output schema, the description covers the main function and side-effect clearly. It does not mention behavior when no active milestone exists, which is a minor gap, but the description is sufficiently complete for typical use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema's parameter description ('Advance step_index by one before suggesting.') fully documents the 'advance' parameter. The tool description adds only a synonym ('step counter') without new meaning, so it neither compensates for nor expands upon the schema. Baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb ('Suggest') and resource ('the next copy-pasteable terminal command for the active roadmap milestone'). It is easy to understand the tool's core purpose, but it does not explicitly distinguish itself from sibling tools like run_teaching_command or verify_quiz_answer, so it lacks overt sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It mentions the context ('for the active roadmap milestone') but does not state exclusions, prerequisites, or how it relates to sibling tools such as run_teaching_command. This leaves the agent to infer usage independently.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_user_statsGet User StatsA

Return the current player profile: XP, level, title, quiz streak, unlocked badges, and roadmap progress.

ParametersJSON Schema
NameRequiredDescriptionDefault
speakNoRead the stats aloud.

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden of indicating behavior. 'Return the current player profile' clearly signals a read-only retrieval with no apparent side effects. It does not detail voice behavior for speak=true, but that is covered by the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, information-dense sentence that front-loads the core purpose and then lists return fields. Every word earns its place with no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter read-only stats tool, the description is complete: it states what is returned, and the schema fully documents the optional speak parameter. The agent has enough information to select and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the only parameter 'speak' is fully documented with type, default, and description. The tool description adds no parameter-specific meaning, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Return the current player profile' and enumerates exactly what is included (XP, level, title, quiz streak, unlocked badges, roadmap progress). This clearly differentiates the tool from siblings like verify_quiz_answer or set_active_roadmap.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: this tool is used when the current player profile or stats are needed. It does not explicitly discuss when not to use it or name alternatives, but the use case is obvious from the description and sibling context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

quick_configQuick ConfigC

Instantly switch the target skill level (Junior/Mid/Senior), roadmap category, roadmap track, or topic via simple key-value parameters.

ParametersJSON Schema
NameRequiredDescriptionDefault
categoryNo
skill_levelNoDepth of explanation used in every teaching card.
roadmap_nameNoe.g. "Backend Developer", "Git and GitHub"
current_topicNo
voice_enabledNo
reset_progressNoWipe saved XP, level, streak and badges back to first-run state.
words_per_minuteNo

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It says 'switch' but gives no indication of side effects, persistence behavior, or the powerful destructive reset_progress option that wipes XP, level, streak, and badges. The schema mentions reset_progress, but the tool description itself does not warn about the impact.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loaded, but it is more under-specified than genuinely concise. Words like 'Instantly' and 'simple' add little information, and a single vague sentence is not enough for a 7-parameter configuration tool with no annotations and no output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 7 optional parameters, no annotations, and no output schema, the description is incomplete. It fails to mention the destructive reset behavior, the voice and words_per_minute settings, what happens if multiple parameters are combined, or what response the agent can expect after the call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 43%, so the description should compensate. It maps a few natural-language labels to parameters (skill_level, category, roadmap_name, current_topic), but it omits voice_enabled, words_per_minute, and the critical reset_progress flag. It also adds no detail about valid values for roadmap_name or current_topic beyond naming them.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific action ('switch') and identifies several configurable targets: skill level, roadmap category, roadmap track, and topic. This is much more informative than a tautology, but it does not explicitly distinguish quick_config from siblings like set_active_roadmap or configure_voice, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus the sibling tools. It mentions switching several settings but never says 'use this instead of set_active_roadmap or configure_voice when changing multiple config values at once.' The intended usage is implied, but not spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNoWorking directory for execution.
commandYesThe shell command to teach and optionally run.
conceptNoConcept label for the card, e.g. 'Filesystem navigation'.
dry_runNoExplain without executing.
is_dangerousNoCaller-asserted danger flag. Dangerous commands are forced into dry-run.

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It usefully discloses that errors return a Tutor Hotfix Diagnostic instead of throwing, and that dry-run is possible. However, it does not mention side effects of executing commands, the behavior of the is_dangerous flag, or any safety caveats, which are important for a command-execution tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no filler. The main action is front-loaded and the output components are listed compactly. It is slightly long due to the enumerative output list, but every listed item adds meaningful context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains what the tool returns and how errors behave, which is good for a tool with no output schema or annotations. However, it lacks guidance on safety, dry-run usage trade-offs, and how optional parameters like cwd or concept affect behavior, leaving some practical gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds no extra parameter-level detail beyond mentioning dry-run in prose, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb-resource pair ('Execute (or dry-run) a shell command') and enumerates the full teaching card contents, making the tool's purpose unmistakable. It is clearly differentiated from siblings like verify_quiz_answer or get_next_roadmap_command, which handle different tasks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies when to use the tool: whenever a shell command needs to be taught with explanation and practice materials. It does not explicitly name alternatives or state exclusions, so it stops short of a perfect score, but the context is clear enough for an agent to select it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_active_roadmapSet Active RoadmapC

Configure the active roadmap: category, roadmap name, current topic node, and progress step counters.

ParametersJSON Schema
NameRequiredDescriptionDefault
categoryYes
step_indexNo
total_stepsNo
roadmap_nameYes
current_topicYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden of disclosing side effects. It states what is configured but does not mention that this likely changes persistent/global active state, whether prior values are overwritten, or what the result/response of the call is.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single efficient sentence with the action and resource front-loaded. Every phrase contributes meaning: the resource, the governed fields, and the counter semantics. There is no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a state-setting tool with five parameters, no annotations, and no output schema, so it needs more context to be safely invoked. Missing side effects, usage timing, and clearer parameter relationships leave important gaps for an agent deciding whether and how to call it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must compensate, and it partially does by grouping step_index and total_steps as 'progress step counters' and interpreting current_topic as 'current topic node.' However, it does not explain individual parameter meaning, constraints, or how the counters relate to the roadmap state.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Configure') with a clear resource ('the active roadmap') and lists the key fields involved. This makes the tool's purpose understandable and distinguishes it from retrieval-oriented siblings like get_next_roadmap_command, though it does not explicitly name a sibling alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to choose this tool over alternatives such as quick_config or get_next_roadmap_command. There are no prerequisites, exclusions, or contextual signals explaining the intended workflow placement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
answerYesThe learner's answer, either a letter (A-D) or the answer text.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the side effects: updating streak, XP, and badges, plus speaking feedback. This gives the agent a clear sense of what will change, though it does not mention reversibility or any prerequisites.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one concise, information-dense sentence. It includes the action, target, and side effects without any filler or repetition of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with no nested objects and no output schema, the description covers the essential action and effects. It could optionally mention that a quiz must be currently pending, but the phrase 'the most recent active-recall quiz' provides enough contextual framing for correct use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers the single parameter with 100% description coverage, explaining that 'answer' is either a letter (A-D) or answer text. The tool description adds no additional parameter meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Evaluate') and names the precise resource ('the learner's answer to the most recent active-recall quiz'). It also lists the tool's effects (streak, XP, badges, feedback), which clearly distinguishes it from the unrelated sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies the tool should be used when a learner provides an answer to the most recent active-recall quiz. It does not explicitly name alternatives or exclusion conditions, but the context is clear and the sibling tools are not overlapping in function.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 8 tool updatesv1.0.0
    • First observedconfigure_voice
    • First observedexport_roadmap_notes
    • First observedget_next_roadmap_command
    • First observedget_user_stats
    • First observedquick_config
    • First observedrun_teaching_command
    • First observedset_active_roadmap
    • First observedverify_quiz_answer
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.5/5.0

Scored across 8 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP Walkthrough

    Stefan-Nitu
    A
    license
    A
    quality
    D
    maintenance
    Enables AI agents to present interactive code walkthroughs with voice narration, opening files, highlighting code, and showing inline explanations with synchronized text-to-speech.
    5
    10 npm
    MIT

  • devcoach

    UltimaPhoenix
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables local, progressive technical coaching inside MCP-compatible AI agents, delivering short targeted lessons calibrated to the user's knowledge after each completed task while storing everything in a local SQLite file.
    568 npm
    4
    AGPL 3.0