typescript-sdk

Implements the full Model Context Protocol specification as a JSON-RPC 2.0-based bidirectional messaging system that enables both request-response and notification patterns between clients and servers. Uses a transport-agnostic message routing layer that decouples protocol logic from underlying communication mechanisms (stdio, HTTP, SSE, in-memory), allowing the same protocol implementation to work across multiple transports without modification.

Provides a declarative API for registering tools on MCP servers using JSON Schema for parameter definition, with automatic validation and type-safe execution. The McpServer class exposes a tool() method that accepts tool name, description, input schema (via Zod or raw JSON Schema), and an async handler function. Validates all incoming tool calls against the registered schema before execution, returning structured errors for schema violations.

Implements an elicitation system that enables interactive discovery and negotiation of capabilities between client and server. Allows servers to request information from clients (e.g., user preferences, available resources) and clients to query server capabilities with filtering. Supports bidirectional capability negotiation rather than static discovery.

Enables MCP servers to request LLM sampling (text generation) from connected clients, allowing servers to invoke LLM capabilities without embedding an LLM themselves. Servers can request completions with specific parameters (temperature, max tokens, etc.) and receive generated text. Implements a request-response pattern where servers initiate sampling requests and clients handle LLM invocation.

Implements a capabilities system that allows clients and servers to declare supported features and negotiate compatibility. Each side declares capabilities (e.g., supported sampling parameters, resource types, prompt features) during initialization. Enables graceful degradation when capabilities don't match and version-aware feature detection.

Implements a notification system that allows both clients and servers to send structured notifications (non-request messages) for logging, events, and status updates. Notifications are JSON-RPC notifications (no response expected) that can be logged, filtered, or broadcast to multiple subscribers. Enables structured event logging and real-time status updates.

Integrates Zod for runtime type validation with automatic JSON Schema generation for protocol compatibility. Allows developers to define schemas in TypeScript using Zod, which are automatically converted to JSON Schema for MCP protocol messages. Validates all incoming messages against schemas before processing, providing type-safe runtime validation.

Implements a resource and prompt management system where servers can expose named resources and prompts using URI-based addressing (e.g., 'file://path/to/resource'). Resources can be text, binary, or streaming content; prompts are templates with arguments that return structured messages. Clients can list available resources/prompts and request specific ones by URI, with the server handling resolution and content delivery.

Provides a Transport interface that abstracts the underlying communication mechanism, with built-in implementations for stdio, HTTP (with streaming support), Server-Sent Events (SSE), and in-memory transports. Each transport implements the same interface (send/receive message handling) but handles protocol-specific concerns (connection lifecycle, message framing, error handling). Allows developers to switch transports by changing configuration without modifying protocol or business logic.

Provides a Streamable HTTP Server Transport that integrates with Express, Hono, and native Node.js HTTP servers, supporting both request-response and streaming message patterns. Handles HTTP-specific concerns like connection lifecycle, request routing, and streaming response delivery. Includes middleware adapters that wrap the MCP protocol handler as Express/Hono middleware, allowing MCP servers to coexist with other HTTP endpoints in the same application.

Implements the MCP client protocol that connects to MCP servers and provides a high-level API for discovering and invoking tools, accessing resources, and requesting prompts. The Client class handles connection lifecycle, message routing, and provides methods like callTool(), listTools(), getResource(), and listPrompts(). Automatically discovers server capabilities during initialization and maintains connection state.

Implements a Server-Sent Events client transport that receives server-initiated messages via SSE while sending client requests via HTTP POST. Handles SSE connection lifecycle, automatic reconnection on disconnect, and message parsing from SSE format. Suitable for scenarios where server-to-client streaming is needed but bidirectional WebSocket is not available or desired.

Provides OAuth 2.0 client and server implementations for MCP, supporting standard OAuth flows (authorization code, client credentials) with built-in providers for common services. Handles token exchange, refresh token management, and secure credential storage. Integrates with MCP server initialization to require OAuth authentication before tool/resource access.

Implements session management that preserves connection state across reconnections, allowing clients to resume interrupted connections without losing context. Tracks session ID, message history, and server state, enabling recovery from network failures. Supports both stateless (per-request) and stateful (session-based) operation modes.

Provides an experimental task system that allows servers to expose long-running operations as tasks with progress tracking and cancellation support. Tasks return a task ID and progress updates, allowing clients to poll for status or receive streaming progress notifications. Enables modeling of async operations like file processing or data analysis.