feat(compat): restore McpServer.tool/.prompt/.resource variadic overloads as deprecated shims

Author: felixweinberger

.changeset/mcpserver-variadic-compat.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/server': patch
+---
+
+Restore `McpServer.tool()`, `.prompt()`, `.resource()` variadic overloads as `@deprecated` v1-compat shims forwarding to `registerTool`/`registerPrompt`/`registerResource`. Emits a one-time deprecation warning; removed in v3.

packages/core/src/index.ts

@@ -48,5 +48,5 @@ export * from './validators/fromJsonSchema.js';
  */
 
 // Core types only - implementations are exported via separate entry points
+export { _resetDeprecationWarnings, deprecate } from './util/deprecate.js';
 export type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator, JsonSchemaValidatorResult } from './validators/types.js';
-export { deprecate } from './util/deprecate.js';

packages/server/src/index.ts

@@ -12,6 +12,10 @@ export type {
     AnyToolHandler,
     BaseToolCallback,
     CompleteResourceTemplateCallback,
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    LegacyPromptCallback,
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    LegacyToolCallback,
     ListResourcesCallback,
     PromptCallback,
     ReadResourceCallback,
@@ -21,7 +25,9 @@ export type {
     RegisteredResourceTemplate,
     RegisteredTool,
     ResourceMetadata,
-    ToolCallback
+    ToolCallback,
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    ZodRawShape
 } from './server/mcp.js';
 export { McpServer, ResourceTemplate } from './server/mcp.js';
 export type { HostHeaderValidationResult } from './server/middleware/hostHeaderValidation.js';

packages/server/src/server/mcp.ts

@@ -30,6 +30,8 @@ import type {
 import {
     assertCompleteRequestPrompt,
     assertCompleteRequestResourceTemplate,
+    deprecate,
+    isStandardSchema,
     promptArgumentsFromStandardSchema,
     ProtocolError,
     ProtocolErrorCode,
@@ -38,6 +40,7 @@ import {
     validateAndWarnToolName,
     validateStandardSchema
 } from '@modelcontextprotocol/core';
+import { z } from 'zod';
 
 import type { ToolTaskHandler } from '../experimental/tasks/interfaces.js';
 import { ExperimentalMcpServerTasks } from '../experimental/tasks/mcpServer.js';
@@ -950,6 +953,135 @@ export class McpServer {
         return registeredPrompt;
     }
 
+    // ---------------------------------------------------------------------
+    // v1-compat variadic registration methods. Frozen at 2025-03-26 surface.
+    // ---------------------------------------------------------------------
+
+    /** @deprecated Use {@linkcode registerTool}. Removed in v3. */
+    tool(name: string, cb: LegacyToolCallback<undefined>): RegisteredTool;
+    /** @deprecated Use {@linkcode registerTool}. Removed in v3. */
+    tool(name: string, description: string, cb: LegacyToolCallback<undefined>): RegisteredTool;
+    /** @deprecated Use {@linkcode registerTool}. Removed in v3. */
+    tool<Args extends ZodRawShape>(
+        name: string,
+        paramsSchemaOrAnnotations: Args | ToolAnnotations,
+        cb: LegacyToolCallback<Args>
+    ): RegisteredTool;
+    /** @deprecated Use {@linkcode registerTool}. Removed in v3. */
+    tool<Args extends ZodRawShape>(
+        name: string,
+        description: string,
+        paramsSchemaOrAnnotations: Args | ToolAnnotations,
+        cb: LegacyToolCallback<Args>
+    ): RegisteredTool;
+    /** @deprecated Use {@linkcode registerTool}. Removed in v3. */
+    tool<Args extends ZodRawShape>(
+        name: string,
+        paramsSchema: Args,
+        annotations: ToolAnnotations,
+        cb: LegacyToolCallback<Args>
+    ): RegisteredTool;
+    /** @deprecated Use {@linkcode registerTool}. Removed in v3. */
+    tool<Args extends ZodRawShape>(
+        name: string,
+        description: string,
+        paramsSchema: Args,
+        annotations: ToolAnnotations,
+        cb: LegacyToolCallback<Args>
+    ): RegisteredTool;
+    tool(name: string, ...rest: unknown[]): RegisteredTool {
+        deprecate('McpServer.tool', 'McpServer.tool() is deprecated. Use registerTool(name, config, cb). Removed in v3.');
+
+        let description: string | undefined;
+        let inputSchema: StandardSchemaWithJSON | undefined;
+        let annotations: ToolAnnotations | undefined;
+
+        if (typeof rest[0] === 'string') description = rest.shift() as string;
+
+        if (rest.length > 1) {
+            const first = rest[0];
+            if (isZodRawShape(first) || isStandardSchema(first)) {
+                inputSchema = wrapRawShape(rest.shift());
+                if (
+                    rest.length > 1 &&
+                    typeof rest[0] === 'object' &&
+                    rest[0] !== null &&
+                    !isZodRawShape(rest[0]) &&
+                    !isStandardSchema(rest[0])
+                ) {
+                    annotations = rest.shift() as ToolAnnotations;
+                }
+            } else if (typeof first === 'object' && first !== null) {
+                annotations = rest.shift() as ToolAnnotations;
+            }
+        }
+
+        if (this._registeredTools[name]) {
+            throw new Error(`Tool ${name} is already registered`);
+        }
+        const cb = rest[0] as ToolCallback<StandardSchemaWithJSON | undefined>;
+        return this._createRegisteredTool(
+            name,
+            undefined,
+            description,
+            inputSchema,
+            undefined,
+            annotations,
+            { taskSupport: 'forbidden' },
+            undefined,
+            cb
+        );
+    }
+
+    /** @deprecated Use {@linkcode registerPrompt}. Removed in v3. */
+    prompt(name: string, cb: PromptCallback): RegisteredPrompt;
+    /** @deprecated Use {@linkcode registerPrompt}. Removed in v3. */
+    prompt(name: string, description: string, cb: PromptCallback): RegisteredPrompt;
+    /** @deprecated Use {@linkcode registerPrompt}. Removed in v3. */
+    prompt<Args extends ZodRawShape>(name: string, argsSchema: Args, cb: LegacyPromptCallback<Args>): RegisteredPrompt;
+    /** @deprecated Use {@linkcode registerPrompt}. Removed in v3. */
+    prompt<Args extends ZodRawShape>(name: string, description: string, argsSchema: Args, cb: LegacyPromptCallback<Args>): RegisteredPrompt;
+    prompt(name: string, ...rest: unknown[]): RegisteredPrompt {
+        deprecate('McpServer.prompt', 'McpServer.prompt() is deprecated. Use registerPrompt(name, config, cb). Removed in v3.');
+
+        let description: string | undefined;
+        if (typeof rest[0] === 'string') description = rest.shift() as string;
+
+        let argsSchema: StandardSchemaWithJSON | undefined;
+        if (rest.length > 1) argsSchema = wrapRawShape(rest.shift());
+
+        if (this._registeredPrompts[name]) {
+            throw new Error(`Prompt ${name} is already registered`);
+        }
+        const cb = rest[0] as PromptCallback<StandardSchemaWithJSON | undefined>;
+        const registered = this._createRegisteredPrompt(name, undefined, description, argsSchema, cb, undefined);
+        this.setPromptRequestHandlers();
+        this.sendPromptListChanged();
+        return registered;
+    }
+
+    /** @deprecated Use {@linkcode registerResource}. Removed in v3. */
+    resource(name: string, uri: string, readCallback: ReadResourceCallback): RegisteredResource;
+    /** @deprecated Use {@linkcode registerResource}. Removed in v3. */
+    resource(name: string, uri: string, metadata: ResourceMetadata, readCallback: ReadResourceCallback): RegisteredResource;
+    /** @deprecated Use {@linkcode registerResource}. Removed in v3. */
+    resource(name: string, template: ResourceTemplate, readCallback: ReadResourceTemplateCallback): RegisteredResourceTemplate;
+    /** @deprecated Use {@linkcode registerResource}. Removed in v3. */
+    resource(
+        name: string,
+        template: ResourceTemplate,
+        metadata: ResourceMetadata,
+        readCallback: ReadResourceTemplateCallback
+    ): RegisteredResourceTemplate;
+    resource(name: string, uriOrTemplate: string | ResourceTemplate, ...rest: unknown[]): RegisteredResource | RegisteredResourceTemplate {
+        deprecate('McpServer.resource', 'McpServer.resource() is deprecated. Use registerResource(name, uri, config, cb). Removed in v3.');
+
+        let metadata: ResourceMetadata = {};
+        if (typeof rest[0] === 'object') metadata = rest.shift() as ResourceMetadata;
+        const readCallback = rest[0] as ReadResourceCallback & ReadResourceTemplateCallback;
+        return this.registerResource(name, uriOrTemplate as string, metadata, readCallback);
+    }
+
     /**
      * Checks if the server is connected to a transport.
      * @returns `true` if the server is connected
@@ -1062,6 +1194,50 @@ export class ResourceTemplate {
     }
 }
 
+/**
+ * v1 raw-shape: a plain record of field schemas, e.g. `{ name: z.string() }`.
+ * @deprecated Wrap in `z.object({...})` and pass to `registerTool`. Removed in v3.
+ */
+export type ZodRawShape = Record<string, StandardSchemaWithJSON>;
+
+type InferRawShape<S extends ZodRawShape> = { [K in keyof S]: StandardSchemaWithJSON.InferOutput<S[K]> };
+
+/** @deprecated Use {@linkcode ToolCallback} with `registerTool`. Removed in v3. */
+export type LegacyToolCallback<Args extends ZodRawShape | undefined> = Args extends ZodRawShape
+    ? (args: InferRawShape<Args>, ctx: ServerContext) => CallToolResult | Promise<CallToolResult>
+    : (ctx: ServerContext) => CallToolResult | Promise<CallToolResult>;
+
+/** @deprecated Use {@linkcode PromptCallback} with `registerPrompt`. Removed in v3. */
+export type LegacyPromptCallback<Args extends ZodRawShape | undefined> = Args extends ZodRawShape
+    ? (args: InferRawShape<Args>, ctx: ServerContext) => GetPromptResult | Promise<GetPromptResult>
+    : (ctx: ServerContext) => GetPromptResult | Promise<GetPromptResult>;
+
+/**
+ * Detects a v1 "raw shape" — a plain object whose values are Standard Schema
+ * field schemas, e.g. `{ name: z.string() }`. Used by the deprecated variadic
+ * `.tool()`/`.prompt()` shims to disambiguate the schema arg from annotations.
+ *
+ * @internal
+ */
+function isZodRawShape(obj: unknown): obj is ZodRawShape {
+    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));
+}
+
+/**
+ * Wraps a v1 raw shape in `z.object()` for the variadic shims; passes Standard
+ * Schemas through unchanged.
+ *
+ * @internal
+ */
+function wrapRawShape(schema: unknown): StandardSchemaWithJSON | undefined {
+    if (schema === undefined) return undefined;
+    if (isZodRawShape(schema)) return z.object(schema as z.core.$ZodLooseShape) as StandardSchemaWithJSON;
+    return schema as StandardSchemaWithJSON;
+}
+
 export type BaseToolCallback<
     SendResultT extends Result,
     Ctx extends ServerContext,

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

@@ -0,0 +1,90 @@
+/* eslint-disable @typescript-eslint/no-deprecated */
+import { _resetDeprecationWarnings } from '@modelcontextprotocol/core';
+import { z } from 'zod';
+import { McpServer, ResourceTemplate } from '../../src/server/mcp.js';
+
+describe('McpServer v1-compat variadic shims', () => {
+    let warnSpy: ReturnType<typeof vi.spyOn>;
+
+    beforeEach(() => {
+        _resetDeprecationWarnings();
+        warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        warnSpy.mockRestore();
+    });
+
+    describe('.tool()', () => {
+        it('registers with raw-shape schema and warns once', () => {
+            const server = new McpServer({ name: 't', version: '1' });
+
+            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);
+        });
+
+        it('supports (name, description, paramsSchema, annotations, cb) overload', () => {
+            const server = new McpServer({ name: 't', version: '1' });
+
+            const reg = server.tool('x', 'desc', { a: z.string() }, { readOnlyHint: true }, ({ a }) => ({
+                content: [{ type: 'text', text: a }]
+            }));
+
+            expect(reg.description).toBe('desc');
+            expect(reg.annotations).toEqual({ readOnlyHint: true });
+            expect(reg.inputSchema).toBeDefined();
+        });
+
+        it('supports (name, cb) zero-arg overload', () => {
+            const server = new McpServer({ name: 't', version: '1' });
+            const reg = server.tool('x', () => ({ content: [{ type: 'text', text: 'ok' }] }));
+            expect(reg.inputSchema).toBeUndefined();
+        });
+    });
+
+    describe('.prompt()', () => {
+        it('registers with raw-shape argsSchema and warns once', () => {
+            const server = new McpServer({ name: 't', version: '1' });
+
+            server.prompt('p1', { topic: z.string() }, ({ topic }) => ({
+                messages: [{ role: 'user', content: { type: 'text', text: topic } }]
+            }));
+            server.prompt('p2', () => ({ messages: [] }));
+
+            // @ts-expect-error private access for test
+            expect(server._registeredPrompts['p1']).toBeDefined();
+            // @ts-expect-error private access for test
+            expect(server._registeredPrompts['p2']).toBeDefined();
+
+            const promptWarnings = warnSpy.mock.calls.filter((c: unknown[]) => String(c[0]).includes('McpServer.prompt()'));
+            expect(promptWarnings).toHaveLength(1);
+        });
+    });
+
+    describe('.resource()', () => {
+        it('forwards to registerResource and warns once', () => {
+            const server = new McpServer({ name: 't', version: '1' });
+
+            server.resource('r1', 'file:///a', () => ({ contents: [] }));
+            server.resource('r2', new ResourceTemplate('file:///{id}', { list: undefined }), () => ({ contents: [] }));
+
+            // @ts-expect-error private access for test
+            expect(server._registeredResources['file:///a']).toBeDefined();
+            // @ts-expect-error private access for test
+            expect(server._registeredResourceTemplates['r2']).toBeDefined();
+
+            const resourceWarnings = warnSpy.mock.calls.filter((c: unknown[]) => String(c[0]).includes('McpServer.resource()'));
+            expect(resourceWarnings).toHaveLength(1);
+        });
+    });
+});