composiohq-modelcontextprotocol-typescript-sdk

Provides native TypeScript/JavaScript bindings for implementing Model Context Protocol servers that expose tools, resources, and prompts to LLM clients. Uses a standardized JSON-RPC 2.0 message protocol over stdio, WebSocket, or HTTP transports to establish bidirectional communication between MCP servers and Claude/other LLM clients. Implements the full MCP specification including request/response handling, error propagation, and capability negotiation during initialization.

Enables developers to declaratively define tools with JSON Schema validation, input/output types, and descriptions that are automatically exposed to MCP clients. Uses a schema-based approach where tools are registered with name, description, input schema (JSON Schema format), and handler functions. The SDK validates incoming tool calls against the schema before invoking handlers, ensuring type safety and preventing malformed requests from reaching business logic.

Manages the full lifecycle of MCP connections including initialization, active communication, and graceful shutdown. Handles connection state tracking, automatic cleanup of resources, and coordinated shutdown of all active connections. Supports connection pooling for high-concurrency scenarios and connection reuse for efficiency. Includes health checks and automatic reconnection for transient failures.

Allows MCP servers to expose read-only resources (documents, files, knowledge bases, API responses) that Claude can retrieve and reference during reasoning. Resources are identified by URIs and served with MIME types and content. The SDK handles resource listing, content retrieval, and optional text-based indexing for semantic search. Supports streaming large resources and caching strategies to reduce redundant fetches.

Enables servers to define reusable prompt templates with variable placeholders that Claude can invoke with specific arguments. Templates are registered with descriptions and argument schemas, allowing Claude to understand when and how to use them. The SDK handles argument substitution, validation against template schemas, and returns completed prompts. Supports template composition where prompts can reference other templates.

Provides a pluggable transport layer supporting stdio, WebSocket, and HTTP transports for MCP communication. Handles protocol negotiation during initialization, including capability exchange, version agreement, and transport-specific configuration. The SDK abstracts transport details, allowing the same server code to run over different transports without modification. Includes built-in error handling, message framing, and connection lifecycle management.

Implements comprehensive error handling for MCP protocol violations, tool execution failures, and resource access errors. Validates incoming requests against MCP schema before processing, returning structured error responses with error codes and messages. Includes logging and debugging utilities for troubleshooting server issues. Handles edge cases like malformed JSON, missing required fields, and timeout scenarios.

Handles the MCP initialization handshake where client and server exchange capabilities, versions, and configuration. The SDK manages the full initialization sequence including client info exchange, server capability declaration, and feature negotiation. Supports optional authentication/authorization during initialization. Ensures both sides agree on protocol version and supported features before processing requests.

Provides async-first execution model for tool handlers and resource retrievers, with automatic context preservation across async boundaries. Handlers can be async functions that perform I/O operations (database queries, API calls, file reads) without blocking the event loop. The SDK manages promise resolution, error propagation, and timeout handling. Supports both callback-based and promise-based handlers for backward compatibility.

Leverages TypeScript generics to provide compile-time type safety for tool definitions and invocations. Tool handlers are typed with input and output generics, enabling IDE autocomplete and type checking. The SDK validates tool calls at runtime against declared types, preventing type mismatches. Supports discriminated unions for polymorphic tool results and conditional types for complex tool signatures.

Provides middleware hooks for intercepting and transforming requests before tool execution and responses after execution. Middleware can be chained to implement cross-cutting concerns like logging, authentication, rate limiting, and response formatting. The SDK supports both sync and async middleware with early termination capabilities. Middleware runs in order and can modify request/response objects or reject requests.