roadmap-core 0.2.3__tar.gz → 0.3.0__tar.gz

{roadmap_core-0.2.3/roadmap_core.egg-info → roadmap_core-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roadmap-core
-Version: 0.2.3
+Version: 0.3.0
 Summary: The roadmap work-item and arc graph: status derivation, validation, and markdown rendering. Stdlib-only, so any repo can adopt it without adopting a backend.
 License: MIT
 Project-URL: Source, https://github.com/gald33/roadmap-core
@@ -156,6 +156,41 @@ this rather than by reading the code:
 `ROADMAP_SOURCE=local` selects the SQLite store. Without it the CLI expects the
 API store, which is how Lucille runs it — see `roadmap_core.stores`.
 
+### Agents (MCP)
+
+`roadmap-mcp` serves the same graph to a coding agent as MCP tools over stdio —
+`ready`, `list`, `show`, `validate`, `claim`, `release`, `set_status`. Point a
+client at it:
+
+```json
+{
+  "mcpServers": {
+    "roadmap": {
+      "command": "roadmap-mcp",
+      "env": { "ROADMAP_SOURCE": "local" }
+    }
+  }
+}
+```
+
+**There is no extra to install and no SDK underneath.** `mcp_server.py` speaks
+the JSON-RPC protocol in stdlib, so it is present wherever the package is —
+which is the same reason the rest of this package is dependency-free, applied to
+one more caller. An extra would be one an adopter can forget, for a server that
+needs nothing.
+
+**Reads default to the files**, so an agent in a fresh clone can ask what to
+work on with no store, no server and no token. Writes need a store to arbitrate
+them: set `ROADMAP_SOURCE=local` as above, or the write tools expect the API
+store. There is deliberately no `files` write target — a claim nothing
+adjudicated is not a claim, and two agents could each hold the same item.
+
+**A write tells the agent to commit something, and it means it.** `claim`,
+`release` and `set_status` project into `roadmap/items/<key>.yaml`, and on the
+floor that projection *is* the durable record — an unmerged one is a claim no
+other checkout can see. The tool result carries the CLI's own words for this
+under `notes`.
+
 ### CI
 
 Copy `templates/roadmap.yml` to `.github/workflows/roadmap.yml`. That is the

{roadmap_core-0.2.3 → roadmap_core-0.3.0}/README.md

@@ -135,6 +135,41 @@ this rather than by reading the code:
 `ROADMAP_SOURCE=local` selects the SQLite store. Without it the CLI expects the
 API store, which is how Lucille runs it — see `roadmap_core.stores`.
 
+### Agents (MCP)
+
+`roadmap-mcp` serves the same graph to a coding agent as MCP tools over stdio —
+`ready`, `list`, `show`, `validate`, `claim`, `release`, `set_status`. Point a
+client at it:
+
+```json
+{
+  "mcpServers": {
+    "roadmap": {
+      "command": "roadmap-mcp",
+      "env": { "ROADMAP_SOURCE": "local" }
+    }
+  }
+}
+```
+
+**There is no extra to install and no SDK underneath.** `mcp_server.py` speaks
+the JSON-RPC protocol in stdlib, so it is present wherever the package is —
+which is the same reason the rest of this package is dependency-free, applied to
+one more caller. An extra would be one an adopter can forget, for a server that
+needs nothing.
+
+**Reads default to the files**, so an agent in a fresh clone can ask what to
+work on with no store, no server and no token. Writes need a store to arbitrate
+them: set `ROADMAP_SOURCE=local` as above, or the write tools expect the API
+store. There is deliberately no `files` write target — a claim nothing
+adjudicated is not a claim, and two agents could each hold the same item.
+
+**A write tells the agent to commit something, and it means it.** `claim`,
+`release` and `set_status` project into `roadmap/items/<key>.yaml`, and on the
+floor that projection *is* the durable record — an unmerged one is a claim no
+other checkout can see. The tool result carries the CLI's own words for this
+under `notes`.
+
 ### CI
 
 Copy `templates/roadmap.yml` to `.github/workflows/roadmap.yml`. That is the

{roadmap_core-0.2.3 → roadmap_core-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "roadmap-core"
-version = "0.2.3"
+version = "0.3.0"
 description = "The roadmap work-item and arc graph: status derivation, validation, and markdown rendering. Stdlib-only, so any repo can adopt it without adopting a backend."
 requires-python = ">=3.11"
 readme = "README.md"
@@ -63,6 +63,11 @@ dev = ["pytest>=8"]
 # A dependency-free library whose tool you cannot get is not an adoptable tool.
 [project.scripts]
 roadmap = "roadmap_core.cli:main"
+# The MCP bridge, and no extra to install it: `mcp_server.py` speaks the stdio
+# protocol in stdlib rather than taking the SDK, so it is already installed
+# wherever the package is. An extra here would be an extra that is always
+# empty — and one an adopter could forget, for a server that needs nothing.
+roadmap-mcp = "roadmap_core.mcp_server:main"
 
 [project.urls]
 Source = "https://github.com/gald33/roadmap-core"

roadmap_core-0.3.0/roadmap_core/mcp_server.py

@@ -0,0 +1,662 @@
+"""The roadmap as MCP tools, over stdio, with nothing installed.
+
+**Why this is not built on the MCP SDK.** The package's whole claim is that it
+stands alone — ``tests.yml``'s ``isolation`` job installs ``[dev]`` and then
+*fails* if ``app``, ``fastapi``, ``sqlalchemy`` or ``yaml`` is importable at
+all, because the graph and the store have to work in a checkout with nothing
+provisioned. A hard dependency on ``mcp`` would end that, and putting it behind
+an extra would only move the question to whichever environment forgot the
+extra. The protocol is newline-delimited JSON-RPC over two pipes; it is written
+out below in stdlib. This is the same call ``switchboard/mcp_server.py`` made,
+and for the same reason it gives: an SDK that renames its API between majors is
+a second thing that can break a server whose own logic did not change.
+
+**STDOUT IS THE PROTOCOL.** Every byte on stdout has to be a JSON-RPC frame, and
+the CLI this server delegates its writes to is a *printing* program — ``claim``
+alone emits four lines, one of them the "when you finish" notice. Those prints
+are not incidental output to be silenced: they are what the CLI tells an
+operator, so they are captured and returned as the tool's own text. That is what
+``_capture`` is for, and it is load-bearing rather than tidy. A single
+uncaptured ``print`` corrupts the stream for the rest of the session, and it
+fails as a client-side parse error a long way from the line that caused it.
+
+**Writes go through the CLI; reads do not.** The two halves are asymmetric on
+purpose:
+
+  writes  ``cmd_claim`` / ``cmd_release`` / ``cmd_status`` do more than talk to
+          the store. They project the claim into ``roadmap/items/<key>.yaml``,
+          take the Switchboard write lock around that read-modify-write, drop
+          the claim when a status reaches ``done``, and warn about artifact
+          contention. That sequence is the repository's answer to
+          "a-claim-cannot-survive-the-floors-ci"; a second copy of it here
+          would be a second answer, free to drift from the first.
+
+  reads   ``list`` / ``ready`` / ``show`` / ``validate`` are ``load()`` plus
+          ``graph``, which are pure. The CLI's versions of these print aligned
+          columns for a human; an agent wants the fields. So the reads are
+          composed here from the same functions the printers use, rather than
+          scraped back out of their output.
+
+**Source resolution matches the CLI exactly**, because an agent and a terminal
+in the same checkout disagreeing about which store they are looking at is the
+kind of difference nobody thinks to check. Reads default to ``files`` — no
+server, no JWT, no network, which is what makes a fresh clone answerable —
+and ``ROADMAP_SOURCE`` overrides that for both halves, as it does for the CLI.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import json
+import os
+import sys
+import traceback
+from argparse import Namespace
+from contextlib import redirect_stderr, redirect_stdout
+from typing import Any, Callable
+
+from . import graph
+from .cli import installed_version, load, load_arcs
+
+__all__ = ["TOOLS", "UnknownTool", "dispatch", "handle_request", "serve_stdio", "main"]
+
+# Negotiated in `initialize`. A client asking for something in this set gets it
+# back verbatim; anything else is answered with the newest we speak, which is
+# what the spec asks a server to do rather than failing the handshake.
+LATEST_PROTOCOL = "2025-06-18"
+SUPPORTED_PROTOCOLS = (LATEST_PROTOCOL, "2025-03-26", "2024-11-05")
+
+JSONRPC_PARSE_ERROR = -32700
+JSONRPC_INVALID_REQUEST = -32600
+JSONRPC_METHOD_NOT_FOUND = -32601
+JSONRPC_INTERNAL_ERROR = -32603
+
+INSTRUCTIONS = (
+    "The roadmap is this repository's backlog as a dependency graph. Call `ready` "
+    "before starting work — it lists only what is startable right now, in the order "
+    "the queue hands work out, and flags items that share a mutable artifact with a "
+    "live claim. Call `claim` before you begin so another session does not take the "
+    "same item, and `release` when you finish or stop; an unreleased claim keeps the "
+    "item off everyone's queue. Use `set_status` to move an item deliberately — "
+    "`verifying` keeps the claim (the branch that shipped it still owns confirming "
+    "it), `done` drops it.\n\n"
+    "Reads default to the committed `roadmap/items/*.yaml` files, so they work with "
+    "no server, no database and no token. Set ROADMAP_SOURCE=local to read and write "
+    "a SQLite store instead, or ROADMAP_SOURCE=db for a served backend. Writes "
+    "project into the item files and tell you to commit them — that projection is "
+    "how a claim survives, so do commit it."
+)
+
+
+def log(message: str) -> None:
+    """Stderr, always. See this module's docstring on why never stdout."""
+    print(f"roadmap-mcp: {message}", file=sys.stderr, flush=True)
+
+
+# --- source resolution --------------------------------------------------------
+#
+# Deliberately not imported from `cli`: the names there (`_ENV_SOURCE`) are
+# private and read at import time, and re-reading the environment here is what
+# lets a test set it. The DEFAULTS are what must agree, and they are stated in
+# terms of the same variable the CLI's `--source` default is built from.
+
+READ_SOURCES = ("files", "local", "db")
+WRITE_SOURCES = ("local", "db")
+
+
+def _read_source(requested: str | None = None) -> str:
+    """Where a read looks, defaulting exactly as `roadmap --source` does.
+
+    `files` last in the chain and first in practice: it is the only source that
+    needs nothing provisioned, which is the property that lets an agent in a
+    fresh clone answer "what should I work on" at all.
+    """
+    source = requested or os.environ.get("ROADMAP_SOURCE") or "files"
+    if source not in READ_SOURCES:
+        raise ValueError(f"unknown source {source!r} — one of {', '.join(READ_SOURCES)}")
+    return source
+
+
+def _write_source(requested: str | None = None) -> str:
+    """Where a write goes.
+
+    `files` is not offered, and its absence is the point rather than an
+    oversight: the item files are a PROJECTION of a write the store arbitrated,
+    so "write to files" would be a claim nothing adjudicated — two sessions
+    could each hold the same item and the transaction that is supposed to decide
+    the race would never run. An environment that says `files` therefore falls
+    through to `db`, which is the CLI's own default for the write commands.
+    """
+    source = requested or os.environ.get("ROADMAP_SOURCE") or "db"
+    if source == "files":
+        source = "db"
+    if source not in WRITE_SOURCES:
+        raise ValueError(f"unknown write source {source!r} — one of {', '.join(WRITE_SOURCES)}")
+    return source
+
+
+# --- schemas ------------------------------------------------------------------
+
+
+def _schema(properties: dict[str, Any], required: list[str] | None = None) -> dict[str, Any]:
+    return {
+        "type": "object",
+        "properties": properties,
+        "required": required or [],
+        "additionalProperties": False,
+    }
+
+
+_SOURCE_PROP = {
+    "type": "string",
+    "enum": list(READ_SOURCES),
+    "description": (
+        "where to read the graph from. Default: ROADMAP_SOURCE, else 'files' — "
+        "the committed YAML, which needs no server and no token."
+    ),
+}
+_WRITE_SOURCE_PROP = {
+    "type": "string",
+    "enum": list(WRITE_SOURCES),
+    "description": (
+        "which store arbitrates the write. Default: ROADMAP_SOURCE, else 'db'. "
+        "There is no 'files' — a write nothing arbitrated is not a claim."
+    ),
+}
+
+TOOLS: list[dict[str, Any]] = [
+    {
+        "name": "ready",
+        "description": (
+            "Items startable right now — nothing blocked, deferred, claimed or done — "
+            "in priority-then-key order, the same order ROADMAP.md and the API use. "
+            "Each carries its related items and any artifact contention with a live "
+            "claim. Call this before starting work."
+        ),
+        "inputSchema": _schema({"source": _SOURCE_PROP}),
+    },
+    {
+        "name": "list",
+        "description": (
+            "Every item grouped by its DERIVED status (ready, deferred, blocked, "
+            "claimed, verifying, done) — derived, so an item with a live claim reads "
+            "'claimed' whatever its stored status column says. Optionally filtered to "
+            "one status."
+        ),
+        "inputSchema": _schema({
+            "source": _SOURCE_PROP,
+            "status": {
+                "type": "string",
+                "enum": list(graph.STATUSES),
+                "description": "only this status. Omit for all of them.",
+            },
+        }),
+    },
+    {
+        "name": "show",
+        "description": (
+            "One item in full: derived status, arc, priority, who holds it and for how "
+            "long, what it is blocked on and what it blocks, related items, artifacts "
+            "and contention, refs, and the evidence prose."
+        ),
+        "inputSchema": _schema(
+            {"key": {"type": "string", "description": "the item key"}, "source": _SOURCE_PROP},
+            ["key"],
+        ),
+    },
+    {
+        "name": "validate",
+        "description": (
+            "Schema problems, dangling dependencies, cycles, and arc coherence. "
+            "'problems' are errors; 'findings' are observations about a thin backlog "
+            "and never make a graph invalid."
+        ),
+        "inputSchema": _schema({"source": _SOURCE_PROP}),
+    },
+    {
+        "name": "claim",
+        "description": (
+            "Stake an item so no other session starts it. The store arbitrates, so "
+            "losing the race is an ordinary refusal and not an error to retry around. "
+            "On success the claim is projected into roadmap/items/<key>.yaml — commit "
+            "that, or the claim is invisible to anyone in a checkout."
+        ),
+        "inputSchema": _schema({
+            "key": {"type": "string", "description": "the item key"},
+            "by": {
+                "type": "string",
+                "description": "who is claiming. Default: the current git branch.",
+            },
+            "force": {
+                "type": "boolean",
+                "description": "take an item someone else holds. Default false.",
+            },
+            "source": _WRITE_SOURCE_PROP,
+        }, ["key"]),
+    },
+    {
+        "name": "release",
+        "description": (
+            "Drop a claim, and project the drop into the item file. Call this when you "
+            "finish or when you stop — an unreleased claim keeps the item off "
+            "everyone's queue until it goes stale."
+        ),
+        "inputSchema": _schema(
+            {"key": {"type": "string", "description": "the item key"},
+             "source": _WRITE_SOURCE_PROP},
+            ["key"],
+        ),
+    },
+    {
+        "name": "set_status",
+        "description": (
+            "Move one item's status deliberately — the only writer for that field. "
+            "'verifying' keeps the claim, because the branch that shipped the work "
+            "still owns observing that it landed; 'done' drops the claim. The new "
+            "status is projected into the item file for you to commit."
+        ),
+        "inputSchema": _schema({
+            "key": {"type": "string", "description": "the item key"},
+            "status": {"type": "string", "enum": list(graph.STATUSES)},
+            "source": _WRITE_SOURCE_PROP,
+        }, ["key", "status"]),
+    },
+]
+
+
+# --- reads --------------------------------------------------------------------
+
+
+def _summary(item: dict[str, Any], by_key: dict[str, dict[str, Any]]) -> dict[str, Any]:
+    """One item as a queue line: what decides whether to start it, and nothing else."""
+    view: dict[str, Any] = {
+        "key": item["key"],
+        "title": item["title"],
+        "status": graph.derive_status(item, by_key),
+        "priority": graph.priority_of(item),
+        "arc": item.get("arc"),
+    }
+    if item.get("claimed_by"):
+        view["claimed_by"] = item["claimed_by"]
+        # Formatted, not raw: PyYAML resolves a timestamp to a datetime while the
+        # API returns a string, so the two sources emit different JSON types for
+        # one field unless this is normalised — the same drift `cmd_list` fixes.
+        view["claimed_at"] = graph.fmt_timestamp(item.get("claimed_at"))
+        age = graph.claim_age_days(item)
+        if age is not None:
+            view["claim_age_days"] = round(age, 1)
+            view["claim_stale"] = age >= graph.STALE_CLAIM_DAYS
+    if unmet := graph.unmet_deps(item, by_key):
+        view["unmet_deps"] = unmet
+    if related := graph.relations_for(item["key"], by_key):
+        view["related"] = related
+    # A merge cost, not a blocker — said against the item so it is read by
+    # whoever is looking at that line, exactly as `cmd_ready` prints it.
+    if contention := graph.artifact_contention(item["key"], by_key):
+        view["artifact_contention"] = contention
+    return view
+
+
+def tool_ready(source: str | None = None) -> dict[str, Any]:
+    by_key = load(_read_source(source))
+    items = [_summary(item, by_key) for item in graph.ready_items(by_key)]
+    result: dict[str, Any] = {"source": _read_source(source), "ready": items}
+    if not items:
+        result["note"] = "nothing ready — everything is claimed, blocked, deferred, or done"
+    # The stale-claim nudge the CLI prints. A session asking what to start is the
+    # one most able to notice a hold that should have been dropped.
+    stale = graph.stale_claims(by_key)
+    if stale:
+        # `claim_age_days` comes from `stale_claims` rather than being
+        # recomputed here — it copies the item with the age already on it
+        # precisely so every surface reports one number from one clock.
+        result["stale_claims"] = [
+            {"key": i["key"], "claimed_by": i.get("claimed_by"),
+             "age_days": i["claim_age_days"]}
+            for i in stale
+        ]
+    return result
+
+
+def tool_list(source: str | None = None, status: str | None = None) -> dict[str, Any]:
+    by_key = load(_read_source(source))
+    wanted = (status,) if status else graph.STATUSES
+    grouped: dict[str, list[dict[str, Any]]] = {}
+    for name in wanted:
+        group = sorted(
+            (i for i in by_key.values() if graph.derive_status(i, by_key) == name),
+            key=graph.queue_sort_key,
+        )
+        if group:
+            grouped[name] = [_summary(item, by_key) for item in group]
+    return {"source": _read_source(source), "total": len(by_key), "by_status": grouped}
+
+
+def tool_show(key: str, source: str | None = None) -> dict[str, Any]:
+    by_key = load(_read_source(source))
+    item = by_key.get(key)
+    if item is None:
+        raise LookupError(f"no such item: {key}")
+    view = _summary(item, by_key)
+    view["source"] = _read_source(source)
+    view["blocked_on"] = [
+        {"key": dep,
+         "title": by_key[dep]["title"] if dep in by_key else None,
+         "done": by_key.get(dep, {}).get("status") == "done",
+         "known": dep in by_key}
+        for dep in item.get("blocked_on") or []
+    ]
+    view["blocks"] = sorted(
+        other_key for other_key, other in by_key.items()
+        if key in (other.get("blocked_on") or [])
+    )
+    view["artifacts"] = graph.normalize_artifacts(item)
+    view["refs"] = list(item.get("refs") or [])
+    if (item.get("defer_reason") or "").strip():
+        view["defer_reason"] = " ".join(item["defer_reason"].split())
+    if item.get("evidence"):
+        view["evidence"] = item["evidence"].rstrip()
+    return view
+
+
+def tool_validate(source: str | None = None) -> dict[str, Any]:
+    resolved = _read_source(source)
+    by_key = load(resolved)
+    arcs = load_arcs(resolved)
+    problems = graph.validate_graph(by_key) + graph.validate_arcs(arcs, by_key)
+    return {
+        "source": resolved,
+        "ok": not problems,
+        "items": len(by_key),
+        "arcs": len(arcs),
+        "problems": problems,
+        # Never a failure. An arc with no startable work describes a thin
+        # backlog, not a malformed graph — see `graph.arc_findings`.
+        "findings": graph.arc_findings(arcs, by_key),
+    }
+
+
+# --- writes -------------------------------------------------------------------
+
+
+def _capture(command: Callable[[Namespace], int], args: Namespace) -> dict[str, Any]:
+    """Run one CLI command with its output diverted off the protocol stream.
+
+    The redirect is the entire reason this wrapper exists. `cmd_claim` and
+    friends `print` — to stdout for what happened, to stderr for what to do next
+    — and stdout here is the JSON-RPC transport. Swapping both means those lines
+    reach the agent as the tool's result, which is where they were always meant
+    to go, instead of desynchronising the client's parser.
+
+    `SystemExit` is caught rather than allowed to propagate because the served
+    path raises it: `cli._api` turns an HTTP error into `SystemExit` after
+    printing the server's own message. Letting that escape would take the whole
+    MCP server down over one failed request against a backend that is merely
+    unreachable.
+    """
+    out, err = io.StringIO(), io.StringIO()
+    try:
+        with redirect_stdout(out), redirect_stderr(err):
+            code = command(args)
+    except SystemExit as exc:
+        code = exc.code if isinstance(exc.code, int) else 1
+        if exc.code and not isinstance(exc.code, int):
+            err.write(f"{exc.code}\n")
+    result: dict[str, Any] = {
+        "ok": code == 0,
+        "exit_code": code,
+        "output": out.getvalue().strip(),
+    }
+    # Kept under its own key rather than merged: the CLI uses stderr for the
+    # advice that follows a SUCCESSFUL command ("when you finish: release"), so
+    # folding it into `output` would read as failure and dropping it would lose
+    # the one instruction a claiming session most needs.
+    if notes := err.getvalue().strip():
+        result["notes"] = notes
+    return result
+
+
+def tool_claim(key: str, by: str | None = None, force: bool = False,
+               source: str | None = None) -> dict[str, Any]:
+    from .cli import cmd_claim
+
+    return _capture(cmd_claim, Namespace(
+        key=key, by=by, force=bool(force), source=_write_source(source),
+    ))
+
+
+def tool_release(key: str, source: str | None = None) -> dict[str, Any]:
+    from .cli import cmd_release
+
+    return _capture(cmd_release, Namespace(key=key, source=_write_source(source)))
+
+
+def tool_set_status(key: str, status: str, source: str | None = None) -> dict[str, Any]:
+    from .cli import cmd_status
+
+    if status not in graph.STATUSES:
+        raise ValueError(f"unknown status {status!r} — one of {', '.join(graph.STATUSES)}")
+    return _capture(cmd_status, Namespace(
+        key=key, status=status, source=_write_source(source),
+    ))
+
+
+HANDLERS: dict[str, Callable[..., Any]] = {
+    "ready": tool_ready,
+    "list": tool_list,
+    "show": tool_show,
+    "validate": tool_validate,
+    "claim": tool_claim,
+    "release": tool_release,
+    "set_status": tool_set_status,
+}
+
+
+class UnknownTool(ValueError):
+    """A name this bridge does not serve.
+
+    Its own type, and a `ValueError` subclass so anything catching that still
+    catches this. The distinction is for the agent on the other end: a bad
+    *value* ("finished" is not a status) and a bad *name* ("nonesuch" is not a
+    tool) send it looking in completely different places, and one message
+    cannot serve both. Reported before the ValueError branch below for the
+    same reason switchboard orders its SpecError ahead of one.
+    """
+
+
+def dispatch(name: str, arguments: dict[str, Any]) -> Any:
+    handler = HANDLERS.get(name)
+    if handler is None:
+        raise UnknownTool(f"unknown tool: {name} — have {', '.join(sorted(HANDLERS))}")
+    return handler(**arguments)
+
+
+# --- JSON-RPC -----------------------------------------------------------------
+
+
+def _response(request_id: Any, result: Any) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": request_id, "result": result}
+
+
+def _error(request_id: Any, code: int, message: str) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": request_id, "error": {"code": code, "message": message}}
+
+
+def _tool_result(payload: Any, is_error: bool = False) -> dict[str, Any]:
+    text = payload if isinstance(payload, str) else json.dumps(payload, indent=2, default=str)
+    return {"content": [{"type": "text", "text": text}], "isError": is_error}
+
+
+def handle_request(request: dict[str, Any]) -> dict[str, Any] | None:
+    """Handle one JSON-RPC message. Returns None for notifications."""
+    method = request.get("method")
+    request_id = request.get("id")
+    params = request.get("params") or {}
+    is_notification = "id" not in request
+
+    if method == "initialize":
+        requested = params.get("protocolVersion")
+        version = requested if requested in SUPPORTED_PROTOCOLS else LATEST_PROTOCOL
+        return _response(request_id, {
+            "protocolVersion": version,
+            "capabilities": {"tools": {"listChanged": False}},
+            "serverInfo": {"name": "roadmap", "version": installed_version()},
+            "instructions": INSTRUCTIONS,
+        })
+
+    if method in ("notifications/initialized", "initialized"):
+        return None
+
+    if method == "ping":
+        return _response(request_id, {})
+
+    if method == "tools/list":
+        return _response(request_id, {"tools": TOOLS})
+
+    if method == "tools/call":
+        name = params.get("name", "")
+        arguments = params.get("arguments") or {}
+        try:
+            result = dispatch(name, arguments)
+        except LookupError as exc:
+            return _response(request_id, _tool_result(
+                {"error": "no_such_item", "detail": str(exc)}, is_error=True))
+        except ImportError as exc:
+            # The `files` source needs PyYAML and the bare package does not ship
+            # it. Named rather than folded into `bad_request`, because the fix is
+            # an install and nothing about the request was wrong. Note that
+            # `cli.load` converts its own missing-PyYAML ImportError into a
+            # SystemExit, so that particular case lands in the branch below;
+            # this one remains for an ImportError raised anywhere else.
+            return _response(request_id, _tool_result(
+                {"error": "missing_dependency", "detail": str(exc),
+                 "fix": "pip install 'roadmap-core[files]'"}, is_error=True))
+        except UnknownTool as exc:
+            return _response(request_id, _tool_result(
+                {"error": "unknown_tool", "detail": str(exc)}, is_error=True))
+        except TypeError as exc:
+            return _response(request_id, _tool_result(
+                {"error": "bad_arguments", "detail": str(exc)}, is_error=True))
+        except ValueError as exc:
+            return _response(request_id, _tool_result(
+                {"error": "bad_request", "detail": str(exc)}, is_error=True))
+        except OSError as exc:
+            # A missing SQLite file, an unwritable directory, a backend that will
+            # not answer. Environmental, and worth distinguishing from a graph
+            # that is genuinely malformed.
+            return _response(request_id, _tool_result(
+                {"error": "store_unavailable", "detail": str(exc)}, is_error=True))
+        except SystemExit as exc:
+            # THE READS ARE NOT WRAPPED IN `_capture`, AND THIS IS THE SEAM.
+            # `cli.load` reports every graph problem by raising SystemExit —
+            # unreadable YAML, an id that disagrees with its filename, a
+            # non-kebab-case key, PyYAML missing for `source=files`. SystemExit
+            # descends from BaseException, so it passes straight through every
+            # `except Exception` between here and the top and ends the process.
+            # On a stdio server that is not an exit: it is the client's pipe
+            # closing mid-session, with the diagnosis going to a stderr nobody
+            # is reading. It bites hardest on `validate`, whose whole job is to
+            # report exactly these problems — an agent asking what is wrong with
+            # the graph would get a dead server instead of the answer.
+            #
+            # The writes never reach here because `_capture` already catches
+            # SystemExit for the same reason. This is the reads' half of it.
+            detail = str(exc.code) if exc.code not in (None, 0) else "the graph could not be read"
+            payload = {"error": "graph_unreadable", "detail": detail}
+            # Semantic rather than sniffed out of the message: if PyYAML is not
+            # importable at all, a `files` read cannot have failed for any other
+            # reason, and the fix is an install rather than an edit.
+            if importlib.util.find_spec("yaml") is None:
+                payload["fix"] = "pip install 'roadmap-core[files]'"
+            return _response(request_id, _tool_result(payload, is_error=True))
+        except Exception as exc:  # noqa: BLE001 - a tool bug must not kill the server
+            log("tool error:\n" + traceback.format_exc())
+            return _response(request_id, _tool_result(
+                {"error": "tool_failed", "detail": f"{type(exc).__name__}: {exc}"},
+                is_error=True))
+        return _response(request_id, _tool_result(result))
+
+    if is_notification:
+        return None
+    return _error(request_id, JSONRPC_METHOD_NOT_FOUND, f"unknown method: {method}")
+
+
+def serve_stdio(stdin: Any = None, stdout: Any = None) -> None:
+    """Read newline-delimited JSON-RPC from stdin, write responses to stdout."""
+    stdin = stdin or sys.stdin
+    stdout = stdout or sys.stdout
+    for line in stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            request = json.loads(line)
+        except ValueError:
+            payload = _error(None, JSONRPC_PARSE_ERROR, "invalid JSON")
+            stdout.write(json.dumps(payload) + "\n")
+            stdout.flush()
+            continue
+        if not isinstance(request, dict):
+            payload = _error(None, JSONRPC_INVALID_REQUEST, "expected a JSON object")
+            stdout.write(json.dumps(payload) + "\n")
+            stdout.flush()
+            continue
+        try:
+            response = handle_request(request)
+        except (Exception, SystemExit):  # noqa: BLE001 - one bad request must not end the session
+            # SystemExit named explicitly alongside Exception: it is not an
+            # `Exception` subclass, and a `sys.exit` reached from anywhere under
+            # here is a request that failed, never a server that should stop
+            # answering the ones after it.
+            log("unhandled error:\n" + traceback.format_exc())
+            response = _error(
+                request.get("id"), JSONRPC_INTERNAL_ERROR, "internal error (see stderr)")
+        if response is not None:
+            stdout.write(json.dumps(response, default=str) + "\n")
+            stdout.flush()
+
+
+USAGE = """usage: roadmap-mcp
+
+Serve the roadmap as MCP tools over stdio. Reads newline-delimited JSON-RPC on
+stdin and writes one frame per line to stdout, so it is normally started by an
+MCP client rather than run by hand.
+
+  -h, --help     this message
+  -V, --version  the installed roadmap-core version
+
+environment:
+  ROADMAP_SOURCE     files (the default for reads) | local | db. Writes never
+                     go to files; an environment saying so writes to db.
+  ROADMAP_STORE      path to the SQLite store used by source=local
+  ROADMAP_REPO_ROOT  the checkout to resolve roadmap/items against
+
+Seven tools: ready, list, show, validate, claim, release, set_status."""
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = sys.argv[1:] if argv is None else list(argv)
+    if args:
+        # A stdio server is launched by a client and takes no arguments, so
+        # anything here is a misconfiguration. It used to be answered by
+        # ignoring argv and blocking on stdin, which is the worst available
+        # response to a typo in an `.mcp.json`: the client sees a server that
+        # never completes a handshake, and nothing anywhere says why. `--help`
+        # from a terminal hung the same way.
+        if args[0] in ("-h", "--help"):
+            # stdout, because this path never serves — no frames follow it.
+            print(USAGE)
+            return 0
+        if args[0] in ("-V", "--version"):
+            print(installed_version())
+            return 0
+        print(f"roadmap-mcp: unrecognised argument: {args[0]}\n", file=sys.stderr)
+        print(USAGE, file=sys.stderr)
+        return 2
+    serve_stdio()
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover - process entry point
+    raise SystemExit(main())

{roadmap_core-0.2.3 → roadmap_core-0.3.0/roadmap_core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roadmap-core
-Version: 0.2.3
+Version: 0.3.0
 Summary: The roadmap work-item and arc graph: status derivation, validation, and markdown rendering. Stdlib-only, so any repo can adopt it without adopting a backend.
 License: MIT
 Project-URL: Source, https://github.com/gald33/roadmap-core
@@ -156,6 +156,41 @@ this rather than by reading the code:
 `ROADMAP_SOURCE=local` selects the SQLite store. Without it the CLI expects the
 API store, which is how Lucille runs it — see `roadmap_core.stores`.
 
+### Agents (MCP)
+
+`roadmap-mcp` serves the same graph to a coding agent as MCP tools over stdio —
+`ready`, `list`, `show`, `validate`, `claim`, `release`, `set_status`. Point a
+client at it:
+
+```json
+{
+  "mcpServers": {
+    "roadmap": {
+      "command": "roadmap-mcp",
+      "env": { "ROADMAP_SOURCE": "local" }
+    }
+  }
+}
+```
+
+**There is no extra to install and no SDK underneath.** `mcp_server.py` speaks
+the JSON-RPC protocol in stdlib, so it is present wherever the package is —
+which is the same reason the rest of this package is dependency-free, applied to
+one more caller. An extra would be one an adopter can forget, for a server that
+needs nothing.
+
+**Reads default to the files**, so an agent in a fresh clone can ask what to
+work on with no store, no server and no token. Writes need a store to arbitrate
+them: set `ROADMAP_SOURCE=local` as above, or the write tools expect the API
+store. There is deliberately no `files` write target — a claim nothing
+adjudicated is not a claim, and two agents could each hold the same item.
+
+**A write tells the agent to commit something, and it means it.** `claim`,
+`release` and `set_status` project into `roadmap/items/<key>.yaml`, and on the
+floor that projection *is* the durable record — an unmerged one is a claim no
+other checkout can see. The tool result carries the CLI's own words for this
+under `notes`.
+
 ### CI
 
 Copy `templates/roadmap.yml` to `.github/workflows/roadmap.yml`. That is the

{roadmap_core-0.2.3 → roadmap_core-0.3.0}/roadmap_core.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ roadmap_core/__init__.py
 roadmap_core/cli.py
 roadmap_core/graph.py
 roadmap_core/impact.py
+roadmap_core/mcp_server.py
 roadmap_core/store.py
 roadmap_core/stores.py
 roadmap_core.egg-info/PKG-INFO
@@ -18,5 +19,6 @@ tests/test_adoption.py
 tests/test_arcs.py
 tests/test_graph.py
 tests/test_impact.py
+tests/test_mcp_server.py
 tests/test_store.py
 tests/test_stores.py

{roadmap_core-0.2.3 → roadmap_core-0.3.0}/roadmap_core.egg-info/entry_points.txt

@@ -1,2 +1,3 @@
 [console_scripts]
 roadmap = roadmap_core.cli:main
+roadmap-mcp = roadmap_core.mcp_server:main

roadmap_core-0.3.0/tests/test_mcp_server.py

@@ -0,0 +1,402 @@
+"""The MCP bridge: the protocol it speaks, and the stream it must not corrupt.
+
+Everything here runs against a ``LocalStore`` in ``tmp_path`` and never touches
+``roadmap/items/``. That is the same rule the rest of this suite follows — a
+package claiming to be adoptable cannot prove it with tests that need this
+repository's own backlog — and it has a second payoff here: the write tools
+reach the item files through ``cmd_claim``, so a test that let them find real
+ones would edit the checkout it is running in.
+
+The isolation job installs ``[dev]`` and fails if ``yaml`` is importable at all,
+so nothing below may use ``source="files"``. Every read is ``local``.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+
+import pytest
+
+from roadmap_core import cli, mcp_server
+from roadmap_core.stores import LocalStore
+
+
+@pytest.fixture(autouse=True)
+def store(tmp_path, monkeypatch):
+    """A store with three items in it, and the CLI pointed at that store.
+
+    ``ROADMAP_STORE_PATH`` is patched rather than the environment variable it is
+    built from, because ``cli`` reads that variable once at import — setting the
+    env here would leave every command still opening the real path, and the
+    tests would pass while proving nothing about the store they set up.
+    """
+    path = tmp_path / "roadmap.db"
+    with LocalStore(path) as local:
+        local.upsert_item({"key": "alpha", "title": "Alpha", "status": "ready"})
+        local.upsert_item({"key": "beta", "title": "Beta", "status": "ready",
+                           "blocked_on": ["alpha"]})
+        local.upsert_item({"key": "gamma", "title": "Gamma", "status": "done"})
+    monkeypatch.setattr(cli, "ROADMAP_STORE_PATH", str(path))
+    monkeypatch.setenv("ROADMAP_SOURCE", "local")
+    # The advisory lease is a no-op without a token, and an inherited one would
+    # make these tests reach a hub over the network.
+    monkeypatch.delenv("SWITCHBOARD_TOKEN", raising=False)
+    return path
+
+
+def _rpc(*requests: dict) -> list[dict]:
+    """Drive `serve_stdio` end to end and return the frames it wrote.
+
+    Through the real loop rather than calling `handle_request` directly: the
+    thing most worth pinning is what lands on stdout, and only the loop writes
+    there.
+    """
+    stdin = io.StringIO("".join(json.dumps(r) + "\n" for r in requests))
+    stdout = io.StringIO()
+    mcp_server.serve_stdio(stdin=stdin, stdout=stdout)
+    return [json.loads(line) for line in stdout.getvalue().splitlines() if line.strip()]
+
+
+def _call(name: str, **arguments):
+    """One tools/call, with its result decoded back out of the text content."""
+    frames = _rpc({"jsonrpc": "2.0", "id": 1, "method": "tools/call",
+                   "params": {"name": name, "arguments": arguments}})
+    assert len(frames) == 1
+    result = frames[0]["result"]
+    payload = json.loads(result["content"][0]["text"])
+    return payload, result.get("isError", False)
+
+
+# --- the protocol -------------------------------------------------------------
+
+
+def test_initialize_answers_with_tools_and_a_version():
+    frames = _rpc({"jsonrpc": "2.0", "id": 1, "method": "initialize",
+                   "params": {"protocolVersion": "2024-11-05"}})
+    result = frames[0]["result"]
+    # Echoed, not overridden: a client that asked for a version we speak gets it.
+    assert result["protocolVersion"] == "2024-11-05"
+    assert result["capabilities"]["tools"] == {"listChanged": False}
+    assert result["serverInfo"]["name"] == "roadmap"
+
+
+def test_an_unknown_protocol_version_gets_the_newest_we_speak():
+    frames = _rpc({"jsonrpc": "2.0", "id": 1, "method": "initialize",
+                   "params": {"protocolVersion": "1999-01-01"}})
+    assert frames[0]["result"]["protocolVersion"] == mcp_server.LATEST_PROTOCOL
+
+
+def test_notifications_are_not_answered():
+    """A response to a notification is a protocol violation, and clients that
+    validate strictly drop the connection over it."""
+    assert _rpc({"jsonrpc": "2.0", "method": "notifications/initialized"}) == []
+
+
+def test_every_tool_advertises_a_schema_and_has_a_handler():
+    names = {tool["name"] for tool in mcp_server.TOOLS}
+    assert names == set(mcp_server.HANDLERS)
+    for tool in mcp_server.TOOLS:
+        assert tool["description"]
+        assert tool["inputSchema"]["type"] == "object"
+
+
+def test_a_malformed_line_is_reported_without_ending_the_session():
+    stdin = io.StringIO(
+        "{not json\n"
+        + json.dumps({"jsonrpc": "2.0", "id": 2, "method": "ping"}) + "\n"
+    )
+    stdout = io.StringIO()
+    mcp_server.serve_stdio(stdin=stdin, stdout=stdout)
+    frames = [json.loads(line) for line in stdout.getvalue().splitlines()]
+    assert frames[0]["error"]["code"] == mcp_server.JSONRPC_PARSE_ERROR
+    # The point of the test: the second request was still served.
+    assert frames[1]["id"] == 2
+
+
+# --- stdout is the protocol ---------------------------------------------------
+
+
+def test_a_write_does_not_leak_the_cli_prints_onto_the_stream():
+    """THE regression this module's `_capture` exists for.
+
+    `cmd_claim` prints four lines a human is meant to read. stdout here is the
+    JSON-RPC transport, so an uncaptured one is not noise — it desynchronises
+    the client's parser for the rest of the session, and the error surfaces a
+    long way from the print that caused it.
+
+    Asserted as "every line on stdout parses as JSON-RPC", which is the property
+    that actually matters, rather than by matching the strings the CLI happens
+    to print today.
+    """
+    stdin = io.StringIO(json.dumps({
+        "jsonrpc": "2.0", "id": 1, "method": "tools/call",
+        "params": {"name": "claim", "arguments": {"key": "alpha", "by": "tester"}},
+    }) + "\n")
+    stdout = io.StringIO()
+    mcp_server.serve_stdio(stdin=stdin, stdout=stdout)
+
+    lines = [line for line in stdout.getvalue().splitlines() if line.strip()]
+    assert len(lines) == 1, f"the CLI's prints reached the protocol stream: {lines}"
+    for line in lines:
+        assert json.loads(line)["jsonrpc"] == "2.0"
+
+
+def test_the_cli_output_is_returned_instead_of_discarded():
+    """Captured, not silenced. What `claim` says is what the agent needs."""
+    payload, is_error = _call("claim", key="alpha", by="tester")
+    assert not is_error
+    assert payload["ok"] is True
+    assert "claimed alpha for tester" in payload["output"]
+    # The "when you finish" notice goes to stderr, and it is the one instruction
+    # a claiming session most needs — so it is kept, under its own key.
+    assert "release" in payload["notes"]
+
+
+# --- reads --------------------------------------------------------------------
+
+
+def test_ready_offers_only_what_is_startable():
+    payload, is_error = _call("ready")
+    assert not is_error
+    keys = [item["key"] for item in payload["ready"]]
+    # beta is blocked on alpha, gamma is done.
+    assert keys == ["alpha"]
+
+
+def test_ready_reflects_a_claim_taken_through_the_bridge():
+    _call("claim", key="alpha", by="tester")
+    payload, _ = _call("ready")
+    assert payload["ready"] == []
+    assert "nothing ready" in payload["note"]
+
+
+def test_list_groups_by_derived_status_not_the_stored_column():
+    """An item with a live claim reads `claimed` whatever its status column says
+    — the divergence `a-claim-cannot-survive-the-floors-ci` documents."""
+    _call("claim", key="alpha", by="tester")
+    payload, _ = _call("list")
+    assert [i["key"] for i in payload["by_status"]["claimed"]] == ["alpha"]
+    assert payload["total"] == 3
+
+
+def test_list_can_be_filtered_to_one_status():
+    payload, _ = _call("list", status="done")
+    assert set(payload["by_status"]) == {"done"}
+
+
+def test_show_names_both_directions_of_the_dependency_edge():
+    payload, is_error = _call("show", key="alpha")
+    assert not is_error
+    assert payload["blocks"] == ["beta"]
+    assert payload["blocked_on"] == []
+
+    payload, _ = _call("show", key="beta")
+    assert payload["blocked_on"][0]["key"] == "alpha"
+    assert payload["blocked_on"][0]["done"] is False
+
+
+def test_validate_reports_a_dangling_dependency():
+    with LocalStore(cli.ROADMAP_STORE_PATH) as local:
+        local.upsert_item({"key": "delta", "title": "Delta", "blocked_on": ["nope"]})
+    payload, _ = _call("validate")
+    assert payload["ok"] is False
+    assert any("nope" in problem for problem in payload["problems"])
+
+
+# --- failures are answers, not crashes ----------------------------------------
+
+
+def test_an_unknown_item_is_a_named_error():
+    payload, is_error = _call("show", key="does-not-exist")
+    assert is_error
+    assert payload["error"] == "no_such_item"
+
+
+def test_an_unknown_tool_is_a_named_error():
+    payload, is_error = _call("nonesuch")
+    assert is_error
+    assert payload["error"] == "unknown_tool"
+
+
+def test_a_bad_argument_is_a_named_error():
+    payload, is_error = _call("show")          # `key` is required
+    assert is_error
+    assert payload["error"] == "bad_arguments"
+
+
+def test_an_unknown_status_is_refused_before_the_store_is_touched():
+    payload, is_error = _call("set_status", key="alpha", status="finished")
+    assert is_error
+    assert payload["error"] == "bad_request"
+
+
+def test_a_failing_tool_leaves_the_server_answering():
+    frames = _rpc(
+        {"jsonrpc": "2.0", "id": 1, "method": "tools/call",
+         "params": {"name": "show", "arguments": {"key": "does-not-exist"}}},
+        {"jsonrpc": "2.0", "id": 2, "method": "tools/list"},
+    )
+    assert frames[0]["result"]["isError"] is True
+    assert frames[1]["result"]["tools"]
+
+
+# --- source resolution --------------------------------------------------------
+
+
+def test_a_write_never_goes_to_the_files_source(monkeypatch):
+    """`files` is a projection of a write something else arbitrated. Offering it
+    as a write target would be a claim no transaction decided — two sessions
+    could each hold the same item."""
+    monkeypatch.setenv("ROADMAP_SOURCE", "files")
+    assert mcp_server._write_source() == "db"
+    assert "files" not in mcp_server.WRITE_SOURCES
+
+
+def test_reads_default_to_files_when_nothing_says_otherwise(monkeypatch):
+    """The default that makes a fresh clone answerable: no server, no token."""
+    monkeypatch.delenv("ROADMAP_SOURCE", raising=False)
+    assert mcp_server._read_source() == "files"
+
+
+def test_an_explicit_source_beats_the_environment(monkeypatch):
+    monkeypatch.setenv("ROADMAP_SOURCE", "db")
+    assert mcp_server._read_source("local") == "local"
+
+
+def test_an_unknown_source_is_refused():
+    with pytest.raises(ValueError):
+        mcp_server._read_source("postgres")
+
+
+# --- writes -------------------------------------------------------------------
+
+
+def test_release_hands_the_item_back_to_the_queue():
+    _call("claim", key="alpha", by="tester")
+    payload, is_error = _call("release", key="alpha")
+    assert not is_error and payload["ok"]
+    assert [i["key"] for i in _call("ready")[0]["ready"]] == ["alpha"]
+
+
+def test_losing_a_claim_race_is_a_refusal_and_not_a_crash():
+    """An ordinary outcome. The store arbitrates, so the second caller is told
+    who holds it rather than handed a traceback."""
+    _call("claim", key="alpha", by="first")
+    payload, _ = _call("claim", key="alpha", by="second")
+    assert payload["ok"] is False
+    assert "first" in (payload["notes"] or "") + payload["output"]
+
+
+def test_set_status_done_drops_the_claim():
+    _call("claim", key="alpha", by="tester")
+    payload, is_error = _call("set_status", key="alpha", status="done")
+    assert not is_error and payload["ok"]
+    shown, _ = _call("show", key="alpha")
+    assert shown["status"] == "done"
+    assert "claimed_by" not in shown
+
+
+def test_set_status_verifying_keeps_the_claim():
+    """The branch that shipped the work still owns observing that it landed."""
+    _call("claim", key="alpha", by="tester")
+    _call("set_status", key="alpha", status="verifying")
+    shown, _ = _call("show", key="alpha")
+    assert shown["claimed_by"] == "tester"
+
+
+# --- the load path reports failure without ending the session -----------------
+#
+# `cli.load` raises SystemExit for every graph problem it finds, and SystemExit
+# is not an `Exception`. The reads call `load` directly rather than through
+# `_capture`, so nothing between them and the interpreter catches it. These
+# monkeypatch `load` rather than pointing a read at a broken `roadmap/items/`,
+# because this file may not use `source="files"` at all — the isolation job runs
+# it with PyYAML absent. What is being pinned is the exception type, and that
+# does not need a real YAML file to be raised.
+
+
+@pytest.mark.parametrize("tool", ["ready", "list", "validate", "show"])
+def test_an_unreadable_graph_is_an_error_frame_not_a_dead_server(tool, monkeypatch):
+    """The bug this guards: a single malformed item file used to take the whole
+    server down, and `validate` — the tool whose entire job is to report that
+    file — went down with it."""
+    def explode(*_args, **_kwargs):
+        raise SystemExit("roadmap/items/oops.yaml: invalid YAML: mapping values not allowed")
+
+    monkeypatch.setattr(mcp_server, "load", explode)
+    arguments = {"key": "alpha"} if tool == "show" else {}
+    frames = _rpc(
+        {"jsonrpc": "2.0", "id": 1, "method": "tools/call",
+         "params": {"name": tool, "arguments": arguments}},
+        # The point of the test is this second frame: the session outlives it.
+        {"jsonrpc": "2.0", "id": 2, "method": "ping"},
+    )
+    assert len(frames) == 2, "the server stopped answering after an unreadable graph"
+    payload = json.loads(frames[0]["result"]["content"][0]["text"])
+    assert frames[0]["result"]["isError"] is True
+    assert payload["error"] == "graph_unreadable"
+    assert "oops.yaml" in payload["detail"]
+    assert frames[1]["id"] == 2
+
+
+def test_a_missing_pyyaml_names_the_install_that_fixes_it(monkeypatch):
+    """`load` turns its own ImportError into SystemExit, so the missing-PyYAML
+    case arrives as one. It still has to arrive carrying the install."""
+    def explode(*_args, **_kwargs):
+        raise SystemExit("PyYAML required for --source files (pip install pyyaml)")
+
+    monkeypatch.setattr(mcp_server, "load", explode)
+    monkeypatch.setattr(mcp_server.importlib.util, "find_spec", lambda name: None)
+    payload, is_error = _call("ready")
+    assert is_error is True
+    assert payload["error"] == "graph_unreadable"
+    assert payload["fix"] == "pip install 'roadmap-core[files]'"
+
+
+def test_a_readable_graph_carries_no_install_advice(monkeypatch):
+    """The `fix` key is conditional. A malformed file in a checkout that HAS
+    PyYAML is an edit, not an install, and saying otherwise sends the reader to
+    the wrong place."""
+    def explode(*_args, **_kwargs):
+        raise SystemExit("roadmap/items/oops.yaml: expected a mapping at the top level")
+
+    monkeypatch.setattr(mcp_server, "load", explode)
+    monkeypatch.setattr(mcp_server.importlib.util, "find_spec", lambda name: object())
+    payload, _ = _call("validate")
+    assert "fix" not in payload
+
+
+def test_a_systemexit_escaping_the_handler_still_leaves_the_loop_running(monkeypatch):
+    """Defence in depth for the loop itself, not the tools/call branch: a
+    SystemExit raised outside a tool must not end the session either."""
+    def explode(_request):
+        raise SystemExit("something above the tools")
+
+    monkeypatch.setattr(mcp_server, "handle_request", explode)
+    frames = _rpc({"jsonrpc": "2.0", "id": 1, "method": "ping"})
+    assert len(frames) == 1
+    assert frames[0]["error"]["code"] == mcp_server.JSONRPC_INTERNAL_ERROR
+
+
+# --- the entry point ----------------------------------------------------------
+
+
+def test_help_and_version_answer_instead_of_blocking_on_stdin(capsys):
+    """`main` used to ignore argv and fall through to reading stdin, so
+    `roadmap-mcp --help` hung with no output — and so did a mistyped flag in an
+    `.mcp.json`, which surfaced as a server that never finished a handshake."""
+    assert mcp_server.main(["--help"]) == 0
+    assert "usage: roadmap-mcp" in capsys.readouterr().out
+
+    assert mcp_server.main(["--version"]) == 0
+    assert capsys.readouterr().out.strip() == cli.installed_version()
+
+
+def test_an_unrecognised_argument_is_refused_on_stderr(capsys):
+    """Non-zero, and said on stderr: the client is owed a reason it can see, and
+    stdout is the protocol even on the path that never gets to speak it."""
+    assert mcp_server.main(["--sorce", "files"]) == 2
+    captured = capsys.readouterr()
+    assert captured.out == ""
+    assert "unrecognised argument: --sorce" in captured.err