Skip to main content
Glama

TypeScript MCP Server Template

by dhinojosac
GitHub
TypeScript
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

TypeScript MCP Server Template

A comprehensive TypeScript MCP Server Template following the official MCP TypeScript SDK best practices, built with Fastify and providing tools, resources, and prompts.

📖 README en Español - Para usuarios que prefieren documentación en español

📌 How to Use or Contribute

This repository is available as both a collaborative project and a template:

  • Use as a template → Create your own MCP server project instantly by clicking Use this template.
  • Contribute improvements → Fork this repo, make your changes, and send a Pull Request so we can review and integrate them.

We welcome:

  • New MCP tools, resources, and prompts
  • Performance optimizations
  • Documentation improvements
  • Bug fixes and code quality enhancements

If you create something based on this template, please mention this repository in your README.

🛠️ Tech Stack & Tools Explained

Core Technologies

  • TypeScript - Type-safe development with compile-time error checking
  • Fastify - Fast and efficient web framework for building APIs
  • @modelcontextprotocol/sdk - Official MCP Server SDK for AI model integration

Development Tools

  • Zod - Runtime type validation and schema definition for API inputs
  • @fastify/cors - CORS support for web clients to access the API
  • tsx - Modern TypeScript execution without compilation step
  • pino-pretty - Beautiful development logging with structured output

Code Quality Tools

  • ESLint - Static code analysis to catch errors and enforce coding standards
  • Prettier - Automatic code formatting for consistent style
  • Husky - Git hooks to run quality checks before commits
  • lint-staged - Run linters only on staged files for faster feedback

Deployment Tools

  • Docker - Containerization for consistent deployment across environments
  • Docker Compose - Multi-container orchestration for development and production

📦 Project Structure

ts-template-mcp-server/ ├── src/ │ ├── server.ts # Main MCP server with HTTP/STDIO transport │ ├── config/ │ │ └── constants.ts # Centralized configuration constants │ ├── utils/ │ │ ├── errorHandler.ts # Centralized error handling utilities │ │ └── logger.ts # Structured logging with Pino │ ├── schemas/ │ │ ├── toolSchemas.ts # Zod schemas for MCP tool validation │ │ └── commonSchemas.ts # Reusable validation schemas │ └── plugins/ │ ├── helloPlugin.ts # Fastify plugin with REST endpoint │ └── weatherPlugin.ts # Weather tools with Zod validation ├── .github/workflows/ │ └── ci.yml # GitHub Actions CI/CD pipeline ├── client-example.js # Example client for testing MCP features ├── Dockerfile # Multi-stage Docker build configuration ├── docker-compose.yml # Docker Compose for local development ├── .dockerignore # Docker build context exclusions ├── DOCKER_TROUBLESHOOTING.md # Docker issues and solutions documentation ├── DOCKER_BEST_PRACTICES.md # Docker best practices guide ├── CHANGELOG.md # Version history and release notes ├── AI_GUIDELINES.md # AI development guidelines and conventions ├── AI_PROMPT_EXAMPLES.md # Specific prompt examples for AI assistance ├── AI_QUICK_START.md # Quick start guide for AI assistants ├── README_ES.md # Spanish documentation for non-English speakers ├── .eslintrc.json # ESLint configuration with TypeScript rules ├── .prettierrc # Prettier formatting rules ├── .husky/pre-commit # Git hook to run lint-staged ├── env.example # Environment variables template ├── tsconfig.json # TypeScript compiler configuration ├── package.json # Dependencies and npm scripts └── README.md # This comprehensive documentation

🚀 Getting Started

1. Install Dependencies

npm install

What this does: Installs all required dependencies including TypeScript, Fastify, MCP SDK, and development tools.

2. Environment Setup

Copy the environment example file and configure your variables:

cp env.example .env

What this does: Creates a local environment file with configuration for:

  • Server settings (port, host)
  • MCP configuration (STDIO mode, session timeout)
  • Logging levels and formatting
  • CORS settings
  • External API keys (weather service)

3. Start Development Server

HTTP Mode (for web clients):

npm run dev

STDIO Mode (for CLI clients like Claude Desktop):

npm run dev:stdio

Debug Mode (with detailed logging):

npm run dev:debug

What each mode does:

  • HTTP Mode: Starts server on port 3000 for web-based MCP clients
  • STDIO Mode: Runs as CLI process for desktop AI applications
  • Debug Mode: Enables verbose logging for troubleshooting

