tuxguitar-claude-mcp

이 MCP 서버는 Claude가 기타/베이스 탭(트랙, 튜닝, 마디, 음표, 팜 뮤트, 트레몰로 피킹, 벤딩, 하모닉스 같은 탭 효과)을 TuxGuitar에서 열 수 있는 .gp5 파일로 직접 작성할 수 있게 해줍니다.

이것은 Phase 1: 파일 기반만 지원합니다. 실행 중인 TuxGuitar 인스턴스를 실시간으로 제어하는 기능은 없습니다(이후 Phase 2로 설계될 수 있는 기능이며 아직 설계되지 않았습니다).

작동 방식

MCP 서버(TypeScript, @modelcontextprotocol/sdk)는 Claude가 도구 호출로 만들어 가는 인메모리 곡 상태를 보유합니다 — 트랙 생성, 마디 추가, 튜닝 설정, 비트와 음표 삽입. save_song은 이 상태를 TuxGuitar 라이브러리 자체로 빌드된 작은 Java 헬퍼(song-writer/)에 전달하며, 헬퍼가 실제 .gp5 파일로 직렬화합니다.

요구 사항

• TuxGuitar가 설치된 Windows. 서버는 설치폴더에 포함된 JRE(jre\bin\java.exe)와 TuxGuitar 자체 라이브러리를 외부 프로세스로 호출해 유효한 .gp5 파일을 작성합니다 — TuxGuitar 자체는 실행 중일 필요가 없습니다. 기본 경로는 C:\Program Files\tuxguitar이며, 다른 곳에 설치되어 있다면 TUXGUITAR_HOME 환경 변수로 덮어쓰세요.

• MCP 서버용 Node.js (18+).

• Java 헬퍼를 한 번 빌드하기 위한 Java 21 (예: Eclipse Temurin JDK 21). 런타임에는 필요하지 않습니다 — TuxGuitar에 포함된 JRE가 그 역할을 합니다.

• 서버를 등록하고 사용하려면 Claude Code(또는 MCP 호환 클라이언트)가 필요합니다.

설정

1. Java song-writer 빌드

powershell -ExecutionPolicy Bypass -File song-writer\build.ps1

선택 사항, 테스트 실행:

powershell -ExecutionPolicy Bypass -File song-writer\test.ps1

2. MCP 서버 빌드

npm install
npm run build
npm run test

3. Claude Code에 등록

Claude Code 구성의 mcpServers에 추가하세요(전역적으로 ~/.claude.json, 또는 프로젝트의 .mcp.json):

"tuxguitar": {
  "type": "stdio",
  "command": "node",
  "args": ["<path-to-repo>\\dist\\index.js"],
  "env": {}
}

TuxGuitar가 C:\Program Files\tuxguitar에 설치되어 있지 않으면 env에 TUXGUITAR_HOME을 설정하세요:

"env": { "TUXGUITAR_HOME": "D:\\Apps\\tuxguitar" }

Claude Code를 다시 시작하면 새 서버가 인식됩니다.

도구

수동 통합 테스트

1. tuxguitar_ping 호출 — "ok" 응답이 기대됩니다.

2. new_song, create_track, add_measure, add_beats, save_song을 순서대로 호출합니다.

3. 결과 .gp5 파일을 실제 TuxGuitar 앱에서 열고 시각적/청각적으로 확인합니다.

알려진 제한 사항

• Phase 1만: 실행 중인 TuxGuitar 인스턴스를 실시간 제어하지 않습니다.

• add_beats는 비트가 마디의 전체 길이 안에 들어가는지 검증하지 않습니다 — 초과분은 조용히 수용됩니다.

• 비트가 없는 마디는 일관성이 없습니다. 마디 0은 완전히 비어 있고, 이후 마디는 TuxGuitar의 자동 채움 쉼표 비트를 유지합니다.

• Windows 전용.

문제 해결

• "Unknown track_id" / "Unknown measure_index": 호출 순서를 확인하세요 — add_beats가 참조하는 트랙과 마디가 존재해야 합니다.

• tuxguitar_ping 실패: song-writer\dist\tuxguitar-song-writer.jar가 존재하는지(build.ps1을 다시 실행)와 TUXGUITAR_HOME(또는 기본값 C:\Program Files\tuxguitar)이 실제 TuxGuitar 설치 경로를 가리키는지 확인하세요.

라이선스

MIT