Skip to main content
L

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-diff

README

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.

AnswersNeeds from you
dsh-agent-permission-auditCan this agent do more than it was allowed to?one session
dsh-plugin-profilerWhat is my installed plugin set costing me?one session
this pluginWhat 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

ChangeSeverityWhy
Tool removedbreakingThe call finds no tool
Parameter removedbreakingExisting arguments now fail validation
Accepted type removed (e.g. number → string)breakingExisting values are rejected
New required parameterbreakingEvery existing call is now incomplete
Enum / const narrowedbreakingPreviously valid values are rejected
Optional parameter addedinfoExisting calls still validate
Required relaxed to optionalinfoExisting calls still validate
Enum / const widenedinfoNothing previously accepted is rejected
Description changedinfoProse only
Default changedwarningValid, but behaviour may differ
Constraint changed (pattern, bounds, format)warningValid values may now be rejected
Composed schema (anyOf / oneOf / $ref …) changedwarningCompared as one opaque signature
Plain type replaced by anyOf (or the reverse)warningThe direction cannot be proven, so it never claims "breaking"
Change below the depth / size comparison limitwarningA 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.ui and no injectBanner. The "banner" is implemented as the two surfaces that do exist: a one-line logger.warn and a plugin-sourced notice message 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-client may 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 truncated warning, never a silent pass and never a guessed direction.
  • const and enum are 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, commands or agents service costs the corresponding surface only.
  • A /mcp-diff name 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.
  • warning on a constraint change is a judgement call: a tighter pattern can 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