mcp-ts-template is more than just a template; it's a feature-rich, production-ready framework for building robust, observable, and secure MCP servers, providing a solid architectural foundation so you can focus entirely on creating powerful tools and resources for AI agents.

This project is designed to be AI-agent-friendly, providing an LLM-optimized AGENTS.md and detailed rules in .clinerules/clinerules.md to ensure your coding agents adhere to best practices from the start.

✨ Core Features

This template is packed with production-grade features designed for high-performance, secure, and maintainable MCP servers.

🚀 Getting Started

Prerequisites

• Bun (v1.2.0 or higher)

Installation

1. Clone the Repository

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

2. Install Dependencies

   bun install

3. Build the Project

   bun build # or bun rebuild

🏃 Running the Server

You can run the server in several modes for development and production.

Standard Transports

• STDIO Transport: Ideal for local development or when the server is a child process.

  bun run start:stdio

• HTTP Transport: For network-accessible deployments.

  bun run start:http
  # Server now running at http://127.0.0.1:3010

Cloudflare Workers Deployment

This template is optimized for deployment to Cloudflare Workers, a global, serverless execution environment.

1. Build the Worker:

   bun run build:worker

2. Run Locally with Wrangler:

   bun run deploy:dev

3. Deploy to Cloudflare:

   bun run deploy:prod

🏗️ Architectural Principles

This template enforces a set of non-negotiable architectural principles to ensure every server built from it is robust, maintainable, and debuggable.

1. The "Logic Throws, Handler Catches" Pattern

This is the cornerstone of control flow and error handling. It creates a complete separation between pure business logic and the surrounding infrastructure concerns.

• Core Logic (logic): Defined within your ToolDefinition, this is a pure, stateless async function. It contains only the business logic for the tool. If an operational or validation error occurs, it must terminate by throwing a structured McpError. It never contains a try...catch block.
• Handler (Auto-Generated): The toolHandlerFactory automatically wraps your logic function in a robust try...catch block at runtime. This factory-generated handler is responsible for creating the RequestContext, measuring performance with OpenTelemetry, invoking your logic, and catching any thrown errors. It is the only place where errors are caught and formatted into a final CallToolResult.

This pattern allows you to write clean, focused business logic while the framework guarantees it's executed within a fully instrumented, safe, and observable context.

2. Full-Stack Observability by Default

Every operation is traceable from end to end without any manual setup.

• OpenTelemetry SDK: Initialized in src/utils/telemetry/instrumentation.ts before any other module, it automatically instruments supported I/O operations (HTTP, DNS, etc.).
• Trace-Aware Context: The requestContextService automatically injects the active traceId and spanId into every RequestContext.
• Error-Trace Correlation: The central ErrorHandler records every handled exception on the active OTel span and sets its status to ERROR, ensuring every failure is visible and searchable in your tracing backend.
• Performance Spans: The measureToolExecution utility wraps every tool call in a dedicated span, capturing duration, status, and input/output sizes as attributes.

3. Declarative, Self-Contained Components

Tools and resources are defined declaratively in single, self-contained files. This makes the system highly modular and easy to reason about.

4. Dependency Injection for Maximum Decoupling

The entire architecture is built around a Dependency Injection (DI) container (tsyringe).

• Centralized Container: All services, providers, and managers are registered in a central DI container, configured in src/container/.
• Inversion of Control: Components never create their own dependencies. Instead, they receive them via constructor injection, making them highly testable and decoupled.
• Auto-Registration: Tool and resource definitions are automatically discovered and registered with the container from barrel exports, eliminating manual wiring.

📁 Project Structure

.
├── .clinerules/         # --> Rules and mandates for LLM-based development agents.
├── .github/             # --> GitHub Actions workflows (e.g., CI/CD).
├── scripts/             # --> Helper scripts for development (cleaning, docs, etc.).
├── src/
│   ├── config/          # --> Application configuration (Zod schemas, loader).
│   ├── container/       # --> Dependency Injection container setup and registrations.
│   ├── mcp-server/
│   │   ├── resources/   # --> Declarative resource definitions (*.resource.ts).
│   │   ├── tools/       # --> Declarative tool definitions (*.tool.ts).
│   │   ├── transports/  # --> HTTP and STDIO transport layers, including auth.
│   │   └── server.ts    # --> Core McpServer setup (resolves components from DI).
│   ├── services/        # --> Clients for external services (e.g., LLM providers).
│   ├── storage/         # --> Abstracted storage layer and providers.
│   ├── types-global/    # --> Global TypeScript types (e.g., McpError).
│   └── utils/           # --> Core utilities (logger, error handler, security).
├── tests/               # --> Vitest integration and unit tests.
├── .env.example         # --> Example environment variables.
├── AGENTS.md            # --> Detailed architectural guide for LLM agents.
└── Dockerfile           # --> For building and running the server in a container.

🔧 Extending the Template

Adding a New Tool

1. Create the Definition: Create a new file at src/mcp-server/tools/definitions/my-new-tool.tool.ts. Use an existing tool as a template.
2. Define the Tool: Export a single const of type ToolDefinition containing the name, Zod schemas, and pure business logic.
3. Register via Barrel Export: Open src/mcp-server/tools/definitions/index.ts and add your new tool definition to the allToolDefinitions array.

// src/mcp-server/tools/definitions/index.ts
import { myNewTool } from './my-new-tool.tool.js';
// ... other imports
export const allToolDefinitions = [
  // ... other tools
  myNewTool,
];

That's it. The DI container automatically discovers and registers all tools from this array at startup.

Adding a New Storage Provider

1. Create Provider: Create a new class under src/storage/providers/ that implements the IStorageProvider interface.
2. Add to Factory: Open src/storage/core/storageFactory.ts. Add a case to the switch statement to instantiate your new provider based on the STORAGE_PROVIDER_TYPE from the config.
3. Update Config Schema: Add your new provider's name to the StorageProviderType enum in src/config/index.ts.
4. Set Environment Variable: In your .env file, set STORAGE_PROVIDER_TYPE to your new provider's name.

⚙️ Configuration

The server is configured via environment variables, loaded and validated by src/config/index.ts. Copy .env.example to .env and fill in the required values.

Refer to .env.example for a complete list of configurable options.

📜 Available Scripts

Key scripts available in package.json:

You can find these scripts in the scripts/ directory.

📦 Publishing to the MCP Registry

This template is configured for easy publishing to the public MCP Registry, making your server discoverable by any MCP-compatible client. The recommended method is to use the all-in-one publishing script.

For a complete walkthrough, including alternative methods and CI/CD automation, please refer to the detailed guide:

➡️ How to Publish Your MCP Server

🤝 Contributing

This is an open-source project. Contributions, issues, and feature requests are welcome. Please feel free to fork the repository, make changes, and open a pull request.

📄 License

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