tuxguitar-claude-mcp

Un servidor MCP que permite a Claude escribir tablaturas de guitarra/bajo — pistas, afinaciones, compases, notas y efectos de tablatura como palm mute, tremolo picking, bends y armónicos — directamente como archivos .gp5 que TuxGuitar puede abrir.

Esta es la Fase 1: solo basado en archivos. No hay control en vivo de una instancia de TuxGuitar en ejecución (eso sería una futura Fase 2, aún no diseñada).

Cómo funciona

El servidor MCP (TypeScript, @modelcontextprotocol/sdk) mantiene un estado de canción en memoria que Claude construye llamada a llamada con los herramientas — crear pistas, añadir compases, establecer afinación, insertar tiempos y notas. save_song entrega ese estado a un pequeño asistente de Java (song-writer/, construido sobre las propias librerías de TuxGuitar) que lo serializa a un archivo .gp5 real.

Requisitos

• Windows, con TuxGuitar instalado. El servidor hace uso de la JRE incluida con esa instalación (jre\bin\java.exe) y de las propias librerías de TuxGuitar para escribir archivos .gp5 válidos — no es necesario que TuxGuitar esté ejecutándose. Usa como predeterminado C:\Program Files\tuxguitar; sobrescríbelo con la variable de entorno TUXGUITAR_HOME si tu instalación está en otro lugar.

• Node.js (18+) para el servidor MCP.

• Java 21 para construir el asistente Java una vez (por ejemplo, Eclipse Temurin JDK 21). No se necesita en tiempo de ejecución — la JRE incluida con TuxGuitar lo maneja.

• Claude Code (u otro cliente compatible con MCP) para registrar y usar el servidor.

Configuración

1. Construir el song-writer de Java

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

Opcional, ejecuta sus pruebas:

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

2. Construir el servidor MCP

npm install
npm run build
npm run test

3. Registrarlo con Claude Code

Añádelo a mcpServers en tu configuración de Claude Code (globalmente en ~/.claude.json, o en el .mcp.json de un proyecto):

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

Si TuxGuitar no está instalado en C:\Program Files\tuxguitar, define TUXGUITAR_HOME en env:

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

Reinicia Claude Code para que detecte el nuevo servidor.

Herramientas

Prueba de integración manual

1. Llama a tuxguitar_ping — espera "ok".

2. Llama a new_song, create_track, add_measure, add_beats, save_song en secuencia.

3. Abre el archivo .gp5 resultante en la aplicación real de TuxGuitar y compruébalo visual/auditivamente.

Limitaciones conocidas

• Solo Fase 1: no hay control en vivo de una instancia de TuxGuitar en ejecución.

• add_beats no valida que los tiempos quepan dentro de la longitud total de un compás — se acepta un exceso de contenido de forma silenciosa.

• Los compases sin tiempos son inconsistentes: el compás 0 está realmente vacío, los compases posteriores conservan el tiempo de silencio que TuxGuitar agrega automáticamente.

• Solo Windows.

Solución de problemas

• "Unknown track_id" / "Unknown measure_index": comprueba el orden de las llamadas — las pistas y los compases deben existir antes de que add_beats haga referencia a ellos.

• tuxguitar_ping falla: comprueba que song-writer\dist\tuxguitar-song-writer.jar exists (vuelve a ejecutar build.ps1) y que TUXGUITAR_HOME (o el valor predeterminado C:\Program Files\tuxguitar) apunta a una instalación real de TuxGuitar.

Licencia

MIT