feat(compat): registerTool/registerPrompt accept raw Zod shape, auto-wrap with z.object()

.changeset/register-rawshape-compat.md

@@ -0,0 +1,8 @@
+---
+'@modelcontextprotocol/core': patch
+'@modelcontextprotocol/server': patch
+---
+
+`registerTool`/`registerPrompt` accept a raw Zod shape (`{ field: z.string() }`) for `inputSchema`/`outputSchema`/`argsSchema` in addition to a wrapped Standard Schema. Raw shapes are auto-wrapped with `z.object()`. The raw-shape overloads are `@deprecated`; prefer wrapping with `z.object()`.
+
+Also widens the `completable()` constraint from `StandardSchemaWithJSON` to `StandardSchemaV1` so v1's `completable(z.string(), fn)` continues to work.

packages/core/src/index.ts

@@ -15,6 +15,7 @@ export * from './types/index.js';
 export * from './util/inMemory.js';
 export * from './util/schema.js';
 export * from './util/standardSchema.js';
+export * from './util/zodCompat.js';
 
 // experimental exports
 export * from './experimental/index.js';

packages/core/src/util/zodCompat.ts

@@ -0,0 +1,72 @@
+/**
+ * Zod-specific helpers for the v1-compat raw-shape shorthand on
+ * `registerTool`/`registerPrompt`. Kept separate from `standardSchema.ts` so
+ * that file stays library-agnostic per the Standard Schema spec.
+ */
+
+import * as z from 'zod/v4';
+
+import type { StandardSchemaWithJSON } from './standardSchema.js';
+import { isStandardSchema, isStandardSchemaWithJSON } from './standardSchema.js';
+
+function isZodV4Schema(v: unknown): v is z.ZodType {
+    // `_zod` is the v4 internal namespace property. Zod v3 schemas have `_def`
+    // and (since 3.24) `~standard.vendor === 'zod'`, but never `_zod`. We require
+    // v4 because the wrap path below uses v4's `z.object()`, which cannot consume
+    // v3 field schemas.
+    return typeof v === 'object' && v !== null && '_zod' in v;
+}
+
+function looksLikeZodV3(v: unknown): boolean {
+    // v3 schemas have `_def.typeName` (e.g. 'ZodString') and no `_zod`.
+    return (
+        typeof v === 'object' &&
+        v !== null &&
+        !('_zod' in v) &&
+        '_def' in v &&
+        typeof (v as { _def?: { typeName?: unknown } })._def?.typeName === 'string'
+    );
+}
+
+/**
+ * Detects a "raw shape" — a plain object whose values are Zod field schemas,
+ * e.g. `{ name: z.string() }`. Powers the auto-wrap in
+ * {@linkcode normalizeRawShapeSchema}, which wraps with `z.object()`, so only
+ * Zod values are supported.
+ *
+ * @internal
+ */
+export function isZodRawShape(obj: unknown): obj is Record<string, z.ZodType> {
+    if (typeof obj !== 'object' || obj === null) return false;
+    if (isStandardSchema(obj)) return false;
+    // [].every() is true, so an empty object is a valid raw shape (matches v1).
+    return Object.values(obj).every(v => isZodV4Schema(v));
+}
+
+/**
+ * Accepts either a {@linkcode StandardSchemaWithJSON} or a raw Zod shape
+ * `{ field: z.string() }` and returns a {@linkcode StandardSchemaWithJSON}.
+ * Raw shapes are wrapped with `z.object()` so the rest of the pipeline sees a
+ * uniform schema type; already-wrapped schemas pass through unchanged.
+ *
+ * @internal
+ */
+export function normalizeRawShapeSchema(
+    schema: StandardSchemaWithJSON | Record<string, z.ZodType> | undefined
+): StandardSchemaWithJSON | undefined {
+    if (schema === undefined) return undefined;
+    if (isZodRawShape(schema)) {
+        return z.object(schema) as StandardSchemaWithJSON;
+    }
+    if (typeof schema === 'object' && !isStandardSchema(schema) && Object.values(schema).some(v => looksLikeZodV3(v))) {
+        throw new TypeError(
+            'Raw-shape inputSchema/outputSchema/argsSchema fields must be Zod v4 schemas. Got a Zod v3 field schema. Import from `zod/v4` (or upgrade your zod import), or wrap with `z.object({...})` yourself.'
+        );
+    }
+    if (!isStandardSchemaWithJSON(schema)) {
+        throw new TypeError(
+            'inputSchema/outputSchema/argsSchema must be a Standard Schema with JSON Schema export (`~standard.jsonSchema`, e.g. z.object({...}) from zod >=4.2.0) or a raw Zod shape ({ field: z.string() }).'
+        );
+    }
+    return schema;
+}

