Migrate to SDK v2 with official Protocol and isolated role peers by tonxxd · Pull Request #720 · modelcontextprotocol/ext-apps

tonxxd · 2026-07-20T18:43:44Z

Summary

This PR brings @khandrew1's SDK v2 migration from #710 upstream together with Felix's public-Protocol port and the role-isolated optional peers alternative.

Problem

The migration to SDK v2 makes both role packages peers of one ext-apps package. A server entry point also imported constants through app.ts, creating a server → app → client edge.

flowchart LR
  Consumer["server-only consumer"] --> ServerEntry["ext-apps/server"]
  ServerEntry --> App["app.js"]
  App --> Client["@modelcontextprotocol/client"]
  ServerEntry --> Server["@modelcontextprotocol/server"]

Proposed architecture

This alternative reuses the official public Protocol base while isolating each entry point to its matching optional role peer.

flowchart TB
  subgraph ClientSide["App / host entry points"]
    AppEntry[". / react"] -. "optional peer" .-> Client["@modelcontextprotocol/client"]
    BridgeEntry["app-bridge"] -. "optional peer" .-> Client
  end

  subgraph ServerSide["Server entry point"]
    ServerEntry["server"] -. "optional peer" .-> Server["@modelcontextprotocol/server"]
  end

  AppEntry --> Core["@modelcontextprotocol/core"]
  BridgeEntry --> Core
  ServerEntry --> Core

Consumer	Installs	Does not install or bundle
App / host	ext-apps + client + core	server
MCP server	ext-apps + server + core	client

Implementation

Preserves @khandrew1's v2 migration.
Ports App and AppBridge to the official Protocol<BaseContext>.
Preserves the Apps-only ui/initialize handshake used by v1 hosts.
Moves resource constants and shared core wire types into neutral modules.
Marks client and server peers optional.
Adds packed app/host-only and server-only compile/install/bundle assertions.
Clears dist before builds so stale role edges cannot enter published packages.

SDK package status

The public Protocol export from typescript-sdk#2501 is published in @modelcontextprotocol/client@2.0.0-beta.5.

This branch now uses the complete registry-published beta.5 package set (client, core, server, express, and node). The temporary pkg.pr.new specifications and MCP overrides have been removed, and the lockfile contains only npmjs.org HTTP(S) package resolutions.

Tradeoff

This keeps request lifecycle, cancellation, validation, and transport behavior in the official SDK. Consumers still install the one role package used by their entry point. The core-only alternative in #719 avoids both role packages but owns more protocol code in ext-apps.

Verification

npm run build
npm run build:all
npm test: 392 passed, 1 skipped
npm run test:dependency-isolation
TypeDoc validation with warnings treated as errors
Prettier, version consistency, and git diff --check
Registry-only lockfile invariant used by CI
Functional integration-server E2E: 5 passed

Replaces the Client/Server subclassing from the v2 migration with direct Protocol extension, now that the SDK exports Protocol from the client package root. This restores the v1 wire contract on the iframe channel: ui/initialize is the first and only handshake, so deployed hosts keep working unchanged. Deleted with the double handshake: the inner MCP initialize round-trip and its pinned protocol version, the contentless inner capabilities and their retro-registration plumbing, the oninitialized defineProperty shadow, and the getCapabilities/getHostCapabilities split (v1 getCapabilities restored). Tests pin the wire order and assert no MCP initialize is sent in either direction. Note: package.json overrides point the SDK packages at locally built tarballs carrying the Protocol export; replace with published versions before any upstream PR.

The Protocol-based migration needs the Protocol class exported from the package roots, which lands in modelcontextprotocol/typescript-sdk#2501. Pin the preview builds so the branch is installable; swap to the next published beta once that PR is released.

Copilot

Pull request overview

This PR migrates @modelcontextprotocol/ext-apps to the split MCP SDK v2 packages while switching the Apps iframe channel to the official public Protocol base (preserving the v1 ui/initialize-first wire contract) and enforcing role-isolated optional peers for client/server dependencies.

Changes:

Ports App/AppBridge and transports/types to v2 split packages (@modelcontextprotocol/{client,core,server}) and updates related tests/snippets.
Moves shared wire types/constants into role-neutral modules and updates server helpers accordingly.
Adds dependency-isolation verification and improves TypeDoc linking to base SDK docs.

