Back to search
mcp-lock
MCP serverGitHub
Tool-surface lockfile and drift gate for MCP servers: snapshot every server tool surface into mcp.lock.json and fail CI when the live surface drifts.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/margosmark--mcp-lock)HTML
<a href="/listings/margosmark--mcp-lock"><img src="/api/listings/margosmark--mcp-lock/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
git clone https://github.com/margosmark/mcp-lock.git cd mcp-lock pip install . # provides the `mcp-lock` command pip install .[dev] # + pytest, ruff
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 180 lines
- # mcp-lock
- **A tool-surface lockfile and drift gate for MCP servers.**
- MCP agents pick tools at runtime by reading descriptions and input schemas.
- Nothing pins them: a server update can silently rename a tool, make a parameter
- required, or reword a description — and the agent's behaviour changes with no
- signal. `mcp-lock` snapshots every configured server's tool surface into
- `mcp.lock.json` and fails CI the moment the live surface drifts from it.
- > Status: alpha. Design contract: [`docs/00-plan.md`](docs/00-plan.md).
- ## Drift classes it catches
- | class | meaning |
- |---|---|
- | `tool added` / `tool removed` | a tool appeared or vanished |
- | `schema changed` | input schema hash differs (e.g. a param became required) |
- | `description-only change` | schema identical, description reworded |
- | `tool changed` | both description and schema differ |
- | `artifact moved` | server-reported version, binary digest, URL or identity changed |
- | `server added` / `server removed` | a configured server is missing from the lockfile (or vice versa) |
- ## Install (from source)
- ```bash
- git clone https://github.com/margosmark/mcp-lock.git
- cd mcp-lock
- pip install . # provides the `mcp-lock` command
- pip install .[dev] # + pytest, ruff
- ```
- ## Worked example
- ### 1. Configure servers — `mcp-lock.toml`
- ```toml
- [server.docs]
- transport = "stdio" # or transport = "http" + url = "..."
- command = ["python3", "tools/docs_server.py"]
- env = { DOCS_INDEX = "/srv/docs" } # optional, merged over process env
- ```
- ### 2. Baseline the surface — `mcp-lock init`
- ```console
- $ mcp-lock init
- mcp-lock: wrote mcp.lock.json — 1 server(s), 2 tool(s).
- ```
- The lockfile records, per server: transport, `serverInfo` (name/version),
- artifact identity (command, resolved binary path, `sha256:` digest of the
- binary, server-reported version), and per tool: the full description, its
- `sha256`, the full input schema, and its canonical `sha256`:
- ```json
- {
- "lockfileVersion": 1,
- "generatedBy": "mcp-lock 0.1.0",
- "generatedAt": "2026-11-21T16:41:10Z",
- "servers": {
- "docs": {
- "transport": "stdio",
- "serverInfo": { "name": "mock-server", "version": "1.0.0" },
- "artifact": {
- "kind": "stdio",
- "version": "1.0.0",
- "digest": "sha256:3642edb46c7bfad367e99751c422ca6b...",
- "resolvedPath": "/usr/bin/python3",
- "command": ["python3", "tools/docs_server.py"],
- "url": null
- },
- "tools": {
- "search": {
- "description": "Search the docs.",
- "descriptionSha256": "sha256:183d402ea78633ef1a9b...",
- "inputSchema": { "type": "object", "properties": { "...": {} } },
- "inputSchemaSha256": "sha256:68c4f3e913af90118259..."
- }
- }
- }
- }
- }
- ```
- Hashes are computed over canonical JSON (`sort_keys`, no whitespace), so key
- order and formatting can never cause false drift. The file itself is written
- sorted and indented for clean git diffs.
- ### 3. Gate — `mcp-lock verify`
- Clean run:
- ```console
- $ mcp-lock verify
- mcp-lock: OK — no drift between mcp.lock.json and live servers.
- ```
- The server ships an update that makes `search.limit` required:
- ```console
- $ mcp-lock verify
- mcp-lock: 1 drift(s) found against mcp.lock.json
- docs:
- schema changed 'search'
- + param 'limit' became required
- ~ param 'limit' definition changed
- ```
- A reworded description (schema untouched):
- ```console
- $ mcp-lock diff
- mcp-lock: 1 drift(s) found against mcp.lock.json
- docs:
- description-only change 'search'
- - Search the docs.
- + Search the documentation (filters now supported).
- ```
- `mcp-lock diff` reports but always exits 0 (local exploration);
- `mcp-lock verify` is the gate. `--json` on either emits a machine-readable
- list of `{server, tool, kind, notes}` objects.
- ### Exit codes (the CI contract)
- | code | meaning |
- |---|---|
- | `0` | no drift / success |
- | `1` | drift found (`verify` only) |
- | `2` | could not verify: bad config, unreachable server, missing/corrupt lockfile |
- A server that is *down* must never make CI green — that's why unreachable
- servers exit `2`, not `0`.
- ## CI integration
- Composite action (`.github/actions/mcp-lock/action.yml`):
- ```yaml
- jobs:
- mcp-surface:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v4
- - uses: ./.github/actions/mcp-lock
- with:
- config: mcp-lock.toml
- lock: mcp.lock.json
- ```
- or directly: `pip install . && mcp-lock verify`.
- ## Artifact honesty
- For stdio servers, `artifact.digest` is the `sha256` of the **resolved
- executable behind `argv[0]`** (e.g. the `python3`/`node` interpreter), not the
- contents of uvx-managed package layers. The primary artifact signal is the
- server-reported `serverInfo.version`; the digest catches interpreter/binary
- swaps. Registry/package-layer verification is future work (see
- [`docs/00-plan.md` §9](docs/00-plan.md)) — the same shallow-layer gap
- Snyk's `mcp-scan` #482 admits, stated openly rather than papered over.
- ## Development
- ```bash
- ruff check . # lint
- pytest # 44 tests: unit + end-to-end against a real mock MCP server
- # (stdio and streamable-HTTP transports, drift variants)
- ```
- `tests/mock_server.py` is a real MCP server (Python SDK) whose surface is
- selected by `MCP_LOCK_VARIANT`: `baseline`, `desc-drift`, `schema-drift`,
- `tool-added`, `tool-removed`, `artifact-drift`.
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.