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

refactor: drop the ext-apps SDK-v1 shims now that 2.0.0 peers on SDK v2

Browse source 
Every site tagged `ext-apps#702` carried a workaround for ext-apps
peering on the v1 SDK while the Inspector runs v2. With 2.0.0 the
package's `AppBridge` extends the v2 `Protocol`, takes the v2 `Client`
and `Implementation` directly, and registers its list-changed forwarding
on that client with `setNotificationHandler("notifications/…", handler)`,
so:

- core/mcp/apps.ts: `getToolUiResourceUri(tool)` takes the v2 `Tool`
  without a cast; `UiMetaShape` is replaced by ext-apps' own
  `McpUiToolMeta` / `McpUiResourceMeta`, which resolve under NodeNext
  since ext-apps#705. `AppInfo.csp` / `.permissions` / `.visibility`
  take the named types too.
- core/mcp/inspectorClient.ts: `getAppRendererClient()` returns the SDK
  client itself; the Proxy that translated the 1.x schema-first
  `setNotificationHandler(Schema, handler)` into the method-string form,
  its `notificationMethodFromSchema` helper and its cached field are
  gone. `AppRendererClient` is now `Client` rather than `unknown`.
- createAppBridgeFactory.ts: `new AppBridge(client, HOST_INFO, …)` with
  no `as unknown as`; `resolveSourceUri` passes the tool straight through.
- AppRenderer.tsx: `sendToolResult(result)` — its params ARE the v2
  `CallToolResult` now.
- requestAppElicitation.ts: the double cast on the `elicitation/create`
  send goes too — v2 `Protocol.request` takes the standard `Request`
  shape, which `ElicitRequest` is. The helper itself stays: ext-apps#733
  is not in 2.0.0.
- core/mcp/extensions.ts: `MCP_APP_MIME_TYPE` re-exports ext-apps'
  `RESOURCE_MIME_TYPE` from `/app-bridge`; `UI_EXTENSION_KEY` stays
  hardcoded because `EXTENSION_ID` is still `/server`-only in 2.0.0.

