mcpengine/docs/DEPLOYMENT.md

# Deployment Guide

Guide to deploying MCPEngine servers in various environments.

## Local Development

### Claude Desktop

1. Build the server:
```bash
cd servers/servicetitan
npm install && npm run build
```

2. Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "servicetitan": {
      "command": "node",
      "args": ["/absolute/path/to/mcpengine/servers/servicetitan/dist/index.js"],
      "env": {
        "SERVICETITAN_API_KEY": "your_api_key",
        "SERVICETITAN_TENANT_ID": "your_tenant"
      }
    }
  }
}
```

3. Restart Claude Desktop

### Cursor IDE

Add to `.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "servicetitan": {
      "command": "node",
      "args": ["../mcpengine/servers/servicetitan/dist/index.js"],
      "env": {
        "SERVICETITAN_API_KEY": "your_key"
      }
    }
  }
}
```

---

## Production Deployment

### Docker

Create `Dockerfile`:
```dockerfile
FROM node:20-slim

WORKDIR /app

COPY servers/servicetitan/package.json .
RUN npm install

COPY servers/servicetitan/src ./src
COPY servers/servicetitan/tsconfig.json .

RUN npm run build

CMD ["node", "dist/index.js"]
```

Build and run:
```bash
docker build -t mcpengine-servicetitan .
docker run -e SERVICETITAN_API_KEY=your_key mcpengine-servicetitan
```

### Docker Compose (Multiple Servers)

`docker-compose.yml`:
```yaml
version: '3.8'

services:
  servicetitan:
    build:
      context: .
      dockerfile: servers/servicetitan/Dockerfile
    environment:
      - SERVICETITAN_API_KEY=${SERVICETITAN_API_KEY}
    restart: unless-stopped

  mailchimp:
    build:
      context: .
      dockerfile: servers/mailchimp/Dockerfile
    environment:
      - MAILCHIMP_API_KEY=${MAILCHIMP_API_KEY}
    restart: unless-stopped
```

Run:
```bash
docker-compose up -d
```

---

## Cloud Deployment

### Railway

1. Connect GitHub repo
2. Add environment variables
3. Deploy:
```bash
railway up
```

### Heroku

```bash
heroku create mcpengine-servicetitan
heroku config:set SERVICETITAN_API_KEY=your_key
git push heroku main
```

### Vercel (Serverless)

Create `vercel.json`:
```json
{
  "builds": [
    {
      "src": "servers/servicetitan/dist/index.js",
      "use": "@vercel/node"
    }
  ],
  "routes": [
    {
      "src": "/",
      "dest": "servers/servicetitan/dist/index.js"
    }
  ]
}
```

Deploy:
```bash
vercel --prod
```

---

## Managed Hosting (Coming Soon)

MCPEngine managed hosting will offer:
- One-click deployment
- Auto-scaling
- 99.9% uptime SLA
- Monitoring & alerts
- Automatic updates

**Pricing:**
- Starter: $49/month (5 servers)
- Pro: $99/month (15 servers)
- Enterprise: Custom pricing

Sign up for early access at [mcpengine.com](https://mcpengine.com)

---

## Security Best Practices

### Never Commit Secrets
Use environment variables or secret managers:
```bash
# Good
export SERVICETITAN_API_KEY=$(cat secrets/servicetitan.key)

# Bad (never do this)
const API_KEY = "sk_live_abc123";
```

### Use Secret Managers

**AWS Secrets Manager:**
```bash
aws secretsmanager get-secret-value --secret-id mcpengine/servicetitan
```

**HashiCorp Vault:**
```bash
vault kv get secret/mcpengine/servicetitan
```

### Rotate Keys Regularly
Set calendar reminders to rotate API keys every 90 days.

### Restrict Permissions
Only grant the minimum required API scopes.

---

## Monitoring

### Health Checks

Add to your server:
```typescript
server.setRequestHandler('health', async () => {
  return {
    status: 'healthy',
    timestamp: new Date().toISOString(),
  };
});
```

### Logging

Use structured logging:
```typescript
console.error(JSON.stringify({
  level: 'info',
  tool: 'get_contacts',
  duration_ms: 150,
  timestamp: new Date().toISOString(),
}));
```

### Metrics

Track:
- Request count
- Error rate
- Response time
- API quota usage

---

## Troubleshooting

### Server won't start
```bash
# Check logs
npm start 2>&1 | tee server.log

# Verify environment variables
env | grep SERVICETITAN

# Test TypeScript compilation
npm run build
```

### API authentication fails
- Verify API key is valid
- Check key has required permissions
- Confirm base URL is correct

### Claude Desktop doesn't see server
- Restart Claude Desktop
- Check config file path
- Verify JSON syntax
- Look at Claude logs: `~/Library/Logs/Claude/`

---

## Performance Tuning

### Connection Pooling
Reuse HTTP connections:
```typescript
const agent = new https.Agent({
  keepAlive: true,
  maxSockets: 50,
});
```

### Caching
Cache frequently accessed data:
```typescript
const cache = new Map();
const TTL = 300000; // 5 minutes
```

### Rate Limiting
Respect API limits:
```typescript
const rateLimiter = new Bottleneck({
  maxConcurrent: 10,
  minTime: 100,
});
```

---

## Updates

### Manual Updates
```bash
cd servers/servicetitan
git pull origin main
npm install
npm run build
# Restart server
```

### Auto-Updates (Docker)
Use Watchtower:
```yaml
watchtower:
  image: containrrr/watchtower
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock
  command: --interval 3600
```

---

## Support

- **Deployment issues:** [GitHub Issues](https://github.com/yourusername/mcpengine/issues)
- **Enterprise support:** enterprise@mcpengine.com
- **Community:** [Discord](https://discord.gg/mcpengine)