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.

Without cloning this repo: since mxl-agent is published to PyPI, uvx can run it ephemerally (no persistent install, no local checkout) for Claude Desktop or any other MCP client:

{
  "mcpServers": {
    "mxl-agent": {
      "command": "uvx",
      "args": ["--from", "mxl-agent[mcp]", "mxl-agent", "mcp-serve", "--workspace-root", "/path/to/workspace"]
    }
  }
}

Verified: uvx --from "mxl-agent[mcp]" mxl-agent doctor --json reports integrations.mcp.available: true from a clean environment (the same import mcp-serve itself depends on); the server's own tool-registration and request-handling logic is covered by this project's existing test suite, not re-verified here. Add --from "mxl-agent[mcp,render]" for session_view's embedded-SVG rendering too.

mcp-serve also supports --transport streamable-http [--host HOST] [--port PORT] (Slice 13.7) for a client that needs a remote HTTP endpoint rather than a locally spawned subprocess -- e.g. ChatGPT's custom MCP connectors, which only accept a remote HTTPS endpoint over Streamable HTTP or SSE, never stdio (confirmed against current OpenAI documentation as of 2026-08-30). Binds to 127.0.0.1 by default and applies no authentication -- do not bind a public interface without first putting your own auth/TLS in front of it (see ROADMAP.md's Slice 13.8, still open).

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.

Using mxl-agent from ChatGPT

There is no ChatGPT equivalent of Claude's Agent Skill format, so this is not a guided workflow the way the Claude Skill is -- it's raw CLI access, and its reachability is not guaranteed. In a ChatGPT session with Code Interpreter enabled, you can try asking it to run:

pip install mxl-agent
mxl-agent session open <uploaded-file> --json
mxl-agent inspect summary <session_id> --json

This may not work at all, depending on your ChatGPT account/tier: Code Interpreter's sandbox has historically had no general internet access by design, and a real user found ChatGPT reporting PyPI unreachable when they tried this. What's actually verified is only that mxl-agent itself installs and runs correctly once pip install succeeds -- not that every ChatGPT session can reach PyPI at all. The longer-term path is a real MCP connector (see "MCP server (optional)" above) hosted somewhere reachable -- ChatGPT calling out to a server, which doesn't depend on this uncertain sandbox networking. That path isn't usable yet either: the MCP server currently exposes only read-only session tools (open/status/checkout/revisions/view), with no inspect, edit, validate, or export, and it only opens files by a path on the server's own disk. See ROADMAP.md Slice 13.14.

If pip install does work in your session: because there's no skill file encoding this project's workflow discipline (dry-run before apply, validate after apply, never paste raw XML into the conversation -- see mxl_agent-skill.md Section 14.4/14.5), whether ChatGPT actually follows that discipline depends entirely on the model and the prompt, not on anything this project enforces. Ask it explicitly to run plan before apply and validate after, and to use inspect/analyze rather than reading the file directly.

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