mcp-ts-template

<div align="center"> <h1>mcp-ts-template</h1> <p><b>TypeScript template for building Model Context Protocol (MCP) servers. Ships with declarative tools/resources, pluggable auth, multi-backend storage, OpenTelemetry observability, and first-class support for both local and edge (Cloudflare Workers) runtimes.</b> <div>7 Tools • 2 Resources • 1 Prompt</div> </p> </div> <div align="center">

</div>

---

✨ Features

• Declarative Tools & Resources: Define capabilities in single, self-contained files. The framework handles registration and execution.
• Elicitation Support: Tools can interactively prompt the user for missing parameters during execution, streamlining user workflows.
• Robust Error Handling: A unified McpError system ensures consistent, structured error responses across the server.
• Pluggable Authentication: Secure your server with zero-fuss support for none, jwt, or oauth modes.
• Abstracted Storage: Swap storage backends (in-memory, filesystem, Supabase, Cloudflare D1/KV/R2) without changing business logic. Features secure opaque cursor pagination, parallel batch operations, and comprehensive validation.
• Full-Stack Observability: Get deep insights with structured logging (Pino) and optional, auto-instrumented OpenTelemetry for traces and metrics.
• Dependency Injection: Custom typed DI container with Token<T> phantom branding — zero external dependencies, fully type-safe resolution.
• Service Integrations: Pluggable services for external APIs, including LLM providers (OpenRouter) and text-to-speech (ElevenLabs).
• Rich Built-in Utility Suite: Helpers for parsing (PDF, YAML, CSV, frontmatter), formatting (diffs, tables, trees, markdown), scheduling, security, and more.
• Edge-Ready: Write code once and run it seamlessly on your local machine or at the edge on Cloudflare Workers.

🏗️ Architecture

This template follows a modular, domain-driven architecture with clear separation of concerns:

┌─────────────────────────────────────────────────────────┐
│              MCP Client (Claude Code, ChatGPT, etc.)    │
└────────────────────┬────────────────────────────────────┘
                     │ JSON-RPC 2.0
                     ▼
┌─────────────────────────────────────────────────────────┐
│           MCP Server (Tools, Resources)                 │
│           📖 [MCP Server Guide](src/mcp-server/)        │
└────────────────────┬────────────────────────────────────┘
                     │ Dependency Injection
                     ▼
┌─────────────────────────────────────────────────────────┐
│          Dependency Injection Container                 │
│              📦 [Container Guide](src/container/)       │
└────────────────────┬────────────────────────────────────┘
                     │
        ┌────────────┼────────────┐
        ▼            ▼            ▼
 ┌──────────┐   ┌──────────┐   ┌──────────┐
 │ Services │   │ Storage  │   │ Utilities│
 │ 🔌 [→]   │   │ 💾 [→]   │   │ 🛠️ [→]   │
 └──────────┘   └──────────┘   └──────────┘

[→]: src/services/    [→]: src/storage/    [→]: src/utils/

Key Modules:

• MCP Server - Tools, resources, prompts, and transport layer implementations
• Container - Typed dependency injection container with zero external dependencies
• Services - External service integrations (LLM, Speech, Graph) with pluggable providers
• Storage - Abstracted persistence layer with multiple backend support
• Utilities - Cross-cutting concerns (logging, security, parsing, telemetry)

💡 Tip: Each module has its own comprehensive README with architecture diagrams, usage examples, and best practices. Click the links above to dive deeper!

🛠️ Included Capabilities

This template includes working examples to get you started.

Tools

| Tool | Description | | :---------------------------------- | :----------------------------------------------------------------------- | | template_echo_message | Echoes a message back with optional formatting and repetition. | | template_cat_fact | Fetches a random cat fact from an external API. | | template_madlibs_elicitation | Demonstrates elicitation by asking for words to complete a story. | | template_code_review_sampling | Uses the LLM service to perform a simulated code review. | | template_image_test | Returns a test image as a base64-encoded data URI. | | template_async_countdown | Demonstrates MCP Tasks API with an async countdown timer (experimental). | | template_data_explorer | Generates sample sales data with an interactive explorer UI (MCP Apps). |

Resources

