mcp-ts-template

Try it live — A public demo instance is running at https://mcp-ts-template.caseyjhand.com/mcp. Connect any MCP client to test the template's tools and resources without installing anything.

Features

• Define tools and resources in single, self-contained files. The framework handles registration.
• Tools can prompt users for missing parameters mid-execution via elicitation.
• Unified McpError system for consistent, structured error responses.
• Auth modes: none, jwt, or oauth. Wrap logic with withToolAuth/withResourceAuth.
• Swap storage backends (in-memory, filesystem, Supabase, Cloudflare D1/KV/R2) without changing tool logic. Includes cursor pagination, batch ops, and input validation.
• Structured logging (Pino) with optional OpenTelemetry for tracing and metrics.
• Custom typed DI container with Token<T> phantom branding. No external deps.
• Pluggable service integrations: LLM (OpenRouter), TTS (ElevenLabs).
• Parsing helpers (PDF, YAML, CSV, frontmatter), formatting (diffs, tables, trees, markdown), scheduling, security.
• Runs on local (stdio/HTTP) and edge (Cloudflare Workers) with the same code.

Architecture

Modular, domain-driven layout 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
• Container — Typed DI container, no external deps
• Services — External integrations (LLM, Speech, Graph) with pluggable providers
• Storage — Persistence layer with multiple backend support
• Utilities — Logging, security, parsing, telemetry

Included capabilities

This template includes working examples to get you started.

Tools

Resources

Prompts

Getting started

MCP client 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"
      }
    }
  }
}

Or connect to the public demo server over HTTP — no installation required:

{
  "mcpServers": {
    "mcp-ts-template": {
      "type": "streamable-http",
      "url": "https://mcp-ts-template.caseyjhand.com/mcp"
    }
  }
}

Prerequisites

• Bun v1.2.0 or higher.

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd mcp-ts-template

3. 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:

Authentication and authorization

• Modes: `non