Metadata-Version: 2.5
Name: mxl-agent
Version: 0.1.0
Summary: Deterministic local MusicXML engine and Claude Code Agent Skill
License: MIT
License-File: LICENSE
License-File: NOTICE
Requires-Python: >=3.12
Requires-Dist: lxml>=5.2
Requires-Dist: pydantic>=2.7
Requires-Dist: typer>=0.12
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: render
Requires-Dist: verovio>=4.0; extra == 'render'
Description-Content-Type: text/markdown

# mxl-agent

A deterministic local MusicXML engine and Claude Code Agent Skill. See
[`mxl_agent-skill.md`](mxl_agent-skill.md) for the full product and engineering specification,
[`ROADMAP.md`](ROADMAP.md) for current implementation status, [`CHANGELOG.md`](CHANGELOG.md) for
what's shipped, and [`COMPATIBILITY.md`](COMPATIBILITY.md) for what's actually been verified
against which Python/OS/optional-integration versions. Licensed under [MIT](LICENSE).

## Development

```bash
uv sync
uv run mxl-agent --help
uv run mxl-agent doctor --json
uv run python scripts/check.py fast
```

## Release engineering

`uv run python scripts/check.py release` builds the package twice and confirms the wheel/sdist
come out byte-for-byte identical, then writes a CycloneDX SBOM and a dependency vulnerability
report to `dist/` (gitignored). It does not sign or publish anything -- see `CHANGELOG.md`'s
"Known limitations" and `ROADMAP.md`'s Slice 10.6 note for what's intentionally out of scope.

## MCP server (optional)

`mxl-agent mcp-serve` runs an [MCP](https://modelcontextprotocol.io) server over stdio, exposing
the `session` tools (`open`/`status`/`checkout`/`revisions`) and a read-only `session_view` tool
to any MCP client. Needs the optional `mcp` extra (and, for `session_view`'s own rendering, the
optional `render` extra too):

```bash
uv sync --extra mcp --extra render
uv run mxl-agent doctor --json   # integrations.mcp.available should be true
```

Point an MCP client at `uv run --directory <this repo> mxl-agent mcp-serve` (add
`--workspace-root <path>` to use a workspace directory other than the default
`.mxl-agent/workspaces`). This is a separate integration from the Claude Code Agent Skill
(`.claude/skills/mxl-agent/`) -- the skill's own wrapper never spawns `mcp-serve`.

In a client that supports the [MCP Apps](https://github.com/modelcontextprotocol/ext-apps)
extension, `session_view` also renders a read-only, embedded Verovio SVG of the session's current
score inline. This extension is new and still evolving (spec dated 2026-01-26); its client-side
half is implemented by a vendored copy of the official library (see `NOTICE`) and is not verified
end-to-end by this project's own test suite, since no compatible host is available here -- server-
side registration and the tool's own output are tested, actual in-host rendering is not.

## Claude Code plugin

This repository is itself a Claude Code plugin (`.claude-plugin/plugin.json`): opening it (or
installing it as a plugin) exposes the Agent Skill (`.claude/skills/mxl-agent/`), registers the
optional MCP server above (`.mcp.json`, still gated behind the `mcp`/`render` extras actually
being installed), and installs one guardrail hook
(`hooks/hooks.json` -> `hooks/block-workspace-mutation.sh`): a `PreToolUse` check on
`Edit`/`Write`/`MultiEdit` that blocks direct hand-edits to files under a session's workspace
directory (`.mxl-agent/workspaces/`), since that tree is managed exclusively by mxl-agent's own
transactional revision system (CLAUDE.md: "Mutations must be typed, dry-runnable, transactional,
reversible..."). The hook fails open (allows the edit) if it can't parse its input or can't find a
working Python interpreter -- it is a guardrail on top of the transaction system, not the only
protection. Validate the manifest with `claude plugin validate .` (a pre-existing "CLAUDE.md at
the plugin root isn't loaded as project context" warning is expected and intentional -- that file
is this repo's own development instructions, not plugin-shipped user context).
