fastmcp-cloud-deployment

What this skill does

# FastMCP Cloud Deployment Skill

This skill provides comprehensive deployment lifecycle management for FastMCP servers, including pre-deployment validation, local testing, post-deployment verification, environment variable checking, and deployment tracking.

## Overview

The deployment lifecycle consists of five phases:
1. **Pre-Deployment Validation** - Syntax, dependencies, configuration
2. **Local Testing** - STDIO and HTTP transport testing
3. **Environment Verification** - Environment variable validation
4. **Deployment** - To FastMCP Cloud, HTTP, or STDIO
5. **Post-Deployment Verification** - Health checks, endpoint testing

## Available Scripts

### 1. Pre-Deployment Validation

**Script**: `scripts/validate-server.sh <server-path>`

**Purpose**: Validates server is ready for deployment

**Checks**:
- Server file exists (server.py, server.ts, index.ts)
- Syntax validation (Python/TypeScript)
- Dependencies declared (requirements.txt or package.json)
- FastMCP dependency included
- fastmcp.json configuration valid
- No hardcoded secrets
- Environment configuration present
- .gitignore properly configured

**Usage**:
```bash
# Validate current directory
./scripts/validate-server.sh .

# Validate specific server
./scripts/validate-server.sh /path/to/server

# Verbose mode
VERBOSE=1 ./scripts/validate-server.sh .
```

**Exit Codes**:
- `0`: Validation passed (may have warnings)
- `1`: Validation failed (must fix before deployment)

**Example Output**:
```
=== FastMCP Server Pre-Deployment Validation ===
✓ Found Python server file: server.py
✓ Python syntax is valid
✓ FastMCP dependency declared in requirements.txt
✓ fastmcp.json has valid JSON syntax
✓ Server name: my-server
⚠ Found 2 unpinned dependencies
✓ No obvious hardcoded secrets detected

Results: 12 passed, 0 failed, 1 warnings
✓ Server passed validation - ready for deployment
```

### 2. Local Testing

**Script**: `scripts/test-local.sh <server-path>`

**Purpose**: Tests server locally before deployment

**Tests**:
- Module imports successful
- STDIO transport working
- HTTP transport responding
- Environment variables configured
- Health endpoints (if configured)
- Server stability (runs for 5+ seconds)

**Usage**:
```bash
# Test with default transport (STDIO)
./scripts/test-local.sh .

# Test both STDIO and HTTP
TRANSPORT=both ./scripts/test-local.sh .

# Test HTTP only on custom port
TRANSPORT=http PORT=3000 ./scripts/test-local.sh .

# Longer test duration
TEST_DURATION=30 ./scripts/test-local.sh .
```

**Environment Variables**:
- `TRANSPORT`: `stdio`, `http`, or `both` (default: `stdio`)
- `PORT`: Port for HTTP testing (default: `8000`)
- `TEST_DURATION`: Test duration in seconds (default: `10`)

**Example Output**:
```
=== FastMCP Server Local Testing ===
✓ Python imports successful
✓ Server started successfully (PID: 12345)
✓ Server is producing MCP protocol messages
✓ HTTP server started (PID: 12346)
✓ Health endpoint responding

Results: 12 passed, 0 failed, 0 warnings
✓ Server tests passed - ready for deployment testing
```

### 3. Environment Variable Check

**Script**: `scripts/check-env-vars.sh <server-path>`

**Purpose**: Validates environment variables are properly configured

**Checks**:
- .env.example exists and documents variables
- Required vs optional variables identified
- Local .env file has all required variables
- fastmcp.json env declarations match .env.example
- .env in .gitignore (security)
- No placeholder values in production

**Usage**:
```bash
# Check default .env file
./scripts/check-env-vars.sh .

# Check specific env file
ENV_FILE=.env.production ./scripts/check-env-vars.sh .

# Check only required variables
CHECK_MODE=required ./scripts/check-env-vars.sh .
```

**Environment Variables**:
- `ENV_FILE`: Environment file to check (default: `.env`)
- `CHECK_MODE`: `all`, `required`, or `optional` (default: `all`)