| Resource | URI | Description | | :--------------------- | :------------------------------------- | :---------------------------------------------------------- | | echo | echo://{message} | A simple resource that echoes back a message. | | data-explorer-ui | ui://template-data-explorer/app.html | Interactive HTML app for the data explorer tool (MCP Apps). |

Prompts

| Prompt | Description | | :---------------- | :--------------------------------------------------------------- | | code-review | A structured prompt for guiding an LLM to perform a code review. |

🚀 Getting Started

MCP Client Settings/Configuration

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "mcp-ts-template": {
      "type": "stdio",
      "command": "bunx",
      "args": ["mcp-ts-template@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "STORAGE_PROVIDER_TYPE": "filesystem",
        "STORAGE_FILESYSTEM_PATH": "/path/to/your/storage"
      }
    }
  }
}

Prerequisites

• Bun v1.2.21 or higher.

Installation

1. Clone the repository:

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

1. Navigate into the directory:

cd mcp-ts-template

1. Install dependencies:

bun install

⚙️ Configuration

All configuration is centralized and validated at startup in src/config/index.ts. Key environment variables in your .env file include:

| Variable | Description | Default | | :------------------------ | :--------------------------------------------------------------------------------------------------------- | :----------- | | MCP_TRANSPORT_TYPE | The transport to use: stdio or http. | stdio | | MCP_HTTP_PORT | The port for the HTTP server. | 3010 | | MCP_HTTP_HOST | The hostname for the HTTP server. | 127.0.0.1 | | MCP_LOG_LEVEL | Logging level (fatal, error, warn, info, debug, trace, silent). | debug | | MCP_AUTH_MODE | Authentication mode: none, jwt, or oauth. | none | | MCP_AUTH_SECRET_KEY | Required for jwt auth mode. A 32+ character secret. | (none) | | OAUTH_ISSUER_URL | Required for oauth auth mode. URL of the OIDC provider. | (none) | | STORAGE_PROVIDER_TYPE | Storage backend: in-memory, filesystem, supabase, cloudflare-d1, cloudflare-kv, cloudflare-r2. | in-memory | | STORAGE_FILESYSTEM_PATH | Path to the storage directory (for filesystem provider). | ./.storage | | SUPABASE_URL | Required for supabase storage. Your Supabase project URL. | (none) | | SUPABASE_ANON_KEY | Required for supabase storage. Your Supabase anon key. | (none) | | OTEL_ENABLED | Set to true to enable OpenTelemetry. | false | | OPENROUTER_API_KEY | API key for OpenRouter LLM service. | (none) |

Authentication & Authorization

• Modes: none (default), jwt (requires MCP_AUTH_SECRET_KEY), or oauth (requires OAUTH_ISSUER_URL and OAUTH_AUDIENCE).
• Enforcement: Wrap your tool/resource logic functions with withToolAuth([...]) or withResourceAuth([...]) to enforce scope checks. Scope checks are bypassed for developer convenience when auth mode is none.

Storage

• Service: A DI-managed StorageService provides a consistent API for persistence. Never access fs or other storage SDKs directly from tool logic.
• Providers: The default is in-memory. Node-only providers include filesystem. Edge-compatible providers include supabase, cloudflare-kv, and cloudflare-r2.
• Multi-Tenancy: The StorageService requires context.tenantId. This is automatically propagated from the tid claim in a JWT when auth is enabled.
• Advanced Features:
  • Secure Pagination: Opaque cursors with tenant ID binding prevent cross-tenant attacks
  • Batch Operations: Parallel execution for getMany(), setMany(), deleteMany()
  • TTL Support: Time-to-live with proper expiration handling across all providers
  • Comprehensive Validation: Centralized input validation for tenant IDs, keys, and options

Observability

• Structured Logging: Pino is integrated out-of-the-box. All logs are JSON and include the RequestContext.
• OpenTelemetry: Disabled by default. Enable with OTEL_ENABLED=true and configure OTLP endpoints. Traces, metrics (duration, payload sizes), and errors are automatically captured for every tool call.

▶️ Running the Server

Local Development

• Build and run the production version:

  # One-time build
  bun rebuild
  
  # Run the built server
  bun start:http
  # or
  bun start:stdio
  

• Run checks and tests:

  bun devcheck # Lints, formats, type-checks, and more
  bun run test # Runs the test suite (Do not use 'bun test' directly as it may not work correctly)
  

