fix: add Zod v3/v4 compatibility for MCP SDK 1.23.0

MCP SDK 1.23.0 now supports both Zod v3 and v4, which have different
internal structures. This caused context parameter injection to fail.

Changes:
- Add zod-compat.ts with version-agnostic detection and utilities
- Update context-parameters.ts to use zod-compat utilities
- Update tracingV2.ts to use zod-compat for schema shape access
- Update Zod dependency to support both v3 and v4
- Add comprehensive tests for zod-compat utilities

Tested with MCP SDK versions 1.21.2 and 1.23.0.

Author: naji247

package.json

@@ -54,7 +54,7 @@
   "packageManager": "pnpm@10.11.0",
   "devDependencies": {
     "@changesets/cli": "^2.29.4",
-    "@modelcontextprotocol/sdk": "1.11",
+    "@modelcontextprotocol/sdk": "~1.23.0",
     "@types/node": "^22.15.21",
     "@typescript-eslint/eslint-plugin": "^8.32.1",
     "@typescript-eslint/parser": "^8.32.1",
@@ -75,7 +75,7 @@
     "@opentelemetry/otlp-transformer": "^0.203.0",
     "mcpcat-api": "0.1.6",
     "redact-pii": "3.4.0",
-    "zod": "3.25.30"
+    "zod": "^3.25 || ^4.0"
   },
   "lint-staged": {
     "*.{ts,js}": [

pnpm-lock.yaml

@@ -1,26 +1,12 @@
 import { RegisteredTool } from "../types";
 import { z } from "zod";
 import { DEFAULT_CONTEXT_PARAMETER_DESCRIPTION } from "./constants";
-
-// Detect if something is a Zod schema (has _def and parse methods)
-function isZodSchema(schema: any): boolean {
-  return (
-    schema &&
-    typeof schema === "object" &&
-    "_def" in schema &&
-    typeof schema.parse === "function"
-  );
-}
-
-// Detect if it's shorthand Zod syntax (object with z.* values)
-function isShorthandZodSyntax(schema: any): boolean {
-  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
-    return false;
-  }
-
-  // Check if any value is a Zod schema
-  return Object.values(schema).some((value) => isZodSchema(value));
-}
+import {
+  isZodSchema,
+  isShorthandZodSyntax,
+  schemaHasProperty,
+  extendObjectSchema,
+} from "./zod-compat";
 
 export function addContextParameterToTool(
   tool: RegisteredTool,
@@ -43,36 +29,25 @@ export function addContextParameterToTool(
     return modifiedTool;
   }
 
-  // Handle Zod z.object() schemas
+  const contextDescription =
+    customContextDescription || DEFAULT_CONTEXT_PARAMETER_DESCRIPTION;
+
+  // Handle Zod z.object() schemas (both v3 and v4)
   if (isZodSchema(modifiedTool.inputSchema)) {
     // Check if context already exists in Zod schema shape
-    if (
-      modifiedTool.inputSchema.shape &&
-      "context" in modifiedTool.inputSchema.shape
-    ) {
+    if (schemaHasProperty(modifiedTool.inputSchema, "context")) {
       return modifiedTool;
     }
-    // It's a Zod schema, augment it with context
-    const contextSchema = z.object({
-      context: z
-        .string()
-        .describe(
-          customContextDescription || DEFAULT_CONTEXT_PARAMETER_DESCRIPTION,
-        ),
-    });
-
-    // Use extend to add context to the schema
-    if (typeof modifiedTool.inputSchema.extend === "function") {
-      modifiedTool.inputSchema = modifiedTool.inputSchema.extend(
-        contextSchema.shape,
-      );
-    } else if (typeof modifiedTool.inputSchema.augment === "function") {
-      modifiedTool.inputSchema =
-        modifiedTool.inputSchema.augment(contextSchema);
-    } else {
-      // Fallback: merge with new z.object
-      modifiedTool.inputSchema = contextSchema.merge(modifiedTool.inputSchema);
-    }
+
+    // Extend the schema with context using our compat layer
+    const contextShape = {
+      context: z.string().describe(contextDescription),
+    };
+
+    modifiedTool.inputSchema = extendObjectSchema(
+      modifiedTool.inputSchema,
+      contextShape,
+    );
 
     return modifiedTool;
   }
@@ -84,18 +59,15 @@ export function addContextParameterToTool(
       return modifiedTool;
     }
 
-    // Create a new Zod schema with context
-    const contextField = z
-      .string()
-      .describe(
-        customContextDescription || DEFAULT_CONTEXT_PARAMETER_DESCRIPTION,
-      );
+    // Extend using our compat layer (handles both v3 and v4)
+    const contextShape = {
+      context: z.string().describe(contextDescription),
+    };
 
-    // Create new z.object with context and all original fields
-    modifiedTool.inputSchema = z.object({
-      context: contextField,
-      ...modifiedTool.inputSchema,
-    });
+    modifiedTool.inputSchema = extendObjectSchema(
+      modifiedTool.inputSchema,
+      contextShape,
+    );
 
     return modifiedTool;
   }
@@ -115,8 +87,7 @@ export function addContextParameterToTool(
 
     modifiedTool.inputSchema.properties.context = {
       type: "string",
-      description:
-        customContextDescription || DEFAULT_CONTEXT_PARAMETER_DESCRIPTION,
+      description: contextDescription,
     };
 
     // Add context to required array if it exists

src/modules/context-parameters.ts

@@ -14,6 +14,7 @@ import { PublishEventRequestEventTypeEnum } from "mcpcat-api";
 import { publishEvent } from "./eventQueue.js";
 import { addContextParameterToTool } from "./context-parameters.js";
 import { handleReportMissing } from "./tools.js";
+import { getObjectShape, getLiteralValue } from "./zod-compat.js";
 import { setupInitializeTracing, setupListToolsTracing } from "./tracing.js";
 import { captureException } from "./exceptions.js";
 
@@ -332,7 +333,8 @@ function setupToolsCallHandlerWrapping(server: HighLevelMCPServerLike): void {
     requestSchema: any,
     handler: any,
   ) {
-    const method = requestSchema?.shape?.method?.value;
+    const shape = getObjectShape(requestSchema);
+    const method = shape?.method ? getLiteralValue(shape.method) : undefined;
 
     // Only wrap tools/call handler
     if (method === "tools/call") {