**Example Output**:
```
=== FastMCP Server Environment Variable Check ===
✓ Found .env.example template
ℹ Required: API_KEY
ℹ Optional: LOG_LEVEL (default: INFO)
✓ All required variables are set
✓ All fastmcp.json variables documented in .env.example
✓ .env files properly excluded from git

Results: 6 passed, 0 failed, 0 warnings
✓ Environment configuration validated
```

### 4. Post-Deployment Verification

**Script**: `scripts/verify-deployment.sh <deployment-url>`

**Purpose**: Verifies deployed server is accessible and functioning

**Checks**:
- DNS resolution working
- Server is reachable
- Health endpoint responding
- MCP endpoint accepting requests
- Valid JSON-RPC responses
- Tools are available
- SSL/TLS certificate valid (HTTPS)
- Response time acceptable

**Usage**:
```bash
# Verify FastMCP Cloud deployment
./scripts/verify-deployment.sh https://my-server.fastmcp.app/mcp

# Verify HTTP deployment
./scripts/verify-deployment.sh https://my-server.example.com/mcp

# Custom timeout and retries
MAX_RETRIES=10 TIMEOUT=60 ./scripts/verify-deployment.sh https://my-server.com/mcp

# Verbose output
VERBOSE=1 ./scripts/verify-deployment.sh https://my-server.com/mcp
```

**Environment Variables**:
- `MAX_RETRIES`: Maximum retry attempts (default: `5`)
- `RETRY_DELAY`: Seconds between retries (default: `10`)
- `TIMEOUT`: Request timeout in seconds (default: `30`)
- `VERBOSE`: Show detailed output (default: `0`)

**Example Output**:
```
=== FastMCP Server Deployment Verification ===
✓ DNS resolved: my-server.fastmcp.app -> 104.21.45.123
✓ Server is reachable
✓ Health endpoint available at /health (HTTP 200)
✓ MCP endpoint responding (HTTP 200)
✓ Valid JSON-RPC response received
✓ Server provides 3 tool(s)
✓ Valid SSL/TLS certificate
✓ Response time excellent (<1s)

Results: 11 passed, 0 failed, 0 warnings
✓ Deployment verified successfully
```

## Templates

### Deployment Tracking Template

**File**: `templates/.fastmcp-deployments.json`

**Purpose**: Track all server deployments with metadata

**Structure**:
```json
{
  "version": "1.0.0",
  "deployments": [
    {
      "id": "deployment-uuid",
      "serverName": "my-server",
      "environment": "production",
      "target": "fastmcp-cloud",
      "url": "https://my-server.fastmcp.app/mcp",
      "status": "active",
      "deployedAt": "2025-01-15T10:30:00Z",
      "version": "1.0.0",
      "validationResults": {
        "preDeployment": {...},
        "postDeployment": {...}
      }
    }
  ]
}
```

**Usage**: Copy template and update with actual deployment details

### Deployment Checklist

**File**: `templates/deployment-checklist.md`

**Purpose**: Step-by-step checklist for successful deployments

**Sections**:
- Pre-Deployment Checklist (code quality, dependencies, config)
- Deployment Checklist (by target: FastMCP Cloud, HTTP, STDIO)
- Post-Deployment Verification (accessibility, functionality, performance)
- Deployment Tracking (record keeping)
- Rollback Plan (if issues occur)

**Usage**: Copy checklist for each deployment, check off items as completed

### Environment Variables Documentation

**File**: `templates/env-var-template.md`

**Purpose**: Template for documenting all environment variables

**Sections**:
- Required Variables (must be set)
- Optional Variables (have defaults)
- Development-Only Variables
- Environment-Specific Configurations
- Security Best Practices
- Troubleshooting

**Usage**: Copy template to server repo as `ENV_VARS.md`, customize with actual variables

## Examples

### Successful Deployment Workflow

**File**: `examples/successful-deployment.md`

**Contents**: Complete end-to-end deployment example including:
- Pre-deployment validation output
- Environment variable checking
- Local testing results
- Deployment process
- Post-deployment verification
- Deployment tracking record
- Post-deployment monitoring
- Lessons learned

**Use Case**: Reference for first-time deployments or training

### Troubleshooting Guide

**File**: `examples/troubleshooting.md`

**Contents**: Common issues and solutions including:
- Pre-deployment validation failures
- Environm