ts-template

This MCP server template implements a TypeScript-based MCP server using Fastify and the official MCP Server SDK. It exposes an HTTP API for web clients and can run in STDIO mode for CLI-based MCP clients. The server wires together tools like a weather plugin and a hello plugin, validates inputs with Zod, and provides a MCP endpoint at /mcp for JSON-RPC 2.0 style interactions. You can also access a lightweight REST example endpoint and dedicated weather endpoints to illustrate tool usage. The included client-example.js demonstrates how to connect to the MCP server, list tools and resources, and invoke prompts. Use the HTTP mode for web integrations and switch to STDIO mode when integrating with desktop AI applications or command-line workflows.

Prerequisites:

• Node.js (12.x or newer) and npm installed
• Git installed (optional for cloning)

1. Clone or download the repository

2. Install dependencies

npm install

3. Configure environment

• Copy the environment template and edit values

cp env.example .env

• Edit .env to configure server ports, session timeouts, CORS, and external API keys (e.g., weather API key)

4. Start the development server (HTTP mode by default)

npm run dev

5. Optional production build

# Clean previous build artifacts (if applicable)
npm run clean

# Build TypeScript to JavaScript
npm run build

# Run the production server
npm start

To run STDIO mode for CLI clients:

npm run dev:stdio

For debugging with verbose logs:

npm run dev:debug

• The template includes HTTP and STDIO MCP transport modes; choose the mode via environment flags or npm scripts.
• Ensure your environment (.env) contains correct MCP_STDIO and SESSION_TIMEOUT values to avoid unexpected disconnects.
• The Weather plugin requires a valid API key if you enable external weather services; omit or neutralize the key if not using the feature.
• If you modify or add new tools/plugins, update the MCP info endpoint and ensure Zod schemas cover new inputs.
• When running in Docker, use the provided docker-compose.yml to streamline local development and testing.