Mcp Sdk Typescript

MCP SDK for TypeScript

Production-ready Model Context Protocol (MCP) SDK for TypeScript with automatic runtime optimization (Bun/Node.js), advanced streamable HTTP transport, comprehensive error handling, and enterprise-grade session management.

✨ Features

• 🚀 Runtime Optimized: Automatically detects and optimizes for Bun or Node.js
• ⚡ High Performance: Uses Bun.serve when available, graceful Node.js fallback
• 🔄 Real-Time Communication: Streamable HTTP transport with Server-Sent Events (SSE)
• 🛡️ Type Safety: Full TypeScript support with Zod schema validation
• 📡 Session Management: Advanced request-response correlation and session tracking
• 🔧 Generator-Based Tools: Async generator pattern for streaming responses
• 🛠️ Production Ready: Comprehensive error handling and memory management
• 📚 Well Documented: Enterprise-grade JSDoc documentation
• 🎯 MCP Compliant: Full support for MCP 2025-03-26 specification
• 🔌 Universal Compatibility: Works seamlessly in both Bun and Node.js environments

🚀 Quick Start

Create a New MCP Server (Recommended)

The fastest way to get started is with our CLI tool:

# Create a new MCP server project
bunx @the-ihor/adi-create-mcp-server
# or
npx @the-ihor/adi-create-mcp-server

This interactive CLI will:

• ✨ Set up a complete MCP server project
• 🎯 Include example tools (echo, random number generator)
• 📦 Support multiple package managers (Bun, npm, yarn, pnpm)
• 🔧 Generate proper TypeScript configuration
• 📚 Include comprehensive documentation

Manual Installation

# 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

📖 Manual Implementation

import { MCPApp, TextResponse, ProgressResponse, LogResponse, z } from "@the-ihor/mcp-sdk-typescript";

const app = new MCPApp({
  name: "my-mcp-server",
  version: "1.0.0",
  transport: {
    host: "localhost",
    port: 3000,
    path: "/mcp"
  }
});

// Create tools with streaming responses
app
  .createTool({
    name: "process-data",
    description: "Process data with real-time progress updates",
    schema: z.object({
      data: z.array(z.string()).describe("Data items to process"),
      delay: z.number().optional().default(100).describe("Processing delay in ms")
    }),
    handler: async function* (args) {
      yield new LogResponse("Starting data processing", "info");
      
      for (let i = 0; i  setTimeout(resolve, args.delay));
        
        yield new TextResponse(`Processed: ${args.data[i]}`);
      }
      
      yield new LogResponse("Processing completed", "info");
    }
  })
  .createTool({
    name: "echo",
    description: "Echo back input with optional transformations",
    schema: z.object({
      text: z.string().describe("Text to echo"),
      uppercase: z.boolean().optional().describe("Convert to uppercase"),
      repeat: z.number().min(1).max(10).optional().default(1).describe("Number of repetitions")
    }),
    handler: async function* (args) {
      let result = args.uppercase ? args.text.toUpperCase() : args.text;
      
      for (let i = 0; i  {
  console.error("Transport error:", error.message);
  // Error context: "Server startup failed: ..." 
  // Error context: "Failed to parse JSON-RPC message: ..."
});

// Handle application errors
app.createTool({
  name: "risky-operation",
  schema: z.object({ value: z.number() }),
  handler: async function* (args) {
    try {
      if (args.value < 0) {
        yield new ErrorResponse("Negative values not allowed", "INVALID_INPUT");
        return;
      }
      yield new TextResponse(`Result: ${Math.sqrt(args.value)}`);
    } catch (error) {
      yield new ErrorResponse(`Unexpected error: ${error.message}`, "INTERNAL_ERROR");
    }
  }
});

Session Management

The transport automatically handles session correlation:

// Client establishes SSE connection: GET /mcp
// Server returns X-Session-ID header
// Client sends requests with session ID: POST /mcp + X-Session-ID header
// Server routes responses back to correct client via SSE stream

🛠️ Development

Using Bun (Recommended)

# Install dependencies
bun install

# Build the library
bun run build

# Type checking
bun run typecheck

# Linting
bun run lint
bun run lint:fix

# Run tests
bun test

Using Node.js

# Install dependencies
npm install

# Build the library (requires Bun for build process)
npm run build

# Type checking
npm run typecheck

# Linting
npm run lint

# Run tests
npm test

Runtime Detection

The SDK automatically detects your runtime:

// Will use Bun.serve if running in Bun
// Will use Node.js HTTP server if running in Node.js
const app = new MCPApp({ name: 'my-app', version: '1.0.0' });
await app.start(); // Optimized for your runtime!

📁 Project Structure

mcp-sdk-typescript/
├── src/
│   ├── app.ts          # Main MCPApp class
│   ├── transport.ts    # HTTP transport with runtime detection
│   ├── responses.ts    # Response type definitions
│   ├── schemas.ts      # Schema utilities and validation
│   └── index.ts        # Public API exports
├── dist/               # Build output
├── docs/               # Additional documentation
└── tests/              # Test suites

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make changes and add tests
4. Ensure linting passes: bun run lint
5. Commit changes: git commit -m "✨ feat: Add amazing feature"
6. Push to branch: git push origin feature/amazing-feature
7. Open a Pull Request

📄 License

MIT License - see [LICENSE](LICENSE) file for details.

🔗 Links

• GitHub: mcp-sdk-typescript
• CLI Tool: adi-create-mcp-server - Create MCP servers instantly
• NPM Package: @the-ihor/adi-create-mcp-server
• Issues: Report bugs
• MCP Specification: Model Context Protocol
• Bun Runtime: Bun.sh
• Node.js Runtime: Node.js

---

Built with ❤️ by The Ihor using Bun, TypeScript, and Claude

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: the-ihor
• Source: the-ihor/mcp-sdk-typescript
• License: MIT
• Homepage: https://www.npmjs.com/package/@the-ihor/mcp-sdk-typescript

Install and usage instructions live in the source repository linked above.