What is Mcp Typescript Boilerplate

mcp-typescript-boilerplate is a comprehensive boilerplate for creating Model Context Protocol (MCP) servers, supporting multiple transport methods including stdio, Server-Sent Events (SSE), and HTTP.

Use cases

Use cases include developing real-time applications, creating APIs for web services, and building scalable server architectures that require modular and maintainable code.

How to use

To use mcp-typescript-boilerplate, clone the repository, install dependencies, build the project, and run it in your desired mode (stdio, HTTP, or development with hot reload). Configure your MCP client to connect to the server as needed.

Key features

Key features include multiple transport support, full type safety with TypeScript, modular architecture, structured logging, a reusable generic API client, a streamlined tool factory, and development-ready features like hot reload and linting.

Where to use

mcp-typescript-boilerplate can be used in various domains where a robust server architecture is needed, particularly in applications requiring real-time data handling and API interactions.

MCP TypeScript Boilerplate

A comprehensive TypeScript boilerplate for creating Model Context Protocol (MCP) servers with support for stdio, SSE, and HTTP transports.

🚀 Features

• Multiple Transport Support: stdio, Server-Sent Events (SSE), and HTTP
• TypeScript: Full type safety and modern development experience
• Modular Architecture: Clean separation of tools, utilities, and server logic
• Structured Logging: Built-in logger with configurable levels
• Generic API Client: Reusable HTTP client with interceptors and error handling
• Tool Factory: Streamlined tool creation with validation and error handling
• Development Ready: Hot reload, linting, formatting, and type checking

🛠️ Getting Started

Prerequisites

• Node.js >= v18.0.0
• MCP Client (Cursor, VS Code, Claude Desktop, etc.)

Local Development

1. Clone and install:

   git clone https://github.com/andradehenrique/mcp-typescript-boilerplate.git
   cd mcp-typescript-boilerplate
   npm install
   

2. Build the project:

   npm run build
   

3. Run in different modes:

   # Stdio mode (default)
   npm run start:stdio
   
   # HTTP server mode
   npm run start:http
   
   # Development with hot reload
   npm run dev
   

MCP Client Configuration

For Local Development

Configure your MCP client to use the built server directly:

{
  "mcpServers": {
    "mcp-typescript-boilerplate": {
      "command": "node",
      "args": [
        "/path/to/mcp-typescript-boilerplate/build/index.js"
      ],
      "env": {
        "API_BASE_URL": "https://your-api-server.com/api",
        "API_TOKEN": "your-api-token"
      }
    }
  }
}

Using tsx for Development

{
  "mcpServers": {
    "mcp-typescript-boilerplate": {
      "command": "npx",
      "args": [
        "tsx",
        "/path/to/mcp-typescript-boilerplate/src/index.ts"
      ],
      "env": {
        "API_BASE_URL": "https://your-api-server.com/api",
        "API_TOKEN": "your-api-token"
      }
    }
  }
}

Docker Support

1. Build and run:

   docker build -t mcp-typescript-boilerplate .
   docker-compose up
   

2. HTTP mode:

   docker run -p 3000:3000 -e MCP_TRANSPORT=http mcp-typescript-boilerplate
   

Environment Variables

• API_BASE_URL: Your API server base URL (optional)
• API_TOKEN: Your API authentication token (optional)
• API_TIMEOUT: Request timeout in milliseconds (default: 30000)
• MCP_TRANSPORT: Transport mode - stdio, http, or sse (default: stdio)
• HTTP_PORT: HTTP server port (default: 3000)

📚 Available Tools

This boilerplate includes 3 example tools:

• hello-world - Simple greeting tool
• calculate-sum - Number calculation example
• make-api-call - External API integration example

For detailed tool information, see TOOLS.md.

🏗️ Architecture

src/
├── index.ts              # Entry point with transport selection
├── server.ts             # MCP server setup and tool registration
├── http-server.ts        # HTTP/SSE server implementation
├── mcp/
│   └── tools/
│       ├── index.ts      # Tool exports
│       ├── toolFactory.ts # Tool creation utilities
│       └── example/      # Example tools
├── types/               # TypeScript type definitions
└── utils/               # Shared utilities
    ├── apiClient.ts     # HTTP client
    ├── clientConfig.ts  # Configuration
    ├── logger.ts        # Logging utilities
    └── responseFormatter.ts # Response formatting

🔧 Creating Tools

Use the provided toolFactory for easy tool creation:

import { z } from "zod";
import { createTool } from "../toolFactory.js";
import { ResponseFormatter } from "../../utils/responseFormatter.js";

export const myTool = createTool({
  name: "my-tool",
  description: "My custom tool",
  schema: z.object({
    input: z.string().describe("Input parameter"),
  }),
  handler: async (input) => {
    // Your logic here
    return ResponseFormatter.success("Success", { result: input });
  },
});

Add to src/mcp/tools/index.ts:

import { myTool } from "./myTool.js";

export const allTools = [
  myTool,
  // ... other tools
];

📝 Available Scripts

• npm run build - Build the project
• npm run dev - Development with hot reload
• npm run start:stdio - Start in stdio mode
• npm run start:http - Start HTTP server
• npm run lint - Run ESLint
• npm run format - Format code with Prettier
• npm run type-check - Type checking
• npm run clean - Clean build directory

🔧 Testing

Test with MCP Inspector:

npx @modelcontextprotocol/inspector node build/index.js

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

See CONTRIBUTING.md for details.

🔗 Resources

• Model Context Protocol Documentation
• MCP TypeScript SDK
• TypeScript Documentation

📄 License

This project is licensed under the MIT License.