Tests: the Proxy-translation test is removed with the Proxy; the
`getAppRendererClient` tests assert the real `Client` instance and that
disconnect withdraws it; the `useInspectorClient` sentinel is a real
(unconnected) `Client`. Comments that cited ext-apps 1.7.5 now cite 2.0.0
where the fact still holds (#733 still unreleased).

Closes #1745
Refs #2309

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PsmUAZ6aLUAFqenjJKSSRp
Signed-off-by: cliffhall <cliff@futurescale.com>
This commit is contained in:
cliffhall 2026-09-13 19:21:06 -04:00
commit a42d7fd99e
4 changed files with 127 additions and 242 deletions
Download patch file Download diff file Expand all files Collapse all files

66
core/mcp/apps.ts
View file

@ -1,4 +1,11 @@
import { getToolUiResourceUri } from "@modelcontextprotocol/ext-apps/app-bridge";
import type {
McpUiResourceCsp,
McpUiResourceMeta,
McpUiResourcePermissions,
McpUiToolMeta,
McpUiToolVisibility,
} from "@modelcontextprotocol/ext-apps/app-bridge";
import type { ReadResourceResult, Tool } from "@modelcontextprotocol/client";
/**
@ -19,13 +26,7 @@ import type { ReadResourceResult, Tool } from "@modelcontextprotocol/client";
* `@inspector/core`.
*/
export function getAppResourceUri(tool: Tool): string | undefined {
// `@modelcontextprotocol/ext-apps` still peers on SDK v1, so its
// `getToolUiResourceUri` param is typed as the v1 `Tool`. The runtime shape
// this reads (`_meta.ui.resourceUri`) is identical under v2, so cast at this
// single boundary. TODO: drop the cast when ext-apps#702 ships a v2 peer.
return getToolUiResourceUri(
tool as Parameters<typeof getToolUiResourceUri>[0],
);
return getToolUiResourceUri(tool);
}
/**
@ -53,10 +54,10 @@ export interface AppInfo {
hasApp: boolean;
toolName: string;
resourceUri?: string;
visibility?: readonly string[];
visibility?: readonly McpUiToolVisibility[];
/** From the UI resource's `_meta.ui` (per spec, csp/permissions/domain live on the resource, not the tool). Absent when the resource was not read. */
csp?: Readonly<Record<string, unknown>>;
permissions?: Readonly<Record<string, unknown>>;
csp?: Readonly<McpUiResourceCsp>;
permissions?: Readonly<McpUiResourcePermissions>;
domain?: string;
prefersBorder?: boolean;
resourceMimeType?: string;
@ -65,37 +66,26 @@ export interface AppInfo {
type WithUiMeta = { _meta?: { ui?: unknown } };
/**
* Structural shape for `_meta.ui` carriers — the ext-apps package's named
* types (`McpUiToolMeta`, `McpUiResourceMeta`) are not importable under
* NodeNext module resolution because of an extensionless re-export in the
* package's `.d.ts`, so we read the fields structurally instead. The values
* pass through verbatim into {@link AppInfo}; callers can narrow them against
* the published Zod schemas if they need strict typing.
* Reads a carrier's `_meta.ui` as one of ext-apps' named `_meta.ui` shapes —
* `McpUiToolMeta` for a tool, `McpUiResourceMeta` for a UI resource — narrowing
* from `unknown` so call sites don't need their own casts. Returns `undefined`
* unless both the carrier and its `_meta.ui` are non-null objects.
*
* TODO: switch to the named `McpUiToolMeta` / `McpUiResourceMeta` types once
* upstream fixes the extensionless re-export so they resolve under NodeNext.
* The narrowing is structural, not validated: the fields pass through verbatim
* into {@link AppInfo}, and a caller that needs strict typing can parse them
* against the published Zod schemas (`McpUiToolMetaSchema` /
* `McpUiResourceMetaSchema`). Typed with the package's own names since ext-apps
* 2.0.0, whose declarations resolve under NodeNext (ext-apps#705) — the
* structural stand-in that preceded it is gone (#1745).
*/
interface UiMetaShape {
visibility?: readonly string[];
csp?: Record<string, unknown>;
permissions?: Record<string, unknown>;
domain?: string;
prefersBorder?: boolean;
}
/**
* Reads a carrier's `_meta.ui` structurally, narrowing from `unknown` so call
* sites don't need their own casts. Returns `undefined` unless both the carrier
* and its `_meta.ui` are non-null objects.
*/
function readUiMeta(carrier: unknown): UiMetaShape | undefined {
function readUiMeta<T extends McpUiToolMeta | McpUiResourceMeta>(
carrier: unknown,
): T | undefined {
const ui =
carrier !== null && typeof carrier === "object"
? (carrier as WithUiMeta)._meta?.ui
: undefined;
return ui !== null && typeof ui === "object"
? (ui as UiMetaShape)
: undefined;
return ui !== null && typeof ui === "object" ? (ui as T) : undefined;
}
/**
@ -149,14 +139,16 @@ export function extractAppInfo(
if (resourceUri === undefined) {
return { hasApp: false, toolName: tool.name };
}
const toolUi = readUiMeta(tool);
const toolUi = readUiMeta<McpUiToolMeta>(tool);
const content = resource && findResourceContent(resource, resourceUri);
// Precedence is intentional: prefer the matched content block's `_meta.ui`,
// falling back to the result-level `_meta.ui`. Per the current spec the
// security posture (csp/permissions/domain) lives on the content block, so we
// don't shallow-merge the two carriers — a content block that declares any
// `ui` is treated as authoritative for all of its fields.
const resourceUi = readUiMeta(content) ?? readUiMeta(resource);
const resourceUi =
readUiMeta<McpUiResourceMeta>(content) ??
readUiMeta<McpUiResourceMeta>(resource);
return {
hasApp: true,
toolName: tool.name,

24
core/mcp/extensions.ts
View file

@ -1,4 +1,5 @@
import type { ClientCapabilities } from "@modelcontextprotocol/client";
import { RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/app-bridge";
import { TASKS_EXTENSION_KEY } from "./modernTaskSchemas.js";
/**
@ -13,21 +14,24 @@ export const EMA_EXTENSION_KEY =
/**
* Extension identifier for the MCP Apps UI extension (SEP-ext-apps). Mirrors
* `EXTENSION_ID` from `@modelcontextprotocol/ext-apps`. Hardcoded rather than
* imported: that constant lives on the package's `/server` subpath, which would
* pull server-only code into the browser bundle. The Inspector always renders
* MCP Apps, so this is advertised by default (#1740).
* imported: as of ext-apps 2.0.0 that constant is still exported only from the
* package's `/server` subpath, which would pull server-only code (and the
* optional `@modelcontextprotocol/server` peer) into the browser bundle. The
* node integration test `extensions-mimetype.test.ts` pins the two together.
* The Inspector always renders MCP Apps, so this is advertised by default
* (#1740).
*/
export const UI_EXTENSION_KEY = "io.modelcontextprotocol/ui";
/**
* The MCP Apps UI resource MIME type the Inspector renders. Mirrors
* `RESOURCE_MIME_TYPE` from `@modelcontextprotocol/ext-apps`; a server checks
* for it in the client's advertised `io.modelcontextprotocol/ui` `mimeTypes` to
* decide whether to serve an App. Hardcoded (stable spec string) because
* ext-apps re-exports it through an extensionless path that doesn't resolve
* cleanly under NodeNext — see the same note in `core/mcp/apps.ts`.
* The MCP Apps UI resource MIME type the Inspector renders. A server checks for
* it in the client's advertised `io.modelcontextprotocol/ui` `mimeTypes` to
* decide whether to serve an App. Re-exported from ext-apps' `/app-bridge`
* subpath — the one the Inspector already imports everywhere — rather than
* restated: the extensionless re-export that once kept this a hardcoded copy
* was fixed upstream (ext-apps#705) and shipped in 2.0.0 (#1745).
*/
export const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
export const MCP_APP_MIME_TYPE = RESOURCE_MIME_TYPE;
/**
* The value the client stamps for each advertised extension. The wire shape is

66
core/mcp/inspectorClient.ts
View file

@ -366,24 +366,6 @@ async function closeSubscriptionBestEffort(
}
}
/**
* Extract the method literal from an MCP notification Zod schema (e.g.
* `ToolListChangedNotificationSchema`), or `undefined` if the shape isn't
* recognized. Used by the App-renderer client proxy to translate the SDK-v1
* schema-first `setNotificationHandler` API — which `@modelcontextprotocol/ext-apps`
* still uses — into SDK v2's method-string form. Reads the `method` literal off
* the notification schema's `shape` (the shape both the v1 SDK and v2 core
* schemas expose).
*/
function notificationMethodFromSchema(schema: unknown): string | undefined {
if (schema !== null && typeof schema === "object") {
const literal = (schema as { shape?: { method?: { value?: unknown } } })
.shape?.method?.value;
if (typeof literal === "string") return literal;
}
return undefined;
}
/**
* The descriptor for a single tools/call, threaded through the retry loop and
* each attempt. Bundled into one object so `callToolWithRetries`/`attemptToolCall`
@ -488,7 +470,6 @@ export class InspectorClient extends InspectorClientEventTarget {
*/
private static readonly MRTR_MAX_ROUNDS = 10;
private client: Client | null = null;
private appRendererClientProxy: AppRendererClient | null = null;
// Lazily-built validator used only on the skipOutputValidation path to detect
// (non-fatally) when a delivered result violates the tool's outputSchema.
private outputValidator: AjvJsonSchemaValidator | null = null;
@ -1017,7 +998,6 @@ export class InspectorClient extends InspectorClientEventTarget {
this.rootsListChangedCapabilityAdvertised =
capabilities.roots?.listChanged === true;
this.appRendererClientProxy = null;
this.clientInfo = options.clientIdentity ?? {
name: corePackageJson.name.split("/")[1] ?? corePackageJson.name,
version: corePackageJson.version,
@ -2612,7 +2592,6 @@ export class InspectorClient extends InspectorClientEventTarget {
this.activeToolCallAbortController?.abort("Disconnected");
this.activeToolCallAbortController = undefined;
this.clearReceiverTasks();
this.appRendererClientProxy = null;
this.capabilities = undefined;
this.serverInfo = undefined;
this.instructions = undefined;
@ -2644,44 +2623,19 @@ export class InspectorClient extends InspectorClientEventTarget {
}
/**
* Returns a client proxy for use by AppRenderer / @mcp-ui. Delegates to the
* internal MCP Client. Returns null when not connected. Use this instead of
* accessing the raw client so behavior can be adapted here later if needed.
* The SDK client for the MCP Apps host bridge, or null when not connected.
*
* ext-apps' `AppBridge` (2.0.0+, an SDK v2 peer) takes the v2 `Client`
* directly and registers its list-changed forwarding on it in the
* method-string form, so this hands out the real client. The Proxy that
* translated the 1.x peer's schema-first `setNotificationHandler(Schema,
* handler)` into that form is gone with it (#1745). Kept as the seam rather
* than exposing the field so the connected-status gate lives in one place
* and hooks, fakes and tests depend on the protocol, not the class.
*/
getAppRendererClient(): AppRendererClient | null {
if (!this.client || this.status !== "connected") return null;
if (this.appRendererClientProxy !== null)
return this.appRendererClientProxy;
const target = this.client;
this.appRendererClientProxy = new Proxy(this.client, {
get(proxyTarget, prop, receiver) {
const value = Reflect.get(proxyTarget, prop, receiver);
if (prop === "setNotificationHandler" && typeof value === "function") {
return (schemaOrMethod: unknown, ...rest: unknown[]) => {
// `@modelcontextprotocol/ext-apps` still peers on SDK v1 and
// subscribes to list-changed notifications with the v1 schema-first
// API `setNotificationHandler(NotificationSchema, handler)`. SDK v2
// requires a method STRING as the first argument and throws
// "'[object Object]' is not a spec notification method" on a schema —
// which broke App rendering during the initial connect handshake.
// Translate a schema-first call to the method-string form; native
// string-first calls (ours) pass through untouched. Remove when
// ext-apps#702 ships a v2 peer.
const method =
typeof schemaOrMethod === "string"
? schemaOrMethod
: (notificationMethodFromSchema(schemaOrMethod) ??
schemaOrMethod);
return (value as (...a: unknown[]) => unknown).apply(target, [
method,
...rest,
]);
};
}
return value;
},
}) as AppRendererClient;
return this.appRendererClientProxy;
return this.client;
}
/**

11
core/mcp/inspectorClientProtocol.ts
View file

@ -25,6 +25,7 @@ import type {
} from "./types.js";
import type {
CacheMode,
Client,
ClientCapabilities,
DiscoverResult,
Implementation,
@ -47,11 +48,13 @@ import type { SamplingCreateMessage } from "./samplingCreateMessage.js";
import type { ElicitationCreateMessage } from "./elicitationCreateMessage.js";
/**
* Opaque type representing the AppRendererClient surface used by @mcp-ui.
* v1.5 aliases this to the SDK `Client` type; v2 leaves it opaque until the
* real InspectorClient (or a focused App-renderer port) lands.
* The SDK `Client` the MCP Apps host bridge is built over. ext-apps'
* `AppBridge` takes it directly and forwards a running app's
* tools/resources/prompts calls (and list-changed notifications) through it.
* Since ext-apps 2.0.0 peers on SDK v2 this is the real client with nothing in
* between — the v1-peer translation proxy it used to name is gone (#1745).
*/
export type AppRendererClient = unknown;
export type AppRendererClient = Client;
/**
* The contract every state manager and hook depends on. Anything that holds