Reviewed changes

Copilot reviewed 122 out of 125 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
typedoc.config.mjs	Adds base-SDK external symbol link mapping + plugin.
src/types.ts	Removes protocol-wide union types; keeps re-exports.
src/spec.types.ts	Switches shared type imports to role-neutral core-types.
src/server/index.ts	Removes server→app edge; updates schemas/types to v2.
src/server/index.test.ts	Updates server type import to v2 package.
src/server/index.examples.ts	Updates examples to v2 server imports + zod objects.
src/react/useApp.tsx	Updates Implementation type import to v2 client package.
src/message-transport.ts	Moves JSONRPC schema to core; transport types to client.
src/message-transport.test.ts	Updates JSONRPCMessage type import to v2 client package.
src/generated/schema.ts	Updates MCP schema imports from sdk to core.
src/generated/schema.json	Regenerated JSON schema reflecting new schema typing.
src/events.ts	Refactors to protocol-independent EventDispatcher with warnings.
src/events.test.ts	Adds unit coverage for EventDispatcher behavior.
src/core-types.ts	New: role-neutral shared types inferred from core schemas.
src/constants.ts	New: role-neutral resource metadata constants.
src/app.ts	Migrates App to Protocol base; updates handlers/capabilities/events.
src/app.test.ts	New tests pin iframe handshake order + v2 Protocol behavior.
src/app.examples.ts	Updates examples to split v2 client/server types.
src/app-bridge.test.ts	Updates to v2 packages; adds handshake/validation/proxy tests.
src/app-bridge.examples.ts	Updates examples to v2 packages + new context signal shape.
scripts/typedoc-plugin-base-sdk-links.mjs	New TypeDoc resolver for base-SDK local refs.
scripts/generate-schemas.ts	Updates schema generator commentary/import rewrite to core.
scripts/check-dependency-isolation.mjs	New packed install/compile/bundle role-isolation check.
README.md	Updates install guidance to split v2 packages.
plugins/mcp-apps/skills/create-mcp-app/SKILL.md	Updates dependency guidance for v2 split packages.
plugins/mcp-apps/skills/convert-web-app/SKILL.md	Updates migration instructions/snippets for v2 APIs.
plugins/mcp-apps/skills/add-app-to-server/SKILL.md	Updates setup + code samples for v2 APIs.
package.json	Switches to split v2 peer deps + adds isolation test script.
package-lock.json	Updates lockfile for split v2 packages + examples.
examples/wiki-explorer-server/src/mcp-app.ts	Updates CallToolResult typing import to v2 client package.
examples/wiki-explorer-server/server.ts	Updates server types/imports to v2 server package.
examples/wiki-explorer-server/package.json	Adds split v2 dependencies.
examples/wiki-explorer-server/main.ts	Updates transports to v2 express/node/server packages.
examples/video-resource-server/src/mcp-app.ts	Updates CallToolResult typing import to v2 client package.
examples/video-resource-server/server.ts	Updates server types/imports + input schema to z.object.
examples/video-resource-server/package.json	Adds split v2 dependencies.
examples/video-resource-server/main.ts	Updates transports to v2 express/node/server packages.
examples/transcript-server/server.ts	Updates server imports + uses z.object({}) inputSchema.
examples/transcript-server/package.json	Adds split v2 dependencies.
examples/transcript-server/main.ts	Updates transports to v2 express/node/server packages.
examples/threejs-server/src/mcp-app-wrapper.tsx	Updates CallToolResult typing import to v2 client package.
examples/threejs-server/server.ts	Updates server imports + uses z.object({}) inputSchema.
examples/threejs-server/package.json	Adds split v2 dependencies.
examples/threejs-server/main.ts	Updates transports to v2 express/node/server packages.
examples/system-monitor-server/server.ts	Updates server imports + outputSchema uses full Zod schema.
examples/system-monitor-server/package.json	Adds split v2 dependencies.
examples/system-monitor-server/main.ts	Updates transports to v2 express/node/server packages.
examples/sheet-music-server/server.ts	Updates server imports to v2 server package.
examples/sheet-music-server/package.json	Adds split v2 dependencies.
examples/sheet-music-server/main.ts	Updates transports to v2 express/node/server packages.
examples/shadertoy-server/server.ts	Updates server imports to v2 server package.
examples/shadertoy-server/package.json	Adds split v2 dependencies.
examples/shadertoy-server/main.ts	Updates transports to v2 express/node/server packages.
examples/scenario-modeler-server/server.ts	Updates imports + uses full Zod schemas (not `.shape`).
examples/scenario-modeler-server/package.json	Adds split v2 dependencies.
examples/scenario-modeler-server/main.ts	Updates transports to v2 express/node/server packages.
examples/say-server/package.json	Removes sdk v1 dependency from python example package.json.
examples/quickstart/server.ts	Updates server import + uses z.object({}) inputSchema.
examples/quickstart/package.json	Adds split v2 dependencies.
examples/quickstart/main.ts	Updates transports to v2 express/node/server packages.
examples/qr-server/package.json	Removes sdk v1 dependency from python example package.json.
examples/pdf-server/src/mcp-app.ts	Updates CallToolResult/ContentBlock imports to v2 client package.
examples/pdf-server/server.ts	Updates server imports + requestId/signal usage to v2 context.
examples/pdf-server/server.test.ts	Updates in-memory client imports to v2 client package.
examples/pdf-server/package.json	Adds split v2 dependencies.
examples/pdf-server/main.ts	Updates transports to v2 express/node/server packages.
examples/map-server/src/mcp-app.ts	Updates ContentBlock typing import to v2 client package.
examples/map-server/server.ts	Updates server imports + uses z.object for schemas.
examples/map-server/package.json	Adds split v2 dependencies.
examples/map-server/main.ts	Updates transports to v2 express/node/server packages.
examples/lazy-auth-server/server.ts	Updates to v2 server/node + z.object({}) schemas + context id.
examples/lazy-auth-server/package.json	Adds split v2 dependencies.
examples/integration-server/src/mcp-app.tsx	Updates CallToolResult typing import to v2 client package.
examples/integration-server/server.ts	Updates server imports + uses z.object({}) inputSchema.
examples/integration-server/package.json	Adds split v2 dependencies.
examples/integration-server/main.ts	Updates transports to v2 express/node/server packages.
examples/debug-server/server.ts	Updates server imports to v2 server package.
examples/debug-server/package.json	Adds split v2 dependencies.
examples/debug-server/main.ts	Updates transports to v2 express/node/server packages.
examples/customer-segmentation-server/server.ts	Updates imports + uses full Zod schemas (not `.shape`).
examples/customer-segmentation-server/package.json	Adds split v2 dependencies.
examples/customer-segmentation-server/main.ts	Updates transports to v2 express/node/server packages.
examples/cohort-heatmap-server/server.ts	Updates imports + uses full Zod schemas (not `.shape`).
examples/cohort-heatmap-server/package.json	Adds split v2 dependencies.
examples/cohort-heatmap-server/main.ts	Updates transports to v2 express/node/server packages.
examples/budget-allocator-server/server.ts	Updates imports + uses z.object({}) inputSchema.
examples/budget-allocator-server/package.json	Adds split v2 dependencies.
examples/budget-allocator-server/main.ts	Updates transports to v2 express/node/server packages.
examples/basic-server-vue/src/App.vue	Updates CallToolResult typing import to v2 client package.
examples/basic-server-vue/server.ts	Updates imports + uses z.object({}) inputSchema.
examples/basic-server-vue/package.json	Adds split v2 dependencies.
examples/basic-server-vue/main.ts	Updates transports to v2 express/node/server packages.
examples/basic-server-vanillajs/src/mcp-app.ts	Updates CallToolResult typing import to v2 client package.
examples/basic-server-vanillajs/server.ts	Updates imports + uses z.object({}) inputSchema.
examples/basic-server-vanillajs/package.json	Adds split v2 dependencies.
examples/basic-server-vanillajs/main.ts	Updates transports to v2 express/node/server packages.
examples/basic-server-svelte/src/App.svelte	Updates CallToolResult typing import to v2 client package.
examples/basic-server-svelte/server.ts	Updates imports + uses z.object({}) inputSchema.
examples/basic-server-svelte/package.json	Adds split v2 dependencies.
examples/basic-server-svelte/main.ts	Updates transports to v2 express/node/server packages.
examples/basic-server-solid/src/mcp-app.tsx	Updates CallToolResult typing import to v2 client package.
examples/basic-server-solid/server.ts	Updates imports + uses z.object({}) inputSchema.
examples/basic-server-solid/package.json	Adds split v2 dependencies.
examples/basic-server-solid/main.ts	Updates transports to v2 express/node/server packages.
examples/basic-server-react/src/mcp-app.tsx	Updates CallToolResult typing import to v2 client package.
examples/basic-server-react/server.ts	Updates imports + uses z.object({}) inputSchema.
examples/basic-server-react/package.json	Adds split v2 dependencies.
examples/basic-server-react/main.ts	Updates transports to v2 express/node/server packages.
examples/basic-server-preact/src/mcp-app.tsx	Updates CallToolResult typing import to v2 client package.
examples/basic-server-preact/server.ts	Updates imports + uses z.object({}) inputSchema.
examples/basic-server-preact/package.json	Adds split v2 dependencies.
examples/basic-server-preact/main.ts	Updates transports to v2 express/node/server packages.
examples/basic-host/src/index.tsx	Updates Tool type import to v2 client package.
examples/basic-host/src/implementation.ts	Updates client + transports imports to v2 client package.
examples/basic-host/package.json	Updates base SDK dependency to v2 client package.
docs/testing-mcp-apps.md	Adds guidance about build/snippet type-checking.
docs/quickstart.md	Updates Node requirement + dependencies/snippets to v2.
docs/patterns.tsx	Updates imports and example code to v2 APIs.
docs/patterns.md	Updates patterns snippets for v2 schema + request usage.
docs/overview.md	Updates architecture/lifecycle explanation for v2 approach.
docs/migrate_from_openai_apps.md	Updates McpServer import + zod object schema examples.
docs/authorization.md	Updates schema example to `z.object(...)`.
build.bun.ts	Clears dist before build; updates externals to split peers.
AGENTS.md	Updates architecture docs for Protocol-based iframe channel.

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

