feat(core): make Protocol concrete and exported with ProtocolSpec generic

Replaces the setCustom*/sendCustom* API with overloads on setRequestHandler /
setNotificationHandler / request / notification:

- Two-arg spec-method form (existing): handler receives the full request object,
  validated by the SDK. Used by Client/Server overrides.
- Three-arg form (new): (method: string, paramsSchema, handler-receives-params).
  Accepts any method string; params validated against caller-supplied schema.

Protocol is no longer abstract:
- 5 assert*Capability methods become no-op virtuals; Client/Server override.
- buildContext gets a default implementation returning the BaseContext as-is.
- Protocol<S extends ProtocolSpec, ContextT> — S declares the request/notification
  vocabulary (autocomplete reserved for follow-up; runtime path complete).
- McpSpec derived from RequestTypeMap/ResultTypeMap/NotificationTypeMap;
  Client/Server extend Protocol<McpSpec, ...>.

This lets MCP-dialect protocols (ext-apps) subclass Protocol directly with no
role enforcement, no wire renames, no setCustom* split — restoring the v1 model
with a cleaner generic shape.

Exports Protocol, ProtocolSpec, McpSpec and InMemoryTransport from core/public.

Tests: customMethods.test.ts rewritten (13 tests covering concrete instantiation,
3-arg overloads, ProtocolSpec, non-Zod StandardSchemaV1). protocol.test.ts and
protocolTransportHandling.test.ts adapted to the new generic position.