4. Build for Production

# Clean previous build (optional) npm run clean # Compile TypeScript to JavaScript npm run build # Run the compiled server npm start

What this does:

  • clean: Removes old build artifacts
  • build: Compiles TypeScript to optimized JavaScript
  • start: Runs the production server

Production STDIO Mode:

npm run start:stdio

🌐 Available Endpoints

HTTP Mode: The server starts on http://localhost:3000 with these endpoints:

MCP Protocol Endpoints

  • POST /mcp - Model Context Protocol interface (handles all MCP operations)
    • Purpose: Main interface for AI models to interact with tools and resources
    • Usage: Send JSON-RPC 2.0 requests with MCP methods

REST API Endpoints

  • GET /hello/:name - Traditional REST API endpoint
    • Purpose: Example of hybrid REST + MCP server
    • Usage: curl http://localhost:3000/hello/YourName

Weather Plugin Endpoints

  • GET /weather/forecast?lat=40.7128&lng=-74.0060 - Weather forecast
    • Purpose: Get weather data for specific coordinates
    • Usage: curl "http://localhost:3000/weather/forecast?lat=40.7128&lng=-74.0060"
  • GET /weather/alerts/:state - Weather alerts for US state
    • Purpose: Get weather alerts for specific US states
    • Usage: curl http://localhost:3000/weather/alerts/CA

Monitoring Endpoints

  • GET /health - Enhanced server status with session info
    • Purpose: Health check with detailed metrics
    • Usage: curl http://localhost:3000/health
  • GET /info - Server capabilities and endpoints
    • Purpose: Discover available features
    • Usage: curl http://localhost:3000/info

STDIO Mode: The server runs as a CLI process for direct integration with MCP clients like Claude Desktop.

🧪 Testing the Server

Quick Health Check

curl http://localhost:3000/health

Expected response:

{ "status": "ok", "timestamp": "2025-07-25T12:00:00.000Z", "server": "ts-template-mcp-server", "version": "1.0.0", "uptime": 123.456, "sessions": 0, "capabilities": ["tools", "resources"] }

What this tells you:

  • Server is running and healthy
  • Current timestamp and uptime
  • Number of active MCP sessions
  • Available MCP capabilities

Using the Client Example

The included client example demonstrates all MCP features:

node client-example.js

This demonstrates:

  • ✅ Connection: Establishing connection to MCP server
  • 🔧 Tools: Listing and calling MCP tools
  • 📚 Resources: Listing and reading MCP resources
  • 💭 Prompts: Listing and getting MCP prompts
  • 🚨 Error Handling: Proper error handling examples

🔧 MCP Features Explained

🛠️ Tools - What They Are and How to Use

Tools are functions that AI models can call to perform actions. Each tool:

  • Has a name, description, and input schema
  • Validates inputs using Zod schemas
  • Returns structured results

Available Tools:

1. sayHello Tool

Purpose: Simple greeting tool for testing MCP communication Input: Person's name Usage Example:

curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -H "Mcp-Session-Id: test-session" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "sayHello", "arguments": { "name": "Developer" } } }'
2. calculate Tool

Purpose: Perform arithmetic operations Input: Operation type and two numbers Usage Example:

curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -H "Mcp-Session-Id: test-session" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "calculate", "arguments": { "operation": "multiply", "a": 15, "b": 7 } } }'
3. getWeatherForecast Tool

Purpose: Get weather forecast for specific coordinates Input: Latitude and longitude Usage: Called by AI models to get weather data

4. getWeatherAlerts Tool

Purpose: Get weather alerts for US states Input: US state name Usage: Called by AI models to get weather alerts

📋 Zod Validation - Why It's Important

Zod provides runtime type validation that matches TypeScript types:

// Example: Weather forecast tool validation const WeatherForecastSchema = z.object({ latitude: z.number().min(-90).max(90), longitude: z.number().min(-180).max(180) }); // Usage in tool const { latitude, longitude } = validateToolArgs(WeatherForecastSchema, args);

Benefits:

  • ✅ Type Safety: Runtime validation matches TypeScript types
  • ✅ Better Errors: Descriptive validation error messages
  • ✅ Reusability: Common schemas can be shared across tools
  • ✅ Maintainability: Centralized validation logic

📚 Resources - What They Are and How to Use

