modelcontextprotocol/typescript-sdk
Watch
1
0
Fork
You've already forked typescript-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

Add code reference links and backticks to JSDoc comments (#1484)

Browse source 
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com>
This commit is contained in:
Jonathan Hefner 2026-02-11 16:40:32 -06:00 • committed by GitHub
commit 42b335953a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 400 additions and 400 deletions
Download patch file Download diff file Expand all files Collapse all files

2
packages/server/src/experimental/tasks/interfaces.ts
View file

@ -30,7 +30,7 @@ export type CreateTaskRequestHandler<ResultT extends Result, Args extends AnySch
>;
/**
* Handler for task operations (get, getResult).
* Handler for task operations (`get`, `getResult`).
* @experimental
*/
export type TaskRequestHandler<ResultT extends Result, Args extends AnySchema | undefined = undefined> = BaseToolCallback<

12
packages/server/src/experimental/tasks/mcpServer.ts
View file

@ -1,5 +1,5 @@
/**
* Experimental McpServer task features for MCP SDK.
* Experimental {@linkcode McpServer} task features for MCP SDK.
* WARNING: These APIs are experimental and may change without notice.
*
* @experimental
@ -11,7 +11,7 @@ import type { AnyToolHandler, McpServer, RegisteredTool } from '../../server/mcp
import type { ToolTaskHandler } from './interfaces.js';
/**
* Internal interface for accessing McpServer's private _createRegisteredTool method.
* Internal interface for accessing {@linkcode McpServer}'s private _createRegisteredTool method.
* @internal
*/
interface McpServerInternal {
@ -29,7 +29,7 @@ interface McpServerInternal {
}
/**
* Experimental task features for McpServer.
* Experimental task features for {@linkcode McpServer}.
*
* Access via `server.experimental.tasks`:
* ```typescript
@ -45,7 +45,7 @@ export class ExperimentalMcpServerTasks {
* Registers a task-based tool with a config object and handler.
*
* Task-based tools support long-running operations that can be polled for status
* and results. The handler must implement `createTask`, `getTask`, and `getTaskResult`
* and results. The handler must implement {@linkcode ToolTaskHandler.createTask | createTask}, {@linkcode ToolTaskHandler.getTask | getTask}, and {@linkcode ToolTaskHandler.getTaskResult | getTaskResult}
* methods.
*
* @example
@ -71,8 +71,8 @@ export class ExperimentalMcpServerTasks {
*
* @param name - The tool name
* @param config - Tool configuration (description, schemas, etc.)
* @param handler - Task handler with createTask, getTask, getTaskResult methods
* @returns RegisteredTool for managing the tool's lifecycle
* @param handler - Task handler with {@linkcode ToolTaskHandler.createTask | createTask}, {@linkcode ToolTaskHandler.getTask | getTask}, {@linkcode ToolTaskHandler.getTaskResult | getTaskResult} methods
* @returns {@linkcode server/mcp.RegisteredTool | RegisteredTool} for managing the tool's lifecycle
*
* @experimental
*/

6
packages/server/src/experimental/tasks/server.ts
View file

@ -33,7 +33,7 @@ import type { Server } from '../../server/server.js';
* const stream = server.experimental.tasks.requestStream(request, schema, options);
* ```
*
* For high-level server usage with task-based tools, use `McpServer.experimental.tasks` instead.
* For high-level server usage with task-based tools, use {@linkcode index.McpServer | McpServer}.experimental.tasks instead.
*
* @experimental
*/
@ -42,7 +42,7 @@ export class ExperimentalServerTasks {
/**
* Sends a request and returns an AsyncGenerator that yields response messages.
* The generator is guaranteed to end with either a 'result' or 'error' message.
* The generator is guaranteed to end with either a `'result'` or `'error'` message.
*
* This method provides streaming access to request processing, allowing you to
* observe intermediate task status updates for task-augmented requests.
@ -50,7 +50,7 @@ export class ExperimentalServerTasks {
* @param request - The request to send
* @param resultSchema - Zod schema for validating the result
* @param options - Optional request options (timeout, signal, task creation params, etc.)
* @returns AsyncGenerator that yields ResponseMessage objects
* @returns AsyncGenerator that yields {@linkcode ResponseMessage} objects
*
* @experimental
*/

20
packages/server/src/server/mcp.ts
View file

@ -53,11 +53,11 @@ import { Server } from './server.js';
/**
* High-level MCP server that provides a simpler API for working with resources, tools, and prompts.
* For advanced usage (like sending notifications or setting custom request handlers), use the underlying
* Server instance available via the `server` property.
* {@linkcode Server} instance available via the {@linkcode McpServer.server | server} property.
*/
export class McpServer {
/**
* The underlying Server instance, useful for advanced operations like sending notifications.
* The underlying {@linkcode Server} instance, useful for advanced operations like sending notifications.
*/
public readonly server: Server;
@ -92,7 +92,7 @@ export class McpServer {
/**
* Attaches to the given transport, starts it, and starts listening for messages.
*
* The `server` object assumes ownership of the Transport, replacing any callbacks that have already been set, and expects that it is the only user of the Transport instance going forward.
* The `server` object assumes ownership of the {@linkcode Transport}, replacing any callbacks that have already been set, and expects that it is the only user of the {@linkcode Transport} instance going forward.
*/
async connect(transport: Transport): Promise<void> {
return await this.server.connect(transport);
@ -297,7 +297,7 @@ export class McpServer {
}
/**
* Handles automatic task polling for tools with taskSupport 'optional'.
* Handles automatic task polling for tools with `taskSupport` `'optional'`.
*/
private async handleAutomaticTaskPolling<RequestT extends CallToolRequest>(
tool: RegisteredTool,
@ -548,7 +548,7 @@ export class McpServer {
/**
* Registers a resource with a config object and callback.
* For static resources, use a URI string. For dynamic resources, use a ResourceTemplate.
* For static resources, use a URI string. For dynamic resources, use a {@linkcode ResourceTemplate}.
*/
registerResource(name: string, uriOrTemplate: string, config: ResourceMetadata, readCallback: ReadResourceCallback): RegisteredResource;
registerResource(
@ -878,7 +878,7 @@ export class McpServer {
/**
* Checks if the server is connected to a transport.
* @returns True if the server is connected
* @returns `true` if the server is connected
*/
isConnected() {
return this.server.transport !== undefined;
@ -887,7 +887,7 @@ 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.
* @see LoggingMessageNotification
* @see {@linkcode LoggingMessageNotification}
* @param params
* @param sessionId Optional for stateless transports and backward compatibility.
*/
@ -985,7 +985,7 @@ export type BaseToolCallback<ResultT extends Result, Ctx extends ServerContext,
: (ctx: Ctx) => ResultT | Promise<ResultT>;
/**
* Callback for a tool handler registered with Server.tool().
* Callback for a tool handler registered with {@linkcode McpServer.registerTool}.
*/
export type ToolCallback<Args extends AnySchema | undefined = undefined> = BaseToolCallback<CallToolResult, ServerContext, Args>;
@ -1029,8 +1029,8 @@ export type RegisteredTool = {
/**
* Creates an executor that invokes the handler with the appropriate arguments.
* When inputSchema is defined, the handler is called with (args, ctx).
* When inputSchema is undefined, the handler is called with just (ctx).
* When `inputSchema` is defined, the handler is called with `(args, ctx)`.
* When `inputSchema` is undefined, the handler is called with just `(ctx)`.
*/
function createToolExecutor(inputSchema: AnySchema | undefined, handler: AnyToolHandler<AnySchema | undefined>): ToolExecutor {
const isTaskHandler = 'createTask' in handler;

6
packages/server/src/server/middleware/hostHeaderValidation.ts
View file

@ -9,7 +9,7 @@ export type HostHeaderValidationResult =
};
/**
* Parse and validate a Host header against an allowlist of hostnames (port-agnostic).
* Parse and validate a `Host` header against an allowlist of hostnames (port-agnostic).
*
* - Input host header may include a port (e.g. `localhost:3000`) or IPv6 brackets (e.g. `[::1]:3000`).
* - Allowlist items should be hostnames only (no ports). For IPv6, include brackets (e.g. `[::1]`).
@ -35,14 +35,14 @@ export function validateHostHeader(hostHeader: string | null | undefined, allowe
}
/**
* Convenience allowlist for localhost DNS rebinding protection.
* Convenience allowlist for `localhost` DNS rebinding protection.
*/
export function localhostAllowedHostnames(): string[] {
return ['localhost', '127.0.0.1', '[::1]'];
}
/**
* Web-standard Request helper for DNS rebinding protection.
* Web-standard `Request` helper for DNS rebinding protection.
* @example
* ```typescript
* const result = validateHostHeader(req.headers.get('host'), ['localhost'])

12
packages/server/src/server/server.ts
View file

@ -74,7 +74,7 @@ export type ServerOptions = ProtocolOptions & {
* The validator is used to validate user input returned from elicitation
* requests against the requested schema.
*
* @default DefaultJsonSchemaValidator (AjvJsonSchemaValidator on Node.js, CfWorkerJsonSchemaValidator on Cloudflare Workers)
* @default {@linkcode DefaultJsonSchemaValidator} ({@linkcode index.AjvJsonSchemaValidator | AjvJsonSchemaValidator} on Node.js, {@linkcode index.CfWorkerJsonSchemaValidator | CfWorkerJsonSchemaValidator} on Cloudflare Workers)
*/
jsonSchemaValidator?: jsonSchemaValidator;
};
@ -84,7 +84,7 @@ export type ServerOptions = ProtocolOptions & {
*
* This server will automatically respond to the initialization flow as initiated from the client.
*
* @deprecated Use `McpServer` instead for the high-level API. Only use `Server` for advanced use cases.
* @deprecated Use {@linkcode server/mcp.McpServer | McpServer} instead for the high-level API. Only use `Server` for advanced use cases.
*/
export class Server extends Protocol<ServerContext> {
private _clientCapabilities?: ClientCapabilities;
@ -95,7 +95,7 @@ export class Server extends Protocol<ServerContext> {
private _experimental?: { tasks: ExperimentalServerTasks };
/**
* Callback for when initialization has fully completed (i.e., the client has sent an `initialized` notification).
* Callback for when initialization has fully completed (i.e., the client has sent an `notifications/initialized` notification).
*/
oninitialized?: () => void;
@ -192,7 +192,7 @@ export class Server extends Protocol<ServerContext> {
}
/**
* Override request handler registration to enforce server-side validation for tools/call.
* Override request handler registration to enforce server-side validation for `tools/call`.
*/
public override setRequestHandler<M extends RequestMethod>(
method: M,
@ -547,7 +547,7 @@ export class Server extends Protocol<ServerContext> {
/**
* Creates an elicitation request for the given parameters.
* For backwards compatibility, `mode` may be omitted for form requests and will default to `'form'`.
* For backwards compatibility, `mode` may be omitted for form requests and will default to `"form"`.
* @param params The parameters for the elicitation request.
* @param options Optional request options.
* @returns The result of the elicitation request.
@ -635,7 +635,7 @@ export class Server extends Protocol<ServerContext> {
/**
* Sends a logging message to the client, if connected.
* Note: You only need to send the parameters object, not the entire JSON-RPC message.
* @see LoggingMessageNotification
* @see {@linkcode LoggingMessageNotification}
* @param params
* @param sessionId Optional for stateless transports and backward compatibility.
*/

4
packages/server/src/server/stdio.ts
View file

@ -5,7 +5,7 @@ import { ReadBuffer, serializeMessage } from '@modelcontextprotocol/core';
import { process } from '@modelcontextprotocol/server/_shims';
/**
* Server transport for stdio: this communicates with an MCP client by reading from the current process' stdin and writing to stdout.
* Server transport for stdio: this communicates with an MCP client by reading from the current process' `stdin` and writing to `stdout`.
*
* This transport is only available in Node.js environments.
*/
@ -32,7 +32,7 @@ export class StdioServerTransport implements Transport {
};
/**
* Starts listening for messages on stdin.
* Starts listening for messages on `stdin`.
*/
async start(): Promise<void> {
if (this._started) {

82
packages/server/src/server/streamableHttp.ts
View file

@ -1,10 +1,10 @@
/**
* Web Standards Streamable HTTP Server Transport
*
* This is the core transport implementation using Web Standard APIs (Request, Response, ReadableStream).
* This is the core transport implementation using Web Standard APIs (`Request`, `Response`, `ReadableStream`).
* It can run on any runtime that supports Web Standards: Node.js 18+, Cloudflare Workers, Deno, Bun, etc.
*
* For Node.js Express/HTTP compatibility, use `NodeStreamableHTTPServerTransport` which wraps this transport.
* For Node.js Express/HTTP compatibility, use {@linkcode @modelcontextprotocol/node!NodeStreamableHTTPServerTransport | NodeStreamableHTTPServerTransport} which wraps this transport.
*/
import type { AuthInfo, JSONRPCMessage, MessageExtraInfo, RequestId, RequestInfo, Transport } from '@modelcontextprotocol/core';
@ -36,10 +36,10 @@ export interface EventStore {
/**
* Get the stream ID associated with a given event ID.
* @param eventId The event ID to look up
* @returns The stream ID, or undefined if not found
* @returns The stream ID, or `undefined` if not found
*
* Optional: If not provided, the SDK will use the streamId returned by
* replayEventsAfter for stream mapping.
* Optional: If not provided, the SDK will use the `streamId` returned by
* {@linkcode replayEventsAfter} for stream mapping.
*/
getStreamIdForEventId?(eventId: EventId): Promise<StreamId | undefined>;
@ -57,7 +57,7 @@ export interface EventStore {
* Internal stream mapping for managing SSE connections
*/
interface StreamMapping {
/** Stream controller for pushing SSE data - only used with ReadableStream approach */
/** Stream controller for pushing SSE data - only used with `ReadableStream` approach */
controller?: ReadableStreamDefaultController<Uint8Array>;
/** Text encoder for SSE formatting */
encoder?: InstanceType<typeof TextEncoder>;
@ -68,7 +68,7 @@ interface StreamMapping {
}
/**
* Configuration options for WebStandardStreamableHTTPServerTransport
* Configuration options for {@linkcode WebStandardStreamableHTTPServerTransport}
*/
export interface WebStandardStreamableHTTPServerTransportOptions {
/**
@ -90,20 +90,20 @@ export interface WebStandardStreamableHTTPServerTransportOptions {
/**
* A callback for session close events
* This is called when the server closes a session due to a DELETE request.
* This is called when the server closes a session due to a `DELETE` request.
* Useful in cases when you need to clean up resources associated with the session.
* Note that this is different from the transport closing, if you are handling
* HTTP requests from multiple nodes you might want to close each
* WebStandardStreamableHTTPServerTransport after a request is completed while still keeping the
* {@linkcode WebStandardStreamableHTTPServerTransport} after a request is completed while still keeping the
* session open/running.
* @param sessionId The session ID that was closed
*/
onsessionclosed?: (sessionId: string) => void | Promise<void>;
/**
* If true, the server will return JSON responses instead of starting an SSE stream.
* If `true`, the server will return JSON responses instead of starting an SSE stream.
* This can be useful for simple request/response scenarios without streaming.
* Default is false (SSE streams are preferred).
* Default is `false` (SSE streams are preferred).
*/
enableJsonResponse?: boolean;
@ -114,42 +114,42 @@ export interface WebStandardStreamableHTTPServerTransportOptions {
eventStore?: EventStore;
/**
* List of allowed host header values for DNS rebinding protection.
* List of allowed `Host` header values for DNS rebinding protection.
* If not specified, host validation is disabled.
* @deprecated Use external middleware for host validation instead.
*/
allowedHosts?: string[];
/**
* List of allowed origin header values for DNS rebinding protection.
* List of allowed `Origin` header values for DNS rebinding protection.
* If not specified, origin validation is disabled.
* @deprecated Use external middleware for origin validation instead.
*/
allowedOrigins?: string[];
/**
* Enable DNS rebinding protection (requires allowedHosts and/or allowedOrigins to be configured).
* Default is false for backwards compatibility.
* Enable DNS rebinding protection (requires `allowedHosts` and/or `allowedOrigins` to be configured).
* Default is `false` for backwards compatibility.
* @deprecated Use external middleware for DNS rebinding protection instead.
*/
enableDnsRebindingProtection?: boolean;
/**
* Retry interval in milliseconds to suggest to clients in SSE retry field.
* When set, the server will send a retry field in SSE priming events to control
* Retry interval in milliseconds to suggest to clients in SSE `retry` field.
* When set, the server will send a `retry` field in SSE priming events to control
* client reconnection timing for polling behavior.
*/
retryInterval?: number;
/**
* List of protocol versions that this transport will accept.
* Used to validate the mcp-protocol-version header in incoming requests.
* Used to validate the `mcp-protocol-version` header in incoming requests.
*
* Note: When using Server.connect(), the server automatically passes its
* supportedProtocolVersions to the transport, so you typically don't need
* Note: When using {@linkcode server/server.Server.connect | Server.connect()}, the server automatically passes its
* `supportedProtocolVersions` to the transport, so you typically don't need
* to set this option directly.
*
* @default SUPPORTED_PROTOCOL_VERSIONS
* @default {@linkcode SUPPORTED_PROTOCOL_VERSIONS}
*/
supportedProtocolVersions?: string[];
}
@ -159,7 +159,7 @@ export interface WebStandardStreamableHTTPServerTransportOptions {
*/
export interface HandleRequestOptions {
/**
* Pre-parsed request body. If provided, the transport will use this instead of parsing req.json().
* Pre-parsed request body. If provided, the transport will use this instead of parsing `req.json()`.
* Useful when using body-parser middleware that has already parsed the body.
*/
parsedBody?: unknown;
@ -172,7 +172,7 @@ export interface HandleRequestOptions {
/**
* Server transport for Web Standards Streamable HTTP: this implements the MCP Streamable HTTP transport specification
* using Web Standard APIs (Request, Response, ReadableStream).
* using Web Standard APIs (`Request`, `Response`, `ReadableStream`).
*
* This transport works on any runtime that supports Web Standards: Node.js 18+, Cloudflare Workers, Deno, Bun, etc.
*
@ -205,8 +205,8 @@ export interface HandleRequestOptions {
* In stateful mode:
* - Session ID is generated and included in response headers
* - Session ID is always included in initialization responses
* - Requests with invalid session IDs are rejected with 404 Not Found
* - Non-initialization requests without a session ID are rejected with 400 Bad Request
* - Requests with invalid session IDs are rejected with `404 Not Found`
* - Non-initialization requests without a session ID are rejected with `400 Bad Request`
* - State is maintained in-memory (connections, message history)
*
* In stateless mode:
@ -251,7 +251,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
}
/**
* Starts the transport. This is required by the Transport interface but is a no-op
* Starts the transport. This is required by the {@linkcode Transport} interface but is a no-op
* for the Streamable HTTP transport as connections are managed per-request.
*/
async start(): Promise<void> {
@ -263,7 +263,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
/**
* Sets the supported protocol versions for header validation.
* Called by the server during connect() to pass its supported versions.
* Called by the server during {@linkcode server/server.Server.connect | connect()} to pass its supported versions.
*/
setSupportedProtocolVersions(versions: string[]): void {
this._supportedProtocolVersions = versions;
@ -300,7 +300,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
/**
* Validates request headers for DNS rebinding protection.
* @returns Error response if validation fails, undefined if validation passes.
* @returns Error response if validation fails, `undefined` if validation passes.
*/
private validateRequestHeaders(req: Request): Response | undefined {
// Skip validation if protection is not enabled
@ -332,8 +332,8 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
}
/**
* Handles an incoming HTTP request, whether GET, POST, or DELETE
* Returns a Response object (Web Standard)
* Handles an incoming HTTP request, whether `GET`, `POST`, or `DELETE`
* Returns a `Response` object (Web Standard)
*/
async handleRequest(req: Request, options?: HandleRequestOptions): Promise<Response> {
// Validate request headers for DNS rebinding protection
@ -360,8 +360,8 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
/**
* Writes a priming event to establish resumption capability.
* Only sends if eventStore is configured (opt-in for resumability) and
* the client's protocol version supports empty SSE data (>= 2025-11-25).
* Only sends if `eventStore` is configured (opt-in for resumability) and
* the client's protocol version supports empty SSE data (>= `2025-11-25`).
*/
private async writePrimingEvent(
controller: ReadableStreamDefaultController<Uint8Array>,
@ -390,7 +390,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
}
/**
* Handles GET requests for SSE stream
* Handles `GET` requests for SSE stream
*/
private async handleGetRequest(req: Request): Promise<Response> {
// The client MUST include an Accept header, listing text/event-stream as a supported content type.
@ -575,7 +575,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
}
/**
* Handles unsupported requests (PUT, PATCH, etc.)
* Handles unsupported requests (`PUT`, `PATCH`, etc.)
*/
private handleUnsupportedRequest(): Response {
return Response.json(
@ -598,7 +598,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
}
/**
* Handles POST requests containing JSON-RPC messages
* Handles `POST` requests containing JSON-RPC messages
*/
private async handlePostRequest(req: Request, options?: HandleRequestOptions): Promise<Response> {
try {
@ -805,7 +805,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
}
/**
* Handles DELETE requests to terminate sessions
* Handles `DELETE` requests to terminate sessions
*/
private async handleDeleteRequest(req: Request): Promise<Response> {
const sessionError = this.validateSession(req);
@ -824,7 +824,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
/**
* Validates session ID for non-initialization requests.
* Returns Response error if invalid, undefined otherwise
* Returns `Response` error if invalid, `undefined` otherwise
*/
private validateSession(req: Request): Response | undefined {
if (this.sessionIdGenerator === undefined) {
@ -853,16 +853,16 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
}
/**
* Validates the MCP-Protocol-Version header on incoming requests.
* Validates the `MCP-Protocol-Version` header on incoming requests.
*
* For initialization: Version negotiation handles unknown versions gracefully
* (server responds with its supported version).
*
* For subsequent requests with MCP-Protocol-Version header:
* For subsequent requests with `MCP-Protocol-Version` header:
* - Accept if in supported list
* - 400 if unsupported
*
* For HTTP requests without the MCP-Protocol-Version header:
* For HTTP requests without the `MCP-Protocol-Version` header:
* - Accept and default to the version negotiated at initialization
*/
private validateProtocolVersion(req: Request): Response | undefined {
@ -906,7 +906,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
}
/**
* Close the standalone GET SSE stream, triggering client reconnection.
* Close the standalone `GET` SSE stream, triggering client reconnection.
* Use this to implement polling behavior for server-initiated notifications.
*/
closeStandaloneSSEStream(): void {