mcp-diff 0.1.0__tar.gz

mcp_diff-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+products/signal-intel/.state.json
+products/signal-intel/.env
+*.env
+.claude/worktrees/
+__pycache__/
+*.pyc

mcp_diff-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,106 @@
+# 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/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-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-0.1.0/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()]