Cloudflare Workers

1. Build the Worker bundle:

bun build:worker

1. Run locally with Wrangler:

bun deploy:dev

1. Deploy to Cloudflare:

bun deploy:prod

Note: The wrangler.toml file is pre-configured to enable nodejs_compat for best results.

📂 Project Structure

| Directory | Purpose & Contents | Guide | | :------------------------------------- | :----------------------------------------------------------------------------------- | :----------------------------------- | | src/mcp-server/tools/definitions | Your tool definitions (*.tool.ts). This is where you add new capabilities. | 📖 MCP Guide | | src/mcp-server/resources/definitions | Your resource definitions (*.resource.ts). This is where you add new data sources. | 📖 MCP Guide | | src/mcp-server/transports | Implementations for HTTP and STDIO transports, including auth middleware. | 📖 MCP Guide | | src/storage | The StorageService abstraction and all storage provider implementations. | 💾 Storage Guide | | src/services | Integrations with external services (e.g., the default OpenRouter LLM provider). | 🔌 Services Guide | | src/container | Dependency injection container registrations and tokens. | 📦 Container Guide | | src/utils | Core utilities for logging, error handling, performance, security, and telemetry. | | | src/config | Environment variable parsing and validation with Zod. | | | tests/ | Unit and integration tests, mirroring the src/ directory structure. | |

📚 Documentation

Each major module includes comprehensive documentation with architecture diagrams, usage examples, and best practices:

Core Modules

• MCP Server Guide - Complete guide to building MCP tools and resources

  • Creating tools with declarative definitions
  • Resource development with URI templates
  • Authentication and authorization
  • Transport layer (HTTP/stdio) configuration
  • SDK context and client interaction
  • Response formatting and error handling

• Container Guide - Typed dependency injection container

  • Understanding DI tokens and registration
  • Service lifetimes (singleton, transient, instance)
  • Constructor injection patterns
  • Testing with mocked dependencies
  • Adding new services to the container

• Services Guide - External service integration patterns

  • LLM provider integration (OpenRouter)
  • Speech services (TTS/STT with ElevenLabs, Whisper)
  • Creating custom service providers
  • Health checks and error handling

• Storage Guide - Abstracted persistence layer

  • Storage provider implementations
  • Multi-tenancy and tenant isolation
  • Secure cursor-based pagination
  • Batch operations and TTL support
  • Provider-specific setup guides

Additional Resources

• AGENTS.md - Strict development rules for AI agents
• CHANGELOG.md - Version history and breaking changes
• docs/tree.md - Complete visual directory structure
• docs/publishing-mcp-server-registry.md - Publishing guide for MCP Registry

🧑‍💻 Agent Development Guide

For a strict set of rules when using this template with an AI agent, please refer to AGENTS.md. Key principles include:

• Logic Throws, Handlers Catch: Never use try/catch in your tool/resource logic. Throw an McpError instead.
• Use Elicitation for Missing Input: If a tool requires user input that wasn't provided, use the elicitInput function from the SdkContext to ask the user for it.
• Pass the Context: Always pass the RequestContext object through your call stack.
• Use the Barrel Exports: Register new tools and resources only in the index.ts barrel files.

❓ FAQ

• Does this work with both STDIO and Streamable HTTP?
  • Yes. Both transports are first-class citizens. Use bun run dev:stdio or bun run dev:http.
• Can I deploy this to the edge?
  • Yes. The template is designed for Cloudflare Workers. Run bun run build:worker and deploy with Wrangler.
• Do I have to use OpenTelemetry?
  • No, it is disabled by default. Enable it by setting OTEL_ENABLED=true in your .env file.
• How do I publish my server to the MCP Registry?
  • Follow the step-by-step guide in docs/publishing-mcp-server-registry.md.

🤝 Contributing

Issues and pull requests are welcome! If you plan to contribute, please run the local checks and tests before submitting your PR.

bun run devcheck
bun test

📜 License

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

---

<div align="center"> <p> <a href="https://github.com/sponsors/cyanheads">Sponsor this project</a> • <a href="https://www.buymeacoffee.com/cyanheads">Buy me a coffee</a> </p> </div>