MCP TypeScript Template 🚀

Jumpstart your Model Context Protocol (MCP) Client & Server development with this TypeScript Repo Template!

This template provides a solid, beginner-friendly foundation for building robust MCP servers and clients, adhering to the MCP 2025-03-26 specification. It includes production-ready utilities, a well-structured codebase, working examples, and clear documentation to get you up and running quickly.

Whether you're creating a new MCP server to extend an AI's capabilities or integrating MCP client features into your application, this template is your starting point.

✨ Key Features

For a more granular breakdown, see the Detailed Features Table below.

🚀 Projects Using This Template

This template is already powering several MCP servers, demonstrating its flexibility and robustness:

Note: toolkit-mcp-server was initially built using an older version of this template and is pending updates to the latest structure.

You can also see my GitHub profile for additional MCP servers I've created, many of which are planned to be migrated to or built upon this template in the future.

📋 Table of Contents

✨ Key Features | 🚀 Projects Using This Template | 🚀 Quick Start | ⚙️ Configuration | Server Configuration | Client Configuration | 🏗️ Project Structure | 🧩 Adding Tools/Resources | 🌍 More MCP Resources | 📜 License | Detailed Features

Quick Start

Get the example server running in minutes:

1. Clone the repository:

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

2. Install dependencies:

   npm install

3. Build the project:

   npm run build
   # Or use 'npm run rebuild' for a clean install (deletes node_modules, logs, dist)

4. Format the code (Optional but Recommended):

   npm run format

