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/test/core/apps.test.ts

@@ -1,8 +1,5 @@
 import { describe, it, expect } from "vitest";
-import type {
-  ReadResourceResult,
-  Tool,
-} from "@modelcontextprotocol/sdk/types.js";
+import type { ReadResourceResult, Tool } from "@modelcontextprotocol/client";
 import {
   extractAppInfo,
   getAppResourceUri,

clients/web/src/test/core/auth/ema/resourceContext.test.ts

@@ -4,7 +4,7 @@ import {
   discoverEmaResourceContext,
   discoverResourceAsMetadata,
 } from "@inspector/core/auth/ema/resourceContext.js";
-import type { OAuthProtectedResourceMetadata } from "@modelcontextprotocol/sdk/shared/auth.js";
+import type { OAuthProtectedResourceMetadata } from "@modelcontextprotocol/client";
 import { minimalOAuthAsMetadata } from "../../../integration/mcp/ema-mock-servers.js";
 
 const SERVER_URL = "http://127.0.0.1:9999/mcp";

clients/web/src/test/core/auth/ema/tokenEndpoint.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, vi } from "vitest";
 import type {
   OAuthClientInformation,
   OAuthMetadata,
-} from "@modelcontextprotocol/sdk/shared/auth.js";
+} from "@modelcontextprotocol/client";
 import {
   parseOAuthTokenErrorResponse,
   postOAuthTokenRequest,

clients/web/src/test/core/auth/ema/transportProvider.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
-import type { OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+import type { OAuthTokens } from "@modelcontextprotocol/client";
 import type { BaseOAuthClientProvider } from "@inspector/core/auth/providers.js";
 import type { EmaFlowConfig } from "@inspector/core/auth/ema/emaFlow.js";
 import { EmaTransportOAuthProvider } from "@inspector/core/auth/ema/transportProvider.js";

clients/web/src/test/core/auth/mcpAuth.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
-import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type { OAuthClientProvider } from "@modelcontextprotocol/client";
 
 const {
   sdkAuth,
@@ -17,11 +17,9 @@ const {
   isHttpsUrl: vi.fn(),
 }));
 
-vi.mock("@modelcontextprotocol/sdk/client/auth.js", async (importOriginal) => {
+vi.mock("@modelcontextprotocol/client", async (importOriginal) => {
   const actual =
-    await importOriginal<
-      typeof import("@modelcontextprotocol/sdk/client/auth.js")
-    >();
+    await importOriginal<typeof import("@modelcontextprotocol/client")>();
   return {
     ...actual,
     auth: sdkAuth,
@@ -34,7 +32,7 @@ vi.mock("@modelcontextprotocol/sdk/client/auth.js", async (importOriginal) => {
 });
 
 import { mcpAuth } from "@inspector/core/auth/mcpAuth.js";
-import { InvalidClientMetadataError } from "@modelcontextprotocol/sdk/server/auth/errors.js";
+import { InvalidClientMetadataError } from "@inspector/core/auth/mcpAuth.js";
 
 function makeProvider(
   overrides: Partial<OAuthClientProvider> = {},

clients/web/src/test/core/auth/storage-browser.test.ts

@@ -7,7 +7,7 @@ import type {
   OAuthClientInformation,
   OAuthTokens,
   OAuthMetadata,
-} from "@modelcontextprotocol/sdk/shared/auth.js";
+} from "@modelcontextprotocol/client";
 
 // Mock sessionStorage for Node.js environment
 class MockSessionStorage implements Storage {

clients/web/src/test/core/jsonUtils.test.ts

@@ -4,7 +4,7 @@ import {
   convertToolParameters,
   convertPromptArguments,
 } from "@inspector/core/json/jsonUtils.js";
-import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { Tool } from "@modelcontextprotocol/client";
 
 describe("JSON Utils", () => {
   describe("convertParameterValue", () => {

clients/web/src/test/core/mcp/authResyncPropagation.test.ts

@@ -3,8 +3,8 @@
  */
 
 import { describe, it, expect, vi } from "vitest";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { LATEST_PROTOCOL_VERSION } from "@modelcontextprotocol/sdk/types.js";
+import { Client } from "@modelcontextprotocol/client";
+import { LATEST_PROTOCOL_VERSION } from "@modelcontextprotocol/client";
 import { MessageTrackingTransport } from "@inspector/core/mcp/messageTrackingTransport.js";
 import { RemoteClientTransport } from "@inspector/core/mcp/remote/remoteClientTransport.js";
 

clients/web/src/test/core/mcp/elicitationCreateMessage.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from "vitest";
-import type { ElicitRequest } from "@modelcontextprotocol/sdk/types.js";
+import type { ElicitRequest } from "@modelcontextprotocol/client";
 import { ElicitationCreateMessage } from "@inspector/core/mcp/elicitationCreateMessage.js";
 
 function urlRequest(): ElicitRequest {

clients/web/src/test/core/mcp/inspectorClientUrlElicitation.test.ts

@@ -1,13 +1,13 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import {
-  ErrorCode,
-  McpError,
+  ProtocolErrorCode,
+  ProtocolError,
   UrlElicitationRequiredError,
-} from "@modelcontextprotocol/sdk/types.js";
+} from "@modelcontextprotocol/client";
 import type {
   ElicitRequestURLParams,
   Tool,
-} from "@modelcontextprotocol/sdk/types.js";
+} from "@modelcontextprotocol/client";
 import { InspectorClient } from "@inspector/core/mcp/inspectorClient.js";
 import { UrlElicitationLoopError } from "@inspector/core/mcp/urlElicitation.js";
 import type { CreateTransport } from "@inspector/core/mcp/types.js";
@@ -224,8 +224,8 @@ describe("InspectorClient URL-elicitation error path", () => {
   it("rethrows a -32042 error with no elicitations without queuing anything", async () => {
     const fake: FakeClient = {
       callTool: vi.fn(async () => {
-        throw new McpError(
-          ErrorCode.UrlElicitationRequired,
+        throw new ProtocolError(
+          ProtocolErrorCode.UrlElicitationRequired,
           "This request requires browser-based authorization.",
         );
       }),
@@ -234,7 +234,7 @@ describe("InspectorClient URL-elicitation error path", () => {
     const client = makeClient(fake);
 
     await expect(client.callTool(tool, {})).rejects.toMatchObject({
-      code: ErrorCode.UrlElicitationRequired,
+      code: ProtocolErrorCode.UrlElicitationRequired,
     });
     expect(client.getPendingElicitations()).toHaveLength(0);
     expect(fake.callTool).toHaveBeenCalledTimes(1);

clients/web/src/test/core/mcp/messageTrackingTransport.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi } from "vitest";
-import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
-import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
+import type { Transport } from "@modelcontextprotocol/client";
+import type { JSONRPCMessage } from "@modelcontextprotocol/client";
 import { MessageTrackingTransport } from "@inspector/core/mcp/messageTrackingTransport.js";
 
 /** Minimal in-memory Transport so we can drive send()/onmessage directly. */

clients/web/src/test/core/mcp/state/managedPromptsState.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from "vitest";
-import type { Prompt } from "@modelcontextprotocol/sdk/types.js";
+import type { Prompt } from "@modelcontextprotocol/client";
 import type { InspectorServerSettings } from "@inspector/core/mcp/types.js";
 import { ManagedPromptsState } from "@inspector/core/mcp/state/managedPromptsState";
 import { FakeInspectorClient } from "@inspector/core/mcp/__tests__/fakeInspectorClient";

clients/web/src/test/core/mcp/state/managedRequestorTasksState.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from "vitest";
-import type { Task } from "@modelcontextprotocol/sdk/types.js";
+import type { Task } from "@modelcontextprotocol/client";
 import { ManagedRequestorTasksState } from "@inspector/core/mcp/state/managedRequestorTasksState";
 import { FakeInspectorClient } from "@inspector/core/mcp/__tests__/fakeInspectorClient";
 import { waitForChangeEvent } from "./waitForChangeEvent";

clients/web/src/test/core/mcp/state/managedResourceTemplatesState.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from "vitest";
-import type { ResourceTemplate } from "@modelcontextprotocol/sdk/types.js";
+import type { ResourceTemplateType as ResourceTemplate } from "@modelcontextprotocol/client";
 import type { InspectorServerSettings } from "@inspector/core/mcp/types.js";
 import { ManagedResourceTemplatesState } from "@inspector/core/mcp/state/managedResourceTemplatesState";
 import { FakeInspectorClient } from "@inspector/core/mcp/__tests__/fakeInspectorClient";

clients/web/src/test/core/mcp/state/managedResourcesState.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from "vitest";
-import type { Resource } from "@modelcontextprotocol/sdk/types.js";
+import type { Resource } from "@modelcontextprotocol/client";
 import type { InspectorServerSettings } from "@inspector/core/mcp/types.js";
 import { ManagedResourcesState } from "@inspector/core/mcp/state/managedResourcesState";
 import { FakeInspectorClient } from "@inspector/core/mcp/__tests__/fakeInspectorClient";

clients/web/src/test/core/mcp/state/managedToolsState.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from "vitest";
-import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { Tool } from "@modelcontextprotocol/client";
 import type { InspectorServerSettings } from "@inspector/core/mcp/types.js";
 import { ManagedToolsState } from "@inspector/core/mcp/state/managedToolsState";
 import { FakeInspectorClient } from "@inspector/core/mcp/__tests__/fakeInspectorClient";

clients/web/src/test/core/mcp/state/mergeTaskIntoList.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import type { Task } from "@modelcontextprotocol/sdk/types.js";
+import type { Task } from "@modelcontextprotocol/client";
 import type { TaskWithOptionalCreatedAt } from "@inspector/core/mcp/inspectorClientEventTarget";
 import { mergeTaskIntoList } from "@inspector/core/mcp/state/mergeTaskIntoList";
 

clients/web/src/test/core/mcp/state/pagedPromptsState.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from "vitest";
-import type { Prompt } from "@modelcontextprotocol/sdk/types.js";
+import type { Prompt } from "@modelcontextprotocol/client";
 import { PagedPromptsState } from "@inspector/core/mcp/state/pagedPromptsState";
 import { FakeInspectorClient } from "@inspector/core/mcp/__tests__/fakeInspectorClient";
 

clients/web/src/test/core/mcp/state/pagedRequestorTasksState.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from "vitest";
-import type { Task } from "@modelcontextprotocol/sdk/types.js";
+import type { Task } from "@modelcontextprotocol/client";
 import { PagedRequestorTasksState } from "@inspector/core/mcp/state/pagedRequestorTasksState";
 import { FakeInspectorClient } from "@inspector/core/mcp/__tests__/fakeInspectorClient";
 

clients/web/src/test/core/mcp/state/pagedResourceTemplatesState.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from "vitest";
-import type { ResourceTemplate } from "@modelcontextprotocol/sdk/types.js";
+import type { ResourceTemplateType as ResourceTemplate } from "@modelcontextprotocol/client";
 import { PagedResourceTemplatesState } from "@inspector/core/mcp/state/pagedResourceTemplatesState";
 import { FakeInspectorClient } from "@inspector/core/mcp/__tests__/fakeInspectorClient";