MCP TypeScript Template: Beginner-Friendly, Production-Ready

MCP TypeScript Template

A beginner-friendly foundation for building Model Context Protocol (MCP) servers (and in the future also clients) with TypeScript. This template provides a comprehensive starting point with production-ready utilities, well-structured code, and working examples for building an MCP server.

Copy this repo to kickstart your own MCP server and set your vibe code session up for success!

Using this template as your repo will get you:

• Utilities : A set of reusable utilities for logging, error handling, ID generation, rate limiting, and request context management.
• Type Safety : Strong typing with TypeScript to catch errors at compile time.
• Security : Built-in security features to protect against common vulnerabilities.
• Error Handling : A robust error handling system that categorizes and formats errors consistently.
• Documentation : Comprehensive documentation for tools and resources, including usage examples and implementation details.
• Example Implementations : Working examples of echo_message (tool) and echo://hello (resource) to help you get started quickly.

.clinerules : This repository includes a .clinerules file that serves as a developer cheat sheet for your LLM coding agent with quick reference for the codebase patterns, file locations, and code snippets. When copying this template for your own project, be sure to update the cheat sheet to reflect your modifications and additions.

Table of Contents

• Overview
  • What is Model Context Protocol?
  • Architecture & Components
• Features
  • Core Utilities
  • Type Safety
  • Error Handling
  • Security
  • Example Implementations
• Installation
• Configuration
• Project Structure
• Tool & Resource Documentation
  • Tools
  • Resources
• Development Guidelines
  • Adding a New Tool
  • Adding a New Resource
• Future Plans
• License

Overview

What is Model Context Protocol?

Model Context Protocol (MCP) is a framework that enables AI systems to interact with external tools and resources. It allows language models to:

• Execute tools that perform actions and return results
• Access structured resources that provide information
• Create contextual workflows through standardized interfaces

This template gives you a head start in building MCP servers that can be used by AI systems to extend their capabilities.

Architecture & Components

The template follows a modular architecture designed for clarity and extensibility:

flowchart TB
    subgraph API["API Layer"]
        direction LR
        MCP["MCP Protocol"]
        Val["Validation"]
        San["Sanitization"]

        MCP --> Val --> San
    end

    subgraph Core["Core Components"]
        direction LR
        Config["Configuration"]
        Logger["Logging System"]
        Error["Error Handling"]
        Server["MCP Server"]

        Config --> Server
        Logger --> Server
        Error --> Server
    end

    subgraph Implementation["Implementation Layer"]
        direction LR
        Tool["Tools"]
        Resource["Resources"]
        Util["Utilities"]

        Tool --> Server
        Resource --> Server
        Util --> Tool
        Util --> Resource
    end

    San --> Config
    San --> Server

    classDef layer fill:#2d3748,stroke:#4299e1,stroke-width:3px,rx:5,color:#fff
    classDef component fill:#1a202c,stroke:#a0aec0,stroke-width:2px,rx:3,color:#fff
    class API,Core,Implementation layer
    class MCP,Val,San,Config,Logger,Error,Server,Tool,Resource,Util component

Core Components:

• Configuration System : Environment-aware configuration with validation
• Logging System : Structured logging with sensitive data redaction
• Error Handling : Centralized error processing with consistent patterns
• MCP Server : Protocol implementation for tools and resources
• Validation Layer : Input validation using Zod schemas
• Utilities : Reusable utility functions for common operations

Features

Core Utilities

• Logging : Configurable logging with file rotation and sensitive data redaction
• Error Handling : Pattern-based error classification and standardized reporting
• ID Generation : Secure unique identifier creation with prefix support
• Rate Limiting : Request throttling to prevent API abuse
• Request Context : Request tracking and correlation
• Sanitization : Input validation and cleaning

Type Safety

• Global Types : Shared type definitions for consistent interfaces
• Error Types : Standardized error codes and structures
• MCP Protocol Types : Type definitions for the MCP protocol
• Tool Types : Interfaces for tool registration and configuration

