mcp-sdk-typescript

The MCP SDK for TypeScript provides a type-safe framework to build streaming MCP servers with real-time communication over HTTP. It exposes an MCPApp for registering tools, a StreamableHttpTransport that handles runtime-optimized transport (Bun or Node.js) and Server-Sent Events, and a rich set of response types (TextResponse, ProgressResponse, LogResponse, ErrorResponse, RawResponse, etc.). You can define tools with schemas using Zod for validation and implement async generator handlers to yield streaming responses as the client consumes them. This setup enables production-grade session management, error handling, and memory management while offering an architecture that scales for real-time, long-running interactions. Use the SDK to create an MCP server project scaffold, register tools such as an echo service or a long-running processor, and rely on the transport layer to manage SSE streams and session correlation across Bun or Node.js runtimes.

Prerequisites:

• Node.js (and optionally Bun for best performance)
• Basic TypeScript project setup (tsconfig, npm/yarn/pnpm)

Install the MCP SDK library into your project:

# Using Bun (recommended for performance)
bun add @the-ihor/mcp-sdk-typescript

# Using npm/Node.js
npm install @the-ihor/mcp-sdk-typescript

# Using yarn
yarn add @the-ihor/mcp-sdk-typescript

If you plan to scaffold a full MCP server project using the provided CLI, install the CLI tool as well (example usage shown in Quick Start):

# Create a new MCP server project (via Bun or NPX)
bunx @the-ihor/adi-create-mcp-server
# or
npx @the-ihor/adi-create-mcp-server

Configure TypeScript and build steps according to your chosen runtime (Bun or Node.js). For example, ensure your tsconfig.json aligns with module resolution and target ES version, and include a build script if you are compiling TS to JS for Node environments.

Tips and common considerations:

• Runtime detection automatically selects Bun.serve when running under Bun; otherwise Node.js HTTP server is used. Ensure your environment supports SSE and persistent streaming.
• Use the provided response types (TextResponse, ProgressResponse, LogResponse, etc.) to convey structured data and progress updates to clients.
• Implement proper session management by leveraging the transport layer, which maps requests to responses via session IDs.
• When debugging, enable verbose logging and inspect transport-level errors, as they often indicate transport or network issues rather than application logic failures.
• If you plan to publish tooling (CLI scaffolds), keep tool schemas in sync with Zod validators to ensure end-user requests are validated server-side.
• For production, monitor memory management around long-lived streams and implement cancellation or cleanup for expired sessions.