feat(core): concrete Protocol with custom-method overloads + deprecated v1 schema-arg shims

[felixweinberger]

Part of the v2 backwards-compatibility series — see reviewer guide.

Makes Protocol concrete and exported; adds 3-arg setRequestHandler(method, paramsSchema, handler) overload for custom (non-spec) methods; method-keyed request() return type; restores @deprecated v1 schema-argument overloads; adds notifyCustom() so notification() stays single-signature (mock-assignable).

Motivation and Context

v2's setRequestHandler<M extends RequestMethod> is a closed union — custom (vendor-prefixed) methods crash at runtime. This restores extensibility via a 3-arg overload, makes request() method-keyed so request({method:'tools/list'}) returns ListToolsResult, and brings back setRequestHandler(ZodSchema, h) as a @deprecated overload so v1 code keeps compiling.

v1 vs v2 patterns

v1:

server.setRequestHandler(ListToolsRequestSchema, async () => ({tools: []}));
const r = await client.request({method:'tools/call', params}, CallToolResultSchema);
client.setNotificationHandler(CustomSchema, h);  // custom method

v2-native:

server.setRequestHandler('tools/list', async () => ({tools: []}));
const r = await client.request({method:'tools/call', params});  // typed return
client.setNotificationHandler('vendor/custom', paramsSchema, h);  // 3-arg form

How Has This Been Tested?

• Unit: customMethods.test.ts, protocol.compat.test.ts — 3-arg overload, schema-arg dispatch, mock-assignment, notifyCustom validation
• Integration: validated bump-only against 5 OSS repos via the v2-bc-integration validation branch
• pnpm typecheck:all && pnpm lint:all && pnpm test:all green (core 507/507)

Breaking Changes

None vs current main — additive. Supersedes the closed #1846/#1868 approach.

Types of changes

• New feature (non-breaking change which adds functionality)

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added or updated documentation as needed

Additional context

Stacks on: C1 (deprecate() helper). This is the largest PR in the series (~+1000 LOC) — could split into "concrete Protocol + overloads" / "deprecated schema-arg shims" if preferred, but they touch the same protocol.ts.

[changeset-bot]

🦋 Changeset detected

Latest commit: 070a9cd

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 7 packages

Name	Type
@modelcontextprotocol/core	Patch
@modelcontextprotocol/client	Minor
@modelcontextprotocol/server	Minor
@modelcontextprotocol/node	Major
@modelcontextprotocol/express	Major
@modelcontextprotocol/fastify	Major
@modelcontextprotocol/hono	Major

Not sure what this means? Click here to learn what changesets are.

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

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/@modelcontextprotocol/client@1891

@modelcontextprotocol/server

npm i https://pkg.pr.new/@modelcontextprotocol/server@1891

@modelcontextprotocol/express

npm i https://pkg.pr.new/@modelcontextprotocol/express@1891

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/@modelcontextprotocol/fastify@1891

@modelcontextprotocol/hono

npm i https://pkg.pr.new/@modelcontextprotocol/hono@1891

@modelcontextprotocol/node

npm i https://pkg.pr.new/@modelcontextprotocol/node@1891

commit: 070a9cd