# tuxguitar-claude-mcp

An MCP server that lets [Claude](https://claude.com) write guitar/bass tabs — tracks, tuning,
measures, notes, and tab effects like palm mute, tremolo picking, bends, and harmonics — directly
as `.gp5` files that [TuxGuitar](https://www.tuxguitar.app/) can open.

This is Phase 1: file-based only. There is no live control of a running TuxGuitar instance (that
would be a future Phase 2, not yet designed).

## How it works

The MCP server (TypeScript, `@modelcontextprotocol/sdk`) holds an in-memory song state that Claude
builds up tool call by tool call — create tracks, add measures, set tuning, insert beats and notes.
`save_song` hands that state to a small Java helper (`song-writer/`, built on the TuxGuitar
libraries themselves) which serializes it to a real `.gp5` file.

## Requirements

- **Windows**, with **TuxGuitar installed**. The server shells out to the JRE bundled with that
  install (`jre\bin\java.exe`) and to TuxGuitar's own libraries to write valid `.gp5` files —
  TuxGuitar itself does not need to be running. Defaults to `C:\Program Files\tuxguitar`; override
  with the `TUXGUITAR_HOME` environment variable if yours is installed elsewhere.
- **Node.js** (18+) for the MCP server.
- **Java 21** to *build* the Java helper once (e.g. [Eclipse Temurin JDK
  21](https://adoptium.net/)). It is not needed at runtime — TuxGuitar's bundled JRE handles that.
- [Claude Code](https://claude.com/claude-code) (or another MCP-compatible client) to register and
  use the server.

## Setup

### 1. Build the Java song-writer

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

Optional, run its tests:

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

### 2. Build the MCP server

```bash
npm install
npm run build
npm run test
```

### 3. Register it with Claude Code

Add it to `mcpServers` in your Claude Code config (globally in `~/.claude.json`, or in a project's
`.mcp.json`):

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

If TuxGuitar isn't installed at `C:\Program Files\tuxguitar`, set `TUXGUITAR_HOME` in `env`:

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

Restart Claude Code so it picks up the new server.

## Tools

| Tool | What it does |
|---|---|
| `tuxguitar_ping` | Checks that Java and the song-writer helper are reachable. |
| `new_song` | Starts a new, empty song (discards current state). |
| `set_song_info` | Sets title and/or artist of the current song. |
| `get_song` | Returns the current song state as JSON. |
| `save_song` | Writes the current song state out as a `.gp5` file. |
| `create_track` | Creates a new track (guitar/bass) with a tuning. |
| `list_tracks` | Lists all tracks of the current song. |
| `set_tuning` | Changes the tuning of an existing track. |
| `add_measure` | Adds a new measure at the end of the song (applies to all tracks). |
| `set_tempo` | Sets the tempo (BPM) of an existing measure. |
| `set_time_signature` | Sets the time signature of an existing measure. |
| `add_beats` | Inserts an ordered list of beats (rhythmic slots with notes) into one track's measure. |
| `clear_measure` | Removes all beats of one track in a given measure. |

## Manual integration test

1. Call `tuxguitar_ping` — expect `"ok"`.
2. Call `new_song`, `create_track`, `add_measure`, `add_beats`, `save_song` in sequence.
3. Open the resulting `.gp5` file in the real TuxGuitar app and check it visually/aurally.

## Known limitations

- Phase 1 only: no live control of a running TuxGuitar instance.
- `add_beats` doesn't validate that beats fit within a measure's total length — silent overfill is
  accepted.
- Measures with no beats stay inconsistent: measure 0 is genuinely empty, later measures keep
  TuxGuitar's own auto-filled rest beat.
- Windows-only.

## Troubleshooting

- **"Unknown track_id" / "Unknown measure_index"**: check the order of calls — tracks and measures
  must exist before `add_beats` references them.
- **`tuxguitar_ping` fails**: check that `song-writer\dist\tuxguitar-song-writer.jar` exists (rerun
  `build.ps1`) and that `TUXGUITAR_HOME` (or the default `C:\Program Files\tuxguitar`) points at a
  real TuxGuitar install.

## License

[MIT](LICENSE)