tuxguitar-claude-mcp

Ein MCP-Server, der es Claude ermöglicht, Gitarren- und Bass-Tabs zu schreiben — Spuren, Stimmung, Takte, Noten und Tab-Effekte wie Palm Mute, Tremolo-Picking, Bends und Flageolett — direkt als .gp5-Dateien, die TuxGuitar öffnen kann.

Das ist Phase 1: nur dateibasiert. Es gibt keine Live-Steuerung einer laufenden TuxGuitar-Instanz (das wäre eine zukünftige, noch nicht entworfene Phase 2).

Funktionsweise

Der MCP-Server (TypeScript, @modelcontextprotocol/sdk) hält einen In-Memory-Songzustand, den Claude Aufruf für Aufruf aufbaut — Spuren erstellen, Takte hinzufügen, Stimmung setzen, Beats und Noten einfügen. save_song übergibt diesen Zustand an einen kleinen Java-Helfer (song-writer/, der auf den TuxGuitar-Bibliotheken selbst basiert), der ihn in eine echte .gp5-Datei serialisiert.

Voraussetzungen

• Windows mit installiertem TuxGuitar. Der Server greift auf die in der Installation gebündelte JRE (jre\bin\java.exe) und auf TuxGuitars eigene Bibliotheken zu, um gültige .gp5-Dateien zu schreiben — TuxGuitar selbst muss nicht laufen. Standard ist C:\Program Files\tuxguitar; falls Ihre Installation woanders liegt, überschreiben Sie den Pfad mit der Umgebungsvariable TUXGUITAR_HOME.

• Node.js (18+) für den MCP-Server.

• Java 21, um den Java-Helfer einmal zu erstellen (z. B. Eclipse Temurin JDK 21). Zur Laufzeit wird es nicht benötigt — TuxGuitars gebündelte JRE übernimmt das.

• Claude Code (oder einen anderen MCP-kompatiblen Client), um den Server zu registrieren und zu verwenden.

Setup

1. Java-Songwriter erstellen

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

Optional können Sie die Tests ausführen:

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

2. MCP-Server erstellen

npm install
npm run build
npm run test

3. Bei Claude Code registrieren

Fügen Sie ihn in mcpServers in Ihrer Claude-Code-Konfiguration hinzu (global in ~/.claude.json, oder in der .mcp.json eines Projekts):

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

Falls TuxGuitar nicht unter C:\Program Files\tuxguitar installiert ist, setzen Sie TUXGUITAR_HOME in env:

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

Starten Sie Claude Code neu, damit er den neuen Server erkennt.

Tools

Manueller Integrationstest

1. Rufen Sie tuxguitar_ping auf — erwarten Sie "ok".

2. Rufen Sie new_song, create_track, add_measure, add_beats und save_song in dieser Reihenfolge auf.

3. Öffnen Sie die resultierende .gp5-Datei in der echten TuxGuitar-Anwendung und prüfen Sie sie optisch und akustisch.

Bekannte Einschränkungen

• Nur Phase 1: keine Live-Steuerung einer laufenden TuxGuitar-Instanz.

• add_beats prüft nicht, ob die Beats in die Gesamtlänge eines Takts passen — stillschweigende Überfüllung wird akzeptiert.

• Takte ohne Beats bleiben inkonsistent: Takt 0 ist wirklich leer, spätere Takte behalten TuxGuitars eigenes, automatisch eingefügtes Ruhe-Beat.

• Nur Windows.

Fehlerbehebung

• "Unknown track_id" / "Unknown measure_index": Prüfen Sie die Reihenfolge der Aufrufe — Spuren und Takte müssen existieren, bevor add_beats auf sie verweist.

• tuxguitar_ping schlägt fehl: Prüfen Sie, ob song-writer\dist\tuxguitar-song-writer.jar vorhanden ist (führen Sie build.ps1 erneut aus) und ob TUXGUITAR_HOME (oder der Standard C:\Program Files\tuxguitar) auf eine echte TuxGuitar-Installation zeigt.

Lizenz

MIT