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: 04d9133

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: 04d9133

[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

[claude]

All prior doc nits are addressed and the type-level machinery looks correct, but since this adds Protocol + the ProtocolSpec/McpSpec/SpecRequests family to the public API surface, a maintainer should sign off on the export decision.

Extended reasoning...

Overview

This PR promotes the abstract Protocol class from internal-only to the curated public barrel (core/public), adds a second generic parameter SpecT extends ProtocolSpec = McpSpec to Protocol, and introduces four new exported type aliases (ProtocolSpec, McpSpec, SpecRequests, SpecNotifications). It also adds spec-typed overload signatures to setRequestHandler/setNotificationHandler. The implementation body of those methods is unchanged — the new overloads are pure type-level declarations that resolve to the existing 3-arg dispatch. Supporting changes: a changeset, CLAUDE.md prose update, the public/index.ts file-header/section-comment updates, and a new protocolSpec.test.ts with type-level assertions and one runtime round-trip.

Review history

I raised three rounds of doc-only nits (stale "internal-only" prose in CLAUDE.md and the file header; ambiguous "the default" wording in the ProtocolSpec JSDoc; misleading "params inferred from SpecT" wording on the handler JSDocs; and a "concrete" vs "abstract" regression in the section comment). All four are now resolved in the current diff — commit 00306b5 fixed the last one. The bug-hunting pass on this revision found nothing.

Security risks

None. No runtime control-flow, auth, transport, or wire-format changes. The only runtime-visible delta is that Protocol is now reachable from @modelcontextprotocol/client/server re-exports; the class itself is unchanged.

Level of scrutiny

Medium. Correctness risk is low (type-only additions, defaulted generic, unchanged implementation). But this is a deliberate public-API expansion in a repo whose REVIEW.md leads with "burden of proof is on addition" and "removing something from the public API is far harder than not adding it." Exporting Protocol commits the SDK to supporting third-party subclassing, and ProtocolSpec/SpecRequests/SpecNotifications become a stable type-level contract. That's a maintainer-level call, not something to auto-approve.

Other factors

The PR is part of the labeled v2-bc series with a linked reviewer guide and stacks on #1916/#1891, so the design has presumably been discussed in that context — but the stacked-PR base and the guide aren't visible here, so I can't independently verify the rationale beyond "v1 exposed this via deep imports." Test coverage is adequate for what's added (typed-SpecT inference, SpecRequests<ProtocolSpec> = never, params-typed-by-schema regression). No outstanding reviewer comments remain.

[felixweinberger]

@claude review

[felixweinberger]

@claude review

[claude]

🟡 Nit: after 7051b7c changed "params/result correlation" → "result-type correlation", this JSDoc (and .changeset/export-protocol-spec.md:6) still says SpecT gives "method-name autocomplete and result-type correlation on the typed overloads of setRequestHandler and setNotificationHandler". Notification handlers return void — there's no result type to correlate, so for setNotificationHandler SpecT only contributes method-name autocomplete. Suggest: "method-name autocomplete on both, plus result-type correlation on setRequestHandler" (or just drop setNotificationHandler from the result-correlation clause).

Extended reasoning...

What's overstated. The ProtocolSpec JSDoc at protocol.ts:311-313 and the changeset at .changeset/export-protocol-spec.md:6 both read: "method-name autocomplete and result-type correlation on the typed overloads of setRequestHandler and setNotificationHandler". The natural English parse distributes both features ("method-name autocomplete" and "result-type correlation") across both methods. But notification handlers have no result type — the SpecT-typed setNotificationHandler overload (protocol.ts:1209-1213) declares the handler as (params: StandardSchemaV1.InferOutput<P>) => void | Promise<void>, identical to the never-guarded string overload below it. There is nothing for "result-type correlation" to correlate.

How it got here. Commit 7051b7c addressed the prior review comment (inline 3100080328) that flagged "params/result correlation" as overstating what SpecT does, since e042fae had dropped the params constraint. The fix changed "params/result" → "result-type" in both locations — correct for setRequestHandler — but left setNotificationHandler in the conjunction. After dropping "params/", setNotificationHandler's only remaining SpecT contribution is the K extends SpecNotifications<SpecT> method-name constraint; the "result-type" half no longer has anything to point at for notifications.

Step-by-step proof.

1. Define type Spec = { notifications: { 'ui/ping': { params: { n: number } } } } and const p = new TestProtocol<Spec>().
2. The SpecT-typed overload at protocol.ts:1209 resolves K = 'ui/ping' (method-name autocomplete ✓).
3. The handler signature is (params: InferOutput<P>) => void | Promise<void> — no _Notifications<SpecT>[K]['result'] lookup exists (notifications have no result field in ProtocolSpec, line 321: notifications?: Record<string, { params?: unknown }>).
4. Compare to setRequestHandler's SpecT overload at protocol.ts:1100-1107, which types the return as _Requests<SpecT>[K]['result'] | Promise<…> — that's the result-type correlation the prose describes.
5. So for setNotificationHandler, SpecT contributes only step 2 (autocomplete); the "result-type correlation" claim is vacuous there.

Partial mitigation, and why it's still worth fixing. The very next paragraph (protocol.ts:316-317: "Only requests[K].result is enforced by the type system") implicitly scopes result enforcement to requests, so a careful reader can reconcile. But the headline sentence is what readers skim, and the changeset prose lands verbatim in published CHANGELOGs where the mitigating paragraph won't follow it. Per REVIEW.md §Documentation & Changesets ("flag any claim the diff doesn't back"), this is the textbook case.

Fix. One-clause reword in both locations, e.g.: "gives method-name autocomplete on the typed overloads of setRequestHandler and setNotificationHandler, plus result-type correlation on setRequestHandler" — or simply drop setNotificationHandler from the sentence and let the next paragraph cover it. Doc-only; no runtime or type-level impact.