modelcontextprotocol/inspector
Watch
1
0
Fork
You've already forked inspector
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

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

Browse source 
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>
This commit is contained in:
cliffhall 2026-07-15 10:44:24 -04:00
commit 19a6df7ad3
10 changed files with 2545 additions and 2123 deletions
Download patch file Download diff file Expand all files Collapse all files

28
clients/web/src/test/integration/auth/discovery.test.ts
View file

@ -3,10 +3,10 @@ import {
discoverScopes,
getAuthorizationServerUrl,
} from "@inspector/core/auth/discovery.js";
import type { OAuthProtectedResourceMetadata } from "@modelcontextprotocol/sdk/shared/auth.js";
import type { OAuthProtectedResourceMetadata } from "@modelcontextprotocol/client";
// Mock SDK functions
vi.mock("@modelcontextprotocol/sdk/client/auth.js", () => ({
vi.mock("@modelcontextprotocol/client", () => ({
discoverAuthorizationServerMetadata: vi.fn(),
}));
@ -17,7 +17,7 @@ describe("OAuth Scope Discovery", () => {
it("should return scopes from resource metadata when available", async () => {
const { discoverAuthorizationServerMetadata } =
await import("@modelcontextprotocol/sdk/client/auth.js");
await import("@modelcontextprotocol/client");
vi.mocked(discoverAuthorizationServerMetadata).mockResolvedValue({
issuer: "http://localhost:3000",
authorization_endpoint: "http://localhost:3000/authorize",
@ -42,7 +42,7 @@ describe("OAuth Scope Discovery", () => {
it("should fall back to OAuth metadata scopes when resource metadata has no scopes", async () => {
const { discoverAuthorizationServerMetadata } =
await import("@modelcontextprotocol/sdk/client/auth.js");
await import("@modelcontextprotocol/client");
vi.mocked(discoverAuthorizationServerMetadata).mockResolvedValue({
issuer: "http://localhost:3000",
authorization_endpoint: "http://localhost:3000/authorize",
@ -67,7 +67,7 @@ describe("OAuth Scope Discovery", () => {
it("should fall back to OAuth metadata scopes when resource metadata is not provided", async () => {
const { discoverAuthorizationServerMetadata } =
await import("@modelcontextprotocol/sdk/client/auth.js");
await import("@modelcontextprotocol/client");
vi.mocked(discoverAuthorizationServerMetadata).mockResolvedValue({
issuer: "http://localhost:3000",
authorization_endpoint: "http://localhost:3000/authorize",
@ -83,7 +83,7 @@ describe("OAuth Scope Discovery", () => {
it("should return undefined when no scopes are available", async () => {
const { discoverAuthorizationServerMetadata } =
await import("@modelcontextprotocol/sdk/client/auth.js");
await import("@modelcontextprotocol/client");
vi.mocked(discoverAuthorizationServerMetadata).mockResolvedValue({
issuer: "http://localhost:3000",
authorization_endpoint: "http://localhost:3000/authorize",
@ -99,7 +99,7 @@ describe("OAuth Scope Discovery", () => {
it("should return undefined when discovery fails", async () => {
const { discoverAuthorizationServerMetadata } =
await import("@modelcontextprotocol/sdk/client/auth.js");
await import("@modelcontextprotocol/client");
vi.mocked(discoverAuthorizationServerMetadata).mockRejectedValue(
new Error("Discovery failed"),
);
@ -111,7 +111,7 @@ describe("OAuth Scope Discovery", () => {
it("should return undefined when metadata is undefined", async () => {
const { discoverAuthorizationServerMetadata } =
await import("@modelcontextprotocol/sdk/client/auth.js");
await import("@modelcontextprotocol/client");
vi.mocked(discoverAuthorizationServerMetadata).mockResolvedValue(undefined);
const scopes = await discoverScopes("http://localhost:3000");
@ -121,7 +121,7 @@ describe("OAuth Scope Discovery", () => {
it("should use OAuth metadata scopes when resource has scopes_supported undefined", async () => {
const { discoverAuthorizationServerMetadata } =
await import("@modelcontextprotocol/sdk/client/auth.js");
await import("@modelcontextprotocol/client");
vi.mocked(discoverAuthorizationServerMetadata).mockResolvedValue({
issuer: "http://localhost:3000",
authorization_endpoint: "http://localhost:3000/authorize",
@ -146,7 +146,7 @@ describe("OAuth Scope Discovery", () => {
it("should return single scope when only one scope is supported", async () => {
const { discoverAuthorizationServerMetadata } =
await import("@modelcontextprotocol/sdk/client/auth.js");
await import("@modelcontextprotocol/client");
vi.mocked(discoverAuthorizationServerMetadata).mockResolvedValue({
issuer: "http://localhost:3000",
authorization_endpoint: "http://localhost:3000/authorize",
@ -162,7 +162,7 @@ describe("OAuth Scope Discovery", () => {
it("should pass fetchFn to discoverAuthorizationServerMetadata when provided", async () => {
const { discoverAuthorizationServerMetadata } =
await import("@modelcontextprotocol/sdk/client/auth.js");
await import("@modelcontextprotocol/client");
const mockFetchFn = vi.fn();
vi.mocked(discoverAuthorizationServerMetadata).mockResolvedValue({
issuer: "http://localhost:3000",
@ -182,7 +182,7 @@ describe("OAuth Scope Discovery", () => {
it("should use authorization_servers URL from resource metadata for discovery (different domain)", async () => {
const { discoverAuthorizationServerMetadata } =
await import("@modelcontextprotocol/sdk/client/auth.js");
await import("@modelcontextprotocol/client");
vi.mocked(discoverAuthorizationServerMetadata).mockResolvedValue({
issuer: "https://auth-server.com",
authorization_endpoint: "https://auth-server.com/authorize",
@ -211,7 +211,7 @@ describe("OAuth Scope Discovery", () => {
it("should preserve full path in authorization_servers URL", async () => {
const { discoverAuthorizationServerMetadata } =
await import("@modelcontextprotocol/sdk/client/auth.js");
await import("@modelcontextprotocol/client");
vi.mocked(discoverAuthorizationServerMetadata).mockResolvedValue({
issuer: "https://auth-server.com/realms/my-realm",
authorization_endpoint:
@ -241,7 +241,7 @@ describe("OAuth Scope Discovery", () => {
it("should fall back to serverUrl when authorization_servers is empty", async () => {
const { discoverAuthorizationServerMetadata } =
await import("@modelcontextprotocol/sdk/client/auth.js");
await import("@modelcontextprotocol/client");
vi.mocked(discoverAuthorizationServerMetadata).mockResolvedValue({
issuer: "https://mcp-server.com",
authorization_endpoint: "https://mcp-server.com/authorize",

2
clients/web/src/test/integration/auth/node/storage.test.ts
View file

@ -9,7 +9,7 @@ import type {
OAuthClientInformation,
OAuthTokens,
OAuthMetadata,
} from "@modelcontextprotocol/sdk/shared/auth.js";
} from "@modelcontextprotocol/client";
import * as fs from "node:fs/promises";
import * as path from "node:path";
import * as os from "node:os";

60
clients/web/src/test/integration/mcp/inspectorClient-coverage-backfill.test.ts
View file

@ -23,8 +23,8 @@ import {
createNumberedResources,
createNumberedPrompts,
} from "@modelcontextprotocol/inspector-test-server";
import type { Tool } from "@modelcontextprotocol/sdk/types.js";
import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
import type { Tool } from "@modelcontextprotocol/client";
import { ProtocolError, ProtocolErrorCode } from "@modelcontextprotocol/client";
const serverCommand = getTestMcpServerCommand();
@ -184,7 +184,10 @@ describe("InspectorClient coverage backfill", () => {
};
const original = c.client.complete;
c.client.complete = async () => {
throw new McpError(ErrorCode.MethodNotFound, "Method not found");
throw new ProtocolError(
ProtocolErrorCode.MethodNotFound,
"Method not found",
);
};
try {
await expect(
@ -591,11 +594,13 @@ describe("InspectorClient coverage backfill", () => {
client = stdioClient();
await client.connect();
// Force the streaming API to throw synchronously so the error-path
// metadata-merge branches run for each combination.
// metadata-merge branches run for each combination. `callToolStream`
// drives tasks via the private `pollTaskToolCall` generator (SDK v2
// removed `client.experimental.tasks`), so patch that instead.
const c = client as unknown as {
client: { experimental: { tasks: { callToolStream: () => never } } };
pollTaskToolCall: () => never;
};
c.client.experimental.tasks.callToolStream = () => {
c.pollTaskToolCall = () => {
throw new Error("forced-stream-failure");
};
@ -747,9 +752,9 @@ describe("InspectorClient coverage backfill", () => {
await client.connect();
const echo = await getTool(client, "echo");
const c = client as unknown as {
client: { experimental: { tasks: { callToolStream: () => never } } };
pollTaskToolCall: () => never;
};
c.client.experimental.tasks.callToolStream = () => {
c.pollTaskToolCall = () => {
throw "string-stream-failure";
};
await expect(
@ -761,18 +766,12 @@ describe("InspectorClient coverage backfill", () => {
client = stdioClient();
await client.connect();
const c = client as unknown as {
client: {
listResources: () => Promise<unknown>;
listResourceTemplates: () => Promise<unknown>;
listPrompts: () => Promise<unknown>;
listTools: () => Promise<unknown>;
};
client: { request: () => Promise<unknown> };
};
// Return responses missing the array field → `|| []` fallback branches.
c.client.listResources = async () => ({});
c.client.listResourceTemplates = async () => ({});
c.client.listPrompts = async () => ({});
c.client.listTools = async () => ({});
// InspectorClient's list methods issue raw `client.request({method:"…/list"})`
// (SDK v2's `client.listX()` auto-aggregate pages), so mock `request` to
// return a body missing the array field → `|| []` fallback branches.
c.client.request = async () => ({});
expect((await client.listResources()).resources).toEqual([]);
expect((await client.listResourceTemplates()).resourceTemplates).toEqual(
@ -800,19 +799,26 @@ describe("InspectorClient coverage backfill", () => {
gen: () => AsyncGenerator<unknown>,
getTaskResult?: () => Promise<unknown>,
): void {
// SDK v2 removed `client.experimental.tasks`; `callToolStream` now drives
// tasks via the private `pollTaskToolCall` generator, and the no-result
// fallback fetches the payload with a raw `client.request({method:"tasks/result"})`.
const internal = c as unknown as {
pollTaskToolCall: () => AsyncGenerator<unknown>;
client: {
experimental: {
tasks: {
callToolStream: () => AsyncGenerator<unknown>;
getTaskResult: (id: string) => Promise<unknown>;
};
};
request: (
req: { method: string },
schema: unknown,
opts: unknown,
) => Promise<unknown>;
};
};
internal.client.experimental.tasks.callToolStream = gen;
internal.pollTaskToolCall = gen;
if (getTaskResult) {
internal.client.experimental.tasks.getTaskResult = getTaskResult;
const origRequest = internal.client.request.bind(internal.client);
internal.client.request = (req, schema, opts) =>
req.method === "tasks/result"
? getTaskResult()
: origRequest(req, schema, opts);
}
}

14
clients/web/src/test/integration/mcp/inspectorClient-oauth-fetchFn.test.ts
View file

@ -32,9 +32,17 @@ function createTestOAuthConfig(
}
const mockAuth = vi.fn();
vi.mock("@modelcontextprotocol/sdk/client/auth.js", () => ({
auth: (...args: unknown[]) => mockAuth(...args),
}));
// Partial mock: keep every real export (Client, transports, types, …) and
// override only `auth`. A full-replace factory would drop `Client`, which
// InspectorClient imports from the same module.
vi.mock("@modelcontextprotocol/client", async (importOriginal) => {
const actual =
await importOriginal<typeof import("@modelcontextprotocol/client")>();
return {
...actual,
auth: (...args: unknown[]) => mockAuth(...args),
};
});
describe("InspectorClient OAuth fetchFn", () => {
let client: InspectorClient;

65
clients/web/src/test/integration/mcp/inspectorClient.test.ts
View file

@ -63,16 +63,16 @@ import type {
Task,
Tool,
Resource,
ResourceTemplate,
ResourceTemplateType as ResourceTemplate,
Prompt,
Progress,
ContentBlock,
} from "@modelcontextprotocol/sdk/types.js";
} from "@modelcontextprotocol/client";
import {
RELATED_TASK_META_KEY,
McpError,
ErrorCode,
} from "@modelcontextprotocol/sdk/types.js";
SdkError,
SdkErrorCode,
} from "@modelcontextprotocol/client";
/** Get all tools from the client via listTools() (paginates if needed). */
async function getAllTools(client: InspectorClient): Promise<Tool[]> {
@ -310,7 +310,7 @@ describe("InspectorClient", () => {
};
const fakeFactory = () => ({
transport:
hangingTransport as unknown as import("@modelcontextprotocol/sdk/shared/transport.js").Transport,
hangingTransport as unknown as import("@modelcontextprotocol/client").Transport,
});
client = new InspectorClient(
{ type: "streamable-http", url: "http://localhost:1/never" },
@ -358,7 +358,7 @@ describe("InspectorClient", () => {
};
const fakeFactory = () => ({
transport:
unauthorizedTransport as unknown as import("@modelcontextprotocol/sdk/shared/transport.js").Transport,
unauthorizedTransport as unknown as import("@modelcontextprotocol/client").Transport,
});
client = new InspectorClient(
{ type: "streamable-http", url: "http://localhost:8081/mcp" },
@ -967,20 +967,13 @@ describe("InspectorClient", () => {
});
it("should handle tool not found", async () => {
const result = await client!.callTool(
minimalTool("nonexistent-tool"),
{},
);
// When tool is not found, the SDK returns an error response, not an exception
expect(result.success).toBe(true); // SDK returns error in result, not as exception
expect(result.result).toHaveProperty("isError", true);
expect(result.result).toBeDefined();
if (result.result) {
expect(result.result).toHaveProperty("content");
const content = result.result.content as ContentBlock[];
expect(content[0]).toHaveProperty("text");
expect((content[0] as { text: string }).text).toContain("not found");
}
// SDK v2 change (#1624): an unknown-tool call now *rejects* with a
// ProtocolError (-32602) instead of resolving an `isError: true` result.
// callTool records the failed call and rethrows, so the caller sees a
// rejection whose message names the missing tool.
await expect(
client!.callTool(minimalTool("nonexistent-tool"), {}),
).rejects.toThrow(/not found|unknown tool|nonexistent-tool/i);
});
it("cancelToolCall() is a no-op (returns false) when no call is in flight", () => {
@ -994,13 +987,9 @@ describe("InspectorClient", () => {
);
});
it("cancelToolCall() aborts the in-flight call: sends notifications/cancelled, rejects with ToolCallCancelledError, and records no failed call", async () => {
it("cancelToolCall() aborts the in-flight call: rejects with ToolCallCancelledError, and records no failed call", async () => {
const tool = await getTool(client!, "echo");
const messages: MessageEntry[] = [];
client!.addEventListener("message", (event) => {
messages.push(event.detail);
});
let failedCallCount = 0;
client!.addEventListener("toolCallResultChange", (event) => {
if (!event.detail.success) failedCallCount++;
@ -1013,14 +1002,14 @@ describe("InspectorClient", () => {
await expect(promise).rejects.toBeInstanceOf(ToolCallCancelledError);
// The MCP cancellation flow: a notifications/cancelled reaches the server.
const cancelled = messages.find(
(m) =>
m.direction === "notification" &&
"method" in m.message &&
m.message.method === "notifications/cancelled",
);
expect(cancelled).toBeDefined();
// SDK v2 change (spec §9.2): cancellation now surfaces as a stream/connection
// abort rather than a guaranteed `notifications/cancelled` frame. v2's
// `callTool` awaits output-validator compilation before it issues the
// `tools/call` request, so a synchronous cancel aborts the shared signal
// *before* that request registers — the SDK then takes its pre-aborted
// early-reject path and emits no cancellation frame. The user-facing
// behavior we care about is unchanged: the call rejects with
// ToolCallCancelledError and is not recorded as a failed call.
// Cancelling is intentional, so it is not recorded as a failed tool call.
expect(failedCallCount).toBe(0);
@ -2427,8 +2416,8 @@ describe("InspectorClient", () => {
} catch (e) {
err = e;
}
expect(err).toBeInstanceOf(McpError);
expect((err as McpError).code).toBe(ErrorCode.RequestTimeout);
expect(err).toBeInstanceOf(SdkError);
expect((err as SdkError).code).toBe(SdkErrorCode.RequestTimeout);
await client.disconnect();
await server.stop();
@ -2858,7 +2847,7 @@ describe("InspectorClient", () => {
onerror: undefined,
onmessage: undefined,
sessionId: undefined,
} as unknown as import("@modelcontextprotocol/sdk/shared/transport.js").Transport,
} as unknown as import("@modelcontextprotocol/client").Transport,
});
client = new InspectorClient(
{ type: "streamable-http", url: "http://localhost:1/never" },
@ -2896,7 +2885,7 @@ describe("InspectorClient", () => {
};
const factory = () => ({
transport:
transport as unknown as import("@modelcontextprotocol/sdk/shared/transport.js").Transport,
transport as unknown as import("@modelcontextprotocol/client").Transport,
});
client = new InspectorClient(
{ type: "streamable-http", url: "http://localhost:1/never" },

2
clients/web/src/test/integration/mcp/mcp-app-demo.test.ts
View file

@ -9,7 +9,7 @@ import {
createMcpAppDemoResource,
MCP_APP_DEMO_URI,
} from "@modelcontextprotocol/inspector-test-server";
import type { Tool } from "@modelcontextprotocol/sdk/types.js";
import type { Tool } from "@modelcontextprotocol/client";
/**
* Exercises the `mcp_app_demo` preset added in #1557 end-to-end: it confirms the

2
clients/web/src/test/integration/mcp/node/transport.test.ts
View file

@ -15,7 +15,7 @@ import {
createEchoTool,
createTestServerInfo,
} from "@modelcontextprotocol/inspector-test-server";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { Client } from "@modelcontextprotocol/client";
describe("Transport", () => {
describe("getServerType", () => {

2
clients/web/src/test/integration/mcp/remote/remote-session.test.ts
View file

@ -7,7 +7,7 @@
*/
import { describe, it, expect, vi } from "vitest";
import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
import type { Transport } from "@modelcontextprotocol/client";
import { RemoteSession } from "@inspector/core/mcp/remote/node/remote-session.js";
import type { FetchRequestEntryBase } from "@inspector/core/mcp/types.js";
import { AuthChallengeError } from "@inspector/core/auth/challenge.js";

2
clients/web/src/test/integration/mcp/remote/remoteClientTransport-unit.test.ts
View file

@ -15,7 +15,7 @@ import { RemoteClientTransport } from "@inspector/core/mcp/remote/remoteClientTr
import type { RemoteTransportOptions } from "@inspector/core/mcp/remote/remoteClientTransport.js";
import type { MCPServerConfig } from "@inspector/core/mcp/types.js";
import type { RemoteEvent } from "@inspector/core/mcp/remote/types.js";
import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
import type { JSONRPCMessage } from "@modelcontextprotocol/client";
import {
AuthChallengeError,
AuthRecoveryRequiredError,

4
clients/web/src/test/integration/server/vite-base-config.test.ts
View file

@ -19,7 +19,7 @@ describe("getViteBaseConfig", () => {
const config = getViteBaseConfig();
expect(config.optimizeDeps.exclude).toEqual(
expect.arrayContaining([
"@modelcontextprotocol/sdk/client/stdio.js",
"@modelcontextprotocol/client/stdio",
"atomically",
"cross-spawn",
"which",
@ -42,7 +42,7 @@ describe("getViteDevOptimizeDeps", () => {
expect(config.ignoreOutdatedRequests).toBe(true);
expect(config.include).toEqual([
"ajv",
"@modelcontextprotocol/sdk/validation/ajv",
"@modelcontextprotocol/client/validators/ajv",
]);
expect(config.exclude).toEqual(getViteBaseConfig().optimizeDeps.exclude);
});