refactor: eliminate sdk-compat.ts via isSpecType() (typescript-sdk#1887)

- spec.types.ts: import RequestId from @modelcontextprotocol/client (already public)
- app.ts/app-bridge.ts: replace pass-through *Schema shims with z.custom<T>(v => isSpecType('T', v))
- generate-schemas.ts: emit isSpecType-backed z.custom for external SDK types instead of importing from sdk-compat
- delete src/sdk-compat.ts

Friction surfaced: ExtensionHandle.setRequestHandler/sendRequest accept AnySchema (Zod-only),
so specTypeSchema()'s StandardSchemaV1 return cannot be passed directly. Wrapped via
z.custom(isSpecType) instead. #1868 should widen the param type to StandardSchemaV1 | AnySchema.

Author: felixweinberger

docs/quickstart.md

@@ -242,7 +242,7 @@ export function createServer(): McpServer {
 ```ts source="../examples/quickstart/main.ts"
 import { createMcpExpressApp } from "@modelcontextprotocol/express";
 import type { McpServer } from "@modelcontextprotocol/server";
-import { StdioServerTransport } from "@modelcontextprotocol/server";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import { NodeStreamableHTTPServerTransport as StreamableHTTPServerTransport } from "@modelcontextprotocol/node";
 import cors from "cors";
 import type { Request, Response } from "express";

package-lock.json

@@ -7,7 +7,7 @@
   "homepage": "https://github.com/modelcontextprotocol/ext-apps",
   "version": "1.5.0",
   "license": "MIT",
-  "description": "MCP Apps SDK \u2014 Enable MCP servers to display interactive user interfaces in conversational clients.",
+  "description": "MCP Apps SDK — Enable MCP servers to display interactive user interfaces in conversational clients.",
   "type": "module",
   "engines": {
     "node": ">=20"
@@ -77,6 +77,10 @@
   "author": "Olivier Chafik",
   "devDependencies": {
     "@boneskull/typedoc-plugin-mermaid": "^0.2.0",
+    "@modelcontextprotocol/client": "file:../../../../../tmp/modelcontextprotocol-client-2.0.0-alpha.2.tgz",
+    "@modelcontextprotocol/express": "file:../../../../../tmp/modelcontextprotocol-express-2.0.0-alpha.2.tgz",
+    "@modelcontextprotocol/node": "file:../../../../../tmp/modelcontextprotocol-node-2.0.0-alpha.2.tgz",
+    "@modelcontextprotocol/server": "file:../../../../../tmp/modelcontextprotocol-server-2.0.0-alpha.2.tgz",
     "@playwright/test": "1.57.0",
     "@types/bun": "^1.3.2",
     "@types/node": "20.19.27",
@@ -104,18 +108,14 @@
     "typedoc": "^0.28.14",
     "typedoc-github-theme": "^0.4.0",
     "typescript": "^5.9.3",
-    "zod": "^4.1.13",
-    "@modelcontextprotocol/client": "file:/tmp/modelcontextprotocol-client-2.0.0-alpha.2.tgz",
-    "@modelcontextprotocol/server": "file:/tmp/modelcontextprotocol-server-2.0.0-alpha.2.tgz",
-    "@modelcontextprotocol/express": "file:/tmp/modelcontextprotocol-express-2.0.0-alpha.2.tgz",
-    "@modelcontextprotocol/node": "file:/tmp/modelcontextprotocol-node-2.0.0-alpha.2.tgz"
+    "zod": "^4.1.13"
   },
   "peerDependencies": {
+    "@modelcontextprotocol/client": "file:../../../../../tmp/modelcontextprotocol-client-2.0.0-alpha.2.tgz",
+    "@modelcontextprotocol/server": "file:../../../../../tmp/modelcontextprotocol-server-2.0.0-alpha.2.tgz",
     "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
     "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0",
-    "zod": "^3.25.0 || ^4.0.0",
-    "@modelcontextprotocol/client": "^2.0.0-alpha",
-    "@modelcontextprotocol/server": "^2.0.0-alpha"
+    "zod": "^3.25.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {
     "react": {

package.json

@@ -187,20 +187,22 @@ function postProcess(content: string): string {
   // 1. Rewrite to zod/v4 and add MCP SDK schema imports.
   // zod/v4 aligns with the SDK's own zod import — composing v3 and v4
   // schema instances throws at parse time. See header comment for details.
-  const mcpImports = EXTERNAL_TYPE_SCHEMAS.join(",\n  ");
+  const typeImports = EXTERNAL_TYPE_SCHEMAS.map((s) =>
+    s.replace(/Schema$/, ""),
+  ).join(", ");
   content = content.replace(
     'import { z } from "zod";',
     `import { z } from "zod/v4";
-import {
-  ${mcpImports},
-} from "../sdk-compat.js";`,
+import { isSpecType } from "@modelcontextprotocol/client";
+import type { ${typeImports} } from "@modelcontextprotocol/client";`,
   );
 
-  // 2. Remove z.any() placeholders for external types (now imported from MCP SDK)
+  // 2. Replace z.any() placeholders for external SDK types with isSpecType-backed z.custom
   for (const schema of EXTERNAL_TYPE_SCHEMAS) {
+    const typeName = schema.replace(/Schema$/, "");
     content = content.replace(
-      new RegExp(`(?:export )?const ${schema} = z\\.any\\(\\);\\n?`, "g"),
-      "",
+      new RegExp(`((?:export )?const ${schema}) = z\\.any\\(\\);`, "g"),
+      `$1 = z.custom<${typeName}>((v) => isSpecType("${typeName}", v));`,
     );
   }
 

scripts/generate-schemas.ts

@@ -26,10 +26,7 @@ import {
 } from "@modelcontextprotocol/server";
 
 import { EventDispatcher } from "./events";
-import {
-  CallToolResultSchema,
-  ListToolsResultSchema,
-} from "./sdk-compat";
+import { isSpecType } from "@modelcontextprotocol/server";
 import {
   LATEST_PROTOCOL_VERSION,
   McpUiAppCapabilities,
@@ -637,7 +634,7 @@ export class AppBridge extends EventDispatcher<AppBridgeEventMap> {
     return this.ui.sendRequest(
       "ui/call-view-tool",
       params,
-      CallToolResultSchema,
+      z.custom<CallToolResult>((v) => isSpecType("CallToolResult", v)),
       options,
     );
   }
@@ -651,7 +648,7 @@ export class AppBridge extends EventDispatcher<AppBridgeEventMap> {
     return this.ui.sendRequest(
       "ui/list-view-tools",
       params,
-      ListToolsResultSchema,
+      z.custom<ListToolsResult>((v) => isSpecType("ListToolsResult", v)),
       options,
     );
   }

src/app-bridge.ts

@@ -20,13 +20,8 @@ import {
 import { EventDispatcher } from "./events";
 export { EventDispatcher, ProtocolWithEvents } from "./events";
 import { PostMessageTransport } from "./message-transport";
-import {
-  CallToolRequestParamsSchema,
-  CallToolResultSchema,
-  EmptyResultSchema,
-  ListToolsRequestParamsSchema,
-  ListToolsResultSchema,
-} from "./sdk-compat";
+import { isSpecType } from "@modelcontextprotocol/client";
+import { z } from "zod/v4";
 import {
   LATEST_PROTOCOL_VERSION,
   McpUiAppCapabilities,
@@ -231,15 +226,19 @@ export class App extends EventDispatcher<AppEventMap> {
     // Non-spec host→iframe tool surface (renamed from tools/call & tools/list).
     this.ui.setRequestHandler(
       "ui/call-view-tool",
-      CallToolRequestParamsSchema,
+      z.custom<CallToolRequest["params"]>((v) =>
+        isSpecType("CallToolRequestParams", v),
+      ),
       async (params, ctx) => {
         if (!this._oncalltool) throw new Error("No oncalltool handler set");
         return this._oncalltool(params, toExtra(ctx));
       },
     );
     this.ui.setRequestHandler(
       "ui/list-view-tools",
-      ListToolsRequestParamsSchema,
+      z.custom<ListToolsRequest["params"]>((v) =>
+        v === undefined || isSpecType("PaginatedRequestParams", v),
+      ),
       async (params, ctx) => {
         if (!this._onlisttools) throw new Error("No onlisttools handler set");
         return this._onlisttools(params, toExtra(ctx));
@@ -431,7 +430,7 @@ export class App extends EventDispatcher<AppEventMap> {
     return this.ui.sendRequest(
       "ui/update-model-context",
       params,
-      EmptyResultSchema,
+      z.custom<Record<string, never>>((v) => isSpecType("EmptyResult", v)),
       options,
     );
   }

src/app.ts

@@ -10,8 +10,8 @@
  * @see https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx
  */
 
-import type { RequestId } from "./sdk-compat.js";
 import type {
+  RequestId,
   CallToolResult,
   ContentBlock,
   EmbeddedResource,