Skip to content

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.

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.mjs
Wrote mcp-snapshot.json: 3 tools, 0 resources, 0 resource templates, 0 prompts.
$ echo $?
0

The 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, http or sse) 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.

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.mjs
4 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 $?
1

Fixing 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 changedClass
A tool, resource, resource template or prompt removedbreaking
One addednon-breaking
Tool input: a new required parameter, a narrowed enum, a changed type, a removed parameter, a tighter boundbreaking
Tool input: a new optional parameter, a widened enum, a looser boundnon-breaking
A resource’s or a template’s mimeTypebreaking
A prompt argument: a new required one, one removed, one that became requiredbreaking
A prompt argument: a new optional onenon-breaking
A capability, or its listChanged or subscribe, removed / addedbreaking / non-breaking
A tool’s execution.taskSupport became requiredbreaking
A uriTemplate changedthe old template removed and a new one added
A name, title, description, the instructions, server.versioninformational
server.nameinformational, 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.

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-onExit 1 on
breaking (default)a breaking change
anyany change, a change that could not be classified included
nonenothing; the report only
ExitMeaning
0No change at the --fail-on level.
1At least one change at the --fail-on level.
2A 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.
3Nothing to compare: neither side holds a tool, resource, resource template or prompt.

--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 $?
1

Every 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.js

The 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.