dsh-mcp-tool-schema-diff
Manifest validBreaking-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, accepte
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
Comments
Loading…
Similar plugins
by zhengqiuyang
Tool-surface snapshot and drift gate: baselines the full visible tool registry (name/description/parameters, MCP tools included) into a committable JSON file and warns loudly when an upgrade adds, rem
★ 0
MIT
JavaScript
Nov 15, 2026
dsh plugin --profile web add dsh-mcp-testby activeing123
DSH plugin bundle that mounts mcptoon as an MCP server: compresses MCP tool discovery from 71,929 to 581 tokens across 255 tools (-99.2%, measured).
★ 3
Apache-2.0
JavaScript
Sep 16, 2026
dsh plugin --profile web add dsh-mcptoonby shiliu153
DeepSeek Harness bundle: manage MCP servers — list, probe, add from pasted project references, toggle, remove, rotate credentials. Official dsh-mcp-client contract compliant.
★ 0
NOASSERTION
JavaScript
Nov 2, 2026
dsh plugin --profile web add @dsh-contrib/dsh-mcp-managerMCP management console for DeepSeek Harness — a left-sidebar page that lists every configured MCP server, trial-calls its tools in place, restarts a single row when its transport dies or never synced,
★ 0
Apache-2.0
TypeScript
dsh plugin --profile web add dsh-mcp-workbenchby zhe97396-tech
MCP gateway for dsh that connects each server on first use and disconnects it after an idle window; tool lists are cached on disk, existing mcpServers files can be imported, and child-process environm
★ 0
MIT
JavaScript
Oct 19, 2026
dsh plugin --profile web add dsh-lazy-mcpMCP server panel for the DeepSeek Harness Web GUI: sidebar list of every MCP server with live connection state, tool count and config, plus in-place enable/disable and reconnect.
★ 0
MIT
JavaScript
dsh plugin --profile web add dsh-mcp-status