feat: Add message middleware support for Protocol

[jerome3o-anthropic]

Summary

Add a middleware pattern that allows transforming JSON-RPC messages before sending and after receiving. This provides a clean way to extend protocol messages (e.g., adding custom capabilities to initialize requests) without needing to subclass or override protocol methods.

This is the TypeScript SDK equivalent of modelcontextprotocol/python-sdk#1911 for the Python SDK.

Motivation

When clients need to add custom fields to MCP messages (like protocol extensions or custom capabilities), they currently have to override protocol methods and duplicate internal logic. This is error-prone and creates maintenance burden.

A middleware approach provides a clean escape hatch that:

• Doesn't require subclassing
• Works with any message type (requests, responses, notifications)
• Supports both sync and async transformations
• Can be composed (multiple middleware functions)

Example Usage

import { Client, isJSONRPCRequest } from '@modelcontextprotocol/sdk/client';

const client = new Client({
    name: 'my-client',
    version: '1.0.0'
}, {
    sendMiddleware: [
        (message) => {
            if (isJSONRPCRequest(message) && message.method === 'initialize') {
                // Add custom capabilities
                return {
                    ...message,
                    params: {
                        ...message.params,
                        capabilities: {
                            ...message.params?.capabilities,
                            extensions: {
                                'io.modelcontextprotocol/ui': { mimeTypes: ['text/html'] }
                            }
                        }
                    }
                };
            }
            return message;
        }
    ]
});

Implementation

• Added MessageMiddleware type: (message: JSONRPCMessageLike) => JSONRPCMessageLike | Promise<JSONRPCMessageLike>
• Added JSONRPCMessageLike type alias for all JSON-RPC message types
• Added sendMiddleware and receiveMiddleware to ProtocolOptions
• Middleware is applied in:
  • connect() for incoming messages (receive middleware)
  • request() for outgoing requests (send middleware)
  • notification() for outgoing notifications (send middleware)
• Both sync and async middleware functions are supported

[changeset-bot]

⚠️ No Changeset found

Latest commit: d4f8dfa

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/client@1406

@modelcontextprotocol/server

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server@1406

@modelcontextprotocol/express

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/express@1406

@modelcontextprotocol/hono

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/hono@1406

@modelcontextprotocol/node

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/node@1406

commit: d4f8dfa