Examples: customMethodExample.ts (server + client) rewritten to use the 3-arg
overloads on stock Client/Server. customMethodExtAppsExample.ts rewritten as
class App extends Protocol<AppSpec> mixing ui/* and tools/call on one object.

Docs: migration.md and migration-SKILL.md custom-methods sections updated.

Author: felixweinberger

docs/migration-SKILL.md

@@ -377,14 +377,14 @@ Schema to method string mapping:
 
 Request/notification params remain fully typed. Remove unused schema imports after migration.
 
-**Custom (non-standard) methods** — vendor extensions or sub-protocols whose method strings are not in the MCP spec — are no longer accepted by `setRequestHandler`/`setNotificationHandler`. Use the `*Custom*` API instead:
+**Custom (non-standard) methods** — vendor extensions or sub-protocols whose method strings are not in the MCP spec — use the three-arg overloads of `setRequestHandler`/`setNotificationHandler`/`request`/`notification`, which accept any method string with a caller-supplied params/result schema. `Protocol` is now concrete and exported, so MCP-dialect protocols can subclass it directly:
 
 | v1                                                           | v2                                                                             |
 | ------------------------------------------------------------ | ------------------------------------------------------------------------------ |
-| `setRequestHandler(CustomReqSchema, (req, extra) => ...)`    | `setCustomRequestHandler('vendor/method', ParamsSchema, (params, ctx) => ...)` |
-| `setNotificationHandler(CustomNotifSchema, n => ...)`        | `setCustomNotificationHandler('vendor/method', ParamsSchema, params => ...)`   |
-| `this.request({ method: 'vendor/x', params }, ResultSchema)` | `this.sendCustomRequest('vendor/x', params, ResultSchema)`                     |
-| `this.notification({ method: 'vendor/x', params })`          | `this.sendCustomNotification('vendor/x', params)`                              |
+| `setRequestHandler(CustomReqSchema, (req, extra) => ...)`    | `setRequestHandler('vendor/method', ParamsSchema, (params, ctx) => ...)` |
+| `setNotificationHandler(CustomNotifSchema, n => ...)`        | `setNotificationHandler('vendor/method', ParamsSchema, params => ...)`   |
+| `this.request({ method: 'vendor/x', params }, ResultSchema)` | `this.request('vendor/x', params, ResultSchema)`                     |
+| `this.notification({ method: 'vendor/x', params })`          | `this.notification('vendor/x', params)`                              |
 | `class X extends Protocol<Req, Notif, Res>`                  | `class X extends Client` (or `Server`), or compose a `Client` instance         |
 
 The v1 schema's `.shape.params` becomes the `ParamsSchema` argument; the `method: z.literal('...')` value becomes the string argument.

docs/migration.md

@@ -384,21 +384,15 @@ Common method string replacements:
 
 ### Custom (non-standard) protocol methods
 
-In v1, `setRequestHandler` accepted any Zod schema with a `method: z.literal('...')` shape, so vendor-specific methods (e.g. `mcp-ui/initialize`) could be registered the same way as spec methods. The `Protocol<SendRequestT, SendNotificationT, SendResultT>` generics widened the
-send-side types to match.
+In v1, vendor-specific methods were registered the same way as spec methods (`setRequestHandler(zodSchemaWithMethodLiteral, handler)`), and `Protocol<SendRequestT, SendNotificationT, SendResultT>` widened the send-side type unions.
 
-In v2, `setRequestHandler`/`setNotificationHandler` accept only standard MCP method strings, and the class-level send-side generics have been removed. For methods outside the MCP spec, use the dedicated `*Custom*` methods on `Client` and `Server` (inherited from `Protocol`):
+In v2, `Protocol` is concrete and exported. Its `setRequestHandler`, `setNotificationHandler`, `request` and `notification` each have a string-method overload that accepts any method name with a caller-supplied params/result schema:
 
 **Before (v1):**
 
 ```typescript
 import { Protocol } from '@modelcontextprotocol/sdk/shared/protocol.js';
 
-const SearchRequestSchema = z.object({
-    method: z.literal('acme/search'),
-    params: z.object({ query: z.string() })
-});
-
 class App extends Protocol<AppRequest, AppNotification, AppResult> {
     constructor() {
         super();
@@ -413,26 +407,26 @@ class App extends Protocol<AppRequest, AppNotification, AppResult> {
 **After (v2):**
 
 ```typescript
-import { Client } from '@modelcontextprotocol/client';
+import { Protocol, type ProtocolSpec } from '@modelcontextprotocol/client';
 
-const SearchParams = z.object({ query: z.string() });
-const SearchResult = z.object({ hits: z.array(z.string()) });
+type AppSpec = {
+    requests: { 'acme/search': { params: { query: string }; result: { hits: string[] } } };
+} satisfies ProtocolSpec;
 
-class App extends Client {
+class App extends Protocol<AppSpec> {
     constructor() {
-        super({ name: 'app', version: '1.0.0' });
-        this.setCustomRequestHandler('acme/search', SearchParams, params => ({ hits: [params.query] }));
+        super();
+        this.setRequestHandler('acme/search', SearchParams, params => ({ hits: [params.query] }));
     }
     search(query: string) {
-        return this.sendCustomRequest('acme/search', { query }, { params: SearchParams, result: SearchResult });
+        return this.request('acme/search', { query }, SearchResult);
     }
 }
 ```
 
-Custom handlers share the same dispatch path as standard handlers — context, cancellation, task delivery, and error wrapping all apply. Passing a `{ params, result }` schema bundle to `sendCustomRequest` (or `{ params }` to `sendCustomNotification`) validates outbound params
-before sending and gives typed `params`; passing a bare result schema sends params unvalidated.
+The `ProtocolSpec` type argument is optional — omit it for ad-hoc method strings without autocomplete. For a single vendor method on a stock `Client` or `Server`, call the three-arg overload directly: `server.setRequestHandler('acme/search', SearchParams, handler)`.
 
-For larger sub-protocols where neither side is semantically an MCP client or server, prefer composition: hold a `Client` (or `Server`) instance, register custom handlers on it, and expose typed facade methods. See `examples/server/src/customMethodExample.ts` and `examples/client/src/customMethodExample.ts` for runnable examples.
+The five `assert*Capability` abstract methods are now no-op virtuals on `Protocol`, so subclasses no longer need to stub them.
 
 ### `Protocol.request()`, `ctx.mcpReq.send()`, and `Client.callTool()` no longer take a schema parameter
 

examples/client/src/customMethodExample.ts

@@ -1,80 +1,47 @@
-// Run with: pnpm tsx src/customMethodExample.ts
-//
-// Demonstrates sending custom (non-standard) requests and receiving custom
-// notifications from the server.
-//
-// The Protocol class exposes sendCustomRequest / setCustomNotificationHandler for
-// vendor-specific methods that are not part of the MCP spec. The schema-bundle
-// overload of sendCustomRequest gives typed params with pre-send validation.
-//
-// Pair with: examples/server/src/customMethodExample.ts (start the server first).
-
-import { Client, ProtocolError, ProtocolErrorCode, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+#!/usr/bin/env node
+/**
+ * Demonstrates calling a vendor method via the three-arg `client.request(method, params, resultSchema)`
+ * overload and registering a vendor notification handler with the three-arg `setNotificationHandler`
+ * overload.
+ *
+ * Pair with: examples/server/src/customMethodExample.ts (which contains the in-memory pair).
+ */
+
+import { Client, InMemoryTransport, Protocol } from '@modelcontextprotocol/client';
 import { z } from 'zod';
 
