Metadata-Version: 2.5
Name: mxl-agent
Version: 0.1.1
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`.

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

```json
{
  "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](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.

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

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