Export Protocol and mergeCapabilities from client/server package roots

.changeset/export-protocol-class.md

@@ -0,0 +1,14 @@
+---
+'@modelcontextprotocol/core-internal': minor
+'@modelcontextprotocol/client': minor
+'@modelcontextprotocol/server': minor
+'@modelcontextprotocol/codemod': patch
+---
+
+Export the `Protocol` base class and `mergeCapabilities` from the `@modelcontextprotocol/client` and `@modelcontextprotocol/server` package roots.
+
+Some SDK consumers build their own JSON-RPC protocols on the `Protocol` engine rather than speaking MCP itself — ext-apps (MCP Apps) runs its `ui/initialize` handshake over an iframe postMessage channel this way. Subclassing `Client`/`Server` forces the core MCP `initialize` handshake onto such channels, which their deployed peers do not understand. Exporting `Protocol` restores the v1 extension point: `Protocol.connect()` wires the transport without any handshake, and non-spec methods pass through the wire layer without era gating.
+
+The supporting protocol types (`ProtocolOptions`, `BaseContext`, `RequestOptions`, `Transport`, …) were already public.
+
+The codemod now rewrites `Protocol` and `mergeCapabilities` imports from `shared/protocol.js` to the client or server package root, like the module's other symbols, instead of dropping them with an action-required marker.

CLAUDE.md

@@ -68,7 +68,7 @@ The SDK is organized into three main layers:
 The SDK separates internal code from the public API surface:
 
 - **`@modelcontextprotocol/core-internal`** (main entry, `packages/core-internal/src/index.ts`) — Internal barrel. Exports everything (including Zod schemas, Protocol class, stdio utils). Only consumed by sibling packages within the monorepo (`private: true`).
-- **`@modelcontextprotocol/core-internal/public`** (`packages/core-internal/src/exports/public/index.ts`) — Curated public API. Exports only TypeScript types, error classes, constants, and guards. Re-exported by client and server packages.
+- **`@modelcontextprotocol/core-internal/public`** (`packages/core-internal/src/exports/public/index.ts`) — Curated public API. Exports TypeScript types, error classes, constants, guards, and the `Protocol` base class (+ `mergeCapabilities`) for consumers that build custom JSON-RPC protocols on the engine. Re-exported by client and server packages.
 - **`@modelcontextprotocol/client`** and **`@modelcontextprotocol/server`** (`packages/*/src/index.ts`) — Final public surface. Package-specific exports (named explicitly) plus re-exports from `core-internal/public`.
 - **`@modelcontextprotocol/core`** (`packages/core/src/index.ts`) — Public Zod-schema package and the canonical home of the schema source modules (`src/schemas.ts`, `src/auth.ts`, `src/constants.ts`). The root entry re-exports **only** the `*Schema` Zod constants (MCP spec + OAuth/OpenID) — the published home for raw runtime validation (`CallToolResultSchema.parse(...)`); runtime-neutral (`zod` is its only dependency). The `./internal` subpath re-exports the schema modules wholesale for the sibling packages: `core-internal` re-exports them at the old module paths, and the `client`/`server`/`server-legacy` bundles resolve `@modelcontextprotocol/core/internal` as a real external dependency instead of carrying their own schema copies (their public surfaces stay Zod-free).
 

docs/migration/upgrade-to-v2.md

