- Home
- Plugins
- Tools & Capabilities
- dsh-mcp-tool-schema-diff
dsh-mcp-tool-schema-diff
liuhange789/dsh-mcp-tool-schema-diff
Breaking-change watchdog for MCP tool contracts. Remembers the last three tool generations per MCP server from the live tools/change registry and diffs them: removed tools, dropped parameters, accepted-type changes, new required fields and narrowed enums are graded breaking; default and constraint changes are warnings; additions are info. A quiet-window debounce absorbs mcp-client re-sync churn, so first connections and reconnects never false-alarm. Reports through a transcript notice plus `/mcp-diff`, caches snapshots under `$DSH_HOME/mcp-schema-cache` (last 3 versions), reads the registry only and writes no other state.
Install
dsh plugin --profile web add github:liuhange789/dsh-mcp-tool-schema-diffREADME
dsh-mcp-tool-schema-diff
Your MCP server upgraded and the workflow broke? This tells you which tool's contract changed, at the moment it changed.
Third-party MCP servers move. A tool gets renamed, a parameter is dropped, limit goes from number to string, an optional field becomes required. Nothing announces it. Yesterday's working call returns a validation error today, and the first thing you do is re-read a tool description you had already memorised.
This plugin keeps the last three tool generations per MCP server and diffs the live registry against them. When a breaking change lands, it tells you before you hit the error — with the server, the tool, the parameter path, and what changed.
This is not a permission audit. dsh-agent-permission-audit compares declared capability against actual usage inside one session. This compares one server version against the next. Different axis, different failure.
| Answers | Needs from you | |
|---|---|---|
dsh-agent-permission-audit | Can this agent do more than it was allowed to? | one session |
dsh-plugin-profiler | What is my installed plugin set costing me? | one session |
| this plugin | What in an MCP server's contract changed between versions? | one upgrade |
Install
dsh plugin add dsh-mcp-tool-schema-diff
The bundle declares its own patch (cordis.patch.yml), so that is the only install step. The first time a server's tools appear, a baseline is recorded; every later registry change is diffed against it.
What counts as breaking
| Change | Severity | Why |
|---|---|---|
| Tool removed | breaking | The call finds no tool |
| Parameter removed | breaking | Existing arguments now fail validation |
Accepted type removed (e.g. number → string) | breaking | Existing values are rejected |
| New required parameter | breaking | Every existing call is now incomplete |
Enum / const narrowed | breaking | Previously valid values are rejected |
| Optional parameter added | info | Existing calls still validate |
| Required relaxed to optional | info | Existing calls still validate |
Enum / const widened | info | Nothing previously accepted is rejected |
| Description changed | info | Prose only |
| Default changed | warning | Valid, but behaviour may differ |
Constraint changed (pattern, bounds, format) | warning | Valid values may now be rejected |
Composed schema (anyOf / oneOf / $ref …) changed | warning | Compared as one opaque signature |
Plain type replaced by anyOf (or the reverse) | warning | The direction cannot be proven, so it never claims "breaking" |
| Change below the depth / size comparison limit | warning | A digest says "it moved", not which way |
Nested object and array parameters are walked to depth 4 (64 properties per level), so parameters.options.limit is reported by its full path, not as "the schema changed somewhere". A change below that budget is reported as a truncated warning rather than ignored.
What a user sees
A transcript notice when a breaking change lands:
MCP tool schema changed for "github": 6 breaking changes. parameters.options.sort no longer accepts "comments" (+5 more breaking). Run /mcp-diff for the full diff.
And /mcp-diff for the detail card. Real output from the synthetic upgrade used in the tests:
MCP tool schema diff · 1 server connected · 6 breaking changes · no warnings
checked 0s ago
github · 6 breaking · 0 warning · 3 info
breaking parameters.options.sort no longer accepts "comments"
breaking parameters.query was removed
breaking parameters.body is now required
breaking parameters.repo is now required
breaking parameters.options.limit no longer accepts number (now string)
breaking tool mcp__github__list_labels was removed
info parameters.options.state is new and optional
info parameters.query is no longer required
… 1 more
Cache C:\Users\HP\.dsh\mcp-schema-cache · last 3 versions per server
The card keeps the last detected diff after it is stored, so it does not go quiet the moment the warning becomes useful. A later upgrade replaces it.
How it detects an upgrade
rc.7 has no per-server connect or upgrade event. What it exposes is tools/change, which fires on every register, unregister and scope change, plus ctx.tools.schemas() for the live registry. @deepseek-ai/dsh-mcp-client names its tools mcp__<serverName>__<rawName>, so this plugin groups the registry by server from the public name.
An MCP re-sync throws away the whole previous generation and registers the new one, which means tools/change fires many times with empty and partial states. Every event only resets a 200ms quiet timer; the diff runs once the registry has stopped moving. Without that window, every reconnect would look like "all tools removed".
- The first snapshot for a server is a baseline and never alarms.
- An unchanged generation is not stored again, so history is three real generations, not three identical ones.
- A fully empty registry is treated as a teardown, not as every tool being removed.
Commands
/mcp-diff— force a fresh check and print the detail card (never wakes an agent)/mcp-diff reset— clear cached versions for every server; the next check re-baselines/mcp-diff reset <server>— clear one server, e.g./mcp-diff reset github
Storage
$DSH_HOME/mcp-schema-cache/<server>.json, falling back to ~/.dsh/mcp-schema-cache/<server>.json. One file per server, last three snapshots, written through a temporary file so a killed process cannot leave a half-written cache that looks like a schema change. Files are capped at 256 KB and 512 tools per server; oversized snapshots are skipped rather than truncated.
The brief suggested ~/.dsh/profiles/web/. That path is not reachable from inside a plugin: rc.7 exposes no DSH_PROFILE, and hard-coding web would silently disable the plugin under tui or headless. The cache is therefore per DSH home, shared across profiles.
What this cannot know
Read this before installing:
- No banner service. rc.7 exposes no
ctx.uiand noinjectBanner. The "banner" is implemented as the two surfaces that do exist: a one-linelogger.warnand aplugin-sourcednoticemessage in the live agent's transcript. Details stay in/mcp-diff, which is the collapsible view. - No per-server upgrade event. Detection is registry-based. If a server replaces its tool set so fast that the registry never settles, the diff waits for the quiet window; nothing is reported mid-sync.
- Server removal is not alarmed. A server that disappears from the registry while others remain only shows as "cached, server not connected". Profiles, config edits and reconnects can all cause that transiently, and paging on it would be noise. Tool removal inside a connected server is still breaking.
- Raw tool names are unrecoverable.
mcp-clientmay append_<12hex>after lossy normalization or truncation. Reports use the public name callers actually invoke, and never guess the original. - Grouping assumes the documented server-name pattern.
mcp__is split at the first__. A server name containing__would group wrongly; the documented config pattern is[A-Za-z0-9_-]{1,32}, which cannot. - Depth and size bounds are deliberate, and visible. Parameters nested deeper than four levels, or lists beyond 64 properties / enum values / required names, are compared by a digest. If something changes past the bound you get a
truncatedwarning, never a silent pass and never a guessed direction. constandenumare one value set.const: "a"→enum: ["a","b"]is a widening,enum: ["a"]→const: "a"is no change, and a server changing spelling cannot fake a break.- A read-only home costs persistence, not detection. The last three generations then live in memory for the rest of the session.
Robustness
Written so it can never be the reason your host breaks:
- Every listener body, timer callback and agent notice is contained; a failure is logged, never thrown into the host.
- The plugin never mutates another plugin or a tool definition; it reads
ctx.tools.schemas()only. - A missing
tools,commandsoragentsservice costs the corresponding surface only. - A
/mcp-diffname already taken (a second copy, or a stale registration) costs the command only; the watcher keeps checking. - Circular parameters, non-object schemas, hostile getters and hand-edited cache files degrade one entry, not the report.
- Cache writes are atomic and bounded; a full disk or a read-only home does not break the session.
Limitations
- The baseline is written the first time the plugin sees a server. Installing this plugin after an already-broken upgrade gives you a clean baseline, not a historical diff.
- Descriptions are compared by hash, so a prose edit with identical meaning still reports as
info. warningon a constraint change is a judgement call: a tighterpatterncan be breaking in practice, but the schema does not say which direction it moved.- The notice wakes the root agent's turn once per unique breaking diff. Repeated identical diffs are suppressed in-process.
Compatibility
DeepSeek Harness 0.1.0-rc.7 (@deepseek-ai/cordis 4.x event bus). Node ^22.19.0 || >=24.0.0. No runtime dependencies beyond Node built-ins. /mcp-diff requires the commands service.
Tests
npm test
Seventeen tests run against a real cordis runtime: first-connection silence, five breaking shapes in one upgrade, re-sync churn with empty and partial generations, three-version trimming, teardown silence, malformed/circular/hostile schemas, missing commands and tools services, a duplicate command name, a read-only cache with in-memory fallback, reset plus re-baseline, mcp__ name parsing, union schemas that must not be called breaking, integer → number widening, const/enum equivalence, boolean schemas and tuple items, a sub-depth change becoming a warning, a 70-value enum reorder staying silent, a second narrowing still raising its own notice, and a manual /mcp-diff not swallowing the pending notice. cordis is loaded from CORDIS_PATH when set, otherwise from the @deepseek-ai/cordis dev dependency, so npm install makes a clean clone testable.
License
MIT
Related plugins
archify (deepseek-harness)
tt-a1i/archify
WeKnora (dsh-weknora)
tencent/weknora
next-ai-draw-io (dsh-plugin)
dayuanjiang/next-ai-draw-io
weknora
tencent/weknora