mxl-agent

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

Development

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 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):

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 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).