Merge branch 'main' into fix/1362-widen-elicit-schema-types

Dave-London · web-flow · commit 4844b3ad1372 · 2026-02-11T05:11:49.000+02:00
diff --git a/.changeset/add-hono-peer-dep.md b/.changeset/add-hono-peer-dep.md
@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/node': patch
+---
+
+Add missing `hono` peer dependency to `@modelcontextprotocol/node`. The package already depends on `@hono/node-server` which requires `hono` at runtime, but `hono` was only listed in the workspace root, not as a peer dependency of the package itself.
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,6 @@
+# Temporary files
+tmp/
+
 # Logs
 logs
 *.log
diff --git a/packages/client/src/client/auth.ts b/packages/client/src/client/auth.ts
@@ -60,7 +60,7 @@ export interface OAuthClientProvider {
     get clientMetadata(): OAuthClientMetadata;
 
     /**
-     * Returns a OAuth2 state parameter.
+     * Returns an OAuth2 state parameter.
      */
     state?(): string | Promise<string>;
 
@@ -654,7 +654,8 @@ export function extractResourceMetadataUrl(res: Response): URL | undefined {
 }
 
 /**
- * Looks up RFC 9728 OAuth 2.0 Protected Resource Metadata.
+ * Looks up {@link https://datatracker.ietf.org/doc/html/rfc9728 | RFC 9728}
+ * OAuth 2.0 Protected Resource Metadata.
  *
  * If the server returns a 404 for the well-known endpoint, this function will
  * return `undefined`. Any other errors will be thrown as exceptions.
@@ -872,8 +873,11 @@ export function buildDiscoveryUrls(authorizationServerUrl: string | URL): { url:
 }
 
 /**
- * Discovers authorization server metadata with support for RFC 8414 OAuth 2.0 Authorization Server Metadata
- * and OpenID Connect Discovery 1.0 specifications.
+ * Discovers authorization server metadata with support for
+ * {@link https://datatracker.ietf.org/doc/html/rfc8414 | RFC 8414} OAuth 2.0
+ * Authorization Server Metadata and
+ * {@link https://openid.net/specs/openid-connect-discovery-1_0.html | OpenID Connect Discovery 1.0}
+ * specifications.
  *
  * This function implements a fallback strategy for authorization server discovery:
  * 1. Attempts RFC 8414 OAuth metadata discovery first
@@ -1206,6 +1210,7 @@ export async function refreshAuthorization(
  * @throws {Error} When provider doesn't implement prepareTokenRequest or token fetch fails
  *
  * @example
+ * ```typescript
  * // Provider for client_credentials:
  * class MyProvider implements OAuthClientProvider {
  *   prepareTokenRequest(scope) {
@@ -1217,6 +1222,7 @@ export async function refreshAuthorization(
  * }
  *
  * const tokens = await fetchToken(provider, authServerUrl, { metadata });
+ * ```
  */
 export async function fetchToken(
     provider: OAuthClientProvider,
@@ -1267,7 +1273,8 @@ export async function fetchToken(
 }
 
 /**
- * Performs OAuth 2.0 Dynamic Client Registration according to RFC 7591.
+ * Performs OAuth 2.0 Dynamic Client Registration according to
+ * {@link https://datatracker.ietf.org/doc/html/rfc7591 | RFC 7591}.
  */
 export async function registerClient(
     authorizationServerUrl: string | URL,
diff --git a/packages/client/src/client/authExtensions.ts b/packages/client/src/client/authExtensions.ts
@@ -13,9 +13,11 @@ import type { AddClientAuthentication, OAuthClientProvider } from './auth.js';
 /**
  * Helper to produce a private_key_jwt client authentication function.
  *
- * Usage:
- *   const addClientAuth = createPrivateKeyJwtAuth({ issuer, subject, privateKey, alg, audience? });
- *   // pass addClientAuth as provider.addClientAuthentication implementation
+ * @example
+ * ```typescript
+ * const addClientAuth = createPrivateKeyJwtAuth({ issuer, subject, privateKey, alg, audience? });
+ * // pass addClientAuth as provider.addClientAuthentication implementation
+ * ```
  */
 export function createPrivateKeyJwtAuth(options: {
     issuer: string;
@@ -30,7 +32,7 @@ export function createPrivateKeyJwtAuth(options: {
         // Lazy import to avoid heavy dependency unless used
         if (globalThis.crypto === undefined) {
             throw new TypeError(
-                'crypto is not available, please ensure you add have Web Crypto API support for older Node.js versions (see https://github.com/modelcontextprotocol/typescript-sdk#nodejs-web-crypto-globalthiscrypto-compatibility)'
+                'crypto is not available, please ensure you have Web Crypto API support for older Node.js versions (see https://github.com/modelcontextprotocol/typescript-sdk#nodejs-web-crypto-globalthiscrypto-compatibility)'
             );
         }
 
@@ -114,6 +116,7 @@ export interface ClientCredentialsProviderOptions {
  * the client authenticates using a client_id and client_secret.
  *
  * @example
+ * ```typescript
  * const provider = new ClientCredentialsProvider({
  *   clientId: 'my-client',
  *   clientSecret: 'my-secret'
@@ -122,6 +125,7 @@ export interface ClientCredentialsProviderOptions {
  * const transport = new StreamableHTTPClientTransport(serverUrl, {
  *   authProvider: provider
  * });
+ * ```
  */
 export class ClientCredentialsProvider implements OAuthClientProvider {
     private _tokens?: OAuthTokens;
@@ -219,9 +223,11 @@ export interface PrivateKeyJwtProviderOptions {
  * OAuth provider for client_credentials grant with private_key_jwt authentication.
  *
  * This provider is designed for machine-to-machine authentication where
- * the client authenticates using a signed JWT assertion (RFC 7523 Section 2.2).
+ * the client authenticates using a signed JWT assertion
+ * ({@link https://datatracker.ietf.org/doc/html/rfc7523#section-2.2 | RFC 7523 Section 2.2}).
  *
  * @example
+ * ```typescript
  * const provider = new PrivateKeyJwtProvider({
  *   clientId: 'my-client',
  *   privateKey: pemEncodedPrivateKey,
@@ -231,6 +237,7 @@ export interface PrivateKeyJwtProviderOptions {
  * const transport = new StreamableHTTPClientTransport(serverUrl, {
  *   authProvider: provider
  * });
+ * ```
  */
 export class PrivateKeyJwtProvider implements OAuthClientProvider {
     private _tokens?: OAuthTokens;
diff --git a/packages/client/src/client/streamableHttp.ts b/packages/client/src/client/streamableHttp.ts
@@ -44,7 +44,7 @@ export interface StartSSEOptions {
 
     /**
      * Override Message ID to associate with the replay message
-     * so that response can be associate with the new resumed request.
+     * so that the response can be associated with the new resumed request.
      */
     replayMessageId?: string | number;
 }
@@ -255,7 +255,7 @@ export class StreamableHTTPClientTransport implements Transport {
     }
 
     /**
-     * Calculates the next reconnection delay using  backoff algorithm
+     * Calculates the next reconnection delay using a backoff algorithm
      *
      * @param attempt Current reconnection attempt count for the specific stream
      * @returns Time to wait in milliseconds before next reconnection attempt
@@ -463,7 +463,7 @@ export class StreamableHTTPClientTransport implements Transport {
             const { resumptionToken, onresumptiontoken } = options || {};
 
             if (resumptionToken) {
-                // If we have at last event ID, we need to reconnect the SSE stream
+                // If we have a last event ID, we need to reconnect the SSE stream
                 this._startOrAuthSse({ resumptionToken, replayMessageId: isJSONRPCRequest(message) ? message.id : undefined }).catch(
                     error => this.onerror?.(error)
                 );
diff --git a/packages/client/test/client/authExtensions.test.ts b/packages/client/test/client/authExtensions.test.ts
@@ -191,7 +191,7 @@ describe('createPrivateKeyJwtAuth', () => {
             const params = new URLSearchParams();
 
             await expect(addClientAuth(new Headers(), params, 'https://auth.example.com/token', undefined)).rejects.toThrow(
-                'crypto is not available, please ensure you add have Web Crypto API support for older Node.js versions'
+                'crypto is not available, please ensure you have Web Crypto API support for older Node.js versions'
             );
         } finally {
             // Restore original crypto to avoid affecting other tests
diff --git a/packages/core/src/auth/errors.ts b/packages/core/src/auth/errors.ts
@@ -1,7 +1,8 @@
 import type { OAuthErrorResponse } from '../shared/auth.js';
 
 /**
- * OAuth error codes as defined by RFC 6749 and extensions.
+ * OAuth error codes as defined by {@link https://datatracker.ietf.org/doc/html/rfc6749#section-5.2 | RFC 6749}
+ * and extensions.
  */
 export enum OAuthErrorCode {
     /**
diff --git a/packages/core/src/experimental/tasks/interfaces.ts b/packages/core/src/experimental/tasks/interfaces.ts
@@ -97,6 +97,7 @@ export interface QueuedError extends BaseQueuedMessage {
  * All methods are async to support external storage implementations.
  * All data in QueuedMessage must be JSON-serializable.
  *
+ * @see {@linkcode InMemoryTaskMessageQueue} for a reference implementation
  * @experimental
  */
 export interface TaskMessageQueue {
@@ -157,6 +158,7 @@ export interface CreateTaskOptions {
  * Similar to Transport, this allows pluggable task storage implementations
  * (in-memory, database, distributed cache, etc.).
  *
+ * @see {@linkcode InMemoryTaskStore} for a reference implementation
  * @experimental
  */
 export interface TaskStore {
diff --git a/packages/core/src/shared/auth.ts b/packages/core/src/shared/auth.ts
@@ -71,7 +71,8 @@ export const OAuthMetadataSchema = z.looseObject({
 
 /**
  * OpenID Connect Discovery 1.0 Provider Metadata
- * see: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata
+ *
+ * @see https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata
  */
 export const OpenIdProviderMetadataSchema = z.looseObject({
     issuer: z.string(),
@@ -148,7 +149,7 @@ export const OAuthErrorResponseSchema = z.object({
 });
 
 /**
- * Optional version of SafeUrlSchema that allows empty string for retrocompatibility on tos_uri and logo_uri
+ * Optional version of SafeUrlSchema that allows empty string for backward compatibility on tos_uri and logo_uri
  */
 // eslint-disable-next-line unicorn/no-useless-undefined
 export const OptionalSafeUrlSchema = SafeUrlSchema.optional().or(z.literal('').transform(() => undefined));
diff --git a/packages/core/src/shared/authUtils.ts b/packages/core/src/shared/authUtils.ts
@@ -4,7 +4,8 @@
 
 /**
  * Converts a server URL to a resource URL by removing the fragment.
- * RFC 8707 section 2 states that resource URIs "MUST NOT include a fragment component".
+ * {@link https://datatracker.ietf.org/doc/html/rfc8707#section-2 | RFC 8707 section 2}
+ * states that resource URIs "MUST NOT include a fragment component".
  * Keeps everything else unchanged (scheme, domain, port, path, query).
  */
 export function resourceUrlFromServerUrl(url: URL | string): URL {
diff --git a/packages/core/src/shared/protocol.ts b/packages/core/src/shared/protocol.ts
@@ -120,7 +120,7 @@ export type ProtocolOptions = {
 };
 
 /**
- * The default request timeout, in miliseconds.
+ * The default request timeout, in milliseconds.
  */
 export const DEFAULT_REQUEST_TIMEOUT_MSEC = 60_000;
 
@@ -1023,7 +1023,7 @@ export abstract class Protocol<ContextT extends BaseContext> {
     protected abstract assertTaskCapability(method: string): void;
 
     /**
-     * A method to check if task handler is supported by the local side, for the given method to be handled.
+     * A method to check if a task handler is supported by the local side, for the given method to be handled.
      *
      * This should be implemented by subclasses.
      */
diff --git a/packages/core/src/shared/toolNameValidation.ts b/packages/core/src/shared/toolNameValidation.ts
@@ -6,6 +6,8 @@
  * Allowed characters: uppercase and lowercase ASCII letters (A-Z, a-z), digits
  * (0-9), underscore (_), dash (-), and dot (.).
  * Tool names SHOULD NOT contain spaces, commas, or other special characters.
+ *
+ * @see {@link https://github.com/modelcontextprotocol/modelcontextprotocol/issues/986 | SEP-986: Specify Format for Tool Names}
  */
 
 /**
diff --git a/packages/core/src/types/types.ts b/packages/core/src/types/types.ts
@@ -1187,7 +1187,7 @@ export const ImageContentSchema = z.object({
 });
 
 /**
- * An Audio provided to or from an LLM.
+ * Audio content provided to or from an LLM.
  */
 export const AudioContentSchema = z.object({
     type: z.literal('audio'),
@@ -1340,7 +1340,7 @@ export const ToolAnnotationsSchema = z.object({
 
     /**
      * If true, calling the tool repeatedly with the same arguments
-     * will have no additional effect on the its environment.
+     * will have no additional effect on its environment.
      *
      * (This property is meaningful only when `readOnlyHint == false`)
      *
@@ -2070,7 +2070,7 @@ export const ElicitResultSchema = ResultSchema.extend({
     /**
      * The user action in response to the elicitation.
      * - "accept": User submitted the form/confirmed the action
-     * - "decline": User explicitly decline the action
+     * - "decline": User explicitly declined the action
      * - "cancel": User dismissed without making an explicit choice
      */
     action: z.enum(['accept', 'decline', 'cancel']),
diff --git a/packages/core/src/validation/ajvProvider.ts b/packages/core/src/validation/ajvProvider.ts
@@ -33,6 +33,8 @@ function createDefaultAjvInstance(): Ajv {
  * const ajv = new Ajv({ strict: true, allErrors: true });
  * const validator = new AjvJsonSchemaValidator(ajv);
  * ```
+ *
+ * @see {@linkcode CfWorkerJsonSchemaValidator} for an edge-runtime-compatible alternative
  */
 export class AjvJsonSchemaValidator implements jsonSchemaValidator {
     private _ajv: Ajv;
diff --git a/packages/core/src/validation/cfWorkerProvider.ts b/packages/core/src/validation/cfWorkerProvider.ts
@@ -4,6 +4,8 @@
  * This provider uses @cfworker/json-schema for validation without code generation,
  * making it compatible with edge runtimes like Cloudflare Workers that restrict
  * eval and new Function.
+ *
+ * @see {@linkcode AjvJsonSchemaValidator} for the Node.js alternative
  */
 
 import { Validator } from '@cfworker/json-schema';
diff --git a/packages/middleware/node/package.json b/packages/middleware/node/package.json
@@ -49,7 +49,8 @@
         "@hono/node-server": "catalog:runtimeServerOnly"
     },
     "peerDependencies": {
-        "@modelcontextprotocol/server": "workspace:^"
+        "@modelcontextprotocol/server": "workspace:^",
+        "hono": "catalog:runtimeServerOnly"
     },
     "devDependencies": {
         "@modelcontextprotocol/server": "workspace:^",
diff --git a/packages/middleware/node/src/streamableHttp.ts b/packages/middleware/node/src/streamableHttp.ts
@@ -1,5 +1,5 @@
 /**
- * Node.js HTTP Streamable HTTP Server Transport
+ * Node.js Streamable HTTP Server Transport
  *
  * This is a thin wrapper around `WebStandardStreamableHTTPServerTransport` that provides
  * compatibility with Node.js HTTP server (IncomingMessage/ServerResponse).
diff --git a/packages/server/src/server/completable.ts b/packages/server/src/server/completable.ts
@@ -20,6 +20,8 @@ export type CompletableSchema<T extends AnySchema> = T & {
 
 /**
  * Wraps a Zod type to provide autocompletion capabilities. Useful for, e.g., prompt arguments in MCP.
+ *
+ * @see {@linkcode server/mcp.McpServer.registerPrompt | McpServer.registerPrompt} for using completable schemas in prompt argument definitions
  */
 export function completable<T extends AnySchema>(schema: T, complete: CompleteCallback<T>): CompletableSchema<T> {
     Object.defineProperty(schema as object, COMPLETABLE_SYMBOL, {
diff --git a/packages/server/src/server/mcp.ts b/packages/server/src/server/mcp.ts
@@ -117,7 +117,7 @@ export class McpServer {
 
         this.server.registerCapabilities({
             tools: {
-                listChanged: true
+                listChanged: this.server.getCapabilities().tools?.listChanged ?? true
             }
         });
 
@@ -429,7 +429,7 @@ export class McpServer {
 
         this.server.registerCapabilities({
             resources: {
-                listChanged: true
+                listChanged: this.server.getCapabilities().resources?.listChanged ?? true
             }
         });
 
@@ -509,7 +509,7 @@ export class McpServer {
 
         this.server.registerCapabilities({
             prompts: {
-                listChanged: true
+                listChanged: this.server.getCapabilities().prompts?.listChanged ?? true
             }
         });
 
@@ -886,10 +886,10 @@ export class McpServer {
 
     /**
      * Sends a logging message to the client, if connected.
-     * Note: You only need to send the parameters object, not the entire JSON RPC message
+     * Note: You only need to send the parameters object, not the entire JSON-RPC message.
      * @see LoggingMessageNotification
      * @param params
-     * @param sessionId optional for stateless and backward compatibility
+     * @param sessionId Optional for stateless transports and backward compatibility.
      */
     async sendLoggingMessage(params: LoggingMessageNotification['params'], sessionId?: string) {
         return this.server.sendLoggingMessage(params, sessionId);
@@ -943,7 +943,7 @@ export class ResourceTemplate {
         uriTemplate: string | UriTemplate,
         private _callbacks: {
             /**
-             * A callback to list all resources matching this template. This is required to specified, even if `undefined`, to avoid accidentally forgetting resource listing.
+             * A callback to list all resources matching this template. This is required to be specified, even if `undefined`, to avoid accidentally forgetting resource listing.
              */
             list: ListResourcesCallback | undefined;
 
diff --git a/packages/server/src/server/middleware/hostHeaderValidation.ts b/packages/server/src/server/middleware/hostHeaderValidation.ts
@@ -44,7 +44,9 @@ export function localhostAllowedHostnames(): string[] {
 /**
  * Web-standard Request helper for DNS rebinding protection.
  * @example
+ * ```typescript
  * const result = validateHostHeader(req.headers.get('host'), ['localhost'])
+ * ```
  */
 export function hostHeaderValidationResponse(req: Request, allowedHostnames: string[]): Response | undefined {
     const result = validateHostHeader(req.headers.get('host'), allowedHostnames);
diff --git a/packages/server/src/server/server.ts b/packages/server/src/server/server.ts
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/test/integration/test/server/mcp.test.ts b/test/integration/test/server/mcp.test.ts
diff --git a/typedoc.config.mjs b/typedoc.config.mjs

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@modelcontextprotocol/node': patch
 +---
++
 +Add missing `hono` peer dependency to `@modelcontextprotocol/node`. The package already depends on `@hono/node-server` which requires `hono` at runtime, but `hono` was only listed in the workspace root, not as a peer dependency of the package itself.