🥋 miyagi

Терпеливый, геймифицированный, с голосовым управлением MCP-репетитор по программированию. Команды выполняете вы. Он тренирует, исправляет, подхватывает при падениях и ведёт счёт.

Натирай воском, снимай воском. miyagi никогда не делает работу за вас. Он выдаёт следующую команду, объясняет её на вашем уровне и превращает каждый результат в урок. Каждый запуск возвращается в виде учебной карточки: где вы находитесь на дорожной карте, разбор Что/Как/Компромиссы с учётом вашего опыта, ментальная модель на Mermaid, ловушки, в которые попадаются люди, подобранные материалы и тест на активное припоминание. Всё это озвучивается через встроенный речевой движок вашей ОС.

Почему его безопасно устанавливать

Он выполняет shell-команды на вашей машине, поэтому его стоит прочитать, прежде чем довериться.

• Ничего катастрофического не выполняется. rm -rf, dd of=/dev/*, fork-бомбы, curl | sh, принудительные push и chmod -R 777 распознаются по шаблону и принудительно переводятся в dry-run независимо от того, что утверждает вызывающая модель. Экран защищает от запутавшегося ИИ, а не только от невнимательного пользователя, поэтому вердикт пересчитывается заново, а не доверяется флагу is_dangerous, который был передан.

• Список запретов — это подстраховка, а не песочница. Настоящая граница — это собственный запрос на подтверждение в вашем MCP-клиенте, где вы читаете команду перед её выполнением. Экран существует для более узкого случая, когда этот запрос обрабатывается плохо: что-то явно разрушительное предлагается тому, кто кликает, не глядя.

• Сбои учат, а не роняют сервер. Ненулевой код выхода возвращает диагностику с лестницей устранения неполадок. Сервер никогда не выбрасывает исключений.

• Ограничено по ресурсам. Таймаут 60 секунд, лимит вывода 4 МБ, никаких сетевых запросов, телеметрии, 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: переключить уровень мастерства (Junior/Mid/Senior), категорию, трек, тему или голос за один вызов. Передайте 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, а не читается напрямую — так файл, утверждающий уровень 99 при 40 XP, будет исправлен. Запись идёт во временный файл с последующим переименованием, так что прерванная запись оставляет предыдущий профиль нетронутым.

Разработка

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

CI прогоняет проверку типов, тесты и реальное рукопожатие по stdio на Node 18, 20 и 22.

Ограничения, о которых стоит знать

• Команды выполняются с вашими правами в вашем каталоге. Без контейнера, ограниченного пользователя и фильтра syscall. Это правильно для локального учебного инструмента, которым управляет владелец, и это первое, что нужно изменить, если он когда-нибудь будет принимать недоверенный ввод.

• Долго выполняющиеся или интерактивные команды — это для вашего собственного терминала. Ограничение в 60 секунд оборвёт их.

• Вопрос о том, действительно ли XP и серии удерживают человека на дорожной карте, остаётся открытым. Файл прогресса — то, что делает его проверяемым.

Лицензия

MIT