+npm install -S @modelcontextprotocol/ext-apps \
+  @modelcontextprotocol/client@2.0.0-beta.4 \
+  @modelcontextprotocol/server@2.0.0-beta.4 \
+  @modelcontextprotocol/core@2.0.0-beta.4 \
+  zod@^4.2.0


khandrew1 and others added 10 commits July 14, 2026 13:35

chore: prepare SDK v2 dependencies

b383847

refactor: compose protocol-neutral event dispatch

209cfc6

refactor: migrate App to SDK v2 client

59e6ffc

refactor: migrate AppBridge to SDK v2 server

d19a1fb

refactor: migrate shared SDK surfaces to v2

a76e3a7

refactor: finish MCP SDK v2 migration

f94cb38

fix: regenerate lockfile for npm 10

f50ec6e

test: isolate optional SDK role dependencies

7664bb1

tonxxd mentioned this pull request Jul 20, 2026

Migrate to SDK v2 with a core-only Apps protocol #719

Draft

idosal requested a review from Copilot July 22, 2026 15:05

Copilot started reviewing on behalf of idosal July 22, 2026 15:05 View session

Copilot AI reviewed Jul 22, 2026

View reviewed changes

tonxxd added 2 commits July 22, 2026 15:24

chore: update MCP SDK packages to beta.5

e7ffe7c

docs: align Protocol and role-specific setup

c847bc0

tonxxd mentioned this pull request Jul 22, 2026

chore: replace MCP v2 preview dependencies mcp-use/mcp-use#1971

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Migrate to SDK v2 with official Protocol and isolated role peers#720

Migrate to SDK v2 with official Protocol and isolated role peers#720
tonxxd wants to merge 12 commits into
modelcontextprotocol:mainfrom
tonxxd:fix/official-protocol-role-peers

tonxxd commented Jul 20, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

tonxxd commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Problem

Proposed architecture

Implementation

SDK package status

Tradeoff

Verification

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

tonxxd commented Jul 20, 2026 •

edited

Loading