feat!: 3.0 — major dependency upgrades + MCP draft-spec forward-compat

[SamMorrowDrums]

Stacked on top of #55 (sammorrowdrums/mcp-spec-update-check). Targets that branch so the in-range bumps land first.

Summary

Refresh of the whole dependency tree to land 3.0, plus a forward-compatibility pass on the MCP draft spec (publishes end of month). The probe is hardened so a server upgrading its SDK across MCP spec revisions — 2025-06-18 → 2025-11-25 → draft — produces a clean diff when the public surface is unchanged. SDK v2 is not yet released so we don't take a dependency on it here — that will be a follow-up.

Major dependency bumps

• zod ^3 → ^4 — breaking: z.record now requires (keyType, valueType); the one call site in src/probe.ts (custom-message response schema) was updated to z.record(z.string(), z.unknown()).
• undici ^6 → ^8 — also updates the overrides block (resolves remaining v6 WebSocket advisories on top of chore: in-range dep updates + dist rebuild (supersedes #51) #55).
• diff ^8 → ^9 — no code change required; the package isn't imported directly any more (the diff logic in src/diff.ts is custom).
• @actions/core ^1 → ^3, @actions/exec ^1 → ^3, @actions/io ^1 → ^3
• eslint ^9 → ^10, @eslint/js ^9 → ^10
• typescript ^5 → ^6 — required adding "types": ["node"] to tsconfig.json (TS 6 no longer auto-includes ambient @types/node).
• jest ^29 → ^30, @types/jest ^29 → ^30
• @types/node ^22 → ^24 (CI now tests Node 22 + 24; Node 20 is dropped — see breaking changes below)
• @vercel/ncc ^0.38 → ^0.44
• prettier, eslint-config-prettier, typescript-eslint: latest

Kept at current major:

• ts-jest stays on ^29.4.x — there is no v30 published yet, but 29.4.11 peer-depends on jest ^29 || ^30 and typescript >=4.3 <7, so it works with the new jest + ts.
• @modelcontextprotocol/sdk stays on ^1.13.2 — v2 is not published.

package.json is bumped to 3.0.0-rc.0. dist/ was regenerated via npm run build (never hand-edited).

MCP draft-spec forward-compat

Targets the changes in the draft changelog without depending on SDK v2:

• CacheableResult stripping (SEP-2461). normalizeProbeResult accepts { stripCacheHints } and removes top-level ttlMs / cacheScope from tools/list, prompts/list, resources/list, and resources/templates/list results before snapshotting.
• initialize → server/discover (SEP-2575). Not renaming the snapshot file yet — SDK v2 isn't out. New CANONICAL_SNAPSHOT_NAMES table in probe.ts is wired in now so when the rename happens we map both spellings to the same initialize snapshot file. That way a server moving across the rename shows up as a content diff on one file instead of "removed + added".
• capabilities.extensions (SEP-2589). No code change needed; InitializeInfo.capabilities is Record<string, unknown> with a comment confirming it stays open-ended.
• Deterministic ordering. Already handled; doc comment now notes the draft mandates this.

Cross-spec-version diff cleanliness

This is the larger of the two probe-level changes. During the draft-spec rollout it's completely normal for the base ref to be on 2025-06-18 / 2025-11-25 and the branch to be on the draft. The diff should highlight intentional API surface changes, not protocol churn.

What now gets normalized away before snapshotting (in addition to CacheableResult above):

• _meta protocol plumbing — an exact-key denylist is stripped from every _meta object at any depth: io.modelcontextprotocol/protocolVersion, clientInfo, clientCapabilities, subscriptionId, logLevel. Not by prefix — official extensions live under the same reserved namespace (MCP Apps' _meta.ui per SEP-1865, Tasks' io.modelcontextprotocol/related-task) and must round-trip. An emptied _meta is dropped entirely.
• W3C trace context inside _meta — traceparent, tracestate, baggage (transport-injected for OTel propagation) are stripped from _meta.
• initialize envelope churn — protocolVersion and capabilities.experimental are excluded from the initialize diff body. Drift on those would otherwise dominate every cross-spec diff.

What is not normalized (intentionally):

• serverInfo.version — the SDK version is a legitimate signal worth tracking.
• Nested ttlMs / cacheScope that live inside a tool/prompt/resource definition (those would be part of the public surface, not envelope hints).
• Any _meta key not on the exact denylist above — including the entire MCP Apps surface (_meta.ui) and vendor extensions (x.acme/*, etc.).

Protocol-version capture

The SDK does not expose the negotiated protocol version through a public getter. We attach (or wrap) transport.setProtocolVersion(...) before client.connect(...) — the SDK calls it after a successful initialize. The captured value lands on result.initialize.protocolVersion and is then propagated into TestResult.branchProtocolVersion / baseProtocolVersion in runner.ts. Works for both stdio and HTTP transports.

Reporter banner

When base vs branch negotiated different protocol versions, the report annotates the affected configuration with:

ℹ️ MCP protocol version changed: 2025-11-25 → draft. Protocol-level plumbing is normalized away; any diff below reflects real public-surface changes.

The PR summary surfaces the same drift at the very top, so reviewers immediately know the diff was taken across spec revisions even when the diff body is empty.

Test coverage

src/__tests__/probe.test.ts (new in this PR) covers:

• normalizeProbeResult strip behaviour for ttlMs / cacheScope (top-level only).
• _meta scrubbing of io.modelcontextprotocol/* and W3C trace-context keys, including the "drop empty _meta" path.
• probeResultToFiles strips cache hints for all four list/templates endpoints and leaves initialize intact except for protocolVersion + capabilities.experimental.
• Cross-version cleanliness suite that feeds the same logical server twice — once with a clean envelope (2025-11-25) and once with the draft envelope (CacheableResult + protocol _meta) — and asserts the normalized tools/list and initialize snapshots are byte-identical. A negative test confirms a real tools delta still produces a diff.

src/__tests__/reporter.test.ts (extended): unit tests for formatProtocolVersionBanner (null when versions match / either side unknown, formatted when they differ) and integration tests asserting both the markdown report and the PR summary surface the banner.

npm run check passes — typecheck + lint + prettier + 96 jest tests across 7 suites (including the folded-in #60 metadata-diff coverage and the #58 runner / reporter / config-missing tests).

Breaking changes — runtime

• Drops Node.js 20 support. Node 20 reached LTS end-of-life on 2026-04-30 and undici v8 (the version this PR bumps to) requires Node 22+ — it calls webidl.util.markAsUncloneable, only present on Node 21+. The CI matrix is now [22, 24] (current LTS + current Current). package.json declares "engines": { "node": ">=22" }. The action's setup_node input defaults to 22 (was 20); workflows passing an explicit node_version of 20 should bump to 22 or newer.

Folded-in PRs (closing on merge)

• Closes test: cover tool metadata diffs #60 — test: cover tool metadata diffs (@kigland). First direct unit tests for the diff engine (compareProbeResults): asserts tool-level description changes AND nested inputSchema.properties.<arg>.description changes both surface under the tools endpoint diff. Zero production-code change, applied clean.

• Fixes One-sided startup failure should show a fail on that side and a full diff against empty on the other #57 (closes feat: diff one-sided startup failures against an empty baseline #58) — feat: diff one-sided startup failures against an empty baseline. When exactly one side fails to start (e.g. a PR introduces a new server configuration behind a CLI flag that doesn't exist on the compare ref), the failed side is now treated as an empty ProbeResult and the working side's full surface renders as added/removed instead of collapsing to an opaque Connection closed error. New config-missing diff category, non-fatal under fail_on_error (only genuine both-sides probe failures still hard-error). New compareConfigResults() exported from runner.ts for unit testability. Reporter classifies into passing / changed / config-missing / error and renders a dedicated 🚫 callout in both the markdown report and PR summary. Adds configMissing?: { side, error } to TestResult. The 2.4.0 version bump from the original PR was dropped (3.0 already moved to 3.0.0-rc.0).

Conflict resolution notes (for the #58 fold)

The only non-trivial conflict was in src/reporter.ts: both PR #56 (this branch) and PR #58 added new pre-diff renderer blocks to generateMarkdownReport. Resolved by keeping BOTH — the protocol-version banner renders first (cross-spec drift heads-up), then the config-missing callout (if applicable), then the existing diff section. Same change applied to generatePRSummary. No semantic conflict; both features render independently into the same lines array.

Follow-up (not in this PR)

• Add a check for the server-card endpoint once the SEP lands (issue Reminder to add server card #65).
• Adopt @modelcontextprotocol/sdk v2 once released, switch the SDK call from initialize to server/discover, and re-evaluate whether client.getProtocolVersion() lands publicly so we can drop the transport-hook trick.

Notes

• This PR is draft and targets sammorrowdrums/mcp-spec-update-check. Once chore: in-range dep updates + dist rebuild (supersedes #51) #55 merges into main, retarget this PR to main (or merge chore: in-range dep updates + dist rebuild (supersedes #51) #55 first, then rebase).

Follow-up: MCP Apps + extension preservation (commit 8181d45)

Caught a regression in my own _meta scrubber before merge: the original implementation matched io.modelcontextprotocol/* by prefix, which would silently delete the entire MCP Apps surface (_meta.ui per SEP-1865) and Tasks' io.modelcontextprotocol/related-task. Flipped to an exact-key denylist so transport plumbing is stripped but extension surfaces round-trip.

Also widened ToolsResult / PromptsResult / ResourcesResult / ResourceTemplatesResult element types with index signatures so annotations, outputSchema, _meta, and MCP Apps fields are first-class at the type level (they were already captured at runtime — the types just understated it).

New kitchen-sink test in src/__tests__/probe.test.ts round-trips a tool with annotations + outputSchema + _meta.ui, a UI resource with the full MCP Apps _meta.ui shape (CSP connectDomains / resourceDomains / frameDomains / baseUriDomains, permissions), prompt arguments, and a resource template — every advertised field has to survive normalization. 74 tests pass.

[Copilot]

Pull request overview

This PR prepares mcp-server-diff for a 3.0 release by upgrading major dependencies and updating the probe/reporting pipeline to remain forward-compatible with upcoming MCP draft-spec changes, with an emphasis on producing clean diffs across spec revisions.

Changes:

• Major dependency upgrades (TypeScript 6, Jest 30, Zod 4, Undici 8, Actions toolkit v3, ESLint 10) and regenerated dist/.
• Added stateless server/discover probing with normalization to strip protocol-shaped noise (_meta plumbing, CacheableResult hints, tool-annotation defaults) and canonicalize snapshot naming.
• Added/extended tests and documentation covering cross-spec diff cleanliness and protocol-version drift banners.

Show a summary per file

File	Description
tsconfig.json	Adds types: ["node"] for TS6 ambient node typings behavior.
src/types.ts	Widens probe result types for forward-compatible fields; adds protocol version fields to results.
src/runner.ts	Plumbs negotiated protocol versions into TestResult for reporting.
src/reporter.ts	Adds protocol-version drift banners in markdown report and PR summary.
src/probe.ts	Implements server/discover stateless probing, protocol-version capture hook, and normalization/canonical snapshot behavior.
src/tests/reporter.test.ts	Adds unit/integration coverage for protocol-version banner formatting and placement.
src/tests/probe.test.ts	Adds extensive normalization + cross-spec cleanliness + regression test coverage.
src/tests/fixtures/github-mcp-server-wire.json	Adds real-wire fixture data for initialize vs discover cross-version normalization tests.
README.md	Documents 3.0 migration notes and cross-spec-version diffing behavior.
package.json	Bumps package version to 3.0.0-rc.0 and upgrades major dependency versions.
dist/types.d.ts	Regenerated types reflecting updated source interfaces.
dist/reporter.d.ts	Regenerated declarations including protocol banner API.
dist/probe.d.ts	Regenerated declarations including discover probing + canonical snapshot naming exports.
dist/licenses.txt	Updated bundled license attributions from rebuild.
dist/cli/types.d.ts	Regenerated CLI types reflecting updated source interfaces.
dist/cli/reporter.d.ts	Regenerated CLI declarations including protocol banner API.
dist/cli/probe.d.ts	Regenerated CLI declarations including discover probing + canonical snapshot naming exports.
dist/cli/licenses.txt	Updated bundled CLI license attributions from rebuild.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 9/19 changed files
• Comments generated: 1
• Review effort level: Low

[Copilot]

Review details

• Files reviewed: 12/22 changed files
• Comments generated: 3
• Review effort level: Low

[Copilot]

Review details

Comments suppressed due to low confidence (1)

src/probe.ts:518

• probeViaInitialize still identifies as version "2.0.0" while the stateless path sends PROBE_CLIENT_INFO.version "3.0". This makes the client identity inconsistent across probe paths and could affect server behavior and/or show up in protocol metadata (even if normalized away). Use the shared PROBE_CLIENT_INFO version to keep both paths aligned.

  const client = new Client(
    {
      name: "mcp-server-diff-probe",
      version: "2.0.0",
    },

• Files reviewed: 12/22 changed files
• Comments generated: 2
• Review effort level: Low

[Copilot]

Review details

• Files reviewed: 12/22 changed files
• Comments generated: 1
• Review effort level: Low