-const SearchParamsSchema = z.object({
-    query: z.string(),
-    limit: z.number().int().positive().optional()
-});
-
-const SearchResultSchema = z.object({
-    results: z.array(z.object({ id: z.string(), title: z.string() })),
-    total: z.number()
-});
-
-const AnalyticsResultSchema = z.object({ recorded: z.boolean() });
-
-const StatusUpdateParamsSchema = z.object({
-    status: z.enum(['idle', 'busy', 'error']),
-    detail: z.string().optional()
-});
-
-const serverUrl = process.argv[2] ?? 'http://localhost:3000/mcp';
+const SearchParams = z.object({ query: z.string() });
+const SearchResult = z.object({ hits: z.array(z.string()) });
+const ProgressParams = z.object({ stage: z.string(), pct: z.number() });
 
-async function main(): Promise<void> {
-    const client = new Client({ name: 'custom-method-client', version: '1.0.0' });
-
-    // Register handler for custom server→client notifications before connecting.
-    client.setCustomNotificationHandler('acme/statusUpdate', StatusUpdateParamsSchema, params => {
-        console.log(`[client] acme/statusUpdate status=${params.status} detail=${params.detail ?? '<none>'}`);
+async function main() {
+    const peer = new Protocol();
+    peer.setRequestHandler('acme/search', SearchParams, async p => {
+        await peer.notification('acme/searchProgress', { stage: 'started', pct: 0 });
+        await peer.notification('acme/searchProgress', { stage: 'done', pct: 100 });
+        return { hits: [p.query, p.query + '-2'] };
+    });
+    // The bare Protocol must respond to MCP initialize so Client.connect() completes.
+    peer.setRequestHandler('initialize', req => ({
+        protocolVersion: req.params.protocolVersion,
+        capabilities: {},
+        serverInfo: { name: 'peer', version: '1.0.0' }
+    }));
+
+    const client = new Client({ name: 'c', version: '1.0.0' }, { capabilities: {} });
+    client.setNotificationHandler('acme/searchProgress', ProgressParams, p => {
+        console.log(`[client] progress: ${p.stage} ${p.pct}%`);
     });
 
-    const transport = new StreamableHTTPClientTransport(new URL(serverUrl));
-    await client.connect(transport);
-    console.log(`[client] connected to ${serverUrl}`);
-
-    // Schema-bundle overload: typed params + pre-send validation, typed result.
-    const searchResult = await client.sendCustomRequest(
-        'acme/search',
-        { query: 'widgets', limit: 5 },
-        { params: SearchParamsSchema, result: SearchResultSchema }
-    );
-    console.log(`[client] acme/search → ${searchResult.total} results, first: "${searchResult.results[0]?.title}"`);
-
-    // Loose overload: bare result schema, untyped params.
-    const analyticsResult = await client.sendCustomRequest('acme/analytics', { event: 'page_view' }, AnalyticsResultSchema);
-    console.log(`[client] acme/analytics → recorded=${analyticsResult.recorded}`);
+    const [t1, t2] = InMemoryTransport.createLinkedPair();
+    await peer.connect(t2);
+    await client.connect(t1);
 
-    // Pre-send validation: schema-bundle overload rejects bad params before the round-trip.
-    try {
-        await client.sendCustomRequest(
-            'acme/search',
-            { query: 'widgets', limit: 'five' } as unknown as z.output<typeof SearchParamsSchema>,
-            { params: SearchParamsSchema, result: SearchResultSchema }
-        );
-        console.error('[client] expected validation error but request succeeded');
-    } catch (error) {
-        const code = error instanceof ProtocolError && error.code === ProtocolErrorCode.InvalidParams ? 'InvalidParams' : 'unknown';
-        console.log(`[client] pre-send validation error (expected, ${code}): ${(error as Error).message}`);
-    }
+    const r = await client.request('acme/search', { query: 'widgets' }, SearchResult);
+    console.log('[client] hits=' + JSON.stringify(r.hits));
 
-    await transport.close();
+    await client.close();
+    await peer.close();
 }
 
-try {
-    await main();
-} catch (error) {
-    console.error('[client] error:', error);
-    // eslint-disable-next-line unicorn/no-process-exit
-    process.exit(1);
-}
+await main();

examples/server/src/customMethodExample.ts

@@ -1,123 +1,47 @@
-// Run with: pnpm tsx src/customMethodExample.ts
-//
-// Demonstrates registering handlers for custom (non-standard) request methods
-// and sending custom notifications back to the client.
-//
-// The Protocol class exposes setCustomRequestHandler / sendCustomNotification for
-// vendor-specific methods that are not part of the MCP spec. Params are validated
-// against user-provided Zod schemas, and handlers receive the same context
-// (cancellation, bidirectional send/notify) as standard handlers.
-//
-// Pair with: examples/client/src/customMethodExample.ts
-
-import { randomUUID } from 'node:crypto';
-
-import { createMcpExpressApp } from '@modelcontextprotocol/express';
-import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
-import { isInitializeRequest, Server } from '@modelcontextprotocol/server';
-import type { Request, Response } from 'express';
+#!/usr/bin/env node
+/**
+ * Demonstrates registering vendor-specific JSON-RPC methods directly on a stock `Server`, and
+ * calling them from a bare `Protocol` peer (which is role-agnostic and so can act as the client
+ * side without depending on the client package).
+ */
+
+import { InMemoryTransport, Protocol, Server } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 
-const SearchParamsSchema = z.object({
-    query: z.string(),
-    limit: z.number().int().positive().optional()
-});
+const SearchParams = z.object({ query: z.string() });
+const SearchResult = z.object({ hits: z.array(z.string()) });
+const TickParams = z.object({ n: z.number() });
 
-const AnalyticsParamsSchema = z.object({
-    event: z.string(),
-    properties: z.record(z.string(), z.unknown()).optional()
-});
-
-const getServer = () => {
+async function main() {
     const server = new Server({ name: 'custom-method-server', version: '1.0.0' }, { capabilities: {} });
 
-    server.setCustomRequestHandler('acme/search', SearchParamsSchema, async (params, ctx) => {
-        console.log(`[server] acme/search query="${params.query}" limit=${params.limit ?? 'unset'} (req ${ctx.mcpReq.id})`);
-
-        // Send a custom server→client notification on the same SSE stream as this response
-        // (relatedRequestId routes it to the request's stream rather than the standalone SSE stream).
-        await server.sendCustomNotification(
-            'acme/statusUpdate',
-            { status: 'busy', detail: `searching "${params.query}"` },
-            { relatedRequestId: ctx.mcpReq.id }
-        );
-
-        return {
-            results: [
-                { id: 'r1', title: `Result for "${params.query}"` },
-                { id: 'r2', title: 'Another result' }
-            ],
-            total: 2
-        };
+    server.setRequestHandler('acme/search', SearchParams, params => {
+        console.log('[server] acme/search query=' + params.query);
+        return { hits: [params.query, params.query + '-result'] };
     });
 
-    server.setCustomRequestHandler('acme/analytics', AnalyticsParamsSchema, async params => {
-        console.log(`[server] acme/analytics event="${params.event}"`);
-        return { recorded: true };
+    server.setNotificationHandler('acme/tick', TickParams, p => {
+        console.log('[server] acme/tick n=' + p.n);
     });
 
-    return server;
-};
-
-const PORT = process.env.PORT ? Number.parseInt(process.env.PORT, 10) : 3000;
-const app = createMcpExpressApp();
-const transports: { [sessionId: string]: NodeStreamableHTTPServerTransport } = {};
+    const peer = new Protocol();
 
-app.post('/mcp', async (req: Request, res: Response) => {
-    const sessionId = req.headers['mcp-session-id'] as string | undefined;
-    try {
-        let transport: NodeStreamableHTTPServerTransport;
-        if (sessionId && transports[sessionId]) {
-            transport = transports[sessionId];
-        } else if (!sessionId && isInitializeRequest(req.body)) {
-            transport = new NodeStreamableHTTPServerTransport({
-                sessionIdGenerator: () => randomUUID(),
-                onsessioninitialized: sid => {
-                    transports[sid] = transport;
-                }
-            });
-            transport.onclose = () => {
-                const sid = transport.sessionId;
-                if (sid) delete transports[sid];
-            };
-            const server = getServer();
-            await server.connect(transport);
-        } else {
-            res.status(400).json({ jsonrpc: '2.0', error: { code: -32_000, message: 'No valid session ID' }, id: null });
-            return;
-        }
-        await transport.handleRequest(req, res, req.body);
-    } catch (error) {
-        console.error('Error handling MCP request:', error);
-        if (!res.headersSent) {
-            res.status(500).json({ jsonrpc: '2.0', error: { code: -32_603, message: 'Internal server error' }, id: null });
-        }
-    }
-});
+    const [peerTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    await server.connect(serverTransport);
+    await peer.connect(peerTransport);
+    await peer.request({
+        method: 'initialize',
+        params: { protocolVersion: '2025-11-25', clientInfo: { name: 'peer', version: '1.0.0' }, capabilities: {} }
+    });
 
-const handleSessionRequest = async (req: Request, res: Response) => {
-    const sessionId = req.headers['mcp-session-id'] as string | undefined;
-    if (!sessionId || !transports[sessionId]) {
-        res.status(400).send('Invalid or missing session ID');
-        return;
-    }
-    await transports[sessionId].handleRequest(req, res);
-};
+    const r = await peer.request('acme/search', { query: 'widgets' }, SearchResult);
+    console.log('[peer] hits=' + JSON.stringify(r.hits));
 
-app.get('/mcp', handleSessionRequest);
-app.delete('/mcp', handleSessionRequest);
+    await peer.notification('acme/tick', { n: 1 });
+    await peer.notification('acme/tick', { n: 2 });
 
-app.listen(PORT, error => {
-    if (error) {
-        console.error('Failed to start server:', error);
-        // eslint-disable-next-line unicorn/no-process-exit
-        process.exit(1);
-    }
-    console.log(`Custom-method example server listening on http://localhost:${PORT}/mcp`);
-    console.log('Custom methods: acme/search, acme/analytics');
-});
+    await peer.close();
+    await server.close();
+}
 
-process.on('SIGINT', async () => {
-    for (const sid in transports) await transports[sid]!.close();
-    process.exit(0);
-});
+await main();