fix: address review — callTool(params, undefined, opts) drops opts; migration.md mcpReq.send claim; complete custom-method example

Author: felixweinberger

docs/migration-SKILL.md

@@ -204,7 +204,7 @@ if (error instanceof OAuthError && error.code === OAuthErrorCode.InvalidClient)
 ```
 
 **Unchanged APIs** (only import paths changed): `Client` constructor and most methods, `McpServer` constructor, `server.connect()`, `server.close()`, all client transports (`StreamableHTTPClientTransport`, `SSEClientTransport`, `StdioClientTransport`), `StdioServerTransport`, all
-Zod schemas, all callback return types. Note: `callTool()` and `request()` signatures changed (schema parameter removed, see section 11).
+Zod schemas, all callback return types. Note: `callTool()` and `request()` schema parameter is now optional (see section 11).
 
 ## 6. McpServer API Changes
 
@@ -416,9 +416,9 @@ Request/notification params remain fully typed. Remove unused schema imports aft
 | `ctx.mcpReq.elicitInput(params, options?)`     | Elicit user input (form or URL)                        | `server.elicitInput(...)` from within handler        |
 | `ctx.mcpReq.requestSampling(params, options?)` | Request LLM sampling from client                       | `server.createMessage(...)` from within handler      |
 
-## 11. Schema parameter removed from `request()`, `send()`, and `callTool()`
+## 11. Schema parameter on `request()` / `callTool()` is optional; removed from `send()`
 
-`Protocol.request()`, `BaseContext.mcpReq.send()`, and `Client.callTool()` no longer take a Zod result schema argument. The SDK resolves the schema internally from the method name.
+`Protocol.request()` and `Client.callTool()` still accept a Zod result schema as the second argument (the v1 form), but it is optional for spec methods — the SDK resolves the schema internally from the method name. `BaseContext.mcpReq.send()` no longer takes a schema.
 
 ```typescript
 // v1: schema required