packages/core/test/util/zodCompat.test.ts

@@ -0,0 +1,58 @@
+import * as z from 'zod/v4';
+
+import { standardSchemaToJsonSchema } from '../../src/util/standardSchema.js';
+import { isZodRawShape, normalizeRawShapeSchema } from '../../src/util/zodCompat.js';
+
+describe('isZodRawShape', () => {
+    test('treats empty object as a raw shape (matches v1)', () => {
+        expect(isZodRawShape({})).toBe(true);
+    });
+    test('detects raw shape with zod fields', () => {
+        expect(isZodRawShape({ a: z.string() })).toBe(true);
+    });
+    test('rejects a Standard Schema instance', () => {
+        expect(isZodRawShape(z.object({ a: z.string() }))).toBe(false);
+    });
+    test('rejects a shape with non-Zod Standard Schema fields', () => {
+        const nonZod = { '~standard': { version: 1, vendor: 'arktype', validate: () => ({ value: 'x' }) } };
+        expect(isZodRawShape({ a: nonZod })).toBe(false);
+    });
+    test('rejects a shape with Zod v3 fields (only v4 is wrappable)', () => {
+        expect(isZodRawShape({ a: mockZodV3String() })).toBe(false);
+    });
+});
+
+// Minimal structural mock of a Zod v3 schema: has `_def.typeName` and
+// `~standard.vendor === 'zod'` (zod >=3.24), but no `_zod`.
+function mockZodV3String(): unknown {
+    return {
+        _def: { typeName: 'ZodString', checks: [], coerce: false },
+        '~standard': { version: 1, vendor: 'zod', validate: (v: unknown) => ({ value: v }) },
+        parse: (v: unknown) => v
+    };
+}
+
+describe('normalizeRawShapeSchema', () => {
+    test('wraps empty raw shape into z.object({})', () => {
+        const wrapped = normalizeRawShapeSchema({});
+        expect(wrapped).toBeDefined();
+        expect(standardSchemaToJsonSchema(wrapped!, 'input').type).toBe('object');
+    });
+    test('passes through an already-wrapped Standard Schema unchanged', () => {
+        const schema = z.object({ a: z.string() });
+        expect(normalizeRawShapeSchema(schema)).toBe(schema);
+    });
+    test('returns undefined for undefined input', () => {
+        expect(normalizeRawShapeSchema(undefined)).toBeUndefined();
+    });
+    test('throws TypeError for an invalid object that is neither raw shape nor Standard Schema', () => {
+        expect(() => normalizeRawShapeSchema({ a: 'not a zod schema' } as never)).toThrow(TypeError);
+    });
+    test('throws TypeError for a Standard Schema without JSON Schema export', () => {
+        const noJson = { '~standard': { version: 1, vendor: 'x', validate: () => ({ value: {} }) } };
+        expect(() => normalizeRawShapeSchema(noJson as never)).toThrow(/~standard\.jsonSchema/);
+    });
+    test('throws actionable TypeError for a raw shape with Zod v3 fields', () => {
+        expect(() => normalizeRawShapeSchema({ a: mockZodV3String() } as never)).toThrow(/Zod v4 schemas.*Got a Zod v3 field schema/);
+    });
+});

packages/server/src/server/completable.ts

@@ -1,19 +1,19 @@
-import type { StandardSchemaWithJSON } from '@modelcontextprotocol/core';
+import type { StandardSchemaV1 } from '@modelcontextprotocol/core';
 
 export const COMPLETABLE_SYMBOL: unique symbol = Symbol.for('mcp.completable');
 
