Template MCP Server CLI: TypeScript, Dual Transport, Extensible

Overview

This Template MCP Server CLI is a starter project for building Model Context Protocol (MCP) servers in TypeScript. It provides a command-line scaffolding and a modular runtime that supports two transport layers (HTTP and WebSocket) out of the box, plus clear extension points so you can add transports, middleware, or model adapters quickly. The goal is to let developers prototype and ship MCP-compatible services without wiring low-level details every time.

The project is useful when you need a reproducible, type-safe foundation for an MCP server: the CLI generates a TypeScript-ready project, the runtime exposes commonly needed hooks (authentication, routing, payload validation), and the dual-transport setup lets clients choose request/response semantics (HTTP for one-off calls, WebSocket for streaming or long-lived sessions).

Features

• TypeScript-first scaffold and runtime with types for handlers and config
• CLI to generate, run, and build MCP server projects
• Dual transport support: HTTP (REST-style) and WebSocket (bi-directional)
• Modular structure: plugins, middleware, and transport adapters are pluggable
• Sample config file with typed options and environment-based overrides
• Example handlers and model adapter templates to speed development
• Development tooling (hot-reload + types) for rapid iteration

Installation / Configuration

Clone the template and create a new project:

# Clone the template repo
git clone https://github.com/mcpdotdirect/template-mcp-server.git my-mcp-server
cd my-mcp-server

# Install dependencies (npm/yarn/pnpm)
pnpm install
# or
npm install

Run the CLI in development mode:

# Start dev server with Hot Module Reload (example)
pnpm dev
# or
npm run dev

Example typed configuration (mcp.config.ts):

import type { MCPConfig } from './types';

const config: MCPConfig = {
  server: {
    port: 4000,
    host: '0.0.0.0',
  },
  transports: {
    http: { enabled: true, route: '/mcp' },
    websocket: { enabled: true, path: '/ws' },
  },
  plugins: [],
};

export default config;

Environment-based override via environment variables is supported by the project scaffolding. Use NODE_ENV=production and a build step to create production artifacts.

Project Layout (quick reference)

Available Tools

• CLI commands (examples)
  • dev — run development server with hot-reload
  • start — run built production server
  • build — compile TypeScript to dist/
  • new — scaffold a new handler/template (if the CLI includes scaffolding helpers)
• Example utilities
  • type-safe request and response interfaces
  • middleware loader for auth, logging, validation
  • transport adapter lifecycle hooks (init, onMessage, shutdown)

Extending the Server

Add a new transport by implementing the transport interface (pseudo-signature):

import type { Transport } from './types';

export class MyTransport implements Transport {
  async init(config) { /* bind sockets or express handlers */ }
  async sendResponse(session, response) { /* send to client */ }
  async shutdown() { /* graceful close */ }
}

Register the transport in your bootstrap:

import { registerTransport } from './runtime';
import { MyTransport } from './transports/my-transport';

registerTransport('my-transport', new MyTransport());

Add middleware by exporting a function that accepts and returns a handler; typical middleware are logging, auth, and payload validation.

Use Cases

• Prototyping an assistant backend that supports short HTTP requests from cron jobs and persistent WebSocket sessions for interactive clients.
  • Use HTTP transport for quick stateless calls: POST /mcp -> handler runs model with current context.
  • Use WebSocket transport for chat sessions: client opens socket at /ws, sends messages, receives streamed tokens.
• Building a multi-client model orchestrator where different clients require different transports.
  • Browser clients connect via WebSocket for streaming updates; server-to-server integrations call the HTTP endpoint.
• Creating a plugin-based MCP gateway that forwards requests to multiple model providers by swapping adapters.
  • Implement model adapter plugin to route a request to an on-premise model or a cloud model provider; plugins expose the same typed handler interface.

Examples

Example handler (TypeScript):

import type { MCPRequest, MCPResponse } from '../types';

export async function echoHandler(req: MCPRequest): Promise<MCPResponse> {
  return { status: 200, body: { echo: req.data } };
}

Start server with only one transport enabled:

# Set config to enable only WebSocket
node ./dist/index.js --config ./mcp.config.ts

For more detailed examples and the full API reference, see the repository: https://github.com/mcpdotdirect/template-mcp-server

This template aims to minimize boilerplate so you can focus on the MCP handlers and integrations that matter for your application.