mcp-ts-template

The mcp-ts-template repository provides a TypeScript-based MCP server scaffold that supports declarative tool and resource definitions, pluggable authentication, multiple storage backends, and runtime compatibility with both local stdio and edge environments (e.g., Cloudflare Workers). It ships with example tools, resources, prompts, and a typed DI container, enabling you to quickly model tools, prompts, and storage adapters without changing core logic. To start using it, clone the project, install dependencies with Bun, and run the server through the recommended Bun command. The included configuration demonstrates how to connect a client to the local stdio transport or to a public HTTP streamable endpoint, facilitating both development and testing workflows. Tools and resources are defined in a centralized, self-contained manner, with support for elicitation, structured errors, and multiple backends for storage.

Prerequisites:

• Node tooling with Bun (bun.sh) installed and in PATH
• Git
• A compatible environment for running TypeScript project code

Installation steps:

1. Clone the repository

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

2. Navigate into the project

cd mcp-ts-template

3. Install dependencies (using Bun)

bun install

4. Run the MCP server (examples shown below)

• Local stdio transport (recommended for development):

bunx mcp-ts-template@latest

• If you prefer to pin a specific version, replace latest with a version tag, e.g. v3.0.6

bunx mcp-ts-template@v3.0.6

Note: The repository can be used via the public demo server as well, see the Getting Started section for client configuration in the README.

• The server supports multiple storage backends (in-memory, filesystem, Supabase, Cloudflare D1/KV/R2); configure STORAGE_PROVIDER_TYPE and related settings in your .env or environment to switch backends without modifying tool logic.
• Transport is configurable; the default example uses stdio for local development, but you can switch to HTTP/streamable modes when connecting from a client.
• Authentication modes include none, jwt, or oauth; you can wrap tool/resource access with withToolAuth/withResourceAuth to enforce access controls.
• OpenTelemetry integration is available for tracing and metrics; enable via environment/configuration if observability is required.
• Ensure your environment variables (MCP_TRANSPORT_TYPE, MCP_HTTP_PORT, etc.) are documented in a .env file or your deployment mechanism to avoid startup errors.
• For edge runtimes (Cloudflare Workers), ensure the build targets and runtime constraints are respected; the template is designed to run in both local and edge environments with the same core code.