Snapshot and diff an MCP server
A server’s author rarely sees a contract change happen: a tool renamed in a refactor, a parameter
that became required, an enum that lost a value, a description rewritten. The clients find out
later, when their calls fail or a model starts choosing differently. From
CLI 0.34.5 plune mcp snapshot writes the contract to a file you
commit, and plune mcp diff tells you, in the pull request, what changed and whether it breaks a
client.
Neither needs a Plune account, and neither talks to the Plune platform: they start the server you
name after --, or connect to the --url you give, and nothing else. How to connect a server is on
Test an MCP server.
Take a snapshot
Section titled “Take a snapshot”On the sample server from Lint an MCP server:
$ npx -y @plune-ai/cli@0.39.9 mcp snapshot --out mcp-snapshot.json -- node server.mjsWrote mcp-snapshot.json: 3 tools, 0 resources, 0 resource templates, 0 prompts.$ echo $?0The file holds what the handshake says (the server’s name, version, capabilities and instructions) and every list the server declares — tools, resources, resource templates, prompts — each read to its last page. It is the same byte for byte for the same server, on any OS, so a change in it is a change in the server:
- keys sorted at every level, tools and prompts by name, resources by URI;
- LF line endings, a two-space indent;
- no time, no command, no environment value, no URL, no header: of the connection only the transport
(
stdio,httporsse) is written; - every value you passed for the connection masked wherever the server repeats it, and your home
folder at the start of a path written as
~.
A capability the server did not declare is null; a declared one with nothing in it is [].
The snapshot of the sample server
{ "capabilities": { "tools": {} }, "instructions": null, "kind": "plune-mcp-snapshot", "prompts": null, "resourceTemplates": null, "resources": null, "schemaVersion": 2, "server": { "name": "mcp-sample-server", "version": "1.0.0" }, "tools": [ { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true }, "inputSchema": { "properties": { "id": { "description": "The id of the note, as list_notes shows it.", "type": "integer" } }, "required": [ "id" ], "type": "object" }, "name": "get_note" }, { "annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true }, "description": "Return the notes with their id, title and status. Do not use it to read one note; use get_note instead.", "inputSchema": { "properties": {}, "type": "object" }, "name": "list_notes" }, { "annotations": { "destructiveHint": true, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": false }, "description": "Change the status of one note. Do not use it to edit the title; this server has no tool for that.", "inputSchema": { "properties": { "id": { "description": "The id of the note to change.", "type": "integer" }, "status": { "description": "The new status: one of open, done, archived.", "type": "string" } }, "required": [ "id", "status" ], "type": "object" }, "name": "set_status" } ], "transport": "stdio"}Commit the file next to the server, and take a new one in the same pull request whenever you change the contract on purpose: the diff of the snapshot is then part of the review.
snapshot exits 2 and writes nothing when the server did not start or a list it declared could not
be read, and 3 when the server lists no tool, resource, resource template or prompt. A file is there
whole or not at all.
Read a diff
Section titled “Read a diff”plune mcp diff <snapshot> compares the snapshot with a live server (after --, or --url) or with
a second snapshot file. Here the committed snapshot of the sample server meets its fixed version, the
one with the three lint findings fixed:
$ npx -y @plune-ai/cli@0.39.9 mcp diff mcp-snapshot.json -- node server-fixed.mjs4 change(s) to the contract, overall breaking: 1 breaking, 1 non-breaking, 2 informational (0 not classified, 2 security) informational tool get_note description added [security]: The description changed: it is what a model is told about the tool. non-breaking tool list_notes inputSchema.limit added: A new optional parameter. breaking tool set_status inputSchema.status added: The enum was narrowed: the values became a fixed list; a call that passes it now fails. informational tool set_status inputSchema.status modified [security]: The parameter description changed: it is what a model reads.
failing on: breaking$ echo $?1Fixing the lint findings is itself a contract change, and the diff says what it costs: the new
limit is optional, so no client breaks; the new enum on status narrows what a call may send, so
a client that sent any other string now fails. Every change has a class and a one-sentence reason:
| What changed | Class |
|---|---|
| A tool, resource, resource template or prompt removed | breaking |
| One added | non-breaking |
Tool input: a new required parameter, a narrowed enum, a changed type, a removed parameter, a tighter bound | breaking |
Tool input: a new optional parameter, a widened enum, a looser bound | non-breaking |
A resource’s or a template’s mimeType | breaking |
| A prompt argument: a new required one, one removed, one that became required | breaking |
| A prompt argument: a new optional one | non-breaking |
A capability, or its listChanged or subscribe, removed / added | breaking / non-breaking |
A tool’s execution.taskSupport became required | breaking |
A uriTemplate changed | the old template removed and a new one added |
A name, title, description, the instructions, server.version | informational |
server.name | informational, marked server identity |
A change no rule understands — a schema keyword such as anyOf, $ref or format, an unknown
field — is not called harmless: it is listed as not classified, counted apart, and fails the run
only with --fail-on any.
The security signal
Section titled “The security signal”Some changes break nothing and still deserve a reviewer’s eyes, because they change what a model is
told or what a tool may do: a changed description of a tool, resource, prompt or parameter; changed
instructions; readOnlyHint that stops being true; destructiveHint that becomes true; a new tool
that does not say it is read-only. They carry [security] in the output and "signal": "security" in
the JSON. The signal is a reason to read, not a failure: it changes neither the class nor the exit
code.
--fail-on
Section titled “--fail-on”--fail-on | Exit 1 on |
|---|---|
breaking (default) | a breaking change |
any | any change, a change that could not be classified included |
none | nothing; the report only |
| Exit | Meaning |
|---|---|
0 | No change at the --fail-on level. |
1 | At least one change at the --fail-on level. |
2 | A snapshot file cannot be read, is not JSON or has a schemaVersion this version does not read; the server did not start or a declared list could not be read; or a flag is wrong. |
3 | Nothing to compare: neither side holds a tool, resource, resource template or prompt. |
In a pull request
Section titled “In a pull request”--format markdown writes the diff as a pull request comment. It starts with a hidden marker, so a
step that updates one comment in place finds its own:
$ npx -y @plune-ai/cli@0.39.9 mcp diff mcp-snapshot.json --format markdown -- node server-fixed.mjs<!-- plune-mcp-diff -->### MCP contract
**Overall: breaking** — 1 breaking, 1 non-breaking, 2 informational (0 not classified, 2 security)
| Class | Entity | Name | Field | Change | Reason || --- | --- | --- | --- | --- | --- || informational (security) | tool | get_note | description | added | The description changed: it is what a model is told about the tool. || non-breaking | tool | list_notes | inputSchema.limit | added | A new optional parameter. || breaking | tool | set_status | inputSchema.status | added | The enum was narrowed: the values became a fixed list; a call that passes it now fails. || informational (security) | tool | set_status | inputSchema.status | modified | The parameter description changed: it is what a model reads. |$ echo $?1Every text from the server is escaped in that comment, so a server cannot add HTML, a mention or a link to your pull request. A step that runs the diff against the pull request’s build:
- run: npm ci && npm run build- run: npx -y @plune-ai/cli mcp diff mcp-snapshot.json --out markdown=mcp-diff.md -- node dist/server.jsThe MCP server checks action does this for you with
steps: lint,check,diff and snapshot-file: it runs diff against the committed snapshot, posts the
comment, annotates the run and fails the check on a breaking change.