ts-mcp-template/README.md

TS MCP Template (V1)

A Node.js template for building Model Context Protocol (MCP) servers with TypeScript. This template focuses on a local-first development experience, protocol-safe stdio execution, and explicit capability registration.

Status: V1 Alpha

This template supports:

• Node.js 20+ runtime
• Single-package architecture
• Protocol-safe Local Stdio transport (Primary)
• Streamable HTTP transport (Secondary)
• Explicit, function-based tool, resource, and prompt registration
• Vitest-powered transport and core logic testing

It does not currently support Bun, Deno, edge runtimes, built-in authentication, or telemetry.

Quickstart: Local Stdio

Stdio is the primary transport for local development and integration with desktop LLM clients like Claude.

1. Install dependencies

   npm install
   

2. Run with MCP Inspector The template includes a protocol-safe launch configuration in package.json to avoid stdout pollution. Use this command to test your server:

   npx @modelcontextprotocol/inspector node ./node_modules/tsx/dist/cli.mjs src/stdio.ts
   

3. Build the project To prepare for production or use with a compiled entry point:

   npm run build
   

Usage: HTTP

The HTTP transport uses the Node-native StreamableHTTPServerTransport for remote or web-based connections.

1. Start the HTTP server

   npm run dev:http
   

   The server defaults to 127.0.0.1:3000. You can configure the port via the HTTP_PORT environment variable.

2. Endpoints

   • POST /mcp: Initialize a new session and handle requests.
   • GET /mcp: Handle ongoing session requests.

Development and Testing

• Typecheck: npm run typecheck
• Test: npm test (Runs Vitest smoke tests for stdio, HTTP, and core logic)
• Dev (Core Logic): npm run dev (Executes src/index.ts)

Repository Structure

• src/core/: The shared MCP core factory (createMcpCore) that builds the server and registry.
• src/capabilities/: Definitions and handlers for tools, resources, and prompts.
• src/stdio.ts: The stdio entry point and transport setup.
• src/http.ts: The HTTP entry point and session management.
• src/config/: Runtime configuration and environment variable parsing.
• src/lib/: Internal utilities, stderr-safe logging, and error handling.

Extension Guidance

This template uses an explicit, function-based registration pattern instead of decorators or reflection.

1. Define Contracts

Add new tool or prompt schemas in src/capabilities/contracts.ts to share types between handlers and tests.

2. Implement Handlers

Create or update files in src/capabilities/ (e.g., tools.ts):

1. Define the handler logic.
2. Update the register...Capabilities function to add descriptors to the registry.
3. Update the register...Handlers function to wire the logic to the McpServer instance.

3. Register with Core

If you create new capability modules, ensure they are called within src/capabilities/index.ts in the registerCoreCapabilities and registerCoreMcpCapabilities functions.

V1 Limitations

• No Auth: HTTP transport does not include built-in authentication.
• Node-only: Specifically tuned for Node.js 20+.
• No Monorepo: Designed as a standalone project template.
• Local Focus: Deployment guides for cloud providers are not provided in V1.