This template provides a comprehensive foundation for building rich Model Context Protocol servers, adhering to the MCP 2025-06-18 specification and modern best practices. It includes a fully-featured server, production-ready utilities, and clear documentation to get you up and running quickly.

🤔 Why Use This Template?

Building a robust server for AI agents is more than just writing code. It requires a solid architecture, consistent error handling, and secure, type-safe practices from the ground up. This template solves these challenges by providing:

• Accelerated Development: Skip the boilerplate and focus on your tool's core logic.
• Production-Ready Foundation: Built-in logging, error handling, security, and testing.
• Best Practices by Default: Enforces a clean, modular architecture that's easy to maintain and extend.
• AI-Ready: Designed with LLM agents in mind, including detailed schemas and rich LLM developer-friendly resources (e.g. .clinerules).

Note on src/mcp-client & src/agent: The MCP client & Agent components have been enhanced and moved to the (Coming Soon)atlas-mcp-agent repository. This template now focuses exclusively on providing a best-in-class server implementation and framework.

✨ Key Features

Architecture Overview

This template is built on a set of architectural principles to ensure modularity, testability, and operational clarity.

• Core Server (src/mcp-server/server.ts): The central point where tools and resources are registered using the standard McpServer from the SDK.
• Transports (src/mcp-server/transports/): The transport layer connects the core server to the outside world. It supports both stdio for direct process communication and a streamable Hono-based http server.
• "Logic Throws, Handler Catches": This is the immutable cornerstone of our error-handling strategy.
  • Core Logic (logic.ts): This layer is responsible for pure, self-contained business logic. It throws a structured McpError on any failure.
  • Handlers (registration.ts): This layer interfaces with the server, invokes the core logic, and catches any errors using centralized utilities (createToolHandler). It is the exclusive location where errors are processed and formatted into a final response.
• Structured, Traceable Operations: Every operation is traced from initiation to completion via a RequestContext that is implicitly available throughout the entire asynchronous call stack using Node.js's AsyncLocalStorage.

Quick Start

1. Installation

Clone the repository and install dependencies:

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

2. Build the Project

npm run build
# Or use 'npm run rebuild' for a clean install

3. Running the Server

• Via Stdio (Default):

  npm run start:stdio

• Via Streamable HTTP:

  npm run start:http

4. Running Tests

This template uses Vitest for testing, with a strong emphasis on integration testing to ensure all components work together correctly.

• Run all tests once:

  npm test

• Run tests in watch mode:

  npm run test:watch

• Run tests and generate a coverage report:

  npm run test:coverage

⚙️ Configuration

Configure the server using these environment variables (or a .env file):

🏗️ Project Structure

• src/mcp-server/: Contains the core MCP server, tools, resources, and transport handlers.
• src/config/: Handles loading and validation of environment variables.
• src/services/: Reusable modules for integrating with external services (DuckDB, OpenRouter).
• src/types-global/: Defines shared TypeScript interfaces and type definitions.
• src/utils/: Core utilities (logging, error handling, security, etc.).
• src/index.ts: The main entry point that initializes and starts the server.

Explore the full structure yourself:

See the current file tree in docs/tree.md or generate it dynamically:

npm run tree

🧩 Extending the System

The template enforces a strict, modular pattern for adding new tools and resources, as mandated by the Architectural Standard. The echoTool (src/mcp-server/tools/echoTool/) serves as the canonical example.

The "Logic Throws, Handler Catches" Pattern

This is the cornerstone of the architecture:

1. logic.ts: This file contains the pure business logic.

   • It defines the Zod schemas for input and output, which serve as the single source of truth for the tool's data contract.
   • The core logic function is pure: it takes validated parameters and either returns a result or throws a structured McpError. It retrieves the request context via getRequestContext().
   • It never contains try...catch blocks for formatting a final response.

2. registration.ts: This file is the "handler" that connects the logic to the MCP server.

   • It imports the schemas and logic function from logic.ts.
   • It calls server.registerTool(), providing the tool's metadata and the runtime handler created by the createToolHandler utility.
   • The centralized handler always wraps the call to the logic function in a try...catch block. This is the only place where errors are caught, processed by the ErrorHandler, and formatted into a standardized error response.

This pattern ensures that core logic remains decoupled, pure, and easily testable, while the registration layer handles all transport-level concerns, side effects, and response formatting.

🌍 Explore More MCP Resources

Looking for more examples, guides, and pre-built MCP servers? Check out the companion repository:

➡️ cyanheads/model-context-protocol-resources

📜 License

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