🥋 miyagi

一位耐心、游戏化、支持语音的 MCP 编程导师。 命令由你来执行。它负责训练、纠错、在你跌倒时扶住你，并为你计分。

抹上去，抹下来。miyagi 从不替你完成工作。它把下一条命令递到你手上，按你的水平讲解，并把每一次结果都变成一堂课。每次运行都会返回一张教学卡片：你处在路线图的哪个位置、按你的经验定制的"是什么/怎么做/权衡取舍"拆解、一张 Mermaid 心智模型图、那些容易坑到人的陷阱、精选文档，以及一次主动回忆测验。所有内容都会通过你操作系统的语音引擎朗读出来。

为什么可以放心安装

它会在你的机器上执行 shell 命令，因此它的设计原则是：先读代码，再谈信任。

• 不会执行任何灾难性操作。 rm -rf、dd of=/dev/*、fork 炸弹、curl | sh、强制推送和 chmod -R 777 都会被模式匹配并强制进入 dry-run 模式，无论调用方模型声称什么。这道防线防的是糊涂的 AI，而不只是粗心的用户——正因如此，它会重新推导判定结果，而不是轻信传入的 is_dangerous 标志。

• 黑名单是兜底，不是沙箱。 真正的边界是你 MCP 客户端自己的审批提示，由你在命令执行前亲自阅读。这道防线只针对那种提示处理不好的更窄场景：有人正一路点"确定"，而命令明显具有破坏性。

• 失败是用来教学的，不是用来崩溃的。 非零退出码会返回一份带排查阶梯的热修复诊断。服务器永远不会抛出异常。

• 有界。 60 秒超时、4 MB 输出上限、无网络调用、无遥测、无 API 密钥、无账号。

• 小到可以审计。 只有两个运行时依赖——MCP SDK 和 zod——全部集中在一个源文件里，坐下来就能读完。

Related MCP server: EduChain MCP Server

安装

将你的 MCP 客户端指向 npx，它会在首次运行时自动拉取：

npx -y miyagi-mcp

或者全局安装，这样你会得到一个 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

然后在下面的配置中使用 "command": "node", "args": ["<ABS_PATH>/dist/miyagi.js"]。

配置你的 MCP 客户端

三行配置，处处通用。无需密钥、无需账号，全部在本地运行。

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

配置写在哪里：

对于 Claude Code，一条命令即可完成：

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

重启客户端，然后试试说："把我的路线图设为后端开发，并教我 docker compose config。"

包含什么

语音引擎

想要语音的 Linux 用户：sudo apt install speech-dispatcher。

工具

• quick_config：一次调用即可切换技能等级（初级/中级/高级）、类别、路线、主题或语音。传入 reset_progress: true 可将已保存的 XP 清空回首次运行状态。

• set_active_roadmap：设置类别、路线图、主题和步骤计数器

• get_next_roadmap_command：下一条可直接复制粘贴的命令，传入 advance: true 可向前推进

• configure_voice：开关音频、设置每分钟字数、朗读一句测试短语

• get_user_stats：XP、等级、头衔、连续答对、徽章、头衔阶梯

• run_teaching_command：执行或 dry-run 一条命令，并返回教学卡片

• verify_quiz_answer：批改测验、更新连续答对和 XP、朗读反馈

• export_roadmap_notes：写入 ROADMAP_PROGRESS.md

进度存放在哪里

~/.miyagi/profile.json，保存着 XP、等级、连续答对、徽章、你的技能等级、语音设置和路线图位置。可以用 MIYAGI_HOME 覆盖该目录，测试也正是借此避开真实的配置文件。

该文件在读取时被视为不可信数据，因为它可以手工编辑，而且一次崩溃就可能截断它。任何解析失败的内容都会被丢弃，代之以全新的配置文件，而不是抛出错误；超出范围的值会被钳制而不是拒绝；等级会根据 XP 重新计算而不是直接读取——因此一个声称 40 XP 却写着等级 99 的文件会被纠正。写入时先写临时文件再重命名，因此一次被中断的写入会保留之前的配置文件完好无损。

开发

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

CI 会在 Node 18、20 和 22 上运行类型检查、测试和一次真实的 stdio 握手。

值得了解的局限

• 命令以你自己的权限、在你自己的目录中运行。没有容器、没有受限用户、没有系统调用过滤。这对一个由所有者驱动的本地教学工具来说是合适的，但如果它将来接受不可信输入，这是第一件需要改变的事。

• 长时间运行或交互式命令请放在你自己的终端里。60 秒上限会将其截断。

• XP 和连续答对是否真的能让一个人坚持走在路线图上，这是一个开放问题。进度文件正是让这个问题可以得到回答的东西。

许可证

MIT