SDK v2 migration (behavior-neutral, versionNegotiation: 'legacy') (#1624)

Migrate all three clients + core + test-servers from
@modelcontextprotocol/sdk@1.29 to SDK v2 (2.0.0-beta.4), keeping behavior
identical against legacy (2025-11-25) servers. Foundation for the SDK V2 +
New Spec stack.

Packages
- Split @modelcontextprotocol/sdk -> @modelcontextprotocol/client (Client,
  transports, OAuth, error taxonomy, protocol types) + core (Zod schemas);
  stdio -> client/stdio, Ajv -> client/validators/ajv. Test-servers ->
  @modelcontextprotocol/server (+ server-legacy/sse). Deterministic import
  rewrite (schemas -> core, everything else -> client); the codemod misroutes
  client code to /server so it was not used for path routing.
- new Client(..., { versionNegotiation: { mode: 'legacy' } }) — nothing
  2026-era goes on the wire.

Runtime (core/mcp/inspectorClient.ts)
- Error taxonomy: McpError -> ProtocolError, ErrorCode -> ProtocolErrorCode;
  RequestTimeout -> SdkError/SdkErrorCode.
- Handlers take method strings; task methods (tasks/*, notifications/tasks/*)
  use the 3-arg custom form (excluded from v2's spec-method set).
- Legacy tasks kept working (per project requirement): requestor tasks re-
  implemented over raw client.request + explicit deprecated schemas;
  experimental.tasks.callToolStream replaced by a local pollTaskToolCall
  async generator (with _progressHandlers revival so task-execution progress
  still reaches the caller). Receiver (server-initiated) tasks: the v2 Client
  validates a sampling/elicit handler result and rejects the legacy { task }
  response with -32602 — installReceiverTaskResponseBypass swaps the wrapped
  entry in the private _requestHandlers map for the task-augmented branch so
  { task } reaches the wire (fixes server-initiated sampling-via-task).
- Pagination: list verbs use raw client.request({method}, List*ResultSchema)
  for single-page behavior (v2's client.listX() auto-aggregate all pages).

Web / auth / apps
- Rename local JsonSchemaType -> InspectorFormSchema + add toFormSchema()
  structural narrowing at the SDK-schema -> form boundary.
- ext-apps still peers on SDK v1: one compat boundary with documented casts
  (remove when ext-apps#702 lands a v2 peer).
- OAuth provider saveClientInformation reconciled with v2's
  OAuthClientInformationContext; InvalidClientMetadataError re-homed as a
  local class (server-legacy/auth is not browser-safe).
- vitest.shared.mts dedupes @modelcontextprotocol/client+core to one copy so
  vi.mock intercepts the SUT's import.

Accepted v2 behavior changes (per #1624 / spec §9.2): unknown-tool call
rejects with -32602; cancellation is stream-abort (no guaranteed
notifications/cancelled frame); output-schema strictness restored via the
Inspector's own Ajv check on the default path.

npm run ci green: validate (web 3087 / cli 212 / tui 274 / launcher 5),
coverage (>=90 per-file, all clients), smoke (launcher/cli/web), storybook
(410).

Closes #1624

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

clients/web/src/components/elements/AnnotationBadge/AnnotationBadge.tsx

@@ -1,5 +1,5 @@
 import { Badge } from "@mantine/core";
-import type { Role } from "@modelcontextprotocol/sdk/types.js";
+import type { Role } from "@modelcontextprotocol/client";
 import { filledBadgeColor } from "../filledBadgeColor";
 
 export type AnnotationFacet =

clients/web/src/components/elements/AppRenderer/AppRenderer.stories.tsx

@@ -2,7 +2,7 @@ import type { Meta, StoryObj } from "@storybook/react-vite";
 import { Box } from "@mantine/core";
 import type { ReactNode } from "react";
 import type { AppBridge } from "@modelcontextprotocol/ext-apps/app-bridge";
-import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { Tool } from "@modelcontextprotocol/client";
 import { fn } from "storybook/test";
 import { AppRenderer, type BridgeFactory } from "./AppRenderer";
 

clients/web/src/components/elements/AppRenderer/AppRenderer.test.tsx

@@ -2,7 +2,7 @@ import { createRef, StrictMode } from "react";
 import { act } from "@testing-library/react";
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import type { AppBridge } from "@modelcontextprotocol/ext-apps/app-bridge";
-import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { CallToolResult, Tool } from "@modelcontextprotocol/client";
 import { renderWithMantine, screen } from "../../../test/renderWithMantine";
 import {
   AppRenderer,

clients/web/src/components/elements/AppRenderer/AppRenderer.tsx

@@ -17,7 +17,7 @@ import type {
   CallToolResult,
   LoggingMessageNotification,
   Tool,
-} from "@modelcontextprotocol/sdk/types.js";
+} from "@modelcontextprotocol/client";
 import {
   currentStyles,
   currentTheme,
@@ -226,7 +226,12 @@ export function AppRenderer({
     if (pendingResultRef.current !== null) {
       const result = pendingResultRef.current;
       pendingResultRef.current = null;
-      void bridge.sendToolResult(result);
+      // ext-apps' AppBridge peers on SDK v1's CallToolResult (whose
+      // `structuredContent` is typed narrower than v2's). Runtime-compatible;
+      // cast at this boundary. TODO: drop when ext-apps#702 ships a v2 peer.
+      void bridge.sendToolResult(
+        result as Parameters<typeof bridge.sendToolResult>[0],
+      );
     }
   }, []);
 

clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts

@@ -7,11 +7,8 @@
  */
 
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import type {
-  Tool,
-  ReadResourceResult,
-} from "@modelcontextprotocol/sdk/types.js";
-import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { Tool, ReadResourceResult } from "@modelcontextprotocol/client";
+import type { Client } from "@modelcontextprotocol/client";
 
 // --- ext-apps mock -------------------------------------------------------
 const bridgeInstances: MockBridge[] = [];

clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts

@@ -8,13 +8,13 @@ import type {
   McpUiHostCapabilities,
   McpUiResourceMeta,
 } from "@modelcontextprotocol/ext-apps/app-bridge";
-import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { Client } from "@modelcontextprotocol/client";
 import type {
   EmbeddedResource,
   Implementation,
   ReadResourceResult,
   ResourceLink,
-} from "@modelcontextprotocol/sdk/types.js";
+} from "@modelcontextprotocol/client";
 import {
   approveCspSources,
   buildSandboxCspPolicy,
@@ -212,9 +212,17 @@ export function createAppBridgeFactory(
     // never mutates the shared HOST_CAPABILITIES constant — each app may
     // declare its own csp/permissions.
     const hostCapabilities: McpUiHostCapabilities = { ...HOST_CAPABILITIES };
-    const bridge = new AppBridge(client, HOST_INFO, hostCapabilities, {
-      hostContext: snapshotHostContext(iframe, HOST_AVAILABLE_DISPLAY_MODES),
-    });
+    // ext-apps' `AppBridge` peers on SDK v1's `Client`/`Implementation`; both
+    // are runtime-compatible with v2's. Cast at this single construction
+    // boundary. TODO: drop when ext-apps#702 ships a v2 peer release.
+    const bridge = new AppBridge(
+      client as unknown as ConstructorParameters<typeof AppBridge>[0],
+      HOST_INFO as unknown as ConstructorParameters<typeof AppBridge>[1],
+      hostCapabilities,
+      {
+        hostContext: snapshotHostContext(iframe, HOST_AVAILABLE_DISPLAY_MODES),
+      },
+    );
 
     // The double-iframe proxy posts `sandboxready` once it can receive content.
     // Read the tool's UI resource and hand its HTML (plus any sandbox/permission
@@ -226,7 +234,9 @@ export function createAppBridgeFactory(
     bridge.addEventListener("sandboxready", () => {
       void (async () => {
         try {
-          const uri = getToolUiResourceUri(tool);
+          const uri = getToolUiResourceUri(
+            tool as Parameters<typeof getToolUiResourceUri>[0],
+          );
           if (!uri) return;
           const result = await deps.readResource(uri);
           const { html, meta } = extractHtmlAndMeta(result);

clients/web/src/components/elements/CapabilityItem/CapabilityItem.tsx

@@ -2,7 +2,7 @@ import { Group, Text } from "@mantine/core";
 import type {
   ClientCapabilities,
   ServerCapabilities,
-} from "@modelcontextprotocol/sdk/types.js";
+} from "@modelcontextprotocol/client";
 
 export type CapabilityKey = keyof ServerCapabilities | keyof ClientCapabilities;
 

clients/web/src/components/elements/ContentViewer/ContentViewer.test.tsx

@@ -3,7 +3,7 @@ import type {
   BlobResourceContents,
   ContentBlock,
   TextResourceContents,
-} from "@modelcontextprotocol/sdk/types.js";
+} from "@modelcontextprotocol/client";
 import { renderWithMantine, screen } from "../../../test/renderWithMantine";
 import { ContentViewer } from "./ContentViewer";
 

clients/web/src/components/elements/ContentViewer/ContentViewer.tsx

@@ -4,7 +4,7 @@ import type {
   BlobResourceContents,
   ContentBlock,
   TextResourceContents,
-} from "@modelcontextprotocol/sdk/types.js";
+} from "@modelcontextprotocol/client";
 import ReactMarkdown from "react-markdown";
 import type { Components } from "react-markdown";
 import remarkGfm from "remark-gfm";

clients/web/src/components/elements/LogEntry/LogEntry.tsx

@@ -2,7 +2,7 @@ import { Group, Stack, Text } from "@mantine/core";
 import type {
   LoggingLevel,
   LoggingMessageNotification,
-} from "@modelcontextprotocol/sdk/types.js";
+} from "@modelcontextprotocol/client";
 import { LogLevelBadge } from "../LogLevelBadge/LogLevelBadge";
 import { accessibleTextColor } from "../accessibleTextColor";
 

clients/web/src/components/elements/LogLevelBadge/LogLevelBadge.test.tsx

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from "vitest";
-import type { LoggingLevel } from "@modelcontextprotocol/sdk/types.js";
+import type { LoggingLevel } from "@modelcontextprotocol/client";
 import { renderWithMantine, screen } from "../../../test/renderWithMantine";
 import { LogLevelBadge } from "./LogLevelBadge";
 

clients/web/src/components/elements/LogLevelBadge/LogLevelBadge.tsx

@@ -1,5 +1,5 @@
 import { Badge } from "@mantine/core";
-import type { LoggingLevel } from "@modelcontextprotocol/sdk/types.js";
+import type { LoggingLevel } from "@modelcontextprotocol/client";
 import { filledBadgeColor } from "../filledBadgeColor";
 
 export interface LogLevelBadgeProps {

clients/web/src/components/elements/MessageBubble/MessageBubble.test.tsx

@@ -2,7 +2,7 @@ import { describe, it, expect } from "vitest";
 import type {
   PromptMessage,
   SamplingMessage,
-} from "@modelcontextprotocol/sdk/types.js";
+} from "@modelcontextprotocol/client";
 import { renderWithMantine, screen } from "../../../test/renderWithMantine";
 import { MessageBubble } from "./MessageBubble";
 

clients/web/src/components/elements/MessageBubble/MessageBubble.tsx

@@ -3,7 +3,7 @@ import type {
   ContentBlock,
   PromptMessage,
   SamplingMessage,
-} from "@modelcontextprotocol/sdk/types.js";
+} from "@modelcontextprotocol/client";
 import { ContentViewer } from "../ContentViewer/ContentViewer";
 
 export interface MessageBubbleProps {

clients/web/src/components/elements/ProgressDisplay/ProgressDisplay.tsx

@@ -1,5 +1,5 @@
 import { Group, Progress, Stack, Text } from "@mantine/core";
-import type { ProgressNotification } from "@modelcontextprotocol/sdk/types.js";
+import type { ProgressNotification } from "@modelcontextprotocol/client";
 
 export interface ProgressDisplayProps {
   params: Pick<

clients/web/src/components/elements/TaskStatusBadge/TaskStatusBadge.test.tsx

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from "vitest";
-import type { TaskStatus } from "@modelcontextprotocol/sdk/types.js";
+import type { TaskStatus } from "@modelcontextprotocol/client";
 import { renderWithMantine, screen } from "../../../test/renderWithMantine";
 import { TaskStatusBadge } from "./TaskStatusBadge";
 

clients/web/src/components/elements/TaskStatusBadge/TaskStatusBadge.tsx

@@ -1,5 +1,5 @@
 import { Badge } from "@mantine/core";
-import type { TaskStatus } from "@modelcontextprotocol/sdk/types.js";
+import type { TaskStatus } from "@modelcontextprotocol/client";
 import { filledBadgeColor } from "../filledBadgeColor";
 
 export interface TaskStatusBadgeProps {

clients/web/src/components/groups/AppControls/AppControls.stories.tsx

@@ -1,7 +1,7 @@
 import { useState } from "react";
 import type { ComponentProps } from "react";
 import type { Meta, StoryObj } from "@storybook/react-vite";
-import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { Tool } from "@modelcontextprotocol/client";
 import { fn, userEvent, within } from "storybook/test";
 import { AppControls } from "./AppControls";
 import { SUN_ICON_SVG } from "../../../test/fixtures/storyIcons";

clients/web/src/components/groups/AppControls/AppControls.test.tsx

@@ -1,7 +1,7 @@
 import { useState } from "react";
 import { describe, it, expect, vi } from "vitest";
 import userEvent from "@testing-library/user-event";
-import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { Tool } from "@modelcontextprotocol/client";
 import { renderWithMantine, screen } from "../../../test/renderWithMantine";
 import { AppControls, type AppControlsProps } from "./AppControls";
 

clients/web/src/components/groups/AppControls/AppControls.tsx

@@ -7,7 +7,7 @@ import {
   Title,
 } from "@mantine/core";
 import { ClearButton } from "../../elements/ClearButton/ClearButton";
-import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { Tool } from "@modelcontextprotocol/client";
 import { ListChangedIndicator } from "../../elements/ListChangedIndicator/ListChangedIndicator";
 import { AppListItem } from "../AppListItem/AppListItem";
 import { useScrollMemory } from "../../../hooks/useScrollMemory";