5. Run the Example Server:

   • Via Stdio (Default): Many MCP host applications will run this automatically using stdio. To run manually for testing:

     npm start
     # or 'npm run start:stdio'

   • Via Streamable HTTP:

     npm run start:http

     This starts a Streamable HTTP server (default: http://127.0.0.1:3010) which uses Server-Sent Events for the server-to-client streaming component. The port, host, and allowed origins are configurable via environment variables (see Configuration).

⚙️ Configuration

Server Configuration (Environment Variables)

Configure the MCP server's behavior using these environment variables:

Note on HTTP Port Retries: If the MCP_HTTP_PORT is busy, the server automatically tries the next port (up to 15 times).

Security Note for HTTP Transport: When using MCP_TRANSPORT_TYPE=http, authentication is mandatory as per the MCP specification. This template includes JWT-based authentication middleware (src/mcp-server/transports/authentication/authMiddleware.ts). You MUST set a strong, unique MCP_AUTH_SECRET_KEY in your production environment for this security mechanism to function correctly. Failure to do so will result in bypassed authentication checks in development and fatal errors in production.

Client Configuration (src/mcp-client/client-config/mcp-config.json)

Configure the connections for the built-in MCP client using src/mcp-client/client-config/mcp-config.json. If this file is missing, it falls back to src/mcp-client/client-config/mcp-config.json.example.

This file defines external MCP servers the client can connect to. The client implementation adheres to the MCP 2025-03-26 specification.

Example mcp-config.json (see src/mcp-client/client-config/mcp-config.json.example for the full version):

{
  "mcpServers": {
    "my-stdio-server": {
      "command": "node", // Command or executable
      "args": ["/path/to/my-server/index.js"], // Arguments for stdio
      "env": { "LOG_LEVEL": "debug" }, // Optional environment variables
      "transportType": "stdio" // Explicitly stdio (or omit for default)
    },
    "my-http-server": {
      "command": "http://localhost:8080", // Base URL for HTTP
      "args": [], // Not used for HTTP
      "env": {}, // Not used for HTTP
      "transportType": "http" // Explicitly http
    }
    // ... add other servers
  }
}

• command: Executable path (stdio) or Base URL (http).
• args: Array of arguments (required for stdio).
• env: Optional environment variables to set for the server process (stdio).
• transportType: stdio (default) or http.

See src/mcp-client/client-config/configLoader.ts for the Zod validation schema and src/mcp-client/client-config/mcp-config.json.example for a complete example.

🏗️ Project Structure

The src/ directory is organized for clarity:

• config/: Loads environment variables and package info.
• mcp-client/: Logic for the client connecting to external MCP servers (updated to MCP 2025-03-26 spec).
  • client-config/: Handles loading and validation of mcp-config.json.
    • configLoader.ts: Loads and validates server configurations.
    • mcp-config.json.example: Example configuration file.
  • core/: Core client logic including connection management and caching.
    • clientManager.ts: Manages client instances and their lifecycle.
    • clientConnectionLogic.ts: Handles the details of connecting and initializing with servers.
    • clientCache.ts: Caches active client connections.
  • transports/: Manages different communication transports (Stdio, HTTP).
    • transportFactory.ts: Creates appropriate transport instances.
    • stdioClientTransport.ts: Implements Stdio transport.
    • httpClientTransport.ts: Implements HTTP transport.
  • index.ts: Barrel file exporting key client functionalities.
• mcp-server/: Logic for the MCP server provided by this template.
  • server.ts: Initializes the server, registers tools/resources.
  • resources/: Example resource implementations (e.g., EchoResource).
  • tools/: Example tool implementations (e.g., EchoTool, and CatFactFetcher demonstrating async/Promise API calls).
  • transports/: Handles stdio and http communication for the server.
• services/: Contains service integrations.
  • duck-db/: Service for interacting with DuckDB, an in-process analytical data management system.
    • duckDBConnectionManager.ts: Manages DuckDB instance and connection lifecycle.
    • duckDBQueryExecutor.ts: Executes SQL queries and manages transactions.
    • duckDBService.ts: Main service class for DuckDB interaction.
    • types.ts: TypeScript types and interfaces for the DuckDB service.
  • llm-providers/: API Providers for Large Language Models.
    • openRouter/: OpenRouter provider implementation.
    • llmFactory.ts: Factory for creating LLM provider clients.
    • index.ts: Barrel file for all LLM providers.
  • index.ts: Barrel file for services.
• storage/: Example usage of services, e.g., duckdbExample.ts.
• types-global/: Shared TypeScript definitions (Errors, MCP types).
• utils/: Reusable utilities (logging, errors, security, parsing, etc.). Exported via index.ts.

Explore the structure yourself:

See the current file tree in docs/tree.md or generate it dynamically:

npm run tree

(This uses scripts/tree.ts to generate a current file tree.)

🧩 Adding Your Own Tools & Resources

This template is designed for extension! Follow the high-level SDK patterns:

1. Create Directories: Add new directories under src/mcp-server/tools/yourToolName/ or src/mcp-server/resources/yourResourceName/.
2. Implement Logic (logic.ts): Define Zod schemas for inputs/outputs and write your core processing function.
3. Register (registration.ts):
   • Tools: Use server.tool(name, description, zodSchemaShape, handler) (SDK v1.10.2+). This handles schema generation, validation, and routing. Remember to add relevant annotations (readOnlyHint, destructiveHint, etc.) as untrusted hints.
   • Resources: Use server.resource(regName, template, metadata, handler).
   • Wrap logic in ErrorHandler.tryCatch for robust error handling.
4. Export & Import: Export the registration function from your new directory's index.ts and call it within createMcpServerInstance in src/mcp-server/server.ts.

Refer to the included EchoTool and EchoResource examples and the .clinerules cheatsheet for detailed patterns.

For an example of a tool that performs asynchronous operations, such as making an external API call, see the get_random_cat_fact tool located in src/mcp-server/tools/catFactFetcher/. This tool demonstrates how to use async/await within your tool's logic and handler, manage Promises, and integrate external data sources.

🌍 Explore More MCP Resources

Looking for more examples, guides, and pre-built MCP servers? Check out the companion repository:

➡️ cyanheads/model-context-protocol-resources

This collection includes servers for Filesystem, Obsidian, Git, GitHub, Perplexity, Atlas, Ntfy, and more, along with in-depth guides based on my real-world MCP development.

📜 License

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

Detailed Features Table