@iflow-mcp/mcp-ts-template

v2.5.7

Published

4 months ago

The definitive, production-grade template for building powerful and scalable Model Context Protocol (MCP) servers with TypeScript, featuring built-in observability (OpenTelemetry), declarative tooling, robust error handling, and a modular, DI-driven archi

✨ 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, SurrealDB, Cloudflare D1/KV/R2) without changing business logic. Features secure opaque cursor pagination, parallel batch operations, and comprehensive validation.
Graph Database Operations: Optional graph service for relationship management, graph traversals, and pathfinding algorithms (SurrealDB provider).
Full-Stack Observability: Get deep insights with structured logging (Pino) and optional, auto-instrumented OpenTelemetry for traces and metrics.
Dependency Injection: Built with tsyringe for a clean, decoupled, and testable architecture.
Service Integrations: Pluggable services for external APIs, including LLM providers (OpenRouter), text-to-speech (ElevenLabs), and graph operations (SurrealDB).
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 - Dependency injection setup with tsyringe for clean architecture
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

Resources

| Resource | URI | Description | | :--------- | :----------------- | :-------------------------------------------- | | echo | echo://{message} | A simple resource that echoes back a message. |

Prompts

🚀 Getting Started

MCP Client Settings/Configuration

Add the following to your MCP Client configuration file (e.g., cline_mcp_settings.json).

{
  "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

Clone the repository:

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

Navigate into the directory:

cd mcp-ts-template

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 & 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, surrealdb, cloudflare-kv, and cloudflare-r2.
SurrealDB Setup: When using surrealdb provider, initialize the database schema using docs/surrealdb-schema.surql before first use.
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

Build the Worker bundle:

bun build:worker

Run locally with Wrangler:

bun deploy:dev

Deploy to Cloudflare:

bun deploy:prod

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

📂 Project 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 - Dependency injection with tsyringe
- 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)
- Graph database operations (SurrealDB)
- 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.