@@ -427,20 +427,20 @@ const result = await client.request({ method: 'tools/call', params: { ... } }, C
 const elicit = await ctx.mcpReq.send({ method: 'elicitation/create', params: { ... } }, ElicitResultSchema);
 const tool = await client.callTool({ name: 'my-tool', arguments: {} }, CompatibilityCallToolResultSchema);
 
-// v2: no schema argument
+// v2: schema optional on request()/callTool(); removed from mcpReq.send()
 const result = await client.request({ method: 'tools/call', params: { ... } });
 const elicit = await ctx.mcpReq.send({ method: 'elicitation/create', params: { ... } });
 const tool = await client.callTool({ name: 'my-tool', arguments: {} });
 ```
 
-| v1 call                                                      | v2 call                            |
-| ------------------------------------------------------------ | ---------------------------------- |
-| `client.request(req, ResultSchema)`                          | `client.request(req)`              |
-| `client.request(req, ResultSchema, options)`                 | `client.request(req, options)`     |
-| `ctx.mcpReq.send(req, ResultSchema)`                         | `ctx.mcpReq.send(req)`             |
-| `ctx.mcpReq.send(req, ResultSchema, options)`                | `ctx.mcpReq.send(req, options)`    |
-| `client.callTool(params, CompatibilityCallToolResultSchema)` | `client.callTool(params)`          |
-| `client.callTool(params, schema, options)`                   | `client.callTool(params, options)` |
+| v1 call                                                      | v2 call                                        |
+| ------------------------------------------------------------ | ---------------------------------------------- |
+| `client.request(req, ResultSchema)`                          | unchanged (schema optional), or `client.request(req)` |
+| `client.request(req, ResultSchema, options)`                 | unchanged, or `client.request(req, options)`   |
+| `ctx.mcpReq.send(req, ResultSchema)`                         | `ctx.mcpReq.send(req)`                         |
+| `ctx.mcpReq.send(req, ResultSchema, options)`                | `ctx.mcpReq.send(req, options)`                |
+| `client.callTool(params, CompatibilityCallToolResultSchema)` | unchanged (schema ignored), or `client.callTool(params)` |
+| `client.callTool(params, schema, options)`                   | unchanged, or `client.callTool(params, options)` |
 
 Remove unused schema imports: `CallToolResultSchema`, `CompatibilityCallToolResultSchema`, `ElicitResultSchema`, `CreateMessageResultSchema`, etc., when they were only used in `request()`/`send()`/`callTool()` calls.
 

docs/migration.md

@@ -397,10 +397,10 @@ server.setRequestHandler(SearchRequestSchema, req => ({ hits: [req.params.query]
 const result = await client.request({ method: 'acme/search', params: { query: 'x' } }, SearchResult);
 ```
 
-### `Protocol.request()`, `ctx.mcpReq.send()`, and `Client.callTool()` schema parameter is now optional
+### `Protocol.request()` and `Client.callTool()` schema parameter is now optional
 
-The public `Protocol.request()`, `BaseContext.mcpReq.send()`, and `Client.callTool()` methods still accept a result schema argument, but for spec methods it is optional — the SDK resolves the correct schema internally from the method name. You no longer need to import result schemas
-like `CallToolResultSchema` or `ElicitResultSchema` when making requests.
+The public `Protocol.request()` and `Client.callTool()` methods still accept a result schema argument, but for spec methods it is optional — the SDK resolves the correct schema internally from the method name. You no longer need to import result schemas
+like `CallToolResultSchema` or `ElicitResultSchema` when making requests. (`BaseContext.mcpReq.send()` no longer accepts a schema; drop it.)
 
 **`client.request()` — Before (v1):**
 

examples/client/README.md

@@ -36,7 +36,7 @@ Most clients expect a server to be running. Start one from [`../server/README.md
 | Client credentials (M2M)                            | Machine-to-machine OAuth client credentials example.                                      | [`src/simpleClientCredentials.ts`](src/simpleClientCredentials.ts)                         |
 | URL elicitation client                              | Drives URL-mode elicitation flows (sensitive input in a browser).                         | [`src/elicitationUrlExample.ts`](src/elicitationUrlExample.ts)                             |
 | Task interactive client                             | Demonstrates task-based execution + interactive server→client requests.                   | [`src/simpleTaskInteractiveClient.ts`](src/simpleTaskInteractiveClient.ts)                 |
-| Custom (non-standard) methods client                | Sends `acme/*` custom requests and handles custom server notifications.                   | [`src/customMethodExample.ts`](src/customMethodExample.ts)                                 |
+| Custom (non-standard) methods client                | Sends `acme/*` custom requests + notifications and handles custom progress notifications from the server. | [`src/customMethodExample.ts`](src/customMethodExample.ts)                                 |
 
 ## URL elicitation example (server + client)
 

examples/server/README.md

@@ -38,7 +38,7 @@ pnpm tsx src/simpleStreamableHttp.ts
 | Task interactive server                   | Task-based execution with interactive server→client requests.                                   | [`src/simpleTaskInteractive.ts`](src/simpleTaskInteractive.ts)                           |
 | Hono Streamable HTTP server               | Streamable HTTP server built with Hono instead of Express.                                      | [`src/honoWebStandardStreamableHttp.ts`](src/honoWebStandardStreamableHttp.ts)           |
 | SSE polling demo server                   | Legacy SSE server intended for polling demos.                                                   | [`src/ssePollingExample.ts`](src/ssePollingExample.ts)                                   |
-| Custom (non-standard) methods server      | Registers `acme/*` custom request handlers and sends custom notifications.                      | [`src/customMethodExample.ts`](src/customMethodExample.ts)                               |
+| Custom (non-standard) methods server      | Registers `acme/*` custom request + notification handlers and emits custom progress notifications. | [`src/customMethodExample.ts`](src/customMethodExample.ts)                               |
 
 ## OAuth demo flags (Streamable HTTP server)
 

examples/server/src/customMethodExample.ts

@@ -27,9 +27,12 @@ const TickNotification = z.object({
 
 const server = new Server({ name: 'custom-method-server', version: '1.0.0' }, { capabilities: {} });
 
-server.setRequestHandler(SearchRequest, request => {
+server.setRequestHandler(SearchRequest, async (request, ctx) => {
     console.log('[server] acme/search query=' + request.params.query);
-    return { hits: [request.params.query, request.params.query + '-result'] };
+    await ctx.mcpReq.notify({ method: 'acme/searchProgress', params: { stage: 'start', pct: 0 } });
+    const hits = [request.params.query, request.params.query + '-result'];
+    await ctx.mcpReq.notify({ method: 'acme/searchProgress', params: { stage: 'done', pct: 100 } });
+    return { hits };
 });
 
 server.setNotificationHandler(TickNotification, n => {

packages/client/src/client/client.ts

@@ -892,10 +892,12 @@ export class Client extends Protocol<ClientContext> {
         optionsOrSchema?: RequestOptions | unknown,
         maybeOptions?: RequestOptions
     ): Promise<CallToolResult> {
-        const options: RequestOptions | undefined =
-            optionsOrSchema && typeof optionsOrSchema === 'object' && 'parse' in optionsOrSchema
-                ? maybeOptions
-                : (optionsOrSchema as RequestOptions | undefined);
+        const arg2IsSchema = optionsOrSchema != null && typeof optionsOrSchema === 'object' && 'parse' in optionsOrSchema;
+        // v1 allowed `callTool(params, undefined, opts)` (resultSchema was optional-with-default);
+        // when arg2 is not a schema, prefer arg3 if present so opts aren't dropped.
+        const options: RequestOptions | undefined = arg2IsSchema
+            ? maybeOptions
+            : (maybeOptions ?? (optionsOrSchema as RequestOptions | undefined));
         // Guard: required-task tools need experimental API
         if (this.isToolTaskRequired(params.name)) {
             throw new ProtocolError(

packages/client/test/client/callTool.compat.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it, vi } from 'vitest';
+import { Client } from '../../src/client/client.js';
+
+describe('callTool v1-compat overload dispatch', () => {
+    function makeClient() {
+        const client = new Client({ name: 't', version: '1.0.0' }, { capabilities: {} });
+        const spy = vi
+            .spyOn(client as unknown as { _requestWithSchema: (...a: unknown[]) => Promise<unknown> }, '_requestWithSchema')
+            .mockResolvedValue({ content: [] });
+        return { client, spy };
+    }
+
+    it('callTool(params, undefined, options) preserves options (v1: optional resultSchema)', async () => {
+        const { client, spy } = makeClient();
+        const opts = { timeout: 5000 };
+        await client.callTool({ name: 'x', arguments: {} }, undefined, opts);
+        expect(spy).toHaveBeenCalledTimes(1);
+        expect(spy.mock.calls[0]?.[2]).toBe(opts);
+    });
+
+    it('callTool(params, schema, options) preserves options', async () => {
+        const { client, spy } = makeClient();
+        const opts = { timeout: 5000 };
+        const schema = { parse: (x: unknown) => x };
+        await client.callTool({ name: 'x', arguments: {} }, schema, opts);
+        expect(spy.mock.calls[0]?.[2]).toBe(opts);
+    });
+
+    it('callTool(params, options) — 2-arg form still works', async () => {
+        const { client, spy } = makeClient();
+        const opts = { timeout: 5000 };
+        await client.callTool({ name: 'x', arguments: {} }, opts);
+        expect(spy.mock.calls[0]?.[2]).toBe(opts);
+    });
+
+    it('callTool(params) — no options', async () => {
+        const { client, spy } = makeClient();
+        await client.callTool({ name: 'x', arguments: {} });
+        expect(spy.mock.calls[0]?.[2]).toBeUndefined();
+    });
+});