@redocly/mcp-typescript-sdk

Provides native TypeScript/JavaScript bindings for implementing MCP servers that expose tools, resources, and prompts to LLM clients. Uses a request-response message protocol over stdio, WebSocket, or SSE transports, with automatic serialization/deserialization of MCP protocol messages and type-safe handler registration via decorators or callback functions.

Automatically generates JSON Schema definitions for tool parameters from TypeScript function signatures or explicit schema objects, enabling LLM clients to understand tool capabilities, required/optional parameters, and type constraints. Supports nested object schemas, enums, arrays, and custom validation rules that are serialized into the MCP tool definition format.

Provides built-in logging infrastructure that captures MCP protocol messages, handler execution, and errors in structured format. Logs can be directed to console, files, or custom handlers, with configurable verbosity levels. Includes request/response tracing to help developers debug complex interactions between servers and clients.

Manages the full lifecycle of MCP connections from initialization through graceful shutdown, including resource cleanup, connection state tracking, and error recovery. Provides hooks for custom initialization and cleanup logic, and handles edge cases like client disconnection, timeout, and protocol errors. Ensures resources are properly released even when errors occur.

Abstracts the underlying transport mechanism for MCP protocol messages, supporting stdio (for local CLI integration), WebSocket (for bidirectional real-time communication), and Server-Sent Events (for unidirectional streaming). Each transport is implemented as a pluggable adapter that handles message framing, connection lifecycle, and error recovery.

Enables servers to expose named resources (documents, files, knowledge bases) that LLM clients can request by URI. Resources are registered with metadata (name, description, MIME type) and content is served on-demand via a content handler function, supporting text, binary, and streaming content. Clients discover available resources through the MCP protocol and can request specific resource content or list resources matching patterns.

Allows servers to register reusable prompt templates with variable placeholders that LLM clients can request and instantiate. Templates are stored server-side with metadata (name, description, arguments) and clients can request template completion by providing argument values. The SDK handles variable substitution and returns the completed prompt text, enabling centralized prompt management and versioning.

Implements JSON-RPC 2.0 message routing that maps incoming requests to registered handler functions and automatically serializes responses. Includes built-in error handling with standardized error codes and messages, request ID tracking for correlation, and support for both synchronous and asynchronous handlers. Errors are caught and formatted according to JSON-RPC 2.0 spec with optional stack traces in development mode.

Enables MCP servers to send requests to connected clients (e.g., asking Claude to generate text or analyze content) and wait for responses. Implements bidirectional communication where servers can invoke client capabilities like text generation, image analysis, or tool execution, with request ID tracking and timeout handling. This allows servers to delegate complex reasoning tasks to the LLM client.

Provides decorator-based syntax for registering tools, resources, and prompts on server classes, enabling compile-time type checking and IDE autocompletion. Decorators extract metadata from function signatures and JSDoc comments, automatically generating tool definitions and parameter schemas. This approach reduces boilerplate compared to manual registration while maintaining full type safety.

Allows tools and resources to return streaming responses that are sent to clients incrementally rather than waiting for the complete result. Implements streaming via generator functions or async iterables that yield content chunks, which are automatically formatted according to the MCP protocol. This enables real-time feedback for long-running operations like file processing or API calls.

Handles the MCP protocol handshake where servers and clients exchange capability information, protocol version, and implementation details. Servers declare supported features (tools, resources, prompts, sampling) and clients declare their capabilities. This negotiation ensures compatibility and allows servers to adapt behavior based on client capabilities.