🥋 miyagi

인내심 많고, 게임화된, 음성 지원 MCP 코딩 튜터. 당신이 명령을 실행합니다. 그것은 훈련시키고, 교정하고, 넘어짐을 잡아주고, 점수를 기록합니다.

왁스 온, 왁스 오프. miyagi는 결코 당신을 대신해 작업을 수행하지 않습니다. 다음 명령을 건네주고, 당신의 수준에 맞게 설명하며, 모든 결과를 교훈으로 바꿉니다. 각 실행은 교육 카드로 돌아옵니다: 로드맵에서의 현재 위치, 당신의 경험에 맞춰진 무엇/어떻게/트레이드오프 분석, Mermaid 정신 모델, 사람들을 괴롭히는 함정, 선별된 문서, 그리고 능동 회상 퀴즈. 이 모든 것이 OS의 자체 음성 엔진을 통해 해설됩니다.

설치해도 안전한 이유

이 도구는 당신의 머신에서 셸 명령을 실행하므로, 신뢰하기 전에 읽어보도록 설계되었습니다.

• 파괴적인 것은 실행되지 않습니다. rm -rf, dd of=/dev/*, 포크 폭탄, curl | sh, 강제 푸시, chmod -R 777은 패턴 매칭되어 호출 모델이 무엇을 주장하든 무조건 드라이런으로 강제됩니다. 이 화면은 부주의한 사용자뿐만 아니라 혼란스러운 AI로부터도 방어합니다. 그래서 전달받은 is_dangerous 플래그를 신뢰하는 대신 판정을 다시 도출합니다.

• 차단 목록은 백스톱이지 샌드박스가 아닙니다. 실제 경계는 MCP 클라이언트 자체의 승인 프롬프트이며, 명령이 실행되기 전에 당신이 읽는 것입니다. 이 화면은 그 프롬프트가 제대로 처리하지 못하는 좁은 경우, 즉 클릭을 통해 지나가는 사람에게 제안된 명백히 파괴적인 것을 위해 존재합니다.

• 실패는 충돌 대신 가르칩니다. 0이 아닌 종료 코드는 문제 해결 사다리가 포함된 핫픽스 진단을 반환합니다. 서버는 절대 예외를 던지지 않습니다.

• 제한적입니다. 60초 타임아웃, 4MB 출력 상한, 네트워크 호출 없음, 텔레메트리 없음, 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: 명령을 실행하거나 드라이런하고 교육 카드를 반환합니다.

• 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 핸드셰이크를 실행합니다.

알아두면 좋은 한계

• 명령은 당신의 권한으로 당신의 디렉터리에서 실행됩니다. 컨테이너도, 제한된 사용자도, syscall 필터도 없습니다. 소유자가 직접 사용하는 로컬 교육 도구에는 적합하며, 신뢰할 수 없는 입력을 받게 된다면 가장 먼저 바꿔야 할 부분입니다.

• 장기 실행 또는 대화형 명령은 당신의 터미널에서 실행하세요. 60초 제한이 끊을 수 있습니다.

• XP와 연속 기록이 실제로 사람을 로드맵에 유지하는지는 열린 질문입니다. 진행 파일이 그 답을 가능하게 만듭니다.

라이선스

MIT