# TypeScript MCP Server Template

A comprehensive **TypeScript MCP Server Template** following the [official MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) best practices, built with **Fastify** and providing tools, resources, and prompts.

**[📖 README en Español](README_ES.md)** - 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](../../generate).
- **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

```bash
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:

```bash
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):**
```bash
npm run dev
```

**STDIO Mode (for CLI clients like Claude Desktop):**
```bash
npm run dev:stdio
```

**Debug Mode (with detailed logging):**
```bash
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

```bash
# 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:**
```bash
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

```bash
curl http://localhost:3000/health
```

**Expected response:**
```json
{
  "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:

```bash
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:**
```bash
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:**
```bash
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:

```typescript
// 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:**
```bash
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:**
```bash
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:**
```bash
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](https://github.com/modelcontextprotocol/typescript-sdk):

- ✅ **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

```bash
# 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](https://www.conventionalcommits.org/):

- `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:
```typescript
{
  name: "myTool",
  description: "My custom tool",
  inputSchema: {
    type: "object",
    properties: {
      param: { type: "string", description: "Parameter description" }
    },
    required: ["param"]
  }
}
```

2. **Handle tool execution** in `tools/call` handler:
```typescript
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

```bash
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

```bash
# 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

```bash
# 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:

- **[Docker Troubleshooting Guide](DOCKER_TROUBLESHOOTING.md)** - Common issues and solutions
- **[Docker Best Practices](DOCKER_BEST_PRACTICES.md)** - Best practices for Node.js containerization

**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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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:
```bash
DEBUG=mcp:* npm run dev
```

**What this provides:** Detailed logging for troubleshooting MCP issues

### Performance Monitoring

The health endpoint provides real-time metrics:
```bash
curl http://localhost:3000/health | jq
```

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

## 📚 Learn More

- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [Official TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [MCP Server Examples](https://github.com/modelcontextprotocol)
- [Fastify Documentation](https://fastify.dev/)
- [Git Flow Documentation](https://nvie.com/posts/a-successful-git-branching-model/)

## 📝 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**:  
   - Click [Use this template](../../generate) and start building.


---

**Built following [Official MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) best practices**