merge commit

Author: KKonstantinov

CLAUDE.md

@@ -147,19 +147,19 @@ When a request arrives from the remote side:
     - Looks up handler in `_requestHandlers` map (keyed by method name)
     - Creates `RequestHandlerExtra` with `signal`, `sessionId`, `sendNotification`, `sendRequest`
     - Invokes handler, sends JSON-RPC response back via transport
-4. **Handler** was registered via `setRequestHandler(Schema, handler)`
+4. **Handler** was registered via `setRequestHandler('method', handler)`
 
 ### Handler Registration
 
 ```typescript
 // In Client (for server→client requests like sampling, elicitation)
-client.setRequestHandler(CreateMessageRequestSchema, async (request, extra) => {
+client.setRequestHandler('sampling/createMessage', async (request, extra) => {
   // Handle sampling request from server
   return { role: "assistant", content: {...}, model: "..." };
 });
 
 // In Server (for client→server requests like tools/call)
-server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+server.setRequestHandler('tools/call', async (request, extra) => {
   // Handle tool call from client
   return { content: [...] };
 });
@@ -206,7 +206,7 @@ const result = await server.createMessage({
 });
 
 // Client must have registered handler:
-client.setRequestHandler(CreateMessageRequestSchema, async (request, extra) => {
+client.setRequestHandler('sampling/createMessage', async (request, extra) => {
   // Client-side LLM call
   return { role: "assistant", content: {...} };
 });
@@ -217,7 +217,7 @@ client.setRequestHandler(CreateMessageRequestSchema, async (request, extra) => {
 ### Request Handler Registration (Low-Level Server)
 
 ```typescript
