mcp-diff 0.1.0__py3-none-any.whl

mcp_diff/__init__.py

@@ -0,0 +1,3 @@
+"""mcp-diff — Schema lockfile and breaking-change detector for MCP servers."""
+
+__version__ = "0.1.0"

mcp_diff/cli.py

@@ -0,0 +1,304 @@
+"""CLI entry point for mcp-diff."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .diff import (
+    classify_changes,
+    deserialize_lockfile,
+    format_changes_json,
+    format_changes_text,
+    has_breaking,
+    serialize_lockfile,
+)
+
+DEFAULT_LOCKFILE = "mcp-schema.lock"
+
+
+def _load_lockfile(path: str) -> dict:
+    """Load and parse a lockfile. Exits with code 2 on failure."""
+    p = Path(path)
+    if not p.exists():
+        print(
+            f"Error: lockfile not found: {path}\n"
+            "Run 'mcp-diff snapshot <command...>' first.",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    try:
+        return json.loads(p.read_text())
+    except json.JSONDecodeError as exc:
+        print(f"Error: invalid lockfile JSON: {exc}", file=sys.stderr)
+        sys.exit(2)
+
+
+def _fetch_tools(command: list[str]) -> list[dict]:
+    """Start the MCP server and fetch its tool list. Exits with code 2 on failure."""
+    from .client import MCPClient, MCPError
+
+    try:
+        with MCPClient(command) as client:
+            return client.list_tools()
+    except MCPError as exc:
+        print(f"Error: failed to connect to MCP server: {exc}", file=sys.stderr)
+        sys.exit(2)
+    except FileNotFoundError:
+        print(
+            f"Error: command not found: {command[0]!r}. Check your command.",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    except Exception as exc:  # noqa: BLE001
+        print(f"Error: unexpected failure starting server: {exc}", file=sys.stderr)
+        sys.exit(2)
+
+
+def cmd_snapshot(args: argparse.Namespace) -> int:
+    """Snapshot the current schema to a lockfile."""
+    if not args.command:
+        print("Error: no command given. Usage: mcp-diff snapshot <command...>", file=sys.stderr)
+        return 2
+
+    tools = _fetch_tools(args.command)
+    lockfile = serialize_lockfile(tools, args.command)
+
+    out_path = args.output or DEFAULT_LOCKFILE
+    Path(out_path).write_text(json.dumps(lockfile, indent=2) + "\n")
+    print(f"Snapshot saved: {len(tools)} tool{'s' if len(tools) != 1 else ''} \u2192 {out_path}")
+    return 0
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    """Check for breaking changes against the lockfile."""
+    if not args.command:
+        print("Error: no command given. Usage: mcp-diff check <command...>", file=sys.stderr)
+        return 2
+
+    lockfile_path = args.lockfile or DEFAULT_LOCKFILE
+    lock_data = _load_lockfile(lockfile_path)
+    old_tools = deserialize_lockfile(lock_data)
+
+    new_tools = _fetch_tools(args.command)
+    changes = classify_changes(old_tools, new_tools)
+
+    use_color = not args.no_color and sys.stderr.isatty()
+
+    if args.json:
+        print(format_changes_json(changes))
+    else:
+        output = format_changes_text(changes, color=use_color)
+        print(output, file=sys.stderr)
+
+        if changes:
+            breaking = [c for c in changes if c.severity == "breaking"]
+            warnings = [c for c in changes if c.severity == "warning"]
+            info = [c for c in changes if c.severity == "info"]
+            summary_parts = []
+            if breaking:
+                label = "\033[31mbreaking\033[0m" if use_color else "breaking"
+                summary_parts.append(f"{len(breaking)} {label}")
+            if warnings:
+                label = "\033[33mwarning\033[0m" if use_color else "warning"
+                summary_parts.append(f"{len(warnings)} {label}")
+            if info:
+                label = "\033[32minfo\033[0m" if use_color else "info"
+                summary_parts.append(f"{len(info)} {label}")
+            print(f"\nFound {', '.join(summary_parts)} change{'s' if len(changes) != 1 else ''}.",
+                  file=sys.stderr)
+        else:
+            ok = "\033[32mOK\033[0m" if use_color else "OK"
+            print(f"{ok} No changes detected.", file=sys.stderr)
+
+    return 1 if has_breaking(changes) else 0
+
+
+def cmd_report(args: argparse.Namespace) -> int:
+    """Generate a verbose report; always exits 0."""
+    if not args.command:
+        print("Error: no command given. Usage: mcp-diff report <command...>", file=sys.stderr)
+        return 2
+
+    lockfile_path = args.lockfile or DEFAULT_LOCKFILE
+    lock_data = _load_lockfile(lockfile_path)
+    old_tools = deserialize_lockfile(lock_data)
+
+    new_tools = _fetch_tools(args.command)
+    changes = classify_changes(old_tools, new_tools)
+
+    use_color = not args.no_color and sys.stdout.isatty()
+
+    # Header
+    print("mcp-diff report")
+    print("=" * 60)
+    print(f"Lockfile : {lockfile_path}")
+    print(f"Created  : {lock_data.get('created_at', 'unknown')}")
+    print(f"Command  : {lock_data.get('command', 'unknown')}")
+    print(f"Baseline : {len(old_tools)} tool{'s' if len(old_tools) != 1 else ''}")
+    print(f"Current  : {len(new_tools)} tool{'s' if len(new_tools) != 1 else ''}")
+    print()
+
+    if not changes:
+        ok = "\033[32m\u2713 No changes detected.\033[0m" if use_color else "OK No changes detected."
+        print(ok)
+        return 0
+
+    breaking = [c for c in changes if c.severity == "breaking"]
+    warnings = [c for c in changes if c.severity == "warning"]
+    info = [c for c in changes if c.severity == "info"]
+
+    if breaking:
+        hdr = "\033[31mBreaking changes\033[0m" if use_color else "Breaking changes"
+        print(f"{hdr} ({len(breaking)})")
+        print("-" * 40)
+        for c in breaking:
+            loc = f"{c.tool}" + (f".{c.param}" if c.param else "")
+            print(f"  [{c.kind}] {loc}")
+            for line in c.detail.splitlines():
+                print(f"    {line}")
+        print()
+
+    if warnings:
+        hdr = "\033[33mWarnings\033[0m" if use_color else "Warnings"
+        print(f"{hdr} ({len(warnings)})")
+        print("-" * 40)
+        for c in warnings:
+            loc = f"{c.tool}" + (f".{c.param}" if c.param else "")
+            print(f"  [{c.kind}] {loc}")
+            for line in c.detail.splitlines():
+                print(f"    {line}")
+        print()
+
+    if info:
+        hdr = "\033[32mInformational\033[0m" if use_color else "Informational"
+        print(f"{hdr} ({len(info)})")
+        print("-" * 40)
+        for c in info:
+            loc = f"{c.tool}" + (f".{c.param}" if c.param else "")
+            print(f"  [{c.kind}] {loc}")
+            for line in c.detail.splitlines():
+                print(f"    {line}")
+        print()
+
+    print("=" * 60)
+    parts = []
+    if breaking:
+        parts.append(f"{len(breaking)} breaking")
+    if warnings:
+        parts.append(f"{len(warnings)} warning{'s' if len(warnings) != 1 else ''}")
+    if info:
+        parts.append(f"{len(info)} info")
+    print(f"Summary: {', '.join(parts)}")
+
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mcp-diff",
+        description="Schema lockfile and breaking-change detector for MCP servers.",
+    )
+    parser.add_argument(
+        "--version", action="version", version="mcp-diff 0.1.0"
+    )
+    sub = parser.add_subparsers(dest="subcommand", metavar="<command>")
+
+    # ---- snapshot ----
+    snap = sub.add_parser(
+        "snapshot",
+        help="Snapshot an MCP server's schema to a lockfile.",
+        description="Start the MCP server, fetch its tool list, and save to a lockfile.",
+    )
+    snap.add_argument(
+        "command",
+        nargs=argparse.REMAINDER,
+        metavar="command",
+        help="Command to start the MCP server (e.g. python3 my_server.py).",
+    )
+    snap.add_argument(
+        "--output", "-o",
+        metavar="PATH",
+        help=f"Output lockfile path (default: {DEFAULT_LOCKFILE}).",
+    )
+
+    # ---- check ----
+    chk = sub.add_parser(
+        "check",
+        help="Check for breaking changes (exits 1 if found).",
+        description=(
+            "Compare the live MCP server schema against the lockfile. "
+            "Exits 1 if breaking changes are found, 0 if clean."
+        ),
+    )
+    chk.add_argument(
+        "command",
+        nargs=argparse.REMAINDER,
+        metavar="command",
+        help="Command to start the MCP server.",
+    )
+    chk.add_argument(
+        "--lockfile", "-l",
+        metavar="PATH",
+        help=f"Lockfile path (default: {DEFAULT_LOCKFILE}).",
+    )
+    chk.add_argument(
+        "--json",
+        action="store_true",
+        help="Output changes as JSON to stdout.",
+    )
+    chk.add_argument(
+        "--no-color",
+        action="store_true",
+        help="Disable ANSI color output.",
+    )
+
+    # ---- report ----
+    rep = sub.add_parser(
+        "report",
+        help="Verbose change report (always exits 0).",
+        description="Same as check but always exits 0 and prints a detailed report.",
+    )
+    rep.add_argument(
+        "command",
+        nargs=argparse.REMAINDER,
+        metavar="command",
+        help="Command to start the MCP server.",
+    )
+    rep.add_argument(
+        "--lockfile", "-l",
+        metavar="PATH",
+        help=f"Lockfile path (default: {DEFAULT_LOCKFILE}).",
+    )
+    rep.add_argument(
+        "--no-color",
+        action="store_true",
+        help="Disable ANSI color output.",
+    )
+
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if not args.subcommand:
+        parser.print_help()
+        sys.exit(0)
+
+    if args.subcommand == "snapshot":
+        sys.exit(cmd_snapshot(args))
+    elif args.subcommand == "check":
+        sys.exit(cmd_check(args))
+    elif args.subcommand == "report":
+        sys.exit(cmd_report(args))
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

mcp_diff/client.py

@@ -0,0 +1,145 @@
+"""MCP client for mcp-diff — connects to a server via stdio."""
+
+import json
+import subprocess
+import threading
+import time
+from typing import Any
+
+
+class MCPError(Exception):
+    """Raised when an MCP call fails or times out."""
+
+
+class MCPClient:
+    """Stdio client for connecting to MCP servers.
+
+    Usage::
+
+        server = MCPClient(["python", "my_server.py"])
+        tools = server.list_tools()
+        server.close()
+
+    Or as a context manager::
+
+        with MCPClient(["python", "my_server.py"]) as server:
+            tools = server.list_tools()
+    """
+
+    def __init__(self, command: list[str] | str, timeout: float = 30.0):
+        """Start the MCP server process and initialize the session.
+
+        Args:
+            command: Command to start the server (list or shell string).
+            timeout: Default timeout in seconds for each call.
+        """
+        if isinstance(command, str):
+            command = command.split()
+        self.command = command
+        self.timeout = timeout
+        self._msg_id = 0
+        self._process: subprocess.Popen | None = None
+        self._lock = threading.Lock()
+        self._start()
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def _start(self) -> None:
+        self._process = subprocess.Popen(
+            self.command,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=1,
+        )
+        # Initialize the MCP session
+        self._call_raw("initialize", {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {},
+            "clientInfo": {"name": "mcp-diff", "version": "0.1.0"},
+        })
+        # Send initialized notification (no response expected)
+        self._send({"jsonrpc": "2.0", "method": "notifications/initialized"})
+
+    def close(self) -> None:
+        """Terminate the server process."""
+        if self._process and self._process.poll() is None:
+            self._process.stdin.close()
+            try:
+                self._process.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                self._process.kill()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.close()
+
+    # ------------------------------------------------------------------
+    # Low-level JSON-RPC
+    # ------------------------------------------------------------------
+
+    def _next_id(self) -> int:
+        with self._lock:
+            self._msg_id += 1
+            return self._msg_id
+
+    def _send(self, msg: dict) -> None:
+        line = json.dumps(msg) + "\n"
+        self._process.stdin.write(line)
+        self._process.stdin.flush()
+
+    def _recv(self, deadline: float) -> dict:
+        """Read lines until we get a JSON-RPC response (has 'id')."""
+        import select
+        while True:
+            if time.time() > deadline:
+                raise MCPError("Timeout waiting for server response")
+            ready, _, _ = select.select([self._process.stdout], [], [], 0.1)
+            if not ready:
+                if self._process.poll() is not None:
+                    stderr = self._process.stderr.read()
+                    raise MCPError(f"Server exited unexpectedly. Stderr: {stderr[:500]}")
+                continue
+            line = self._process.stdout.readline()
+            if not line:
+                raise MCPError("Server closed stdout")
+            try:
+                msg = json.loads(line)
+                if "id" in msg:
+                    return msg
+                # Notification or log — skip
+            except json.JSONDecodeError:
+                pass  # Skip non-JSON lines (server log output etc.)
+
+    def _call_raw(self, method: str, params: dict) -> dict:
+        """Send a JSON-RPC request and return the raw response."""
+        req_id = self._next_id()
+        msg = {"jsonrpc": "2.0", "id": req_id, "method": method, "params": params}
+        self._send(msg)
+        deadline = time.time() + self.timeout
+        response = self._recv(deadline)
+        if "error" in response:
+            raise MCPError(f"RPC error: {response['error']}")
+        return response.get("result", {})
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def list_tools(self) -> list[dict]:
+        """Return the list of tools the server exposes.
+
+        Returns:
+            List of tool dicts with 'name', 'description', 'inputSchema'.
+        """
+        result = self._call_raw("tools/list", {})
+        return result.get("tools", [])
+
+    def tool_names(self) -> list[str]:
+        """Return just the tool names."""
+        return [t["name"] for t in self.list_tools()]

mcp_diff/diff.py

@@ -0,0 +1,261 @@
+"""Schema diff engine for mcp-diff."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+
+SEVERITY_BREAKING = "breaking"
+SEVERITY_WARNING = "warning"
+SEVERITY_INFO = "info"
+
+
+@dataclass
+class Change:
+    """Represents a single detected change between two schemas."""
+
+    kind: str
+    """
+    One of: 'removed', 'added', 'description_changed',
+    'param_added_required', 'param_removed', 'param_type_changed',
+    'param_description_changed', 'param_added_optional'.
+    """
+    tool: str
+    """The tool name this change applies to."""
+    param: str | None
+    """Param name, or None for tool-level changes."""
+    severity: str
+    """One of: 'breaking', 'warning', 'info'."""
+    detail: str
+    """Human-readable description of the change."""
+
+
+def _normalize_tool(tool: dict) -> dict:
+    """Return a canonical dict for comparison (sorted keys, stable repr)."""
+    return {
+        "name": tool.get("name", ""),
+        "description": tool.get("description", ""),
+        "inputSchema": tool.get("inputSchema", {}),
+    }
+
+
+def _get_params(tool: dict) -> dict[str, dict]:
+    """Extract parameters from a tool's inputSchema as {name: schema}."""
+    schema = tool.get("inputSchema", {})
+    props = schema.get("properties", {})
+    return {k: dict(v) for k, v in sorted(props.items())}
+
+
+def _get_required(tool: dict) -> set[str]:
+    """Return the set of required param names for a tool."""
+    schema = tool.get("inputSchema", {})
+    return set(schema.get("required", []))
+
+
+def classify_changes(old_tools: list[dict], new_tools: list[dict]) -> list[Change]:
+    """Compare two lists of MCP tool schemas and return all detected changes.
+
+    Args:
+        old_tools: Tool list from the lockfile (baseline).
+        new_tools: Tool list from the live server (current).
+
+    Returns:
+        List of Change objects sorted by severity then tool name.
+    """
+    changes: list[Change] = []
+
+    old_map = {t["name"]: _normalize_tool(t) for t in old_tools}
+    new_map = {t["name"]: _normalize_tool(t) for t in new_tools}
+
+    old_names = set(old_map)
+    new_names = set(new_map)
+
+    # Removed tools — breaking
+    for name in sorted(old_names - new_names):
+        changes.append(Change(
+            kind="removed",
+            tool=name,
+            param=None,
+            severity=SEVERITY_BREAKING,
+            detail=f"Tool '{name}' was removed.",
+        ))
+
+    # Added tools — info
+    for name in sorted(new_names - old_names):
+        changes.append(Change(
+            kind="added",
+            tool=name,
+            param=None,
+            severity=SEVERITY_INFO,
+            detail=f"Tool '{name}' was added.",
+        ))
+
+    # Changed tools — inspect each shared tool
+    for name in sorted(old_names & new_names):
+        old_tool = old_map[name]
+        new_tool = new_map[name]
+
+        # Description changed — warning (description IS the behavioral contract)
+        old_desc = old_tool.get("description", "")
+        new_desc = new_tool.get("description", "")
+        if old_desc != new_desc:
+            changes.append(Change(
+                kind="description_changed",
+                tool=name,
+                param=None,
+                severity=SEVERITY_WARNING,
+                detail=f"Tool description changed.\n  was: {old_desc!r}\n  now: {new_desc!r}",
+            ))
+
+        # Param-level diff
+        old_params = _get_params(old_tool)
+        new_params = _get_params(new_tool)
+        old_required = _get_required(old_tool)
+        new_required = _get_required(new_tool)
+
+        old_param_names = set(old_params)
+        new_param_names = set(new_params)
+
+        # Removed params — breaking
+        for pname in sorted(old_param_names - new_param_names):
+            changes.append(Change(
+                kind="param_removed",
+                tool=name,
+                param=pname,
+                severity=SEVERITY_BREAKING,
+                detail=f"Parameter '{pname}' was removed from tool '{name}'.",
+            ))
+
+        # Added params
+        for pname in sorted(new_param_names - old_param_names):
+            if pname in new_required:
+                # New required param — breaking (callers must now supply it)
+                changes.append(Change(
+                    kind="param_added_required",
+                    tool=name,
+                    param=pname,
+                    severity=SEVERITY_BREAKING,
+                    detail=(
+                        f"Required parameter '{pname}' was added to tool '{name}'. "
+                        "Existing callers will now fail."
+                    ),
+                ))
+            else:
+                changes.append(Change(
+                    kind="param_added_optional",
+                    tool=name,
+                    param=pname,
+                    severity=SEVERITY_INFO,
+                    detail=f"Optional parameter '{pname}' was added to tool '{name}'.",
+                ))
+
+        # Changed params
+        for pname in sorted(old_param_names & new_param_names):
+            old_p = old_params[pname]
+            new_p = new_params[pname]
+
+            # Type changed — breaking
+            old_type = old_p.get("type")
+            new_type = new_p.get("type")
+            if old_type != new_type:
+                changes.append(Change(
+                    kind="param_type_changed",
+                    tool=name,
+                    param=pname,
+                    severity=SEVERITY_BREAKING,
+                    detail=(
+                        f"Parameter '{pname}' type changed: {old_type!r} → {new_type!r} "
+                        f"in tool '{name}'."
+                    ),
+                ))
+
+            # Description changed — warning
+            old_pdesc = old_p.get("description", "")
+            new_pdesc = new_p.get("description", "")
+            if old_pdesc != new_pdesc:
+                changes.append(Change(
+                    kind="param_description_changed",
+                    tool=name,
+                    param=pname,
+                    severity=SEVERITY_WARNING,
+                    detail=(
+                        f"Parameter '{pname}' description changed in tool '{name}'.\n"
+                        f"  was: {old_pdesc!r}\n  now: {new_pdesc!r}"
+                    ),
+                ))
+
+    # Sort: breaking first, then warning, then info; then by tool name
+    severity_order = {SEVERITY_BREAKING: 0, SEVERITY_WARNING: 1, SEVERITY_INFO: 2}
+    changes.sort(key=lambda c: (severity_order.get(c.severity, 9), c.tool, c.param or ""))
+    return changes
+
+
+def has_breaking(changes: list[Change]) -> bool:
+    """Return True if any change is severity 'breaking'."""
+    return any(c.severity == SEVERITY_BREAKING for c in changes)
+
+
+def serialize_lockfile(tools: list[dict], command: list[str]) -> dict:
+    """Build the lockfile dict from a tool list."""
+    import datetime
+    return {
+        "version": "1",
+        "created_at": datetime.datetime.now(datetime.timezone.utc).strftime(
+            "%Y-%m-%dT%H:%M:%SZ"
+        ),
+        "command": " ".join(command),
+        "tools": [_normalize_tool(t) for t in sorted(tools, key=lambda t: t.get("name", ""))],
+    }
+
+
+def deserialize_lockfile(data: dict) -> list[dict]:
+    """Extract tool list from a parsed lockfile dict."""
+    return data.get("tools", [])
+
+
+def format_changes_text(changes: list[Change], color: bool = True) -> str:
+    """Format changes as human-readable colored text."""
+    if not changes:
+        return _c("No changes detected.", "\033[32m", color)
+
+    lines = []
+    for c in changes:
+        if c.severity == SEVERITY_BREAKING:
+            prefix = _c("[BREAKING]", "\033[31m", color)
+        elif c.severity == SEVERITY_WARNING:
+            prefix = _c("[WARNING] ", "\033[33m", color)
+        else:
+            prefix = _c("[INFO]    ", "\033[32m", color)
+
+        loc = f"{c.tool}"
+        if c.param:
+            loc += f".{c.param}"
+        lines.append(f"{prefix} {loc}: {c.detail}")
+
+    return "\n".join(lines)
+
+
+def format_changes_json(changes: list[Change]) -> str:
+    """Format changes as JSON."""
+    return json.dumps(
+        [
+            {
+                "kind": c.kind,
+                "tool": c.tool,
+                "param": c.param,
+                "severity": c.severity,
+                "detail": c.detail,
+            }
+            for c in changes
+        ],
+        indent=2,
+    )
+
+
+def _c(text: str, code: str, color: bool) -> str:
+    """Wrap text in ANSI color code if color is enabled."""
+    if not color:
+        return text
+    return f"{code}{text}\033[0m"

