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 still tests Node 20 + 22, action recipes are unchanged)
• @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 + 72 jest tests across 4 suites.

Follow-up (not in this PR)

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