Metadata-Version: 2.5
Name: render-mcp
Version: 0.1.2
Summary: MCP server that renders MusicXML to PDF or PNG
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: choir,mcp,music,musicxml,pdf,png,render
Classifier: Development Status :: 3 - Alpha
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 :: Scientific/Engineering :: Visualization
Requires-Python: >=3.11
Requires-Dist: cairosvg>=2.7.0
Requires-Dist: mcp<2.0.0,>=1.28.1
Requires-Dist: pillow>=10.0.0
Requires-Dist: pypdf>=4.0.0
Requires-Dist: verovio>=3.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

# render-mcp

MCP server that renders MusicXML scores to PDF or PNG images.

## What it does

Takes a MusicXML document and produces print-ready PDFs or screen-ready PNG images. Uses Verovio for layout and engraving — no external tools or GUI required.

## Tools

| Tool | Description |
|------|-------------|
| `render_to_pdf` | Render the full score to a multi-page PDF file |
| `render_to_image` | Render a single page to PNG or SVG |
| `list_capabilities` | Return server metadata: backend version, supported formats, available renderers |

## Installation

```bash
cd render-mcp
uv sync
```

`libcairo` is required for PNG output:

```bash
# Ubuntu / Debian (usually pre-installed on desktop systems)
sudo apt install libcairo2
```

## Running

```bash
uv run render-mcp
```

No environment variables required.

## Usage examples

```json
// Render full score to PDF
{
  "tool": "render_to_pdf",
  "arguments": {
    "musicxml_path": "/path/to/score.mxl",
    "output_path": "/tmp/score.pdf"
  }
}

// Render page 1 to PNG at 150 DPI
{
  "tool": "render_to_image",
  "arguments": {
    "musicxml_path": "/path/to/score.mxl",
    "output_path": "/tmp/page1.png",
    "page": 1,
    "dpi": 150
  }
}
```

DPI range: 72–600. Default: 150. Page numbers are 1-indexed.

## Testing

```bash
# All tests including integration (Verovio runs in-process, no external tool needed)
VIRTUAL_ENV= .venv/bin/pytest tests/ -v
```

## Dependencies

- [verovio](https://www.verovio.org/) — MusicXML engraving to SVG (pure Python, in-process)
- [cairosvg](https://cairosvg.org/) — SVG to PNG/PDF conversion
- [pypdf](https://pypdf.readthedocs.io/) — multi-page PDF assembly
- [Pillow](https://python-pillow.org/) — image utilities
- [mcp](https://github.com/modelcontextprotocol/python-sdk) — MCP protocol

## System requirements

- Python 3.11+
- `libcairo2` shared library (for PNG/PDF output via cairosvg)
