Build MCPLock: catch breaking MCP tool changes

.github/workflows/test.yml

@@ -0,0 +1,25 @@
+name: test
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.11", "3.14"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e . --no-deps
+      - run: python -m unittest discover -s tests -v
+      - run: python -m mcplock --help

.gitignore

@@ -1,2 +1,9 @@
 /.worktrees/
 /.superpowers/
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/
+/mcp.lock.json

CONTRIBUTING.md

@@ -0,0 +1,13 @@
+# Contributing
+
+MCPLock intentionally keeps a small standard-library core.
+
+1. Use Python 3.11 or newer.
+2. Install with `python -m pip install -e . --no-deps`.
+3. Add a failing `unittest` for every behavior change.
+4. Run `python -m unittest discover -s tests -v`.
+5. Keep runtime dependencies at zero and tests offline.
+
+Bug reports should include the MCPLock command, exit code, sanitized stderr,
+operating system, Python version, and a minimal MCP server fixture when
+possible. Never include credentials or an unsanitized environment.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MCPLock contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,63 @@
+# MCPLock
+
+> Catch breaking MCP tool changes before your agents do.
+
+MCPLock creates a Git-friendly lockfile for one stdio MCP server's `tools/list`
+contract. Run it again in CI to catch removed tools, newly required inputs,
+narrowed types, removed enum values, and forbidden additional properties.
+
+- No model or API key
+- No service, daemon, database, or telemetry
+- No runtime dependencies
+- Deterministic JSON suitable for code review
+
+## One-minute offline demo
+
+~~~console
+python -m pip install -e . --no-deps
+mcplock update -- python tests/fake_server.py --scenario baseline
+mcplock check -- python tests/fake_server.py --scenario breaking
+~~~
+
+The second command exits `1` and identifies the new required input. The first
+command writes `mcp.lock.json`; commit that file beside your MCP server.
+
+## Use it with your server
+
+~~~console
+mcplock update -- python my_server.py
+git add mcp.lock.json
+mcplock check -- python my_server.py
+~~~
+
+Use `--lock path/to/name.lock.json` for multiple servers and `--timeout 60`
+for slow startup. MCPLock passes every token after `--` directly to the child
+process without invoking a shell.
+
+## CI
+
+~~~yaml
+- name: Check MCP tool contract
+  run: mcplock check -- python my_server.py
+~~~
+
+Exit codes are `0` for compatible or warning-only changes, `1` for certain
+breaking changes, `2` for usage/lockfile/launch/protocol failures, and `130`
+for user interruption.
+
+## What counts as breaking
+
+MCPLock fails for a removed tool, newly required input, removed input
+property, narrowed JSON type, removed enum value, or a change from allowed
+additional properties to forbidden. Every other observed contract change is
+shown for review without claiming complete JSON Schema analysis.
+
+## Scope
+
+Version 0.1 supports stdio MCP revisions `2025-11-25`, `2025-06-18`,
+`2025-03-26`, and `2024-11-05`. It does not call tools, connect over HTTP,
+scan for vulnerabilities, use models, or upload data.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). MCPLock is MIT licensed.

pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcplock"
+version = "0.1.0"
+description = "Catch breaking MCP tool changes before your agents do"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+keywords = ["ai-agents", "mcp", "model-context-protocol", "testing"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+dependencies = []
+
+[project.scripts]
+mcplock = "mcplock.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcplock"]

src/mcplock/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

src/mcplock/cli.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import math
+from pathlib import Path
+import sys
+
+from .contract import (
+    ContractError,
+    build_lock,
+    compare_locks,
+    load_lock,
+    write_lock,
+)
+from .stdio import DiscoveryError, SUPPORTED_PROTOCOL_VERSIONS, discover
+
+
+def positive_timeout(value):
+    timeout = float(value)
+    if not math.isfinite(timeout) or timeout <= 0:
+        raise argparse.ArgumentTypeError("timeout must be greater than zero")
+    return timeout
+
+
+def parser():
+    result = argparse.ArgumentParser(
+        prog="mcplock",
+        description="Catch breaking MCP tool changes before your agents do.",
+    )
+    commands = result.add_subparsers(dest="action", required=True)
+    for action in ("update", "check"):
+        command = commands.add_parser(action)
+        command.add_argument("--lock", type=Path, default=Path("mcp.lock.json"))
+        command.add_argument("--timeout", type=positive_timeout, default=30.0)
+        command.add_argument("server_command", nargs=argparse.REMAINDER)
+    return result
+
+
+def render_changes(changes):
+    if not changes:
+        return "MCPLock: compatible\n"
+    counts = {
+        severity: sum(item.severity == severity for item in changes)
+        for severity in ("breaking", "warning", "info")
+    }
+    summary = ", ".join(
+        f"{count} {severity}"
+        for severity, count in counts.items()
+        if count
+    )
+    lines = [f"MCPLock: {summary} change(s)", ""]
+    for item in changes:
+        lines.extend([
+            f"{item.severity.upper():8}  {item.path}",
+            f"          {item.message}",
+            "",
+        ])
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def main(argv=None):
+    args = parser().parse_args(argv)
+    command = list(args.server_command)
+    if not command or command.pop(0) != "--" or not command:
+        print("MCPLock error: server command is required after --", file=sys.stderr)
+        return 2
+    try:
+        discovery = discover(command, timeout=args.timeout)
+        try:
+            result = asyncio.run(discovery)
+        finally:
+            discovery.close()
+        current = build_lock(result.protocol_version, result.server, result.tools)
+        if args.action == "update":
+            write_lock(args.lock, current)
+            print(
+                f"MCPLock: wrote {args.lock} "
+                f"({current['stats']['toolCount']} tools)"
+            )
+            return 0
+        baseline = load_lock(args.lock)
+        if baseline["protocolVersion"] not in SUPPORTED_PROTOCOL_VERSIONS:
+            raise ContractError(
+                "unsupported lockfile protocol version: "
+                f"{baseline['protocolVersion']}"
+            )
+        changes = compare_locks(baseline, current)
+        print(render_changes(changes), end="")
+        return 1 if any(item.severity == "breaking" for item in changes) else 0
+    except KeyboardInterrupt:
+        return 130
+    except (ContractError, DiscoveryError, OSError) as exc:
+        print(f"MCPLock error: {exc}", file=sys.stderr)
+        diagnostic = getattr(exc, "diagnostic", "")
+        if diagnostic:
+            print(diagnostic, file=sys.stderr)
+        return 2