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.