MCP TypeScript Simple

A production-ready MCP (Model Context Protocol) server built with TypeScript featuring both basic tools and advanced LLM-powered capabilities with type-safe provider and model selection and dual-mode operation (STDIO + Streamable HTTP with OAuth).

Quick Start

Create a production-ready MCP server in under 2 minutes:

npm create @mcp-typescript-simple@latest my-mcp-server
cd my-mcp-server
cp .env.example .env
npm run dev:stdio

What you get:

• ✅ Full-featured MCP server (OAuth, LLM, Docker)
• ✅ Graceful degradation (works without API keys)
• ✅ Production-ready testing (unit + system tests)
• ✅ Docker deployment (nginx + Redis + multi-replica)
• ✅ Validation pipeline (vibe-validate)

Adding API keys: Edit .env to add your provider keys (all optional):

• ANTHROPIC_API_KEY - Claude LLM tools
• OPENAI_API_KEY - GPT LLM tools
• GOOGLE_API_KEY - Gemini LLM tools
• GOOGLE_CLIENT_ID/SECRET - Google OAuth
• GITHUB_CLIENT_ID/SECRET - GitHub OAuth
• MICROSOFT_CLIENT_ID/SECRET - Microsoft OAuth

See Getting Started Guide for full documentation.

Key Features

🔒 Type-Safe LLM Integration

• Provider Selection: Choose between Claude, OpenAI, and Gemini with compile-time validation
• Model Selection: Select specific models per provider with type safety
• Intelligent Defaults: Each tool optimized for specific provider/model combinations
• Runtime Flexibility: Override provider/model per request
• Backward Compatibility: Existing code continues to work unchanged

🚀 Dual-Mode Operation

• STDIO Mode: Traditional stdin/stdout for development and Claude Desktop
• Streamable HTTP Mode: HTTP endpoints with streaming support for web applications
• OAuth Authentication: Secure Google/GitHub/Microsoft OAuth integration for production
• Dynamic Client Registration: RFC 7591 compliant OAuth DCR for automatic client registration
• Development Bypass: Easy auth bypass for local development
• Claude Code Ready: Full compatibility with Claude Code integration

📊 Production Observability

• Structured Logging: Pino-based high-performance logging with environment-aware configuration
• OpenTelemetry Integration: Distributed tracing and metrics collection
• Session Correlation: Secure UUID-based session tracking for distributed systems
• Local Development: Grafana OTEL-LGTM stack for observability validation
• Cross-Platform: Compatible with Express.js, Kubernetes, and Vercel deployments

Current State

This project provides a containerized MCP server with comprehensive CI/CD testing and multi-LLM support:

Basic Tools

• hello: Greets a person by name
• echo: Echoes back a provided message
• current-time: Returns the current timestamp

LLM-Powered Tools (Optional)

• chat: Interactive AI assistant using Claude Haiku (fast responses)
• analyze: Deep text analysis using GPT-4 (sentiment, themes, structure)
• summarize: Text summarization using Gemini Flash (cost-effective)
• explain: Educational explanations using Claude (clear, adaptive to level)

Note: LLM tools require API keys. The server gracefully runs with basic tools only if no API keys are configured.

Prerequisites

• Node.js 22+ (Current LTS)
• Docker (via Colima on macOS)
• Optional: API keys for LLM providers (Anthropic, OpenAI, Google)

Setup

1. Environment Configuration

Copy the example environment file and add your API keys:

cp .env.example .env
# Edit .env with your API keys

API Key Sources:

• Anthropic Claude: https://console.anthropic.com/
• OpenAI: https://platform.openai.com/api-keys
• Google Gemini: https://ai.google.dev/

Tip: You can use any combination of providers. The server will automatically detect available APIs and enable corresponding tools.

2. Development

Local Development

# Install dependencies
npm install

# STDIO Mode (traditional MCP - recommended for development)
npm run dev:stdio

# Streamable HTTP Mode (for web development - no auth)
npm run dev:http

# Streamable HTTP Mode (with OAuth - requires Google credentials)
npm run dev:oauth

# Vercel Serverless Development (test as serverless functions)
npm run dev:vercel

# Build the project
npm run build

# Production STDIO mode
npm start

# Type checking
npm run typecheck

# Linting
npm run lint

# Unit tests with coverage
npm run test:unit

# Integration / CI suite
npm run test:integration

# Test dual-mode functionality
npm run test:dual-mode

# Observability features
npm run otel:start      # Start Grafana OTEL-LGTM stack (requires Docker)
npm run otel:stop       # Stop observability stack
npm run otel:logs       # View observability stack logs

# API Documentation
npm run docs:validate   # Validate OpenAPI specification
npm run docs:preview    # Preview docs locally with Redocly
npm run docs:build      # Build static Redoc HTML
npm run docs:bundle     # Bundle OpenAPI spec to JSON

API Documentation

This project includes comprehensive OpenAPI 3.1 specification and interactive documentation. When running the server (development or production), access:

• 📖 /docs - Beautiful read-focused documentation (Redoc)
• 🧪 /api-docs - Interactive API testing with OAuth support (Swagger UI)
• 📄 /openapi.yaml - OpenAPI specification (YAML format)
• 📄 /openapi.json - OpenAPI specification (JSON format)