Error Handling

• Pattern-Based Classification : Automatically categorize errors based on message patterns
• Consistent Formatting : Standardized error responses with additional context
• Error Mapping : Custom error transformation for domain-specific errors
• Safe Try/Catch Patterns : Centralized error processing helpers

Security

• Input Validation : Schema-based validation using Zod
• Input Sanitization : Protection against injection attacks
• Parameter Bounds : Enforced limits to prevent abuse
• Sensitive Data Redaction : Automatic redaction in logs

Example Implementations

• Echo Tool : Complete example of a tool implementation
• Echo Resource : Complete example of a resource implementation
• Registration Helpers : Utilities for consistent component registration

Installation

Prerequisites

• Node.js (v18+)
• npm or yarn

Setup

1. Clone this repository:

   git clone https://github.com/cyanheads/mcp-ts-template.git

cd mcp-ts-template

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. Start the server:

   npm run start

Configuration

Environment Variables (Optional)

Create a .env file based on .env.example:

# Server Configuration
NODE_ENV=development # development, production
LOG_LEVEL=info # debug, info, warn, error

# Rate Limiting
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX_REQUESTS=100

Configuration System

The configuration system provides a flexible way to manage settings:

• Environment Config : Load settings from environment variables
• MCP Servers Config : Configure MCP server connections (for future client implementations)
• Lazy Loading : Configurations are loaded only when needed

Project Structure

The codebase follows a modular structure:

src/
├── config/                 # Configuration management
│   ├── envConfig.ts        # Environment variable handling
│   ├── index.ts            # Unified configuration
│   └── mcpConfig.ts        # MCP server configuration
│
├── mcp-server/             # MCP server implementation
│   ├── resources/          # Resource implementations
│   │   └── echoResource/   # Example resource
│   ├── tools/              # Tool implementations
│   │   └── echoTool/       # Example tool
│   └── utils/              # Server utilities
│       └── registrationHelper.ts  # Registration helpers
│
├── types-global/           # Shared type definitions
│   ├── errors.ts           # Error types and codes
│   ├── mcp.ts              # MCP protocol types
│   └── tool.ts             # Tool registration types
│
├── utils/                  # Common utilities
│   ├── errorHandler.ts     # Error handling
│   ├── idGenerator.ts      # ID generation
│   ├── logger.ts           # Logging system
│   ├── rateLimiter.ts      # Rate limiting
│   ├── requestContext.ts   # Request context
│   ├── sanitization.ts     # Input sanitization
│   └── security.ts         # Security utilities
│
└── [index.ts](src/index.ts)                # Application entry point
.clinerules                 # Developer cheat sheet for LLM coding agent

Tool & Resource Documentation

Tools

See the Echo Tool documentation for detailed usage examples and implementation details.

Resources

See the Echo Resource documentation for detailed usage examples and implementation details.

Development Guidelines

Adding a New Tool

1. Create a new directory under src/mcp-server/tools/
2. Define types and schemas in a types.ts file
3. Implement the handler in a dedicated file
4. Create an index.ts file that registers the tool
5. Add your tool to the server registration in src/mcp-server/server.ts

Example tool registration:

// In your tool's index.ts
export const registerMyTool = async (server: McpServer): Promise<void> => {
  return registerTool(server, { name: "my_tool" }, async (server, logger) => {
    server.tool(
      "my_tool",
      {
        /* input schema */
      },
      async (params) => {
        // Your implementation
      }
    );
  });
};

// In src/mcp-server/server.ts
await registerMyTool(mcpServer);

Adding a New Resource

1. Create a new directory under src/mcp-server/resources/
2. Define types and schemas in a types.ts file
3. Implement the handler in a dedicated file
4. Create an index.ts file that registers the resource
5. Add your resource to the server registration in src/mcp-server/server.ts

Future Plans

This template serves as a foundation for:

• MCP Client Implementation : Support for creating MCP clients that connect to various AI models

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Copyright 2025 Casey Hand @cyanheads

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.