@@ -108,9 +108,9 @@
   `completable(schema, cb).optional()` (see
   [Standard Schema objects](#standard-schema-objects-raw-shapes-deprecated)); shapes it
   cannot invert get an `@mcp-codemod-error` marker.
-- Drops `Protocol` / `mergeCapabilities` from `shared/protocol.js` imports, re-exports,
-  mocks, and dynamic imports — no v2 package exports them — leaving a marker with the
-  replacement at each site.
+- Rewrites `Protocol` / `mergeCapabilities` imports from `shared/protocol.js` to the
+  client or server package root, like the module's other symbols (see
+  [Removed type aliases](#removed-type-aliases) for the subclass shape changes).
 
 ## What the codemod does NOT handle
 
@@ -1444,13 +1444,26 @@
 objects. A payload typed `Record<string, unknown>` no longer assigns (`TS2322`) — give
 the source a JSON-compatible type or cast at the boundary.
 
-The `Protocol` base class itself is no longer exported (it is internal engine). If you
-were reaching into protocol internals — rare, mostly debugging tools —
-`client.fallbackRequestHandler` / `server.fallbackRequestHandler` receives every
-inbound request that no registered handler matches, before capability gating. Delete
-the v1 `shared/protocol.js` import: `Protocol` has no v2 import path. The codemod
-drops `Protocol` (and `mergeCapabilities`) from the rewritten import and leaves an
-`@mcp-codemod-error` marker at the site explaining the replacement.
+The `Protocol` base class and `mergeCapabilities` moved: import them from the
+`@modelcontextprotocol/client` or `@modelcontextprotocol/server` package root instead
+of `shared/protocol.js`. Extending `Protocol` directly remains the right shape for
+consumers that run their own JSON-RPC protocol on the SDK engine (custom methods, own
+handshake) — `Protocol.connect()` wires the transport without performing the MCP
+`initialize` handshake. Subclasses adapt to the v2 shape: one `ContextT` type
+parameter instead of the three message generics, a `buildContext` implementation
+(identity is fine), and method-string-keyed handler registration (see
+[`setRequestHandler` / `setNotificationHandler` use method strings](#setrequesthandler--setnotificationhandler-use-method-strings)). If you
+were only reaching into protocol internals for
+debugging, prefer `client.fallbackRequestHandler` / `server.fallbackRequestHandler`,
+which receives every inbound request that no registered handler matches, before
+capability gating. The codemod rewrites `Protocol` and `mergeCapabilities` imports to
+the package root, like the module's other symbols.
+
+One caveat: the client and server packages each bundle their own compiled copy of the
+class, so the two roots' `Protocol` exports are distinct classes. Import it from one
+package consistently within a process — `instanceof` returns `false` across the two
+copies, and their type declarations are nominally incompatible (the class has private
+members).
 
 #### JSON Schema 2020-12 posture (SEP-1613, SEP-2106)
 

packages/client/test/client/protocolExport.test.ts

@@ -0,0 +1,17 @@
+/**
+ * Pins that the `Protocol` base class and `mergeCapabilities` are exported from
+ * the package ROOT — not just from the core-internal public barrel. The root's
+ * `export * from '@modelcontextprotocol/core-internal/public'` is what carries
+ * them; replacing it with named exports (or adding a colliding explicit export)
+ * would silently drop them while the barrel-level pin stays green.
+ */
+import { describe, expect, test } from 'vitest';
+
+import { mergeCapabilities, Protocol } from '../../src/index';
+
+describe('package root exports', () => {
+    test('Protocol and mergeCapabilities are exported from the client root', () => {
+        expect(typeof Protocol).toBe('function');
+        expect(typeof mergeCapabilities).toBe('function');
+    });
+});

packages/codemod/README.md

@@ -42,8 +42,8 @@ guards that mix the two enums), add `import { z } from 'zod'` when a wrap needs
 it, rewrite `vi.mock`
 / `jest.mock` / dynamic `import()` paths, invert optional completable nesting
 (`completable(schema.optional(), cb)` becomes `completable(schema, cb).optional()`),
-and drop `Protocol` / `mergeCapabilities` (no v2 export) with an action-required
-marker naming the replacement.
+and rewrite `Protocol` / `mergeCapabilities` imports from `shared/protocol.js` to the
+client or server package root.
 
 ## `@mcp-codemod-error` markers
 

packages/codemod/src/migrations/v1-to-v2/mappings/importMap.ts

@@ -171,20 +171,10 @@
             ResourceTemplate: 'ResourceTemplateType'
         }
     },
     '@modelcontextprotocol/sdk/shared/protocol.js': {
         target: 'RESOLVE_BY_CONTEXT',
-        status: 'moved',
-        removedSymbols: {
-            Protocol:
-                'The Protocol base class is not exported by the v2 packages. To observe or handle inbound requests ' +
-                'that have no registered handler, use client.fallbackRequestHandler / server.fallbackRequestHandler; ' +
-                'build custom behavior on Client or Server instead of subclassing Protocol. ' +
-                'See the migration guide: Behavioral changes > Client connection & dispatch.',
-            mergeCapabilities:
-                'mergeCapabilities() is not exported by the v2 packages. Pass the complete capabilities object to the ' +
-                'Client/Server constructor, or merge capability objects with a plain object spread.'
-        }
+        status: 'moved'
     },
     '@modelcontextprotocol/sdk/shared/transport.js': {
         target: 'RESOLVE_BY_CONTEXT',
         status: 'moved'

packages/codemod/src/migrations/v1-to-v2/transforms/importPaths.ts

@@ -225,9 +225,9 @@ export const importPathsTransform: Transform = {
                         );
                     }
                 }
-                // Qualified accesses to symbols with no v2 export (`ns.Protocol`) can't be fixed by
+                // Qualified accesses to symbols with no v2 export (`ns.GoneClass`) can't be fixed by
                 // moving the namespace binding — flag each accessed one. Expression positions are
-                // PropertyAccessExpressions; type positions (`let p: ns.Protocol`) are QualifiedNames.
+                // PropertyAccessExpressions; type positions (`let p: ns.GoneClass`) are QualifiedNames.
                 if (mapping.removedSymbols) {
                     const nsName = namespaceImport.getText();
                     const accessedRemoved = new Map<string, Node>();