Resources are data sources that AI models can read. Each resource:

  • Has a URI scheme (mcp://, file://, etc.)
  • Contains structured data
  • Can be read multiple times

Available Resources:

1. Server Information (mcp://server-info)

Purpose: Provides server metadata and capabilities Usage:

curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -H "Mcp-Session-Id: test-session" \ -d '{ "jsonrpc": "2.0", "id": 3, "method": "resources/read", "params": { "uri": "mcp://server-info" } }'
2. Hello Message (mcp://hello-message)

Purpose: Example resource with greeting content Usage:

curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -H "Mcp-Session-Id: test-session" \ -d '{ "jsonrpc": "2.0", "id": 4, "method": "resources/read", "params": { "uri": "mcp://hello-message" } }'

💭 Prompts - What They Are and How to Use

Prompts are template messages that AI models can use. Each prompt:

  • Has a name and description
  • Accepts arguments for customization
  • Returns formatted messages

Available Prompts:

Greeting Prompt (greeting-prompt)

Purpose: Generate personalized greetings Usage:

curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -H "Mcp-Session-Id: test-session" \ -d '{ "jsonrpc": "2.0", "id": 5, "method": "prompts/get", "params": { "name": "greeting-prompt", "arguments": { "name": "Alice", "style": "enthusiastic" } } }'

🏗️ Architecture & Best Practices

Official SDK Patterns Used

This template follows the official MCP TypeScript SDK documentation:

  • ✅ Proper Request Handlers: Using setRequestHandler() for all MCP operations
  • ✅ Session Management: Map-based session storage for transport instances
  • ✅ Streamable HTTP Transport: Latest transport method (not deprecated SSE)
  • ✅ Standard JSON Schema: Proper tool input schemas without Zod dependency
  • ✅ Error Handling: Comprehensive error handling with proper MCP error responses
  • ✅ Resource URI Schemes: Using mcp:// scheme following best practices

Key Improvements Over Basic Implementation

  1. Session Management: Proper session tracking with cleanup
  2. Enhanced Error Handling: Detailed error responses and logging
  3. Multiple Capabilities: Tools, resources, AND prompts (many examples only show one)
  4. Production Ready: Graceful shutdown, health checks, proper logging
  5. Type Safety: Full TypeScript support without runtime schema validation overhead
  6. Code Quality: ESLint, Prettier, and Husky for consistent code
  7. Containerization: Docker support for easy deployment
  8. CI/CD: GitHub Actions pipeline for automated testing

Integration Features

  • CORS: Enhanced CORS configuration for web clients
  • Logging: Structured logging with pino-pretty for development
  • Health Monitoring: Detailed health endpoint with session metrics
  • REST + MCP: Hybrid server supporting both traditional REST and MCP protocols
  • Error Handling: Centralized error handling with custom error types
  • Configuration: Centralized configuration management

🔄 Git Flow Workflow

This project follows Git Flow methodology for organized development:

Branch Structure

  • main - Production-ready code
  • develop - Integration branch for features
  • feature/* - New features and improvements
  • release/* - Release preparation
  • hotfix/* - Critical production fixes

Development Workflow

# Start a new feature git flow feature start feature-name # Work on your feature... git add . git commit -m "feat: add new feature" # Finish the feature (merges to develop) git flow feature finish feature-name # Create a release git flow release start v1.1.0 # Finish release (merges to main and develop) git flow release finish v1.1.0 # Create hotfix for critical issues git flow hotfix start critical-fix git flow hotfix finish critical-fix

Commit Message Convention

We follow Conventional Commits:

  • feat: - New features
  • fix: - Bug fixes
  • docs: - Documentation changes
  • style: - Code style changes (formatting, etc.)
  • refactor: - Code refactoring
  • test: - Adding or updating tests
  • chore: - Maintenance tasks

🔧 Development Tools Explained

Available Scripts

Development Scripts
  • npm run dev - Start development server with hot reload and pretty logging
    • Purpose: Main development command with live reload
    • Use when: Developing new features
  • npm run dev:debug - Start with debug logging enabled
    • Purpose: Detailed logging for troubleshooting
    • Use when: Debugging issues or understanding server behavior
  • npm run dev:stdio - Start in STDIO mode for CLI clients
    • Purpose: Run server for desktop AI applications
    • Use when: Testing with Claude Desktop or similar
Build Scripts
  • npm run build - Compile TypeScript to JavaScript in dist/ folder
    • Purpose: Create production-ready JavaScript files
    • Use when: Deploying to production
  • npm run build:watch - Build with watch mode
    • Purpose: Auto-rebuild when files change
    • Use when: Developing with build step
  • npm start - Run compiled server (production mode)
    • Purpose: Start production server
    • Use when: Running in production environment
Code Quality Scripts
  • npm run clean - Remove compiled files
    • Purpose: Clean build artifacts
    • Use when: Troubleshooting build issues
  • npm run lint - Run ESLint
    • Purpose: Check code quality and style
    • Use when: Before committing code
  • npm run lint:fix - Run ESLint with auto-fix
    • Purpose: Automatically fix linting issues
    • Use when: ESLint reports fixable errors
  • npm run format - Format code with Prettier
    • Purpose: Ensure consistent code formatting
    • Use when: Code formatting is inconsistent
  • npm run type-check - Run TypeScript type checking
    • Purpose: Verify TypeScript types without building
    • Use when: Checking for type errors
  • npm run validate - Run type check and linting
    • Purpose: Comprehensive code quality check
    • Use when: Before pushing code or creating PRs
Testing Scripts
  • npm test - Run tests (placeholder)
    • Purpose: Execute test suite
    • Use when: Verifying functionality

Environment Requirements

  • Node.js: >=18.0.0 (for modern JavaScript features)
  • TypeScript: ^5.7.2 (for type safety)
  • MCP SDK: ^1.0.4 (for MCP protocol support)

Adding New MCP Tools

Following official SDK patterns:

  1. Add tool definition to tools/list handler:
{ name: "myTool", description: "My custom tool", inputSchema: { type: "object", properties: { param: { type: "string", description: "Parameter description" } }, required: ["param"] } }
  1. Handle tool execution in tools/call handler:
case "myTool": const { param } = args as { param: string }; return { content: [{ type: "text", text: `Result: ${param}` }] };

Adding New Resources

  1. Add to resources/list handler - Define available resources
  2. Handle reading in resources/read handler - Implement resource reading logic
  3. Use proper URI schemes (mcp://, file://, etc.) - Follow MCP conventions

Adding Prompts

  1. Add to prompts/list handler - Define available prompts
  2. Handle generation in prompts/get handler - Implement prompt generation logic
  3. Return proper message format with roles - Follow MCP prompt format

🐳 Docker Support

Building the Image

docker build -t ts-template-mcp-server .

What this does:

  • Creates a multi-stage Docker image
  • Optimizes for production with minimal size
  • Includes all necessary dependencies

Running with Docker

# Production mode docker run -p 3000:3000 ts-template-mcp-server # Development mode docker-compose up mcp-server-dev

What each does:

  • Production mode: Runs optimized container for production
  • Development mode: Runs with volume mounts for live development

Docker Compose

# Start all services docker-compose up # Start only production server docker-compose up mcp-server # Start development server docker-compose --profile dev up mcp-server-dev

What this provides:

  • Multi-service orchestration: Easy management of multiple containers
  • Development profiles: Separate configurations for dev/prod
  • Volume mounts: Live code reloading in development

Docker Documentation

For detailed information about Docker setup, troubleshooting, and best practices:

Key improvements made:

  • ✅ Multi-stage builds for optimized production images
  • ✅ Non-root user execution for security
  • ✅ Proper healthcheck configuration with curl
  • ✅ Separate npm scripts to avoid prestart hook issues
  • ✅ Comprehensive .dockerignore for faster builds

🌐 CORS & Security

Enhanced CORS configuration for MCP compatibility:

  • Origin: Flexible origin handling (true instead of *)
  • Headers: All required MCP headers plus standard web headers
  • Methods: All HTTP methods for maximum compatibility
  • Session Security: Session-based transport isolation

🚨 Troubleshooting

Common Issues

1. Port Already in Use
# Check what's using port 3000 netstat -ano | findstr :3000 # Kill the process or change port in server.ts

What this fixes: Resolves port conflicts when starting the server

2. TypeScript Compilation Errors
# Clean and rebuild npm run clean npm run build

What this fixes: Resolves build issues caused by stale files

3. MCP Connection Issues
  • Ensure proper Mcp-Session-Id header
  • Check CORS configuration for web clients
  • Verify JSON-RPC 2.0 format in requests

What this fixes: Resolves MCP protocol communication issues

4. STDIO Mode Not Working
# Ensure proper environment variable export MCP_STDIO=true npm run dev:stdio

What this fixes: Ensures server runs in correct mode for CLI clients

5. Linting Errors
# Auto-fix linting issues npm run lint:fix # Format code npm run format

What this fixes: Resolves code style and quality issues

Debug Mode

Enable debug logging by setting environment variable:

DEBUG=mcp:* npm run dev

What this provides: Detailed logging for troubleshooting MCP issues

Performance Monitoring

The health endpoint provides real-time metrics:

curl http://localhost:3000/health | jq

What this shows: Server status, uptime, active sessions, and capabilities

📚 Learn More

📝 License

MIT License - see LICENSE file for details

🤝 Contributing

We encourage both direct contributions and independent projects based on this template.

  1. To collaborate:
    • Fork the repository.
    • Create a feature branch using Git Flow: git flow feature start feature-name.
    • Follow the patterns from the official MCP SDK documentation.
    • Add tests if applicable.
    • Submit a Pull Request.
  2. To create your own project without linking back:

Built following Official MCP TypeScript SDK best practices

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A comprehensive template for building MCP servers with TypeScript, Fastify, and Docker support. Includes tools for calculations and weather data, resources for server information, and prompts for greetings with full development tooling.

  1. 📌 How to Use or Contribute
    1. 🛠️ Tech Stack & Tools Explained
      1. Core Technologies
      2. Development Tools
      3. Code Quality Tools
      4. Deployment Tools
    2. 📦 Project Structure
      1. 🚀 Getting Started
        1. 1. Install Dependencies
        2. 2. Environment Setup
        3. 3. Start Development Server
        4. 4. Build for Production
      2. 🌐 Available Endpoints
        1. MCP Protocol Endpoints
        2. REST API Endpoints
        3. Weather Plugin Endpoints
        4. Monitoring Endpoints
      3. 🧪 Testing the Server
        1. Quick Health Check
        2. Using the Client Example
      4. 🔧 MCP Features Explained
        1. 🛠️ Tools - What They Are and How to Use
        2. 📋 Zod Validation - Why It's Important
        3. 📚 Resources - What They Are and How to Use
        4. 💭 Prompts - What They Are and How to Use
      5. 🏗️ Architecture & Best Practices
        1. Official SDK Patterns Used
        2. Key Improvements Over Basic Implementation
        3. Integration Features
      6. 🔄 Git Flow Workflow
        1. Branch Structure
        2. Development Workflow
        3. Commit Message Convention
      7. 🔧 Development Tools Explained
        1. Available Scripts
        2. Environment Requirements
        3. Adding New MCP Tools
        4. Adding New Resources
        5. Adding Prompts
      8. 🐳 Docker Support
        1. Building the Image
        2. Running with Docker
        3. Docker Compose
        4. Docker Documentation
      9. 🌐 CORS & Security
        1. 🚨 Troubleshooting
          1. Common Issues
          2. Debug Mode
          3. Performance Monitoring
        2. 📚 Learn More
          1. 📝 License
            1. 🤝 Contributing

              Related MCP Servers

              • MCP Server Template

                stevennevins
                A
                security
                F
                license
                A
                quality
                A template for creating Model Context Protocol (MCP) servers in TypeScript, offering features like container-based dependency injection, a service-based architecture, and integration with the LLM CLI for architectural design feedback through natural language.
                Last updated -
                1
                2
                6
                TypeScript

              • MCP Framework

                ronangrant
                -
                security
                F
                license
                -
                quality
                A TypeScript framework for building Model Context Protocol (MCP) servers with automatic discovery and loading of tools, resources, and prompts.
                Last updated -
                1
                TypeScript
                • Apple

              • MCP TypeScript Server Template

                Mearman
                -
                security
                F
                license
                -
                quality
                A template repository for building Model Context Protocol (MCP) servers with TypeScript, featuring full TypeScript support, testing setup, CI/CD pipelines, and modular architecture for easy extension.
                Last updated -
                2
                TypeScript

              • MCP Server Template

                koki-develop
                -
                security
                A
                license
                -
                quality
                A template repository for creating MCP servers that can be easily containerized and used with MCP clients.
                Last updated -
                710
                1
                MIT License

              View all related MCP servers

              New MCP Servers

              MCP directory API

              We provide all the information about MCP servers via our MCP API.

              curl -X GET 'https://glama.ai/api/mcp/v1/servers/dhinojosac/calendar-mcp'

              If you have feedback or need assistance with the MCP directory API, please join our Discord server