feat(core): export Protocol class + ProtocolSpec generic for typed custom vocabularies

[felixweinberger]

Part of the v2 BC series — see reviewer guide. Stacks on #1916 (which stacks on #1891).

Exports the abstract Protocol class (was reachable in v1 via deep imports; ext-apps subclasses it) and adds Protocol<ContextT, SpecT extends ProtocolSpec = McpSpec>. Supplying a concrete ProtocolSpec gives method-name autocomplete and params/result correlation on the typed setRequestHandler/setNotificationHandler overloads.

Motivation and Context

v1 exposed Protocol via deep imports (sdk/shared/protocol.js). MCP-dialect protocols (e.g., MCP Apps) subclass it. v2 omitted it from the public surface — this restores it and adds a ProtocolSpec type-level vocabulary.

How Has This Been Tested?

packages/core/test/shared/protocolSpec.test.ts — typed-SpecT inference, SpecRequests<ProtocolSpec> = never, params typed by passed schema (not SpecT).

Breaking Changes

None — additive. Protocol stays abstract; the second generic defaults so existing Protocol<ContextT> references work unchanged.

Types of changes

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

Additional context

Stacks on #1916 → #1891.

[changeset-bot]

🦋 Changeset detected

Latest commit: a6a9a52

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

This PR includes changesets to release 6 packages

Name	Type
@modelcontextprotocol/client	Minor
@modelcontextprotocol/server	Minor
@modelcontextprotocol/express	Major
@modelcontextprotocol/fastify	Major
@modelcontextprotocol/hono	Major
@modelcontextprotocol/node	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@1917

@modelcontextprotocol/server

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

@modelcontextprotocol/express

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

@modelcontextprotocol/fastify

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

@modelcontextprotocol/hono

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

@modelcontextprotocol/node

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

commit: a6a9a52

[felixweinberger]

@claude review

[claude]

No correctness issues spotted beyond the doc-drift nit, but this promotes Protocol (plus four new types) into the curated public surface and adds a second class-level generic — that's exactly the kind of API-surface commitment REVIEW.md says needs a human maintainer's sign-off, so deferring.

Extended reasoning...

Overview

This PR (third in the v2-bc stack) does two things: (1) re-exports the abstract Protocol class from core/public along with four new type-level helpers (ProtocolSpec, McpSpec, SpecRequests, SpecNotifications), and (2) extends Protocol with a second generic parameter SpecT extends ProtocolSpec = McpSpec plus a new spec-typed overload at the front of the setRequestHandler / setNotificationHandler overload sets. ContextT also gains a = BaseContext default. A new vitest file covers the type inference, and a changeset is included.

Security risks

None identified — purely type-level additions and an export-barrel change; no new runtime code paths, I/O, auth, or parsing logic.

Level of scrutiny

High, on API-surface grounds rather than correctness. REVIEW.md is explicit that the burden of proof is on addition and that every new public export must be intentional; CLAUDE.md §Public API Exports until now used Protocol as the canonical internal-only example. Promoting it (and committing to ProtocolSpec as a public extension contract) is a deliberate policy reversal that a maintainer should explicitly approve — even if the motivation (v1 deep-import parity, ext-apps subclassing) is sound.

Other factors

• I verified Client and Server both re-declare their own setRequestHandler overload sets, so the new SpecT-typed overload on the base class is shadowed there and shouldn't perturb existing user-facing inference; the change is effectively scoped to direct Protocol subclasses.
• The defaults (ContextT = BaseContext, SpecT = McpSpec) keep existing extends Protocol<X> references compiling, and SpecRequests<ProtocolSpec> = never correctly disables the typed overload for the unconstrained default — both are exercised in the new test.
• One nit (posted inline): the file-header JSDoc in exports/public/index.ts and CLAUDE.md still cite Protocol as internal-only, contradicting the new export.
• Stacked on #1916 → #1891; reviewer should confirm this lands in the intended order.

[felixweinberger]

@claude review

[felixweinberger]

@claude review

[felixweinberger]

@claude review

[felixweinberger]

@claude review

[claude]

