Merge origin/fweinberger/v2-bc-register-rawshape into v2-bc-d1-base

Author: felixweinberger

.changeset/register-rawshape-compat.md

@@ -0,0 +1,6 @@
+---
+'@modelcontextprotocol/core': patch
+'@modelcontextprotocol/server': patch
+---
+
+v1-compat: `registerTool`/`registerPrompt` accept a raw Zod shape (`{ field: z.string() }`) for `inputSchema`/`outputSchema`/`argsSchema` again. The shape is auto-wrapped in `z.object()` and a one-time deprecation warning is emitted. Wrap in `z.object({...})` to silence the warning; the shim will be removed in v3.

packages/core/src/util/standardSchema.ts

@@ -6,6 +6,9 @@
 
 /* eslint-disable @typescript-eslint/no-namespace */
 
+import * as z from 'zod/v4';
+import { deprecate } from './deprecate.js';
+
 // Standard Schema interfaces — vendored from https://standardschema.dev (spec v1, Jan 2025)
 
 export interface StandardTypedV1<Input = unknown, Output = Input> {
@@ -136,6 +139,42 @@ export function isStandardSchemaWithJSON(schema: unknown): schema is StandardSch
     return isStandardJSONSchema(schema) && isStandardSchema(schema);
 }
 
+/**
+ * Detects a "raw shape" — a plain object whose values are Zod (or other
+ * Standard Schema) field schemas, e.g. `{ name: z.string() }`. v1 accepted
+ * this shorthand directly; v2 expects `z.object({...})`. This guard powers
+ * the deprecated auto-wrap shim in {@linkcode normalizeRawShapeSchema}.
+ *
+ * @internal
+ */
+export function isZodRawShape(obj: unknown): obj is Record<string, StandardSchemaV1> {
+    if (typeof obj !== 'object' || obj === null) return false;
+    if (isStandardSchema(obj)) return false;
+    const values = Object.values(obj);
+    return values.length > 0 && values.every(v => isStandardSchema(v) || (typeof v === 'object' && v !== null && '_def' in v));
+}
+
+/**
+ * v1-compat shim: if a tool/prompt was registered with the v1 raw-shape
+ * shorthand `{ field: z.string() }`, wrap it in `z.object()` so the rest of
+ * the pipeline sees a {@linkcode StandardSchemaWithJSON}. Passes through
+ * already-wrapped schemas unchanged. Warns once per process.
+ *
+ * @internal
+ */
+export function normalizeRawShapeSchema(schema: unknown): StandardSchemaWithJSON | undefined {
+    if (schema === undefined) return undefined;
+    if (isZodRawShape(schema)) {
+        deprecate(
+            'raw-shape',
+            'Passing a raw shape like `{ field: z.string() }` as inputSchema/argsSchema is deprecated. ' +
+                'Wrap it in z.object({...}) (or your schema library equivalent). Auto-wrapping for now; this shim will be removed in v3.'
+        );
+        return z.object(schema as z.core.$ZodLooseShape) as StandardSchemaWithJSON;
+    }
+    return schema as StandardSchemaWithJSON;
+}
+
 // JSON Schema conversion
 
 /**

packages/server/src/server/mcp.ts

@@ -32,6 +32,7 @@ import {
     assertCompleteRequestResourceTemplate,
     deprecate,
     isStandardSchema,
+    normalizeRawShapeSchema,
     promptArgumentsFromStandardSchema,
     ProtocolError,
     ProtocolErrorCode,
@@ -876,6 +877,31 @@ export class McpServer {
             _meta?: Record<string, unknown>;
         },
         cb: ToolCallback<InputArgs>
+    ): RegisteredTool;
+    /** @deprecated Pass a Standard Schema (e.g. wrap your raw shape in `z.object({...})`). Raw-shape inputs are auto-wrapped at runtime. Removed in v3. */
+    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`);
@@ -887,8 +913,8 @@ export class McpServer {
             name,
             title,
             description,
-            inputSchema,
-            outputSchema,
+            normalizeRawShapeSchema(inputSchema),
+            normalizeRawShapeSchema(outputSchema),
             annotations,
             { taskSupport: 'forbidden' },
             _meta,
@@ -931,6 +957,27 @@ export class McpServer {
             _meta?: Record<string, unknown>;
         },
         cb: PromptCallback<Args>
+    ): RegisteredPrompt;
+    /** @deprecated Pass a Standard Schema (e.g. wrap your raw shape in `z.object({...})`). Raw-shape inputs are auto-wrapped at runtime. Removed in v3. */
+    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`);
@@ -942,7 +989,7 @@ export class McpServer {
             name,
             title,
             description,
-            argsSchema,
+            normalizeRawShapeSchema(argsSchema),
             cb as PromptCallback<StandardSchemaWithJSON | undefined>,
             _meta
         );

