Migrate to SDK v2 with official Protocol and isolated role peers

[tonxxd]

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"]

Loading

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

Loading

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

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