Metadata-Version: 2.5
Name: musicxml-abc-mcp
Version: 0.1.2
Summary: MCP server that converts between MusicXML and ABC notation for LLM-assisted score editing
Project-URL: Homepage, https://github.com/raulkivi/music-assistant
Project-URL: Repository, https://github.com/raulkivi/music-assistant
Project-URL: Bug Tracker, https://github.com/raulkivi/music-assistant/issues
Author-email: Raul Kivi <raulkivi@users.noreply.github.com>
License: MIT
Keywords: abc,llm,mcp,music,musicxml,notation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: mcp<2.0.0,>=1.28.1
Requires-Dist: music21>=9.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# musicxml-abc-mcp

MCP server that converts between MusicXML and ABC notation.

## What it does

Bridges MusicXML (the standard but verbose XML format) and ABC notation (a compact, human-readable text format). The primary use case is enabling LLM-assisted score editing: MusicXML → ABC → Claude edits → ABC → MusicXML.

ABC is ideal for LLM editing because it is concise enough to fit in a context window and expressive enough to represent most choral music.

## Tools

| Tool | Description |
|------|-------------|
| `musicxml_to_abc` | Convert MusicXML to ABC notation; optionally filter to a single part |
| `abc_to_musicxml` | Convert ABC notation back to MusicXML |
| `validate_abc` | Parse an ABC string and return errors or warnings |
| `list_capabilities` | Return server metadata: backend version, ABC standard |

## Installation

```bash
cd musicxml-abc-mcp
uv sync --extra dev
```

Note: use `--extra dev` (not `--group dev`) to install pytest.

## Running

```bash
uv run musicxml-abc-mcp
```

No environment variables required.

## Usage examples

```json
// Convert full score to ABC
{
  "tool": "musicxml_to_abc",
  "arguments": {"musicxml_path": "/path/to/score.mxl"}
}

// Extract just the Soprano part
{
  "tool": "musicxml_to_abc",
  "arguments": {"musicxml_path": "/path/to/score.mxl", "part_name": "Soprano"}
}

// Convert edited ABC back to MusicXML
{
  "tool": "abc_to_musicxml",
  "arguments": {"abc_text": "X:1\nT:My Song\n...", "output_path": "/tmp/edited.mxl"}
}

// Validate ABC before converting
{
  "tool": "validate_abc",
  "arguments": {"abc_text": "X:1\nT:My Song\n..."}
}
```

## ABC notation basics

This server uses ABC standard v2.1:

- `c` (lowercase) = C4 (middle C)
- `C` (uppercase) = C3 (one octave below middle C)
- Apostrophe raises an octave: `c'` = C5
- Comma lowers an octave: `C,` = C2

Round-trips preserve notes within ±2%. Dynamics and complex articulations are not preserved.

## Testing

```bash
# All tests including integration (round-trip SATB conversion)
VIRTUAL_ENV= .venv/bin/pytest tests/ -v
```

## Dependencies

- [music21](https://web.mit.edu/music21/) — score parsing; ABC output uses a custom serializer (music21 9.x has no ABC writer)
- [mcp](https://github.com/modelcontextprotocol/python-sdk) — MCP protocol

## System requirements

- Python 3.11+
- No system libraries required