packages/server/test/server/mcp.compat.test.ts

@@ -1,7 +1,9 @@
 /* eslint-disable @typescript-eslint/no-deprecated */
-import { _resetDeprecationWarnings } from '@modelcontextprotocol/core';
-import { z } from 'zod';
-import { McpServer, ResourceTemplate } from '../../src/server/mcp.js';
+import { _resetDeprecationWarnings, isStandardSchema } from '@modelcontextprotocol/core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import * as z from 'zod/v4';
+import { McpServer } from '../../src/index.js';
+import { ResourceTemplate } from '../../src/server/mcp.js';
 
 describe('McpServer v1-compat variadic shims', () => {
     let warnSpy: ReturnType<typeof vi.spyOn>;
@@ -22,13 +24,11 @@ describe('McpServer v1-compat variadic shims', () => {
             server.tool('x', { a: z.string() }, ({ a }) => ({ content: [{ type: 'text', text: a }] }));
             server.tool('y', { b: z.number() }, ({ b }) => ({ content: [{ type: 'text', text: String(b) }] }));
 
-            // both registered
             // @ts-expect-error private access for test
             expect(server._registeredTools['x']).toBeDefined();
             // @ts-expect-error private access for test
             expect(server._registeredTools['y']).toBeDefined();
 
-            // deprecation warned exactly once for the .tool() shim
             const toolWarnings = warnSpy.mock.calls.filter((c: unknown[]) => String(c[0]).includes('McpServer.tool()'));
             expect(toolWarnings).toHaveLength(1);
         });
@@ -88,3 +88,59 @@ describe('McpServer v1-compat variadic shims', () => {
         });
     });
 });
+
+describe('v1 compat: registerTool/registerPrompt raw-shape auto-wrap', () => {
+    beforeEach(() => {
+        _resetDeprecationWarnings();
+    });
+
+    it('registerTool accepts a raw shape for inputSchema, auto-wraps, and warns once', () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const server = new McpServer({ name: 't', version: '1.0.0' });
+
+        server.registerTool('a', { inputSchema: { x: z.number() } }, async ({ x }) => ({
+            content: [{ type: 'text' as const, text: String(x) }]
+        }));
+        server.registerTool('b', { inputSchema: { y: z.number() } }, async ({ y }) => ({
+            content: [{ type: 'text' as const, text: String(y) }]
+        }));
+
+        const tools = (server as unknown as { _registeredTools: Record<string, { inputSchema?: unknown }> })._registeredTools;
+        expect(Object.keys(tools)).toEqual(['a', 'b']);
+        expect(isStandardSchema(tools['a']?.inputSchema)).toBe(true);
+
+        const rawShapeWarns = warn.mock.calls.filter(c => String(c[0]).includes('raw shape'));
+        expect(rawShapeWarns.length).toBe(1);
+        warn.mockRestore();
+    });
+
+    it('registerTool with z.object() inputSchema does not warn', () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const server = new McpServer({ name: 't', version: '1.0.0' });
+
+        server.registerTool('c', { inputSchema: z.object({ x: z.number() }) }, async ({ x }) => ({
+            content: [{ type: 'text' as const, text: String(x) }]
+        }));
+
+        const rawShapeWarns = warn.mock.calls.filter(c => String(c[0]).includes('raw shape'));
+        expect(rawShapeWarns.length).toBe(0);
+        warn.mockRestore();
+    });
+
+    it('registerPrompt accepts a raw shape for argsSchema and warns', () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const server = new McpServer({ name: 't', version: '1.0.0' });
+
+        server.registerPrompt('p', { argsSchema: { topic: z.string() } }, async ({ topic }) => ({
+            messages: [{ role: 'user' as const, content: { type: 'text' as const, text: topic } }]
+        }));
+
+        const prompts = (server as unknown as { _registeredPrompts: Record<string, { argsSchema?: unknown }> })._registeredPrompts;
+        expect(Object.keys(prompts)).toContain('p');
+        expect(isStandardSchema(prompts['p']?.argsSchema)).toBe(true);
+
+        const rawShapeWarns = warn.mock.calls.filter(c => String(c[0]).includes('raw shape'));
+        expect(rawShapeWarns.length).toBe(1);
+        warn.mockRestore();
+    });
+});