mxl-agent 0.1.0__py3-none-any.whl

mxl_agent/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

mxl_agent/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Adapters over optional external tools (Section 8.2). Nothing in the core engine imports these
+-- each is reached only through its own module, and only when the corresponding capability is
+actually requested."""
+
+from __future__ import annotations

mxl_agent/adapters/chord_text.py

@@ -0,0 +1,89 @@
+"""Chord-chart text adapters: a small, pluggable text grammar for typed chord-chart input
+(Section 15.12, 20 Slice 8.2).
+
+This slice implements only "a small documented generic dialect" -- the spec bullet's first half.
+JJazzLab-oriented fixtures/dialect support is a documented follow-up, not implemented here.
+
+Grammar (the "generic" dialect):
+
+- Bars are separated by ``|``. A single leading and/or trailing ``|`` (an opening/closing
+  barline) is optional and stripped before splitting -- it does not itself produce an extra bar.
+- Within a bar, chord symbols are separated by whitespace and are spaced evenly across the bar's
+  exact quarter-note length (Section 3.5's exact rational time, never a float): the *i*-th of
+  *n* tokens in a bar sits at offset ``i * measure_length / n``.
+- An empty bar (no tokens between two ``|``) means no chord in that measure -- a deliberate rest/
+  unspecified bar, not an error.
+- A bar containing exactly the single token ``%`` repeats the immediately preceding bar's chord
+  entries verbatim (the standard chart "simile" convention); it cannot be the chart's first bar,
+  and cannot be mixed with other tokens in the same bar.
+
+This grammar does not itself validate chord-symbol *text* -- ``symbol`` is carried through as-is.
+That mirrors ``generate.lead_sheet``'s own layering: its harmony entries aren't run through
+``model.harmony.parse_chord_symbol`` until they are actually materialized, keeping "chart
+grammar" and "chord-symbol semantics" as two separately testable layers.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from fractions import Fraction
+
+from mxl_agent.errors import MxlAgentError
+from mxl_agent.model.duration import measure_quarter_length
+
+__all__ = ["ChordChartParseError", "ChordChartEntry", "parse_generic_chord_chart"]
+
+
+class ChordChartParseError(MxlAgentError):
+    code = "CHORD_CHART_PARSE_ERROR"
+
+
+@dataclass(frozen=True)
+class ChordChartEntry:
+    offset_q: Fraction
+    symbol: str
+
+
+def _strip_outer_barlines(text: str) -> str:
+    stripped = text.strip()
+    if stripped.startswith("|"):
+        stripped = stripped[1:]
+    if stripped.endswith("|"):
+        stripped = stripped[:-1]
+    return stripped
+
+
+def parse_generic_chord_chart(
+    text: str, *, beats: int, beat_type: int
+) -> tuple[tuple[ChordChartEntry, ...], ...]:
+    """Parse ``text`` (the generic dialect above) into one tuple of ``ChordChartEntry`` per bar,
+    in order. ``beats``/``beat_type`` give the time signature used to space each bar's tokens --
+    same meaning as ``model.duration.measure_quarter_length``."""
+    if not text.strip():
+        raise ChordChartParseError("chord chart text is empty")
+    measure_length = measure_quarter_length(beats, beat_type)
+
+    bars: list[tuple[ChordChartEntry, ...]] = []
+    body = _strip_outer_barlines(text)
+    for bar_index, raw_bar in enumerate(body.split("|")):
+        tokens = raw_bar.split()
+        if "%" in tokens:
+            if tokens != ["%"]:
+                raise ChordChartParseError(
+                    f"bar {bar_index}: '%' must be the only token in its bar, got {tokens!r}"
+                )
+            if not bars:
+                raise ChordChartParseError(
+                    f"bar {bar_index} uses '%' but there is no preceding bar to repeat"
+                )
+            bars.append(bars[-1])
+            continue
+
+        count = len(tokens)
+        bars.append(
+            tuple(
+                ChordChartEntry(offset_q=measure_length * i / count, symbol=token)
+                for i, token in enumerate(tokens)
+            )
+        )
+    return tuple(bars)

mxl_agent/adapters/jjazzlab_sng.py

@@ -0,0 +1,200 @@
+"""JJazzLab ``.sng`` chord-chart import (Section 15.12, 20 Slice 8.2's JJazzLab residual,
+Slice 11.13).
+
+``.sng`` is JJazzLab's own project file format: a custom (not raw-reflection XStream) XML
+serialization of its internal song model, undocumented and not covered by any compatibility
+guarantee -- field names could shift across JJazzLab versions. Reverse-engineered here against a
+real corpus of ~1,460 ``.sng`` files (JJazzLab 4, each itself converted from iReal Pro charts via
+MuseScore/MusicXML import), not just a single sample. Read-only and best-effort: this project
+never authors ``.sng``, only extracts a chord leadsheet from an existing one.
+
+Structure actually observed (the only part this adapter reads):
+
+- ``<Song spName="..." spTempo="...">`` -- the whole project. ``spName``/``spTempo`` become
+  ``JJazzLabChart.name``/``.tempo``.
+- ``<spChordLeadSheet><spItems>...</spItems><spSize>N</spSize></spChordLeadSheet>`` -- the chord
+  chart itself, ``N`` bars long (global bar count, not per-section). ``<spItems>`` interleaves:
+  - ``<CLI__SectionImpl spName="..." spTs="FOUR_FOUR" spBarIndex="8">`` -- a section starting at
+    a global bar index, carrying its own time signature (``spTs``: one of the seven enum values
+    in ``_TIME_SIGNATURES`` below, the complete set found across the whole corpus). A later
+    section's ``spTs`` applies from its ``spBarIndex`` onward, carried forward exactly like every
+    other "active X at this position" walk in this codebase (e.g. ``analysis._key.active_key_at``)
+    -- confirmed necessary, not just theoretical: several real files in the corpus do change time
+    signature mid-chart.
+  - ``<CLI__ChordSymbolImpl>`` wrapping ``<spChord spName="Fm7" .../>`` (the chord symbol text,
+    JJazzLab's own dialect, structurally the same vocabulary as a plain pop chord symbol -- slash
+    chords, altered tensions, etc.) and ``<spPos spPos="[bar:beat]"/>`` (a 0-indexed global bar
+    and a 0-indexed *beat* within that bar's own time signature -- confirmed against real files:
+    beat values only ever appear in the range the active time signature's beat count allows).
+    When a section repeats an earlier one with the exact same chord (common: an "A-2" section
+    reusing "A-1"'s chords), JJazzLab does not duplicate the ``<spChord>`` content -- it writes an
+    empty ``<spChord reference="../../CLI__ChordSymbolImpl[N]/spChord"/>`` pointing back at the
+    first real one instead (an XStream object-identity back-reference). Confirmed the *only*
+    reference shape in the corpus (``_CHORD_BACK_REFERENCE``); resolved via a validated,
+    restricted XPath lookup rather than executing the untrusted ``reference`` string outright.
+
+Deliberately not read: ``<spSongStructure>``/``<SongPartImpl>`` (rhythm-style/playback assignment
+-- a different concern from the chord chart itself), ``<spRenderingInfo>`` (display-only chord
+symbol features like PEDAL_BASS), ``<spClientProperties>`` (arbitrary key/value extension data),
+and the back-reference ``reference="../.."``-style XStream plumbing used for cyclic object graphs.
+None of these affect the chord-chart content this adapter extracts.
+
+Output deliberately mirrors ``adapters.chord_text.parse_generic_chord_chart``'s shape -- one tuple
+of ``ChordChartEntry`` per bar, same dataclass -- so a parsed JJazzLab chart slots into the exact
+same "copy into `create lead-sheet`'s `measures[].harmony` by hand" workflow Slice 8.2 already
+established, rather than inventing a second, incompatible typed shape for the same kind of data.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from fractions import Fraction
+
+from lxml import etree
+
+from mxl_agent.adapters.chord_text import ChordChartEntry
+from mxl_agent.errors import MxlAgentError
+from mxl_agent.model.duration import measure_quarter_length
+from mxl_agent.xml.parser import parse_xml_document
+
+# The one back-reference shape found across a ~1,460-file corpus (see below): a repeated chord
+# object -- the same chord symbol reused verbatim, typically because a later section repeats an
+# earlier one -- is serialized as an empty `<spChord reference="../../CLI__ChordSymbolImpl.../
+# spChord"/>` pointing back at the first `<spChord>` with the real content, instead of duplicating
+# it. Validated against this fixed pattern (rather than handed to `.xpath()` unchecked) since
+# `reference` is untrusted input and arbitrary XPath is not a string this project executes blind.
+_CHORD_BACK_REFERENCE = re.compile(r"^(?:\.\./)+CLI__ChordSymbolImpl(?:\[[1-9][0-9]*\])?/spChord$")
+
+__all__ = ["JJazzLabSngParseError", "JJazzLabChart", "parse_jjazzlab_sng"]
+
+
+class JJazzLabSngParseError(MxlAgentError):
+    code = "JJAZZLAB_SNG_PARSE_ERROR"
+
+
+# The complete set of JJazzLab time-signature enum values found across a ~1,460-file corpus.
+_TIME_SIGNATURES: dict[str, tuple[int, int]] = {
+    "TWO_FOUR": (2, 4),
+    "THREE_FOUR": (3, 4),
+    "FOUR_FOUR": (4, 4),
+    "FIVE_FOUR": (5, 4),
+    "SIX_FOUR": (6, 4),
+    "SIX_EIGHT": (6, 8),
+    "TWELVE_EIGHT": (12, 8),
+}
+
+
+@dataclass(frozen=True)
+class JJazzLabChart:
+    name: str
+    tempo: int | None
+    bars: tuple[tuple[ChordChartEntry, ...], ...]
+
+
+def _resolve_chord_element(spchord_el: etree._Element) -> etree._Element:
+    """Follow a repeated chord's back-``reference`` (see ``_CHORD_BACK_REFERENCE``) to the
+    ``<spChord>`` element that actually carries ``spName``; returns ``spchord_el`` unchanged if it
+    has no ``reference``."""
+    reference = spchord_el.get("reference")
+    if reference is None:
+        return spchord_el
+    if not _CHORD_BACK_REFERENCE.match(reference):
+        raise JJazzLabSngParseError(f"unrecognized <spChord> reference shape: {reference!r}")
+    targets = spchord_el.xpath(reference)
+    if not isinstance(targets, list) or not targets or not isinstance(targets[0], etree._Element):
+        raise JJazzLabSngParseError(f"<spChord> reference {reference!r} does not resolve")
+    return targets[0]
+
+
+def _parse_position(raw: str, item_desc: str) -> tuple[int, int]:
+    body = raw[1:-1] if raw.startswith("[") and raw.endswith("]") else None
+    if body is None or ":" not in body:
+        raise JJazzLabSngParseError(f"{item_desc}: malformed position {raw!r}")
+    bar_text, _, beat_text = body.partition(":")
+    try:
+        return int(bar_text), int(beat_text)
+    except ValueError as exc:
+        raise JJazzLabSngParseError(f"{item_desc}: malformed position {raw!r}") from exc
+
+
+def parse_jjazzlab_sng(data: bytes) -> JJazzLabChart:
+    """Extract a chord chart from a JJazzLab ``.sng`` project file's bytes."""
+    tree = parse_xml_document(data)
+    root = tree.getroot()
+    if root.tag != "Song":
+        raise JJazzLabSngParseError(f"expected a <Song> root element, got <{root.tag}>")
+
+    name = root.get("spName") or ""
+    tempo_text = root.get("spTempo")
+    tempo = int(tempo_text) if tempo_text is not None and tempo_text.isdigit() else None
+
+    leadsheet = root.find("spChordLeadSheet")
+    if leadsheet is None:
+        raise JJazzLabSngParseError("<Song> has no <spChordLeadSheet>")
+    items = leadsheet.find("spItems")
+    size_el = leadsheet.find("spSize")
+    if items is None or size_el is None or size_el.text is None:
+        raise JJazzLabSngParseError("<spChordLeadSheet> is missing <spItems> or <spSize>")
+    try:
+        size = int(size_el.text)
+    except ValueError as exc:
+        raise JJazzLabSngParseError(f"<spSize> is not an integer: {size_el.text!r}") from exc
+
+    sections: list[tuple[int, tuple[int, int]]] = []
+    for section_el in items.findall("CLI__SectionImpl"):
+        bar_index_text = section_el.get("spBarIndex")
+        ts_text = section_el.get("spTs")
+        if bar_index_text is None or ts_text is None:
+            raise JJazzLabSngParseError("<CLI__SectionImpl> is missing spBarIndex or spTs")
+        if ts_text not in _TIME_SIGNATURES:
+            raise JJazzLabSngParseError(f"unrecognized JJazzLab time signature {ts_text!r}")
+        try:
+            bar_index = int(bar_index_text)
+        except ValueError as exc:
+            raise JJazzLabSngParseError(
+                f"<CLI__SectionImpl> spBarIndex is not an integer: {bar_index_text!r}"
+            ) from exc
+        sections.append((bar_index, _TIME_SIGNATURES[ts_text]))
+    if not sections or sections[0][0] != 0:
+        raise JJazzLabSngParseError("chord leadsheet has no section starting at bar 0")
+    sections.sort(key=lambda entry: entry[0])
+
+    def _time_signature_at(bar_index: int) -> tuple[int, int]:
+        active = sections[0][1]
+        for start, time_signature in sections:
+            if start > bar_index:
+                break
+            active = time_signature
+        return active
+
+    entries_by_bar: dict[int, list[tuple[int, str]]] = {}
+    for chord_el in items.findall("CLI__ChordSymbolImpl"):
+        chord_ref = chord_el.find("spChord")
+        pos_ref = chord_el.find("spPos")
+        if chord_ref is None or pos_ref is None:
+            raise JJazzLabSngParseError("<CLI__ChordSymbolImpl> is missing spChord or spPos")
+        chord_ref = _resolve_chord_element(chord_ref)
+        symbol = chord_ref.get("spName")
+        pos_text = pos_ref.get("spPos")
+        if symbol is None or pos_text is None:
+            raise JJazzLabSngParseError("<CLI__ChordSymbolImpl> is missing spName or spPos")
+        bar_index, beat = _parse_position(pos_text, f"chord {symbol!r}")
+        if not (0 <= bar_index < size):
+            raise JJazzLabSngParseError(
+                f"chord {symbol!r} at bar {bar_index} is outside the chart's {size}-bar range"
+            )
+        entries_by_bar.setdefault(bar_index, []).append((beat, symbol))
+
+    bars: list[tuple[ChordChartEntry, ...]] = []
+    for bar_index in range(size):
+        beats, beat_type = _time_signature_at(bar_index)
+        quarter_per_beat = measure_quarter_length(beats, beat_type) / beats
+        raw_entries = sorted(entries_by_bar.get(bar_index, ()), key=lambda entry: entry[0])
+        bars.append(
+            tuple(
+                ChordChartEntry(offset_q=Fraction(beat) * quarter_per_beat, symbol=symbol)
+                for beat, symbol in raw_entries
+            )
+        )
+    return JJazzLabChart(name=name, tempo=tempo, bars=tuple(bars))

mxl_agent/adapters/mcp.py

@@ -0,0 +1,246 @@
+"""MCP server adapter: exposes the Slice 10.1 `session` service as MCP tools, plus an embedded,
+read-only score view through the MCP Apps extension (Section 15.10/15.13, 20 Slice 10.2/10.3).
+
+Read-only tools first (Section 20's own MCP rollout order): every session tool here calls the
+exact same ``mxl_agent.service.session`` functions the CLI's ``session open``/``status``/
+``checkout``/``revisions`` commands do -- "The MCP server delegates to the same application
+service used by the CLI. It must not duplicate parsing or editing logic" (Section 15.10). None
+of these tools mutate score content; ``checkout`` only moves a session's current-revision
+pointer between revisions that already exist.
+
+Every tool returns the *same* JSON envelope shape the CLI's ``--json`` output does
+(``mxl_agent.result.build_envelope``) rather than raising on an expected failure -- one client
+sees one contract whether it calls the CLI or MCP.
+
+``session_view`` additionally renders that score as an embedded "MCP App" (a still-evolving MCP
+extension, specification dated 2026-01-26) -- a read-only Verovio SVG shown inline in a
+compatible client, through ``mcp.server.apps.Apps`` and the vendored official client library
+(``adapters/vendor/ext_apps_client.js``, see NOTICE). This project never reimplements that
+extension's JSON-RPC-over-postMessage handshake itself (Section 22: "prefer reusing tested
+machinery over re-deriving it"). Server-side registration and the tool's own structured output
+are covered by this project's test suite; end-to-end rendering inside a real compatible host is
+not, since no such host is available in this environment -- an explicit, documented limitation
+(Section 21).
+
+This module is the only place that imports the optional ``mcp`` package -- like
+``adapters.verovio``/``adapters.musescore``, it is entirely absent from the default install and
+the core CLI/library never import it (CLAUDE.md: "Core behavior must work without Claude, a
+browser, Verovio, or MuseScore").
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from mxl_agent.adapters.verovio import render_score_page
+from mxl_agent.errors import MxlAgentError
+from mxl_agent.result import build_envelope
+from mxl_agent.service import session as session_service
+from mxl_agent.session.workspace import DEFAULT_WORKSPACE_ROOT, open_workspace
+
+__all__ = ["McpUnavailableError", "build_server", "run_stdio_server", "mcp_availability"]
+
+_SCORE_VIEW_RESOURCE_URI = "ui://mxl-agent/score-view"
+_VENDORED_CLIENT_JS_PATH = Path(__file__).parent / "vendor" / "ext_apps_client.js"
+
+
+class McpUnavailableError(MxlAgentError):
+    code = "MCP_UNAVAILABLE"
+
+
+def _import_mcp_server_class() -> Any:
+    try:
+        from mcp.server.mcpserver import MCPServer
+    except ImportError:
+        return None
+    return MCPServer
+
+
+def _import_apps_extension_class() -> Any:
+    try:
+        from mcp.server.apps import Apps
+    except ImportError:
+        return None
+    return Apps
+
+
+def mcp_availability() -> dict[str, object]:
+    """``doctor``'s capability-detection payload for the optional MCP server (`mcp-serve`)."""
+    if _import_mcp_server_class() is None:
+        return {"available": False, "version": None}
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        installed_version = version("mcp")
+    except PackageNotFoundError:
+        installed_version = None
+    return {"available": True, "version": installed_version}
+
+
+def _build_score_view_html() -> str:
+    """The ``ui://mxl-agent/score-view`` resource: the vendored MCP Apps client library, plus a
+    small amount of mxl-agent-authored initialization that connects to the host and renders
+    whatever SVG the ``session_view`` tool's ``structuredContent.svg`` carries."""
+    vendored_js = _VENDORED_CLIENT_JS_PATH.read_text(encoding="utf-8")
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta name="color-scheme" content="light dark">
+<title>mxl-agent score view</title>
+<style>
+  body {{ margin: 0; padding: 8px; font-family: system-ui, sans-serif; }}
+  #score svg {{ max-width: 100%; height: auto; }}
+</style>
+</head>
+<body>
+<div id="score">Loading score...</div>
+<script type="module">
+{vendored_js}
+
+// -- mxl-agent's own initialization (Slice 10.3), using the App class the vendored library
+// -- above exposed via window.McpApp (see the comment at the end of that file).
+const {{ App }} = window.McpApp;
+const app = new App({{ name: "mxl-agent score view", version: "1.0.0" }});
+const container = document.getElementById("score");
+
+function render(result) {{
+  const content = result && result.structuredContent;
+  if (content && content.ok && content.svg) {{
+    container.innerHTML = content.svg;
+  }} else if (content && content.error) {{
+    container.textContent = "Could not render score: " + content.error.message;
+  }} else {{
+    container.textContent = "No score data received.";
+  }}
+}}
+
+app.ontoolresult = render;
+app.onerror = (err) => {{ container.textContent = "Error: " + err; }};
+app.connect().catch((err) => {{ container.textContent = "Failed to connect: " + err; }});
+</script>
+</body>
+</html>"""
+
+
+def _tool_result(command: str, fn: Callable[[], dict[str, Any]]) -> dict[str, Any]:
+    """Run ``fn``, returning the same envelope shape ``cli._run`` builds for ``--json`` output
+    -- an expected ``MxlAgentError`` becomes ``{"ok": false, "error": {...}}``, never a raised
+    exception the MCP transport would have to translate on our behalf."""
+    try:
+        result = fn()
+        return build_envelope(command, ok=True, **result)
+    except MxlAgentError as exc:
+        return build_envelope(command, ok=False, **exc.to_envelope_fields())
+
+
+def build_server(*, workspace_root: Path = DEFAULT_WORKSPACE_ROOT) -> Any:
+    """Build (but do not run) the MCP server exposing the session tool family.
+
+    Raises ``McpUnavailableError`` if the optional ``mcp`` package isn't installed.
+    """
+    mcp_server_cls = _import_mcp_server_class()
+    if mcp_server_cls is None:
+        raise McpUnavailableError(
+            "the optional `mcp` package is not installed (install the `mcp` extra to enable this)"
+        )
+
+    # The Apps extension (Slice 10.3) is registered before the server itself is constructed --
+    # MCPServer takes its extensions at construction time. Older installs of the `mcp` package
+    # may lack this specific extension even when the base server class is present, so this is
+    # guarded separately: a missing Apps extension degrades to "no embedded score view", not to
+    # "no MCP server at all".
+    apps_extension_cls = _import_apps_extension_class()
+    extensions = None
+    if apps_extension_cls is not None:
+        apps_extension = apps_extension_cls()
+        apps_extension.add_html_resource(
+            _SCORE_VIEW_RESOURCE_URI,
+            _build_score_view_html(),
+            name="score-view",
+            title="Score view",
+            description="A read-only rendered view of the session's current score.",
+        )
+
+        @apps_extension.tool(resource_uri=_SCORE_VIEW_RESOURCE_URI)  # type: ignore[untyped-decorator]
+        async def session_view(session_id: str, page: int = 1) -> dict[str, Any]:
+            """Render the session's current revision as an embedded score view (Section
+            15.13, Slice 10.3), through the optional Verovio integration -- read-only.
+
+            Declared ``async`` (and calling Verovio directly, not via a thread pool) on purpose:
+            the MCP SDK dispatches plain ``def`` tool functions through ``anyio.to_thread``, and
+            Verovio's native toolkit has been observed to permanently break every later call in
+            the process once its first use happens on such a worker thread rather than the main
+            thread (see ROADMAP.md Slice 10.3). Blocking the event loop briefly here is an
+            acceptable trade-off for a single-client local stdio server (Section 15.10).
+            """
+
+            def _fn() -> dict[str, Any]:
+                ws = open_workspace(session_id, workspace_root=workspace_root)
+                svg = render_score_page(ws.read_working_bytes(), page=page)
+                return {"session_id": session_id, "page": page, "svg": svg}
+
+            return _tool_result("session_view", _fn)
+
+        extensions = [apps_extension]
+
+    server = mcp_server_cls(name="mxl-agent", extensions=extensions)
+
+    @server.tool()  # type: ignore[untyped-decorator]
+    def session_open(input_path: str, score: str | None = None) -> dict[str, Any]:
+        """Open a .musicxml, .xml, or .mxl file into a new session at revision 0. `score`
+        selects which score to open when an .mxl package declares more than one."""
+
+        def _fn() -> dict[str, Any]:
+            data = Path(input_path).read_bytes()
+            return session_service.open_session(
+                data, workspace_root=workspace_root, score_selector=score
+            )
+
+        return _tool_result("session_open", _fn)
+
+    @server.tool()  # type: ignore[untyped-decorator]
+    def session_status(session_id: str) -> dict[str, Any]:
+        """The session's current revision and (if `undo` was just called) its pending redo
+        target."""
+        return _tool_result(
+            "session_status",
+            lambda: session_service.session_status(session_id, workspace_root=workspace_root),
+        )
+
+    @server.tool()  # type: ignore[untyped-decorator]
+    def session_checkout(
+        session_id: str, revision: int | None = None, checkpoint: str | None = None
+    ) -> dict[str, Any]:
+        """Jump directly to any existing revision, by number or by checkpoint name (exactly one
+        of `revision`/`checkpoint` is required)."""
+        return _tool_result(
+            "session_checkout",
+            lambda: session_service.session_checkout(
+                session_id,
+                revision=revision,
+                checkpoint=checkpoint,
+                workspace_root=workspace_root,
+            ),
+        )
+
+    @server.tool()  # type: ignore[untyped-decorator]
+    def session_revisions(session_id: str) -> dict[str, Any]:
+        """Every revision's own metadata, sorted by revision number -- the full branch
+        structure."""
+        return _tool_result(
+            "session_revisions",
+            lambda: session_service.session_revisions(session_id, workspace_root=workspace_root),
+        )
+
+    return server
+
+
+def run_stdio_server(*, workspace_root: Path = DEFAULT_WORKSPACE_ROOT) -> None:
+    """Build and run the MCP server over stdio -- the standard transport for a locally spawned
+    MCP server process."""
+    server = build_server(workspace_root=workspace_root)
+    server.run(transport="stdio")

mxl_agent/adapters/mei.py

@@ -0,0 +1,59 @@
+"""MEI adapter: optional MusicXML -> MEI conversion and MEI -> SVG render interoperability,
+through the same optional Verovio integration (Section 8.2, 9.6; 20 Slice 9.6).
+
+MEI (Music Encoding Initiative) is supported only for export and read-only rendering
+interoperability -- never as an editable input format (CLAUDE.md: "MusicXML is canonical. Never
+regenerate a score through MIDI, MEI, music21, Verovio, or MuseScore."). There is no
+``session open`` path for MEI and no MEI-sourced workspace: ``convert_to_mei`` returns a plain
+string the caller may save wherever it likes, and ``render_mei_to_svg`` renders a standalone MEI
+document directly, entirely outside the session/workspace system.
+
+Reuses ``adapters.verovio``'s toolkit loader and error types -- MEI support is the same optional
+Verovio dependency, just a different input/output format.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mxl_agent.adapters.verovio import VerovioRenderError, _load_toolkit
+
+__all__ = ["convert_to_mei", "render_mei_to_svg"]
+
+
+def convert_to_mei(musicxml_bytes: bytes, *, options: dict[str, Any] | None = None) -> str:
+    """Convert ``musicxml_bytes`` (raw, uncompressed MusicXML) to an MEI XML string, through
+    Verovio. Export/interoperability only: the result is never written back as a session's
+    canonical document.
+
+    Raises ``VerovioUnavailableError``/``VerovioRenderError`` (same meanings as
+    ``adapters.verovio.render_score_page``).
+    """
+    toolkit = _load_toolkit(musicxml_bytes, options)
+    try:
+        return str(toolkit.getMEI())
+    except Exception as exc:
+        raise VerovioRenderError(f"verovio failed to convert to MEI: {exc}") from exc
+
+
+def render_mei_to_svg(mei_bytes: bytes, *, page: int = 1) -> str:
+    """Render page ``page`` (1-based) of a standalone MEI document to an SVG string, through
+    Verovio. Read-only interoperability: ``mei_bytes`` is never opened as a session/workspace,
+    and MEI never becomes this project's canonical document.
+
+    Raises ``VerovioUnavailableError`` if the optional package isn't installed, or
+    ``VerovioRenderError`` if Verovio can't load ``mei_bytes`` or ``page`` is out of range.
+    """
+    toolkit = _load_toolkit(mei_bytes, input_from="mei")
+
+    page_count = toolkit.getPageCount()
+    if page < 1 or page > page_count:
+        raise VerovioRenderError(
+            f"page {page} is out of range (document has {page_count} page(s))",
+            page=page,
+            page_count=page_count,
+        )
+    try:
+        return str(toolkit.renderToSVG(page))
+    except Exception as exc:
+        raise VerovioRenderError(f"verovio failed to render page {page}: {exc}") from exc