MCP TypeScript Template

A TypeScript template for building remote Model Context Protocol (MCP) servers with modern tooling and best practices while leveraging the MCP TypeScript SDK.

Features

This template provides:

• TypeScript - Full TypeScript support with strict configuration

• Vite - Fast build system with ES modules output

• Express - Fast, unopinionated web framework for HTTP server

• ESLint + Prettier - Code quality and formatting

• Docker - Containerization support

• Example Tool - Simple echo tool to demonstrate MCP tool implementation

Getting Started

1. Clone or use this template

   git clone <your-repo-url> cd mcp-typescript-template

2. Install dependencies

   npm install

3. Build the project

   npm run build

4. Start the server

   npm start

The server will be available at http://localhost:3000 for MCP connections.

Development

Watch mode for development (with hot reloading)

Build the project

Linting

• Lint the project

• Fix all auto-fixable lint errors

Formatting

• Format files in the project

• Check formatting

Available Tools

The template includes one example tool:

echo

Echoes back the provided message - a simple example to demonstrate MCP tool implementation.

Parameters:

• message (string) - The message to echo back

Customizing Your MCP Server

1. Update package.json - Change name, description, and keywords

2. Modify src/index.ts - Replace the echo tool with your custom tools

3. Add your logic - Create additional TypeScript files for your business logic

4. Update README - Document your specific MCP server functionality

Docker

Build and run using Docker:

• Build the Docker image

• Run the container

Docker Compose

Project Structure

Architecture

This template follows a simple architecture:

• HTTP Transport - Uses Express with StreamableHTTPServerTransport for remote MCP connections

• Tool Registration - Tools are registered with JSON schemas for input validation

• Error Handling - Proper MCP-formatted error responses

• Session Management - Handles MCP session initialization and management

Example: Adding a New Tool

Why Express?

This template uses Express for the HTTP server, which provides:

• MCP SDK Compatibility - Full compatibility with the MCP TypeScript SDK's StreamableHTTPServerTransport

• Mature & Stable - Battle-tested HTTP server with extensive ecosystem

• TypeScript Support - Excellent TypeScript support with comprehensive type definitions

• Middleware Ecosystem - Rich ecosystem of middleware for common tasks

• Documentation - Comprehensive documentation and community support

• Reliability - Proven reliability for production applications

Repository Guidelines

Contributors should review AGENTS.md for project structure, coding standards, and pull request expectations before opening changes.