Demo: migrate to SDK v2 by extending the Protocol base class

[felixweinberger]

Demonstration of the Protocol-based v2 migration discussed in #710 — built directly on top of #710's commits (thanks @khandrew1, the package/schema/zod migration there carries this branch). Draft: depends on modelcontextprotocol/typescript-sdk#2501, pinned here via its pkg.pr.new preview builds.

Motivation and Context

#710 subclasses the v2 Client/Server roles, which puts a core MCP initialize handshake on the iframe channel before ui/initialize. Deployed hosts don't recognize a view-initiated initialize and reject it, so new views would break existing hosts.

typescript-sdk#2501 exports the Protocol base class from the client/server package roots. Protocol.connect() performs no handshake, so App and AppBridge can extend it directly — same shape as v1 — and the wire contract stays exactly v1: ui/initialize is the first and only handshake. Existing hosts keep working unchanged.

Compared to #710's head this removes the inner-handshake machinery entirely (−61 lines): the pinned inner protocol version, the contentless inner capabilities and their retro-registration, the oninitialized property shadowing, and the getCapabilities/getHostCapabilities split (v1 getCapabilities restored).

One behavior note: host-side tools/call result validation from the base Server is gone — as in v1, results are validated on the App side (CallToolResultSchema), so malformed host results surface as parse errors in the view.

How Has This Been Tested?

• Unit suite: 302 tests pass; new tests pin the wire order ["ui/initialize", "ui/notifications/initialized"] and assert no initialize/notifications/initialized is sent in either direction.
• Built dist driven end-to-end (App ↔ AppBridge over a linked transport pair): handshake, View-ready gate, and proxied tools/call all work with only ui/* methods on the wire.
• Bundle size (app-with-deps.js): 337 KB on v1 → 422 KB here → 482 KB on Migrate ext-apps to @modelcontextprotocol/server v2 SDK #710's head.

Breaking Changes

None relative to v1 wire behavior — that's the point. Relative to #710 (unreleased): AppBridge.getHostCapabilities() is folded back into getCapabilities(), and the inner MCP handshake no longer happens.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

The SDK packages are pinned to the pkg.pr.new preview builds of typescript-sdk#2501, so npm i works on a checkout — but the lockfile-hygiene CI check (registry.npmjs.org-only resolved URLs) is expected to fail until that PR ships in a published beta. Once it does, the three specs in package.json (devDependencies + overrides) become exact registry versions and CI should go green. Happy for this to be folded into #710 rather than land separately.

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/ext-apps

npm i https://pkg.pr.new/@modelcontextprotocol/ext-apps@712

@modelcontextprotocol/server-basic-preact

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-preact@712

@modelcontextprotocol/server-basic-react

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-react@712

@modelcontextprotocol/server-basic-solid

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-solid@712

@modelcontextprotocol/server-basic-svelte

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-svelte@712

@modelcontextprotocol/server-basic-vanillajs

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-vanillajs@712

@modelcontextprotocol/server-basic-vue

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-vue@712

@modelcontextprotocol/server-budget-allocator

npm i https://pkg.pr.new/@modelcontextprotocol/server-budget-allocator@712

@modelcontextprotocol/server-cohort-heatmap

npm i https://pkg.pr.new/@modelcontextprotocol/server-cohort-heatmap@712

@modelcontextprotocol/server-customer-segmentation

npm i https://pkg.pr.new/@modelcontextprotocol/server-customer-segmentation@712

@modelcontextprotocol/server-debug

npm i https://pkg.pr.new/@modelcontextprotocol/server-debug@712

@modelcontextprotocol/server-lazy-auth

npm i https://pkg.pr.new/@modelcontextprotocol/server-lazy-auth@712

@modelcontextprotocol/server-map

npm i https://pkg.pr.new/@modelcontextprotocol/server-map@712

@modelcontextprotocol/server-pdf

npm i https://pkg.pr.new/@modelcontextprotocol/server-pdf@712

@modelcontextprotocol/server-scenario-modeler

npm i https://pkg.pr.new/@modelcontextprotocol/server-scenario-modeler@712

@modelcontextprotocol/server-shadertoy

npm i https://pkg.pr.new/@modelcontextprotocol/server-shadertoy@712

@modelcontextprotocol/server-sheet-music

npm i https://pkg.pr.new/@modelcontextprotocol/server-sheet-music@712

@modelcontextprotocol/server-system-monitor

npm i https://pkg.pr.new/@modelcontextprotocol/server-system-monitor@712

@modelcontextprotocol/server-threejs

npm i https://pkg.pr.new/@modelcontextprotocol/server-threejs@712

@modelcontextprotocol/server-transcript

npm i https://pkg.pr.new/@modelcontextprotocol/server-transcript@712

@modelcontextprotocol/server-video-resource

npm i https://pkg.pr.new/@modelcontextprotocol/server-video-resource@712

@modelcontextprotocol/server-wiki-explorer

npm i https://pkg.pr.new/@modelcontextprotocol/server-wiki-explorer@712

commit: 432d42b