mcp_diff-0.1.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: mcp-diff
+Version: 0.1.0
+Summary: Schema lockfile and breaking-change detector for MCP servers — like package-lock.json for MCP
+License: MIT
+Keywords: breaking-changes,ci,diff,mcp,model-context-protocol,schema
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# mcp-diff
+
+Schema lockfile and breaking-change detector for MCP servers.
+
+**The problem:** MCP servers serve tool schemas at runtime. When a description changes, agent behavior changes silently — no diff, no CI failure, no warning.
+
+**The solution:** Commit a `mcp-schema.lock` to git. Fail CI on breaking changes.
+
+## Install
+
+```bash
+pip install mcp-diff
+```
+
+## Usage
+
+```bash
+# Snapshot your server's current schema
+mcp-diff snapshot python3 my_server.py
+
+# Check for breaking changes (exits 1 if found)
+mcp-diff check python3 my_server.py
+
+# Human-readable report (always exits 0)
+mcp-diff report python3 my_server.py
+```
+
+## Example output
+
+```
+mcp-diff check python3 my_server.py
+
+[BREAKING]  read_file: Tool 'read_file' was removed.
+[BREAKING]  search_files.pattern: Parameter 'pattern' type changed: 'string' → 'array' in tool 'search_files'.
+[WARNING]   search_files: Tool description changed.
+              was: 'Search for files matching a pattern.'
+              now: 'Search files. Use glob patterns.'
+[INFO]      write_file: Tool 'write_file' was added.
+
+Found 2 breaking, 1 warning, 1 info changes.
+```
+
+## Change severity
+
+| Severity | When | CI impact |
+|---|---|---|
+| **breaking** | Tool removed, required param added/removed, param type changed | exits 1 |
+| **warning** | Tool or param description changed (descriptions are behavioral contracts for LLMs) | exits 0 |
+| **info** | Tool added, optional param added | exits 0 |
+
+## CI integration (GitHub Actions)
+
+```yaml
+- name: Snapshot MCP schema
+  run: mcp-diff snapshot python3 my_server.py
+  # Commit mcp-schema.lock to your repo
+
+- name: Check for breaking changes
+  run: mcp-diff check python3 my_server.py
+  # Exits 1 and fails the build if breaking changes are detected
+```
+
+## Lockfile format
+
+```json
+{
+  "version": "1",
+  "created_at": "2026-03-22T03:00:00Z",
+  "command": "python3 my_server.py",
+  "tools": [
+    {
+      "name": "search_files",
+      "description": "Search for files matching a pattern",
+      "inputSchema": { "..." : "..." }
+    }
+  ]
+}
+```
+
+Commit `mcp-schema.lock` to git. The diff in your PR is the schema diff.
+
+## Options
+
+```
+mcp-diff snapshot [--output PATH] <command...>
+mcp-diff check    [--lockfile PATH] [--json] [--no-color] <command...>
+mcp-diff report   [--lockfile PATH] [--no-color] <command...>
+```
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Clean (no breaking changes) |
+| 1 | Breaking changes detected |
+| 2 | Error (missing lockfile, server failed to start) |
+
+## Part of the MCP developer toolkit
+
+- [agent-friend](https://github.com/0-co/agent-friend) — schema quality linter
+- [mcp-patch](https://github.com/0-co/mcp-patch) — AST security scanner
+- [mcp-pytest](https://github.com/0-co/mcp-test) — testing framework
+- [mcp-snoop](https://github.com/0-co/mcp-snoop) — stdio debugger
+- **mcp-diff** — schema lockfile and breaking-change detector
+
+Source: [github.com/0-co/mcp-diff](https://github.com/0-co/mcp-diff)

mcp_diff-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+mcp_diff/__init__.py,sha256=y7fMxClBwTAP4qIvXrnq0YQ4vqhzpf0Jy86cjADkDOA,104
+mcp_diff/cli.py,sha256=Cfwp-66VqlLTB7TzTAUKHhhr4FtbhTDzFl6A47P06WI,9660
+mcp_diff/client.py,sha256=SGBQCmpdL8MCX2HtfaE-VN66ZB43h9jGw_ySmprEwiA,4895
+mcp_diff/diff.py,sha256=1upYN0REpsJANhTx1Z4lAWfqNOZXS5Z29eOK5_7xuFM,8632
+mcp_diff-0.1.0.dist-info/METADATA,sha256=NFfzwZCkSCpm3eEDX3y65EHOzMw_m9yQmgIbXfVwifM,3604
+mcp_diff-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+mcp_diff-0.1.0.dist-info/entry_points.txt,sha256=EQxYnQXcsDOHkpA_ja7Gt5E6HGfGGkUhnl2F6cX7O_g,47
+mcp_diff-0.1.0.dist-info/RECORD,,

mcp_diff-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_diff-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-diff = mcp_diff.cli:main