-server.setRequestHandler(SomeRequestSchema, async (request, extra) => {
+server.setRequestHandler('tools/call', async (request, extra) => {
     // extra contains sessionId, authInfo, sendNotification, etc.
     return {
         /* result */

docs/migration-SKILL.md

@@ -4,20 +4,19 @@ This guide covers the breaking changes introduced in v2 of the MCP TypeScript SD
 
 ## Overview
 
-Version 2 of the MCP TypeScript SDK introduces several breaking changes to improve modularity, reduce dependency bloat, and provide a cleaner API surface. The biggest change is the split from a single `@modelcontextprotocol/sdk` package into separate `@modelcontextprotocol/core`,
-`@modelcontextprotocol/client`, and `@modelcontextprotocol/server` packages.
+Version 2 of the MCP TypeScript SDK introduces several breaking changes to improve modularity, reduce dependency bloat, and provide a cleaner API surface. The biggest change is the split from a single `@modelcontextprotocol/sdk` package into separate `@modelcontextprotocol/core`, `@modelcontextprotocol/client`, and `@modelcontextprotocol/server` packages.
 
 ## Breaking Changes
 
 ### Package split (monorepo)
 
 The single `@modelcontextprotocol/sdk` package has been split into three packages:
 
-| v1                          | v2                                                         |
-| --------------------------- | ---------------------------------------------------------- |
+| v1 | v2 |
+|----|-----|
 | `@modelcontextprotocol/sdk` | `@modelcontextprotocol/core` (types, protocol, transports) |
-|                             | `@modelcontextprotocol/client` (client implementation)     |
-|                             | `@modelcontextprotocol/server` (server implementation)     |
+| | `@modelcontextprotocol/client` (client implementation) |
+| | `@modelcontextprotocol/server` (server implementation) |
 
 Remove the old package and install only the packages you need:
 
@@ -65,19 +64,18 @@ Note: `@modelcontextprotocol/client` and `@modelcontextprotocol/server` both re-
 v2 requires **Node.js 20+** and ships **ESM only** (no more CommonJS builds).
 
 If your project uses CommonJS (`require()`), you will need to either:
-
 - Migrate to ESM (`import`/`export`)
 - Use dynamic `import()` to load the SDK
 
 ### Server decoupled from HTTP frameworks
 
 The server package no longer depends on Express or Hono. HTTP framework integrations are now separate middleware packages:
 
-| v1                                     | v2                                          |
-| -------------------------------------- | ------------------------------------------- |
+| v1 | v2 |
+|----|-----|
 | Built into `@modelcontextprotocol/sdk` | `@modelcontextprotocol/node` (Node.js HTTP) |
-|                                        | `@modelcontextprotocol/express` (Express)   |
-|                                        | `@modelcontextprotocol/hono` (Hono)         |
+| | `@modelcontextprotocol/express` (Express) |
+| | `@modelcontextprotocol/hono` (Hono) |
 
 Install the middleware package for your framework:
 
@@ -130,12 +128,12 @@ This affects both transport constructors and request handler code that reads hea
 ```typescript
 // Transport headers
 const transport = new StreamableHTTPClientTransport(url, {
-    requestInit: {
-        headers: {
-            Authorization: 'Bearer token',
-            'X-Custom': 'value'
-        }
-    }
+  requestInit: {
+    headers: {
+      'Authorization': 'Bearer token',
+      'X-Custom': 'value',
+    },
+  },
 });
 
 // Reading headers in a request handler
@@ -147,12 +145,12 @@ const sessionId = extra.requestInfo?.headers['mcp-session-id'];
 ```typescript
 // Transport headers
 const transport = new StreamableHTTPClientTransport(url, {
-    requestInit: {
-        headers: new Headers({
-            Authorization: 'Bearer token',
-            'X-Custom': 'value'
-        })
-    }
+  requestInit: {
+    headers: new Headers({
+      'Authorization': 'Bearer token',
+      'X-Custom': 'value',
+    }),
+  },
 });
 
 // Reading headers in a request handler
@@ -172,22 +170,22 @@ const server = new McpServer({ name: 'demo', version: '1.0.0' });
 
 // Tool with schema
 server.tool('greet', { name: z.string() }, async ({ name }) => {
-    return { content: [{ type: 'text', text: `Hello, ${name}!` }] };
+  return { content: [{ type: 'text', text: `Hello, ${name}!` }] };
 });
 
 // Tool with description
 server.tool('greet', 'Greet a user', { name: z.string() }, async ({ name }) => {
-    return { content: [{ type: 'text', text: `Hello, ${name}!` }] };
+  return { content: [{ type: 'text', text: `Hello, ${name}!` }] };
 });
 
 // Prompt
 server.prompt('summarize', { text: z.string() }, async ({ text }) => {
-    return { messages: [{ role: 'user', content: { type: 'text', text: `Summarize: ${text}` } }] };
+  return { messages: [{ role: 'user', content: { type: 'text', text: `Summarize: ${text}` } }] };
 });
 
 // Resource
-server.resource('config', 'config://app', async uri => {
-    return { contents: [{ uri: uri.href, text: '{}' }] };
+server.resource('config', 'config://app', async (uri) => {
+  return { contents: [{ uri: uri.href, text: '{}' }] };
 });
 ```
 
@@ -200,29 +198,28 @@ const server = new McpServer({ name: 'demo', version: '1.0.0' });
 
 // Tool with schema
 server.registerTool('greet', { inputSchema: { name: z.string() } }, async ({ name }) => {
-    return { content: [{ type: 'text', text: `Hello, ${name}!` }] };
+  return { content: [{ type: 'text', text: `Hello, ${name}!` }] };
 });
 
 // Tool with description
 server.registerTool('greet', { description: 'Greet a user', inputSchema: { name: z.string() } }, async ({ name }) => {
-    return { content: [{ type: 'text', text: `Hello, ${name}!` }] };
+  return { content: [{ type: 'text', text: `Hello, ${name}!` }] };
 });
 
 // Prompt
 server.registerPrompt('summarize', { argsSchema: { text: z.string() } }, async ({ text }) => {
-    return { messages: [{ role: 'user', content: { type: 'text', text: `Summarize: ${text}` } }] };
+  return { messages: [{ role: 'user', content: { type: 'text', text: `Summarize: ${text}` } }] };
 });
 
 // Resource
-server.registerResource('config', 'config://app', {}, async uri => {
-    return { contents: [{ uri: uri.href, text: '{}' }] };
+server.registerResource('config', 'config://app', {}, async (uri) => {
+  return { contents: [{ uri: uri.href, text: '{}' }] };
 });
 ```
 
 ### Host header validation moved
 
-Express-specific middleware (`hostHeaderValidation()`, `localhostHostValidation()`) moved from the server package to `@modelcontextprotocol/express`. The server package now exports framework-agnostic functions instead: `validateHostHeader()`, `localhostAllowedHostnames()`,
-`hostHeaderValidationResponse()`.
+Express-specific middleware (`hostHeaderValidation()`, `localhostHostValidation()`) moved from the server package to `@modelcontextprotocol/express`. The server package now exports framework-agnostic functions instead: `validateHostHeader()`, `localhostAllowedHostnames()`, `hostHeaderValidationResponse()`.
 
 **Before (v1):**
 
@@ -240,6 +237,66 @@ app.use(hostHeaderValidation(['example.com']));
 
 Note: the v2 signature takes a plain `string[]` instead of an options object.
 
+### `setRequestHandler` and `setNotificationHandler` use method strings
+
+The low-level `setRequestHandler` and `setNotificationHandler` methods on `Client`, `Server`, and `Protocol` now take a method string instead of a Zod schema.
+
+**Before (v1):**
+
+```typescript
+import { Server, InitializeRequestSchema, LoggingMessageNotificationSchema } from '@modelcontextprotocol/sdk/server/index.js';
+
+const server = new Server({ name: 'my-server', version: '1.0.0' });
+
+// Request handler with schema
+server.setRequestHandler(InitializeRequestSchema, async (request) => {
+  return { protocolVersion: '...', capabilities: {}, serverInfo: { name: '...', version: '...' } };
+});
+
+// Notification handler with schema
+server.setNotificationHandler(LoggingMessageNotificationSchema, (notification) => {
+  console.log(notification.params.data);
+});
+```
+
+**After (v2):**
+
+```typescript
+import { Server } from '@modelcontextprotocol/server';
+
+const server = new Server({ name: 'my-server', version: '1.0.0' });
+
+// Request handler with method string
+server.setRequestHandler('initialize', async (request) => {
+  return { protocolVersion: '...', capabilities: {}, serverInfo: { name: '...', version: '...' } };
+});
+
+// Notification handler with method string
+server.setNotificationHandler('notifications/message', (notification) => {
+  console.log(notification.params.data);
+});
+```
+
+The request and notification parameters remain fully typed via `RequestTypeMap` and `NotificationTypeMap`. You no longer need to import the individual `*RequestSchema` or `*NotificationSchema` constants for handler registration.
+
+Common method string replacements:
+
+| Schema (v1) | Method string (v2) |
+|-------------|-------------------|
+| `InitializeRequestSchema` | `'initialize'` |
+| `CallToolRequestSchema` | `'tools/call'` |
+| `ListToolsRequestSchema` | `'tools/list'` |
+| `ListPromptsRequestSchema` | `'prompts/list'` |
+| `GetPromptRequestSchema` | `'prompts/get'` |
+| `ListResourcesRequestSchema` | `'resources/list'` |
+| `ReadResourceRequestSchema` | `'resources/read'` |
+| `CreateMessageRequestSchema` | `'sampling/createMessage'` |
+| `ElicitRequestSchema` | `'elicitation/create'` |
+| `LoggingMessageNotificationSchema` | `'notifications/message'` |
+| `ToolListChangedNotificationSchema` | `'notifications/tools/list_changed'` |
+| `ResourceListChangedNotificationSchema` | `'notifications/resources/list_changed'` |
+| `PromptListChangedNotificationSchema` | `'notifications/prompts/list_changed'` |
+
 ### Registered primitives are now classes
 
 `RegisteredTool`, `RegisteredPrompt`, `RegisteredResource`, and `RegisteredResourceTemplate` are now proper classes instead of plain object types. They are exported from `@modelcontextprotocol/server`.
@@ -297,27 +354,24 @@ mcpServer.resourceTemplates;
 To restore v1 behavior (throw an error when capabilities are missing), set `enforceStrictCapabilities: true`:
 
 ```typescript
-const client = new Client(
-    { name: 'my-client', version: '1.0.0' },
-    {
-        enforceStrictCapabilities: true
-    }
-);
+const client = new Client({ name: 'my-client', version: '1.0.0' }, {
+  enforceStrictCapabilities: true,
+});
 ```
 
 ### Removed type aliases and deprecated exports
 
 The following deprecated type aliases have been removed from `@modelcontextprotocol/core`:
 
-| Removed                                  | Replacement                                      |
-| ---------------------------------------- | ------------------------------------------------ |
-| `JSONRPCError`                           | `JSONRPCErrorResponse`                           |
-| `JSONRPCErrorSchema`                     | `JSONRPCErrorResponseSchema`                     |
-| `isJSONRPCError`                         | `isJSONRPCErrorResponse`                         |
-| `isJSONRPCResponse`                      | `isJSONRPCResultResponse`                        |
-| `ResourceReferenceSchema`                | `ResourceTemplateReferenceSchema`                |
-| `ResourceReference`                      | `ResourceTemplateReference`                      |
-| `IsomorphicHeaders`                      | Use Web Standard `Headers`                       |
+| Removed | Replacement |
+|---------|-------------|
+| `JSONRPCError` | `JSONRPCErrorResponse` |
+| `JSONRPCErrorSchema` | `JSONRPCErrorResponseSchema` |
+| `isJSONRPCError` | `isJSONRPCErrorResponse` |
+| `isJSONRPCResponse` | `isJSONRPCResultResponse` |
+| `ResourceReferenceSchema` | `ResourceTemplateReferenceSchema` |
+| `ResourceReference` | `ResourceTemplateReference` |
+| `IsomorphicHeaders` | Use Web Standard `Headers` |
 | `AuthInfo` (from `server/auth/types.js`) | `AuthInfo` (now in `@modelcontextprotocol/core`) |
 
 All other types and schemas exported from `@modelcontextprotocol/sdk/types.js` retain their original names in `@modelcontextprotocol/core`.
@@ -348,8 +402,7 @@ The following APIs are unchanged between v1 and v2 (only the import paths change
 
 ## Using an LLM to migrate your code
 
-An LLM-optimized version of this guide is available at [`docs/migration-SKILL.md`](migration-SKILL.md). It contains dense mapping tables designed for tools like Claude Code to mechanically apply all the changes described above. You can paste it into your LLM context or load it as
-a skill.
+An LLM-optimized version of this guide is available at [`docs/migration-SKILL.md`](migration-SKILL.md). It contains dense mapping tables designed for tools like Claude Code to mechanically apply all the changes described above. You can paste it into your LLM context or load it as a skill.
 
 ## Need Help?
 

docs/migration.md

@@ -21,8 +21,6 @@ import type {
 import {
     CallToolResultSchema,
     Client,
-    ElicitationCompleteNotificationSchema,
-    ElicitRequestSchema,
     ErrorCode,
     getDisplayName,
     ListToolsResultSchema,
@@ -560,10 +558,10 @@ async function connect(url?: string): Promise<void> {
     console.log('👤 Client created');
 
     // Set up elicitation request handler with proper validation
-    client.setRequestHandler(ElicitRequestSchema, elicitationRequestHandler);
+    client.setRequestHandler('elicitation/create', elicitationRequestHandler);
 
     // Set up notification handler for elicitation completion
-    client.setNotificationHandler(ElicitationCompleteNotificationSchema, notification => {
+    client.setNotificationHandler('notifications/elicitation/complete', notification => {
         const { elicitationId } = notification.params;
         const pending = pendingURLElicitations.get(elicitationId);
         if (pending) {

examples/client/src/elicitationUrlExample.ts

@@ -1,10 +1,5 @@
 import type { CallToolRequest, CallToolResult } from '@modelcontextprotocol/client';
-import {
-    CallToolResultSchema,
-    Client,
-    LoggingMessageNotificationSchema,
-    StreamableHTTPClientTransport
-} from '@modelcontextprotocol/client';
+import { CallToolResultSchema, Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
 
 /**
  * Multiple Clients MCP Example
@@ -42,7 +37,7 @@ async function createAndRunClient(config: ClientConfig): Promise<{ id: string; r
     };
 
     // Set up client-specific notification handler
-    client.setNotificationHandler(LoggingMessageNotificationSchema, notification => {
+    client.setNotificationHandler('notifications/message', notification => {
         console.log(`[${config.id}] Notification: ${notification.params.data}`);
     });
 

examples/client/src/multipleClientsParallel.ts

@@ -1,11 +1,5 @@
 import type { CallToolResult, ListToolsRequest } from '@modelcontextprotocol/client';
-import {
-    CallToolResultSchema,
-    Client,
-    ListToolsResultSchema,
-    LoggingMessageNotificationSchema,
-    StreamableHTTPClientTransport
-} from '@modelcontextprotocol/client';
+import { CallToolResultSchema, Client, ListToolsResultSchema, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
 
 /**
  * Parallel Tool Calls MCP Client
@@ -44,7 +38,7 @@ async function main(): Promise<void> {
         console.log('Successfully connected to MCP server');
 
         // Set up notification handler with caller identification
-        client.setNotificationHandler(LoggingMessageNotificationSchema, notification => {
+        client.setNotificationHandler('notifications/message', notification => {
             console.log(`Notification: ${notification.params.data}`);
         });