Skip to content
Back to search

mcp-lock

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/margosmark--mcp-lock/badge.svg)](/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
  1. # mcp-lock
  2. **A tool-surface lockfile and drift gate for MCP servers.**
  3. MCP agents pick tools at runtime by reading descriptions and input schemas.
  4. Nothing pins them: a server update can silently rename a tool, make a parameter
  5. required, or reword a description — and the agent's behaviour changes with no
  6. signal. `mcp-lock` snapshots every configured server's tool surface into
  7. `mcp.lock.json` and fails CI the moment the live surface drifts from it.
  8. > Status: alpha. Design contract: [`docs/00-plan.md`](docs/00-plan.md).
  9. ## Drift classes it catches
  10. | class | meaning |
  11. |---|---|
  12. | `tool added` / `tool removed` | a tool appeared or vanished |
  13. | `schema changed` | input schema hash differs (e.g. a param became required) |
  14. | `description-only change` | schema identical, description reworded |
  15. | `tool changed` | both description and schema differ |
  16. | `artifact moved` | server-reported version, binary digest, URL or identity changed |
  17. | `server added` / `server removed` | a configured server is missing from the lockfile (or vice versa) |
  18. ## Install (from source)
  19. ```bash
  20. git clone https://github.com/margosmark/mcp-lock.git
  21. cd mcp-lock
  22. pip install . # provides the `mcp-lock` command
  23. pip install .[dev] # + pytest, ruff
  24. ```
  25. ## Worked example
  26. ### 1. Configure servers — `mcp-lock.toml`
  27. ```toml
  28. [server.docs]
  29. transport = "stdio" # or transport = "http" + url = "..."
  30. command = ["python3", "tools/docs_server.py"]
  31. env = { DOCS_INDEX = "/srv/docs" } # optional, merged over process env
  32. ```
  33. ### 2. Baseline the surface — `mcp-lock init`
  34. ```console
  35. $ mcp-lock init
  36. mcp-lock: wrote mcp.lock.json — 1 server(s), 2 tool(s).
  37. ```
  38. The lockfile records, per server: transport, `serverInfo` (name/version),
  39. artifact identity (command, resolved binary path, `sha256:` digest of the
  40. binary, server-reported version), and per tool: the full description, its
  41. `sha256`, the full input schema, and its canonical `sha256`:
  42. ```json
  43. {
  44. "lockfileVersion": 1,
  45. "generatedBy": "mcp-lock 0.1.0",
  46. "generatedAt": "2026-11-21T16:41:10Z",
  47. "servers": {
  48. "docs": {
  49. "transport": "stdio",
  50. "serverInfo": { "name": "mock-server", "version": "1.0.0" },
  51. "artifact": {
  52. "kind": "stdio",
  53. "version": "1.0.0",
  54. "digest": "sha256:3642edb46c7bfad367e99751c422ca6b...",
  55. "resolvedPath": "/usr/bin/python3",
  56. "command": ["python3", "tools/docs_server.py"],
  57. "url": null
  58. },
  59. "tools": {
  60. "search": {
  61. "description": "Search the docs.",
  62. "descriptionSha256": "sha256:183d402ea78633ef1a9b...",
  63. "inputSchema": { "type": "object", "properties": { "...": {} } },
  64. "inputSchemaSha256": "sha256:68c4f3e913af90118259..."
  65. }
  66. }
  67. }
  68. }
  69. }
  70. ```
  71. Hashes are computed over canonical JSON (`sort_keys`, no whitespace), so key
  72. order and formatting can never cause false drift. The file itself is written
  73. sorted and indented for clean git diffs.
  74. ### 3. Gate — `mcp-lock verify`
  75. Clean run:
  76. ```console
  77. $ mcp-lock verify
  78. mcp-lock: OK — no drift between mcp.lock.json and live servers.
  79. ```
  80. The server ships an update that makes `search.limit` required:
  81. ```console
  82. $ mcp-lock verify
  83. mcp-lock: 1 drift(s) found against mcp.lock.json
  84. docs:
  85. schema changed 'search'
  86. + param 'limit' became required
  87. ~ param 'limit' definition changed
  88. ```
  89. A reworded description (schema untouched):
  90. ```console
  91. $ mcp-lock diff
  92. mcp-lock: 1 drift(s) found against mcp.lock.json
  93. docs:
  94. description-only change 'search'
  95. - Search the docs.
  96. + Search the documentation (filters now supported).
  97. ```
  98. `mcp-lock diff` reports but always exits 0 (local exploration);
  99. `mcp-lock verify` is the gate. `--json` on either emits a machine-readable
  100. list of `{server, tool, kind, notes}` objects.
  101. ### Exit codes (the CI contract)
  102. | code | meaning |
  103. |---|---|
  104. | `0` | no drift / success |
  105. | `1` | drift found (`verify` only) |
  106. | `2` | could not verify: bad config, unreachable server, missing/corrupt lockfile |
  107. A server that is *down* must never make CI green — that's why unreachable
  108. servers exit `2`, not `0`.
  109. ## CI integration
  110. Composite action (`.github/actions/mcp-lock/action.yml`):
  111. ```yaml
  112. jobs:
  113. mcp-surface:
  114. runs-on: ubuntu-latest
  115. steps:
  116. - uses: actions/checkout@v4
  117. - uses: ./.github/actions/mcp-lock
  118. with:
  119. config: mcp-lock.toml
  120. lock: mcp.lock.json
  121. ```
  122. or directly: `pip install . && mcp-lock verify`.
  123. ## Artifact honesty
  124. For stdio servers, `artifact.digest` is the `sha256` of the **resolved
  125. executable behind `argv[0]`** (e.g. the `python3`/`node` interpreter), not the
  126. contents of uvx-managed package layers. The primary artifact signal is the
  127. server-reported `serverInfo.version`; the digest catches interpreter/binary
  128. swaps. Registry/package-layer verification is future work (see
  129. [`docs/00-plan.md` §9](docs/00-plan.md)) — the same shallow-layer gap
  130. Snyk's `mcp-scan` #482 admits, stated openly rather than papered over.
  131. ## Development
  132. ```bash
  133. ruff check . # lint
  134. pytest # 44 tests: unit + end-to-end against a real mock MCP server
  135. # (stdio and streamable-HTTP transports, drift variants)
  136. ```
  137. `tests/mock_server.py` is a real MCP server (Python SDK) whose surface is
  138. selected by `MCP_LOCK_VARIANT`: `baseline`, `desc-drift`, `schema-drift`,
  139. `tool-added`, `tool-removed`, `artifact-drift`.
  140. ## License
  141. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.