Example: Start the server and visit http://localhost:3000/docs

npm run dev:http
# Open http://localhost:3000/docs in your browser

The documentation includes:

• All HTTP endpoints with request/response examples
• OAuth 2.0 authentication flows with interactive testing
• JSON-RPC 2.0 MCP protocol endpoints
• Dynamic Client Registration (RFC 7591/7592)
• OAuth Discovery metadata (RFC 8414/9728)
• Admin and monitoring endpoints

Development Guides

• 📘 Traditional Development: Use the commands above for STDIO/Streamable HTTP modes
• 🛠️ Vercel Local Development - Complete guide for developing with Vercel locally
• 🏗️ System Architecture - Detailed architecture overview with diagrams
• 🚀 Dual-Mode Operation Guide - Understanding STDIO and HTTP transport modes
• 🔐 OAuth Setup Guide - Configure OAuth authentication
• 🔓 OAuth Dynamic Client Registration - Automatic client registration (RFC 7591)
• 📊 Observability Setup - Structured logging and OpenTelemetry integration

Docker Deployment

Single Instance Deployment

# Build production Docker image
npm run run:docker:build

# Run Docker container with multi-provider OAuth
npm run run:docker            # Uses .env.oauth (supports Google, GitHub, Microsoft)

# Manual Docker commands
docker build -t mcp-typescript-simple:latest .
docker run --rm -p 3000:3000 --env-file .env.oauth mcp-typescript-simple:latest

Multi-Node Load Balanced Deployment

For production-grade horizontal scaling with Redis session persistence:

# Start 3 MCP servers + Redis + Nginx load balancer
docker-compose --profile loadbalanced up -d

# Test the load-balanced deployment
curl http://localhost:8080/health

Features:

• 3 MCP server instances with round-robin load balancing
• Redis-backed session persistence and recovery
• Session handoff across instances
• OpenTelemetry observability integration

📘 Multi-Node Deployment Guide - Complete guide for horizontally scaled deployment with testing instructions

Progressive Production Fidelity Testing

Test with increasing production-like fidelity:

Level 1: Development Mode (TypeScript via tsx)

npm run dev:oauth

Level 2: Docker Container

npm run run:docker:build
npm run run:docker:google

Level 3: Vercel Serverless Automatic deployment via GitHub Actions on PR merge to main.

Project Structure

src/
├── index.ts                    # Main MCP server implementation
├── auth/                       # OAuth authentication system
├── config/                     # Environment and configuration management
├── llm/                        # Multi-LLM provider integration
├── observability/              # Structured logging and OpenTelemetry integration
├── server/                     # HTTP and MCP server implementations
├── session/                    # Session management
├── tools/                      # MCP tool implementations
└── transport/                  # Transport layer abstractions
api/                            # Vercel serverless functions
├── mcp.ts                      # Main MCP protocol endpoint
├── health.ts                   # Health check and status
├── auth.ts                     # OAuth authentication endpoints
└── admin.ts                    # Administration and metrics
test/
├── unit/                       # Unit tests (mirrors src/ structure)
├── integration/                # Integration tests
└── system/                     # End-to-end system tests
tools/                          # Manual development and testing utilities
├── interactive-client.ts       # Interactive MCP client
├── remote-http-client.ts       # Remote HTTP MCP client
├── test-oauth.ts               # OAuth flow testing
└── manual/                     # Manual testing scripts
docs/                           # Deployment and architecture documentation
examples/                       # Usage examples and demonstrations
.github/workflows/              # GitHub Actions CI/CD pipeline
build/                          # Compiled TypeScript output
Dockerfile                      # Container configuration
vercel.json                     # Vercel deployment configuration

Testing

Testing Strategy

This project uses a comprehensive testing approach with multiple layers:

• Unit Tests: Individual component testing (test/unit/)
• Integration Tests: Component interaction testing (test/integration/)
• System Tests: End-to-end deployment validation (test/system/)

System Testing

End-to-end system tests validate the complete deployed application. See test/system/README.md for detailed documentation.

# Run against local development server
npm run test:system:local

# Run against Docker container
npm run test:system:docker

# Run against Vercel preview deployment
npm run test:system:preview

# Run against production deployment
npm run test:system:production

System tests cover:

• Health & Configuration: Deployment validation and environment detection
• Authentication: OAuth provider configuration and security
• MCP Protocol: JSON-RPC compliance and tool discovery
• Tool Functionality: Basic tools and LLM integration testing

CI/CD Testing (Regression Testing)

Primary command for GitHub Actions and automated testing:

# Complete regression test suite - USE THIS FOR CI/CD
npm run test:ci

# Alternative: Full validation including build
npm run validate

The test:ci command runs:

• TypeScript compilation
• Type checking
• Code linting
• MCP server startup validation
• MCP protocol compliance
• All tool functionality tests
• Error handling verification
• Docker build test (if Docker available)

Development Testing

Unit tests live under test/unit/ (mirroring src/** paths, e.g. test/unit/config/environment.test.ts) and feed npm run test:unit; integration suites live under test/integration/ and are exercised by npm run test:integration.

# Individual test commands
npm run test:mcp        # MCP-specific functionality tests
npm run test:interactive # Interactive client testing
npm run typecheck       # TypeScr