-export type CompleteCallback<T extends StandardSchemaWithJSON = StandardSchemaWithJSON> = (
-    value: StandardSchemaWithJSON.InferInput<T>,
+export type CompleteCallback<T extends StandardSchemaV1 = StandardSchemaV1> = (
+    value: StandardSchemaV1.InferInput<T>,
     context?: {
         arguments?: Record<string, string>;
     }
-) => StandardSchemaWithJSON.InferInput<T>[] | Promise<StandardSchemaWithJSON.InferInput<T>[]>;
+) => StandardSchemaV1.InferInput<T>[] | Promise<StandardSchemaV1.InferInput<T>[]>;
 
-export type CompletableMeta<T extends StandardSchemaWithJSON = StandardSchemaWithJSON> = {
+export type CompletableMeta<T extends StandardSchemaV1 = StandardSchemaV1> = {
     complete: CompleteCallback<T>;
 };
 
-export type CompletableSchema<T extends StandardSchemaWithJSON> = T & {
+export type CompletableSchema<T extends StandardSchemaV1> = T & {
     [COMPLETABLE_SYMBOL]: CompletableMeta<T>;
 };
 
@@ -48,7 +48,7 @@ export type CompletableSchema<T extends StandardSchemaWithJSON> = T & {
  *
  * @see {@linkcode server/mcp.McpServer.registerPrompt | McpServer.registerPrompt} for using completable schemas in prompt argument definitions
  */
-export function completable<T extends StandardSchemaWithJSON>(schema: T, complete: CompleteCallback<T>): CompletableSchema<T> {
+export function completable<T extends StandardSchemaV1>(schema: T, complete: CompleteCallback<T>): CompletableSchema<T> {
     Object.defineProperty(schema as object, COMPLETABLE_SYMBOL, {
         value: { complete } as CompletableMeta<T>,
         enumerable: false,
@@ -61,14 +61,14 @@ export function completable<T extends StandardSchemaWithJSON>(schema: T, complet
 /**
  * Checks if a schema is completable (has completion metadata).
  */
-export function isCompletable(schema: unknown): schema is CompletableSchema<StandardSchemaWithJSON> {
+export function isCompletable(schema: unknown): schema is CompletableSchema<StandardSchemaV1> {
     return !!schema && typeof schema === 'object' && COMPLETABLE_SYMBOL in (schema as object);
 }
 
 /**
  * Gets the completer callback from a completable schema, if it exists.
  */
-export function getCompleter<T extends StandardSchemaWithJSON>(schema: T): CompleteCallback<T> | undefined {
+export function getCompleter<T extends StandardSchemaV1>(schema: T): CompleteCallback<T> | undefined {
     const meta = (schema as unknown as { [COMPLETABLE_SYMBOL]?: CompletableMeta<T> })[COMPLETABLE_SYMBOL];
     return meta?.complete as CompleteCallback<T> | undefined;
 }

packages/server/src/server/mcp.ts

@@ -30,6 +30,7 @@ import type {
 import {
     assertCompleteRequestPrompt,
     assertCompleteRequestResourceTemplate,
+    normalizeRawShapeSchema,
     promptArgumentsFromStandardSchema,
     ProtocolError,
     ProtocolErrorCode,
@@ -39,6 +40,7 @@ import {
     validateStandardSchema
 } from '@modelcontextprotocol/core';
 
+import type * as z from 'zod/v4';
 import type { ToolTaskHandler } from '../experimental/tasks/interfaces.js';
 import { ExperimentalMcpServerTasks } from '../experimental/tasks/mcpServer.js';
 import { getCompleter, isCompletable } from './completable.js';
@@ -873,6 +875,31 @@ export class McpServer {
             _meta?: Record<string, unknown>;
         },
         cb: ToolCallback<InputArgs>
+    ): RegisteredTool;
+    /** @deprecated Wrap with `z.object({...})` instead. Raw-shape form: `inputSchema`/`outputSchema` may be a plain `{ field: z.string() }` record; it is auto-wrapped with `z.object()`. */
+    registerTool<InputArgs extends ZodRawShape, OutputArgs extends ZodRawShape | StandardSchemaWithJSON | undefined = undefined>(
+        name: string,
+        config: {
+            title?: string;
+            description?: string;
+            inputSchema?: InputArgs;
+            outputSchema?: OutputArgs;
+            annotations?: ToolAnnotations;
+            _meta?: Record<string, unknown>;
+        },
+        cb: LegacyToolCallback<InputArgs>
+    ): RegisteredTool;
+    registerTool(
+        name: string,
+        config: {
+            title?: string;
+            description?: string;
+            inputSchema?: StandardSchemaWithJSON | ZodRawShape;
+            outputSchema?: StandardSchemaWithJSON | ZodRawShape;
+            annotations?: ToolAnnotations;
+            _meta?: Record<string, unknown>;
+        },
+        cb: ToolCallback<StandardSchemaWithJSON | undefined> | LegacyToolCallback<ZodRawShape>
     ): RegisteredTool {
         if (this._registeredTools[name]) {
             throw new Error(`Tool ${name} is already registered`);
@@ -884,8 +911,8 @@ export class McpServer {
             name,
             title,
             description,
-            inputSchema,
-            outputSchema,
+            normalizeRawShapeSchema(inputSchema),
+            normalizeRawShapeSchema(outputSchema),
             annotations,
             { taskSupport: 'forbidden' },
             _meta,
@@ -928,6 +955,27 @@ export class McpServer {
             _meta?: Record<string, unknown>;
         },
         cb: PromptCallback<Args>
+    ): RegisteredPrompt;
+    /** @deprecated Wrap with `z.object({...})` instead. Raw-shape form: `argsSchema` may be a plain `{ field: z.string() }` record; it is auto-wrapped with `z.object()`. */
+    registerPrompt<Args extends ZodRawShape>(
+        name: string,
+        config: {
+            title?: string;
+            description?: string;
+            argsSchema?: Args;
+            _meta?: Record<string, unknown>;
+        },
+        cb: LegacyPromptCallback<Args>
+    ): RegisteredPrompt;
+    registerPrompt(
+        name: string,
+        config: {
+            title?: string;
+            description?: string;
+            argsSchema?: StandardSchemaWithJSON | ZodRawShape;
+            _meta?: Record<string, unknown>;
+        },
+        cb: PromptCallback<StandardSchemaWithJSON> | LegacyPromptCallback<ZodRawShape>
     ): RegisteredPrompt {
         if (this._registeredPrompts[name]) {
             throw new Error(`Prompt ${name} is already registered`);
@@ -939,7 +987,7 @@ export class McpServer {
             name,
             title,
             description,
-            argsSchema,
+            normalizeRawShapeSchema(argsSchema),
             cb as PromptCallback<StandardSchemaWithJSON | undefined>,
             _meta
         );
@@ -1062,6 +1110,26 @@ export class ResourceTemplate {
     }
 }
 
+/**
+ * A plain record of Zod field schemas, e.g. `{ name: z.string() }`. Accepted by
+ * `registerTool`/`registerPrompt` as a shorthand; auto-wrapped with `z.object()`.
+ * Zod schemas only — `z.object()` cannot wrap other Standard Schema libraries.
+ */
+export type ZodRawShape = Record<string, z.ZodType>;
+
+/** Infers the parsed-output type of a {@linkcode ZodRawShape}. */
+export type InferRawShape<S extends ZodRawShape> = z.infer<z.ZodObject<S>>;
+
+/** {@linkcode ToolCallback} variant used when `inputSchema` is a {@linkcode ZodRawShape}. */
+export type LegacyToolCallback<Args extends ZodRawShape | undefined> = Args extends ZodRawShape
+    ? (args: InferRawShape<Args>, ctx: ServerContext) => CallToolResult | Promise<CallToolResult>
+    : (ctx: ServerContext) => CallToolResult | Promise<CallToolResult>;
+
+/** {@linkcode PromptCallback} variant used when `argsSchema` is a {@linkcode ZodRawShape}. */
+export type LegacyPromptCallback<Args extends ZodRawShape | undefined> = Args extends ZodRawShape
+    ? (args: InferRawShape<Args>, ctx: ServerContext) => GetPromptResult | Promise<GetPromptResult>
+    : (ctx: ServerContext) => GetPromptResult | Promise<GetPromptResult>;
+
 export type BaseToolCallback<
     SendResultT extends Result,
     Ctx extends ServerContext,