🟡 Nit: 8a26ebc applied the same never-guard + ResultTypeMap[M] 3-arg overload to both Server.setRequestHandler and Client.setRequestHandler, but only Server got a @ts-expect-error type-regression test (packages/server/test/server/setRequestHandlerSchemaParity.test.ts:106-112). The parallel packages/client/test/client/setRequestHandlerSchemaParity.test.ts already exists and mirrors the other Server cases — worth dropping the same ~6-line test in there so a future edit to client.ts can't silently drop the guard (subclass overload sets fully shadow Protocol's, so neither protocolSpec.test.ts nor the Server test covers Client).

Extended reasoning...

What's missing. Commit 8a26ebc propagated the never-guard fix to both subclass overrides: Server.setRequestHandler (server.ts:235-244) and Client.setRequestHandler (client.ts:348-357) each gained an M extends RequestMethod 3-arg overload returning ResultTypeMap[M], plus the method: M extends RequestMethod ? never : M guard on the loose overload. The same commit added a type-level regression test for Server at packages/server/test/server/setRequestHandlerSchemaParity.test.ts:106-112 — a @ts-expect-error asserting that s.setRequestHandler('ping', z.object({}), () => ({ ok: 'wrong-type' })) fails to compile. No equivalent test was added for Client, even though a directly parallel file packages/client/test/client/setRequestHandlerSchemaParity.test.ts already exists (91 lines) and otherwise mirrors the Server parity tests case-for-case.

Why the existing tests don't cover it. The whole reason 8a26ebc had to touch client.ts and server.ts at all (per resolved inline comment 3100080308) is that a subclass which redeclares an overloaded method's signature set fully shadows the base class's overloads at call sites. So:

• packages/core/test/shared/protocolSpec.test.ts:69-76 exercises the guard on a direct Protocol subclass — it never sees Client's overload set.
• packages/server/.../setRequestHandlerSchemaParity.test.ts:106-112 exercises Server's overload set — it never sees Client's.
• The client parity file's existing 3-arg test at line 80 uses () => invalidElicitResult as never to bypass the new return-type constraint for a runtime assertion. An as never cast compiles whether or not the guard exists, so it is not a regression test for the type-level change.

A future edit to client.ts that dropped the never-guard or the ResultTypeMap[M] overload would therefore pass pnpm typecheck:all and pnpm test:all cleanly.

Step-by-step proof.

1. Open packages/client/src/client/client.ts:353-357: the loose 3-arg overload's first parameter is method: M extends RequestMethod ? never : M.
2. Hypothetically revert that line to method: string (the pre-8a26ebc form) and delete the ResultTypeMap[M] overload at lines 348-352.
3. grep -r '@ts-expect-error' packages/client/test/ → no matches. There is no type-level assertion in the client package that depends on the guard.
4. The client parity file's line 80 still compiles (as never is assignable to anything). Lines 87-89 ('acme/echo', non-spec method) still compile against plain method: string.
5. The core test at protocolSpec.test.ts:69-76 calls new TestProtocol<AppSpec>().setRequestHandler(...), which resolves against Protocol's overload set, not Client's — still passes.
6. The server test at setRequestHandlerSchemaParity.test.ts:108 calls new Server(...).setRequestHandler(...) — unaffected by the Client edit.
7. Result: the regression ships with green CI.

Why it's worth flagging. Per REVIEW.md §Tests ("New behavior has vitest coverage") and §Completeness ("when a PR replaces a pattern, grep the package for surviving instances"), this is the textbook asymmetric-coverage shape: the PR established the test-the-override pattern for Server but skipped Client for an identical change in the same commit. The parallel test file already exists, already imports Client and z, and already has 3-arg-form cases — so the marginal cost is ~6 lines.

Fix. Mirror the Server case into packages/client/test/client/setRequestHandlerSchemaParity.test.ts, e.g.:

it('three-arg form on Client enforces spec-method result type (no fallthrough to loose overload)', () => {
    const c = new Client({ name: 't', version: '1.0' }, { capabilities: {} });
    // @ts-expect-error -- result for 'ping' must be EmptyResult-compatible; loose overload is never-guarded for spec methods
    c.setRequestHandler('ping', z.object({}), () => ({ ok: 'wrong-type' }) as { ok: string });
    // non-spec methods still allow loose Result
    c.setRequestHandler('acme/custom', z.object({}), () => ({ anything: 1 }));
});

Nit-level — no runtime or correctness impact; this is purely about locking in the type-level guarantee on both subclasses.