system-diff 0.1.0__py3-none-any.whl

system_diff/mcp_server.py

@@ -0,0 +1,206 @@
+"""`system-diff mcp`: system-diff as an MCP server over stdio, for Claude Code and other MCP clients.
+
+An optional extra (`pip install "system-diff[mcp]"`): the official MCP SDK is its only dependency. The tools read the
+repository the client runs in, and write pictures under .git/system-diff/, which is never committed. They return the
+exact text (headline, plan) for the model to explain from, and the picture's path for the person.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Literal, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+try:  # the MCP SDK's 2.x name; 1.x called it FastMCP, with the same constructor, decorator and run()
+    from mcp.server.mcpserver import MCPServer as Server
+except ImportError:  # pragma: no cover - mcp 1.x
+    from mcp.server.fastmcp import FastMCP as Server
+
+from . import compare as cmp
+from . import config, graph, pictures
+from .extract import extract
+from .sources import GitSource, git, repo_root
+
+INSTRUCTIONS = (
+    "system-diff shows what a change does to a system's structure: its parts, entry points, connections, outside "
+    "systems and stored data. Use system_diff after changing the code, to tell the person in plain words what changed "
+    "in the system and to point them at the picture; base 'checkpoint' is what they last marked as seen. Use "
+    "system_map for the whole system, and draw for a picture of something else (a process, a sequence). Call "
+    "checkpoint only when the person says they have seen and understood the current state."
+)
+
+
+class Code(BaseModel):
+    code: str = Field(description="shown in a monospace font, e.g. a route or a table")
+
+
+Line = Union[str, Code]
+
+
+class _Spec(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+
+class Node(_Spec):
+    id: str
+    col: str = Field(description="the key of one of `columns`")
+    title: str
+    sub: str = ""
+    type: Literal["component", "store", "host"] = "component"
+    style: Literal["", "new", "legacy", "shared", "undeclared"] = ""
+    lines: List[Line] = []
+
+
+class Edge(_Spec):
+    from_: str = Field(alias="from")
+    to: str
+    kind: Literal["call", "data", "network"] = "call"
+
+
+class Stage(_Spec):
+    title: str
+    lines: List[Line] = []
+    hi: bool = Field(False, description="highlight this stage")
+
+
+class Loop(_Spec):
+    from_: int = Field(alias="from", description="index of the stage it goes back from")
+    to: int = Field(description="index of the stage it goes back to")
+    label: str = ""
+
+
+class Exit(_Spec):
+    label: str
+    note: str = ""
+
+
+class Gate(_Spec):
+    text: str = Field(description="where a person comes in, e.g. 'A person approves'")
+    from_: Optional[List[int]] = Field(None, alias="from", description="indexes of the stages that lead to it")
+
+
+class Lane(_Spec):
+    id: str
+    title: str
+    sub: str = ""
+    person: bool = False
+
+
+class Step(_Spec):
+    from_: Optional[str] = Field(None, alias="from", description="a lane id (a message step)")
+    to: Optional[str] = Field(None, description="a lane id (a message step)")
+    text: Optional[str] = Field(None, description="what is sent (a message step)")
+    kind: Optional[Literal["call", "data", "network"]] = None
+    note: Optional[str] = Field(None, description="a note across lanes instead of a message")
+    over: Optional[List[str]] = Field(None, description="the lane ids a note spans")
+
+
+class Spec(_Spec):
+    """One picture. `map` needs columns and nodes (edges optional); `stages` needs stages; `sequence` needs lanes
+    and steps."""
+    picture: Literal["map", "stages", "sequence"]
+    label: str = ""
+    columns: Optional[List[List[str]]] = Field(None, description='map: [["logic", "Logic"], ["store", "Stored data"]]')
+    nodes: Optional[List[Node]] = None
+    edges: Optional[List[Edge]] = None
+    stages: Optional[List[Stage]] = None
+    loops: Optional[List[Loop]] = None
+    exits: Optional[List[Exit]] = None
+    gate: Optional[Gate] = None
+    lanes: Optional[List[Lane]] = None
+    steps: Optional[List[Step]] = None
+
+
+def _out(root: Path, *parts: str) -> Path:
+    """A folder under .git/system-diff (the repository's own git dir, worktrees included)."""
+    gitdir = Path(git("rev-parse", "--absolute-git-dir", cwd=root).strip())
+    out = gitdir.joinpath("system-diff", *parts)
+    out.mkdir(parents=True, exist_ok=True)
+    return out
+
+
+def tool_map(root: Path, ref: str = ".") -> Dict[str, Any]:
+    sha, label = cmp.resolve(root, ref)
+    source = GitSource(sha, root)
+    cfg = config.load(source, root)
+    bp = extract(source, cfg)
+    path = _out(root, "mcp") / "system.svg"
+    pictures.write_if_changed(path, graph.system_svg(bp, cfg))
+    comps = bp["components"]
+    return {"of": label, "picture": str(path),
+            "parts": [{"id": k, "label": v["label"], "column": graph.part_kind(k, v, bp, cfg), "files": v["files"]}
+                      for k, v in sorted(comps.items(), key=lambda kv: graph.part_order(kv[1], kv[0]))],
+            "connections": [f"{comps.get(s, {}).get('label', s)} → {comps.get(t, {}).get('label', t)}"
+                            for s, t in (k.split(">") for k in bp["flows"])],
+            "entry_points": len(bp["routes"]), "tables": len(bp["tables"]),
+            "outside_systems": [v["label"] for v in bp["externals"].values()],
+            "read_but_not_deployed": [v["label"] for v in bp["dormant"].values()],
+            "undeclared_parts": sorted(k for k, v in comps.items() if not v["declared"])}
+
+
+def tool_diff(root: Path, base: str = "checkpoint", head: str = ".") -> Dict[str, Any]:
+    c = cmp.compare(root, base, head)
+    svg = graph.diff_svg(c.diff, c.before, c.after, c.cfg)
+    path = _out(root, "mcp") / "diff.svg"
+    if svg:
+        pictures.write_if_changed(path, svg)
+    elif path.is_file():
+        path.unlink()
+    return {"from": c.base, "to": c.head, "headline": c.diff["headline"], "plan": c.diff["plan"],
+            "changes": len(c.diff["changes"]), "impacts": c.diff["impacts"],
+            "picture": str(path) if svg else None,
+            "live_page": "run `system-diff watch` for a page that redraws as the code changes"}
+
+
+def tool_draw(root: Path, spec: Spec, name: str = "picture") -> Dict[str, Any]:
+    data = spec.model_dump(by_alias=True, exclude_none=True)
+    problems = pictures.check(data)
+    if problems:
+        return {"error": "the spec could not be drawn: " + "; ".join(problems), "do": "fix these and draw again"}
+    try:
+        svg = pictures.draw(data)
+    except (KeyError, IndexError, TypeError, ValueError) as exc:
+        return {"error": f"the spec could not be drawn: {type(exc).__name__}: {exc}",
+                "do": "check that every edge, loop, gate and step names an id or index the spec has"}
+    safe = "".join(ch if ch.isalnum() or ch in "-_" else "-" for ch in name)[:60] or "picture"
+    path = _out(root, "pictures") / f"{safe}.svg"
+    pictures.write_if_changed(path, svg)
+    return {"picture": str(path)}
+
+
+def build() -> Server:
+    server = Server("system-diff", instructions=INSTRUCTIONS)
+
+    @server.tool()
+    def system_map(ref: str = ".") -> Dict[str, Any]:
+        """The system's structure: its parts by column, the connections between them, how many entry points and
+        tables, and its outside systems. `ref`: a commit, or "." for the working tree. Returns the picture's path."""
+        return tool_map(repo_root(), ref)
+
+    @server.tool()
+    def system_diff(base: str = "checkpoint", head: str = ".") -> Dict[str, Any]:
+        """What changed in the system from `base` to `head`: one sentence, the exact list (each line with its impact,
+        e.g. new-interface, breaking-interface, data-schema-change, test-gap) and a picture of only what changed.
+        `base` "checkpoint" is what the person last marked as seen (HEAD if nothing yet); `head` "." is the working
+        tree, uncommitted files included. Explain it from the plan, never beyond it."""
+        return tool_diff(repo_root(), base, head)
+
+    @server.tool()
+    def draw(spec: Spec, name: str = "picture") -> Dict[str, Any]:
+        """Draw a picture in system-diff's look: a `map` (boxes in columns), `stages` (a process left to right, with
+        loops back, exits and where a person comes in) or a `sequence` (who talks to whom, in order). Returns the
+        SVG's path, or what is wrong with the spec."""
+        return tool_draw(repo_root(), spec, name)
+
+    @server.tool()
+    def checkpoint(ref: str = "") -> Dict[str, Any]:
+        """Mark the working tree (or `ref`) as seen by the person, so the next system_diff from "checkpoint" shows
+        only what is new to them. Only when the person says they have seen and understood the current state."""
+        sha = cmp.checkpoint(repo_root(), ref or None)
+        return {"checkpoint": sha[:9], "of": ref or "the working tree"}
+
+    return server
+
+
+def main() -> None:
+    build().run("stdio")

system_diff/narrate.py

@@ -0,0 +1,141 @@
+"""The optional plain-words summary on top of the exact diff, written by an LLM; the pictures never depend on it.
+
+Which LLM: the one your Claude Code uses (its settings files' `env` blocks, layered as Claude Code layers them, with
+ANTHROPIC_* in the environment over all of them); else an OpenAI-compatible gateway exported in your own shell
+(SYSTEM_DIFF_LLM_BASE_URL / _API_KEY / _MODEL, or LLM_*). Only the headline, the exact plan and the commit messages are
+sent: never the code. Nothing answers, no summary.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import socket
+import ssl
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.parse import urlparse
+
+DEFAULT_MODEL = "claude-sonnet-5-5"
+
+SYSTEM = (
+    "You explain to the reviewers of a pull request what it does to a system's architecture. You are given an "
+    "exact, machine-extracted structural diff and the commit messages. Write two parts, plain words, no headings: "
+    "1) two to four sentences on what changes in the system and why; 2) up to four bullet points a reviewer should "
+    "check, each grounded in a line of the diff. Never mention a component, endpoint, table or system that is not "
+    "in the diff. If the diff shows no structural change, say so in one sentence."
+)
+
+
+def claude_settings_files(root: Path, extra: List[str] = ()) -> List[Tuple[Path, str]]:
+    """Claude Code settings that can carry the gateway, lowest precedence first: user, user-local, project,
+    project-local, then any the config adds."""
+    home, repo = Path.home() / ".claude", root / ".claude"
+    files = [(home / "settings.json", "~/.claude/settings.json"),
+             (home / "settings.local.json", "~/.claude/settings.local.json"),
+             (repo / "settings.json", ".claude/settings.json"),
+             (repo / "settings.local.json", ".claude/settings.local.json")]
+    return files + [(Path(os.path.expanduser(p)), p) for p in extra]
+
+
+def claude_llm(root: Path, extra: List[str] = ()) -> Optional[Dict[str, Any]]:
+    """The gateway your Claude Code uses; whatever model it names is the model used."""
+    env: Dict[str, str] = {}
+    source = ""
+    for path, label in claude_settings_files(root, extra):
+        try:
+            block = json.loads(path.read_text(encoding="utf-8")).get("env", {}) or {}
+        except (OSError, ValueError):
+            continue
+        env.update(block)
+        if block.get("ANTHROPIC_BASE_URL") or block.get("ANTHROPIC_API_KEY"):
+            source = label
+    for k, v in os.environ.items():
+        if k.startswith("ANTHROPIC_") and v:
+            env[k] = v
+            if k in ("ANTHROPIC_BASE_URL", "ANTHROPIC_API_KEY"):
+                source = "ANTHROPIC_* in the environment"
+    token = env.get("ANTHROPIC_AUTH_TOKEN") or env.get("ANTHROPIC_API_KEY", "")
+    if not token:
+        return None
+    base = (env.get("ANTHROPIC_BASE_URL") or "https://api.anthropic.com").rstrip("/")
+    return {"base_url": base, "token": token, "model": env.get("ANTHROPIC_MODEL", DEFAULT_MODEL), "source": source}
+
+
+def shell_llm() -> Optional[Dict[str, Any]]:
+    """An OpenAI-compatible LLM someone exported in their own shell on purpose — never a committed file."""
+    env = os.environ
+    base = env.get("SYSTEM_DIFF_LLM_BASE_URL") or env.get("LLM_BASE_URL", "")
+    key = env.get("SYSTEM_DIFF_LLM_API_KEY") or env.get("LLM_API_KEY", "")
+    model = env.get("SYSTEM_DIFF_LLM_MODEL") or env.get("LLM_MODEL", "")
+    if base and key and model:
+        return {"kind": "openai", "base_url": base.rstrip("/"), "token": key, "model": model,
+                "verify": env.get("LLM_SSL_VERIFY", "true").lower() == "true"}
+    return None
+
+
+def ask(s: Dict[str, Any], user: str, max_tokens: int, timeout: int) -> str:
+    """One tool-less completion, OpenAI-compatible or Anthropic Messages."""
+    if s.get("kind") == "openai":
+        url = s["base_url"] + "/chat/completions"
+        body: Dict[str, Any] = {"model": s["model"], "max_tokens": max_tokens,
+                                "messages": [{"role": "system", "content": SYSTEM}, {"role": "user", "content": user}]}
+        headers = {"content-type": "application/json", "authorization": "Bearer " + s["token"]}
+    else:
+        url = s["base_url"] + "/v1/messages"
+        body = {"model": s["model"], "max_tokens": max_tokens, "system": SYSTEM,
+                "messages": [{"role": "user", "content": user}]}
+        if s.get("thinking"):
+            # A reasoning model given no thinking budget can think until max_tokens and return no text at all.
+            body["thinking"] = {"type": "enabled", "budget_tokens": s["thinking"]}
+        headers = {"content-type": "application/json", "anthropic-version": "2023-06-01",
+                   "authorization": "Bearer " + s["token"], "x-api-key": s["token"]}
+    # Fail in seconds, not after the read timeout, when this machine cannot reach the gateway at all.
+    u = urlparse(url)
+    socket.create_connection((u.hostname, u.port or (443 if u.scheme == "https" else 80)), timeout=5).close()
+    context = None if s.get("verify", True) else ssl._create_unverified_context()
+    req = urllib.request.Request(url, data=json.dumps(body).encode(), method="POST", headers=headers)
+    with urllib.request.urlopen(req, timeout=timeout, context=context) as r:
+        data = json.loads(r.read())
+    if s.get("kind") == "openai":
+        text = ((data.get("choices") or [{}])[0].get("message") or {}).get("content") or ""
+    else:
+        text = "".join(b.get("text", "") for b in data.get("content", []) if b.get("type") == "text")
+    return re.sub(r"<think>.*?</think>", "", text, flags=re.S).strip()
+
+
+def narrate(d: dict, commits: str, root: Path, cfg: Dict[str, Any], timeout: int = 120) -> Optional[str]:
+    """The summary, naming the model that wrote it; None when no LLM answers from here."""
+    user = f"Headline: {d['headline']}\n\nStructural diff (exact):\n{d['plan']}\n\nCommit messages:\n{commits[:4000]}"
+    claude = claude_llm(root, cfg.get("narrate", {}).get("settings", []))
+    if claude:
+        # With a thinking budget first (some gateways' reasoning models need one); without it if refused.
+        for attempt in ({**claude, "thinking": 4000}, claude):
+            try:
+                text = ask(attempt, user, 12000, timeout)
+            except urllib.error.HTTPError as exc:
+                if exc.code == 400 and attempt.get("thinking"):
+                    continue  # this model or gateway takes no thinking parameter
+                print(f"system-diff: {claude['model']} via {claude['source']}: HTTP {exc.code}", file=sys.stderr)
+                break
+            except (OSError, ValueError) as exc:  # not reachable from here, or not JSON
+                print(f"system-diff: {claude['model']} via {claude['source']}: {type(exc).__name__}: {str(exc)[:120]}",
+                      file=sys.stderr)
+                break
+            if text:
+                return f"{text[:1500]}\n\n_Summary written by {claude['model']} ({claude['source']}) from the exact diff below._"
+    shell = shell_llm()
+    if shell:
+        for tokens in (2500, 12000):
+            try:
+                text = ask(shell, user, tokens, timeout)
+            except (OSError, ValueError) as exc:
+                print(f"system-diff: {shell['model']} via {shell['base_url']}: {type(exc).__name__}: {str(exc)[:120]}",
+                      file=sys.stderr)
+                break
+            if text:
+                return f"{text[:1500]}\n\n_Summary written by {shell['model']} (an LLM set in this shell) from the exact diff below._"
+    return None