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 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 employs a modular, transport-agnostic architecture to ensure a clean separation of concerns.

• Core Server (src/mcp-server/server.ts): The central point where tools and resources are registered. It remains independent of how the server is accessed.
• Transports (src/mcp-server/transports/): The transport layer connects the core server to the outside world.
  • StdioTransport: For direct process-to-process communication.
  • HttpTransport: A modern, streamable HTTP server built with Hono. It uses a middleware-based approach for handling CORS, rate limiting, authentication, and MCP request processing.
• Transport Managers (src/mcp-server/transports/core/): These managers bridge the gap between the transport layer (like Hono) and the MCP SDK, handling session management (stateful vs. stateless) and request lifecycle.

This design allows you to add new tools and logic to the core server without worrying about the underlying transport details.

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:server

• Via Streamable HTTP:

  npm run start:server: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 canonical pattern for adding new tools and resources is defined in the .clinerules file. It mandates a strict separation of concerns:

1. logic.ts: Contains the pure business logic, Zod schemas, and type definitions. This file throws structured errors on failure.
2. registration.ts: Acts as the "handler." It registers the tool with the server, wraps the logic call in a try...catch block, and formats the final success or error response.

This "Logic Throws, Handler Catches" pattern ensures that core logic remains pure and testable, while the registration layer handles all 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.