docs: update prose now that Protocol is concrete and public

Author: felixweinberger

CLAUDE.md

@@ -67,7 +67,7 @@ The SDK is organized into three main layers:
 The SDK has a two-layer export structure to separate internal code from the public API:
 
 - **`@modelcontextprotocol/core`** (main entry, `packages/core/src/index.ts`) — Internal barrel. Exports everything (including Zod schemas, Protocol class, stdio utils). Only consumed by sibling packages within the monorepo (`private: true`).
-- **`@modelcontextprotocol/core/public`** (`packages/core/src/exports/public/index.ts`) — Curated public API. Exports only TypeScript types, error classes, constants, and guards. Re-exported by client and server packages.
+- **`@modelcontextprotocol/core/public`** (`packages/core/src/exports/public/index.ts`) — Curated public API. Exports TypeScript types, error classes, constants, guards, and the `Protocol` class. Re-exported by client and server packages.
 - **`@modelcontextprotocol/client`** and **`@modelcontextprotocol/server`** (`packages/*/src/index.ts`) — Final public surface. Package-specific exports (named explicitly) plus re-exports from `core/public`.
 
 When modifying exports:

packages/core/src/exports/public/index.ts

@@ -4,9 +4,9 @@
  * This module defines the stable, public-facing API surface. Client and server
  * packages re-export from here so that end users only see supported symbols.
  *
- * Internal utilities (Protocol class, stdio parsing, schema helpers, etc.)
- * remain available via the internal barrel (@modelcontextprotocol/core) for
- * use by client/server packages.
+ * Internal utilities (stdio parsing, schema helpers, etc.) remain available via
+ * the internal barrel (@modelcontextprotocol/core) for use by client/server
+ * packages.
  */
 
 // Auth error classes
@@ -38,7 +38,7 @@ export { checkResourceAllowed, resourceUrlFromServerUrl } from '../../shared/aut
 // Metadata utilities
 export { getDisplayName } from '../../shared/metadataUtils.js';
 
-// Protocol class (abstract — subclass for custom vocabularies) + types. NOT mergeCapabilities.
+// Protocol class (concrete; subclass for custom vocabularies via SpecT) + types. NOT mergeCapabilities.
 export type {
     BaseContext,
     ClientContext,

packages/core/src/shared/protocol.ts

@@ -310,7 +310,8 @@ type TimeoutInfo = {
  *
  * Supplying a concrete `ProtocolSpec` as `Protocol`'s second type argument gives method-name
  * autocomplete and params/result correlation on the typed overloads of `setRequestHandler`
- * and `setNotificationHandler`. The default leaves them string-keyed and untyped.
+ * and `setNotificationHandler`. `Protocol` defaults to {@linkcode McpSpec}; using the bare
+ * `ProtocolSpec` type leaves methods string-keyed and untyped.
  */
 export type ProtocolSpec = {
     requests?: Record<string, { params?: unknown; result: unknown }>;
@@ -1082,8 +1083,9 @@ export abstract class Protocol<ContextT extends BaseContext = BaseContext, SpecT
      *   Any method string; the supplied schema validates incoming `params`. Absent or undefined
      *   `params` are normalized to `{}` (after stripping `_meta`) before validation, so for
      *   no-params methods use `z.object({})`. `paramsSchema` may be any Standard Schema (Zod,
-     *   Valibot, ArkType, etc.). When `method` is listed in this instance's
-     *   {@linkcode ProtocolSpec}, params and result types are inferred from `SpecT`.
+     *   Valibot, ArkType, etc.). The handler's `params` type is inferred from the passed
+     *   `paramsSchema`; when `method` is listed in this instance's {@linkcode ProtocolSpec},
+     *   `paramsSchema`'s input and the handler's result type are constrained by `SpecT`.
      * - **Zod schema** — `setRequestHandler(RequestZodSchema, (request, ctx) => …)`. The method
      *   name is read from the schema's `method` literal; the handler receives the parsed request.
      */
@@ -1193,8 +1195,9 @@ export abstract class Protocol<ContextT extends BaseContext = BaseContext, SpecT
      * Mirrors {@linkcode setRequestHandler}: a two-arg spec-method form (handler receives the full
      * notification object), a three-arg form with a `paramsSchema` (handler receives validated
      * `params`), and a Zod-schema form (method read from the schema's `method` literal). When the
-     * three-arg form's `method` is listed in this instance's {@linkcode ProtocolSpec}, the params
-     * type is inferred from `SpecT`.
+     * three-arg form's `method` is listed in this instance's {@linkcode ProtocolSpec},
+     * `paramsSchema`'s input is constrained by `SpecT`; the handler's `params` type is always
+     * inferred from the passed schema.
      */
     setNotificationHandler<K extends SpecNotifications<SpecT>, P extends StandardSchemaV1<_Notifications<SpecT>[K]['params']>>(
         method: K,