# MCP Memory Service - Deployment Guide

Complete guide for deploying the MCP Memory Service with Clerk OAuth authentication to both development and production environments.

## Table of Contents

- [Prerequisites](#prerequisites)
- [Environment Setup](#environment-setup)
- [Local Development](#local-development)
- [Production Deployment](#production-deployment)
- [Configuration Reference](#configuration-reference)
- [Security Checklist](#security-checklist)
- [Troubleshooting](#troubleshooting)

---

## Prerequisites

### Required Services

1. **Turso Database** (https://turso.tech/)
   - Create a LibSQL database
   - Generate authentication token
   - Note the database URL

2. **OpenAI API** (https://platform.openai.com/)
   - Create an API key for embeddings
   - Ensure sufficient credits

3. **Clerk Account** (https://dashboard.clerk.com/)
   - Development keys for testing
   - Production keys for deployment
   - Webhook secret for event handling

4. **Vercel Account** (https://vercel.com/)
   - Install Vercel CLI: `npm install -g vercel@latest`
   - Authenticate: `vercel login`

### Development Tools

- Node.js >= 18.0.0
- npm or yarn package manager
- Git for version control

---

## Environment Setup

### 1. Development Environment

Copy `.env.example` to `.env` or `.env.development`:

```bash
cp .env.example .env.development
```

Update the following values in `.env.development`:

```bash
# Database (from Turso)
TURSO_URL=libsql://your-database.turso.io
TURSO_AUTH_TOKEN=your-turso-auth-token

# OpenAI (for embeddings)
OPENAI_API_KEY=sk-proj-your-openai-api-key

# Clerk Development Keys
CLERK_SECRET_KEY=sk_test_your-dev-secret-key
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_your-dev-publishable-key

# Development Settings
NODE_ENV=development
LOG_LEVEL=debug
MCP_DEBUG=1
REMOTE_MCP_PORT=3003
CORS_ORIGIN=*
```

### 2. Production Environment

Create `.env.production` for production settings:

```bash
cp .env.example .env.production
```

Update with production values:

```bash
# Database
TURSO_URL=libsql://your-database.turso.io
TURSO_AUTH_TOKEN=your-turso-auth-token

# OpenAI
OPENAI_API_KEY=sk-proj-your-openai-api-key

# Clerk Production Keys
CLERK_SECRET_KEY=sk_live_your-production-secret-key
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_your-production-publishable-key
CLERK_WEBHOOK_SECRET=whsec_your-webhook-secret

# Production Settings
NODE_ENV=production
LOG_LEVEL=info
MCP_DEBUG=0
CORS_ORIGIN=https://ai-memory.app,https://www.ai-memory.app
ALLOWED_ORIGINS=https://ai-memory.app,https://www.ai-memory.app,https://clerk.ai-memory.app
RATE_LIMIT_REQUESTS_PER_MINUTE=100
ALLOW_DEV_AUTH=false
```

---

## Local Development

### Starting the Development Server

1. **Install dependencies:**
   ```bash
   npm install
   ```

2. **Build the project:**
   ```bash
   npm run build
   ```

3. **Start the remote MCP server:**
   ```bash
   npm run mcp-server-remote
   ```

   The server will start on `http://localhost:3003`

### Testing Locally

1. **Health check:**
   ```bash
   curl http://localhost:3003/health
   ```

2. **Test with authentication:**
   ```bash
   # Get a session token from Clerk
   export CLERK_TOKEN="your-clerk-session-token"
   
   # Test MCP initialize
   curl -X POST http://localhost:3003/mcp \
     -H "Authorization: Bearer $CLERK_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}'
   ```

3. **Run test suite:**
   ```bash
   npm test
   ```

---

## Production Deployment

### Method 1: Automated Deployment Script

```bash
# 1. Set up Vercel environment variables (one-time setup)
npm run setup:vercel

# 2. Deploy to production
npm run deploy:vercel production
```

### Method 2: Manual Vercel Deployment

#### Step 1: Link Vercel Project

```bash
vercel link
```

Follow the prompts to link or create a Vercel project.

#### Step 2: Set Environment Variables

Use Vercel dashboard or CLI to set environment variables:

```bash
# Database
vercel env add TURSO_URL production
vercel env add TURSO_AUTH_TOKEN production

# OpenAI
vercel env add OPENAI_API_KEY production

# Clerk (Production Keys)
vercel env add CLERK_SECRET_KEY production
vercel env add NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY production
vercel env add CLERK_WEBHOOK_SECRET production

# Configuration
vercel env add NODE_ENV production
vercel env add LOG_LEVEL production
vercel env add MCP_DEBUG production
vercel env add CORS_ORIGIN production
vercel env add ALLOWED_ORIGINS production
vercel env add RATE_LIMIT_REQUESTS_PER_MINUTE production
```

#### Step 3: Deploy

```bash
# Deploy to production
vercel --prod

# Or deploy to preview
vercel
```

### Post-Deployment Steps

1. **Verify deployment:**
   ```bash
   curl https://your-deployment.vercel.app/health
   ```

2. **Configure Clerk webhook:**
   - Go to Clerk Dashboard > Webhooks
   - Add endpoint: `https://your-deployment.vercel.app/api/auth/webhook`
   - Copy webhook signing secret
   - Update `CLERK_WEBHOOK_SECRET` in Vercel

3. **Test production endpoints:**
   ```bash
   npm run test:vercel
   ```

4. **Monitor deployment:**
   - Check Vercel dashboard for logs
   - Monitor error rates
   - Verify CORS headers

---

## Configuration Reference

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `NODE_ENV` | Yes | `development` | Environment mode |
| `TURSO_URL` | Yes | - | Turso database URL |
| `TURSO_AUTH_TOKEN` | Yes | - | Turso authentication token |
| `OPENAI_API_KEY` | Yes | - | OpenAI API key for embeddings |
| `CLERK_SECRET_KEY` | Yes | - | Clerk secret key |
| `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` | Yes | - | Clerk publishable key |
| `CLERK_WEBHOOK_SECRET` | Production | - | Clerk webhook signing secret |
| `LOG_LEVEL` | No | `info` | Logging level (debug/info/warn/error) |
| `MCP_DEBUG` | No | `0` | Enable MCP debug logging |
| `REMOTE_MCP_PORT` | No | `3003` | Server port |
| `REMOTE_MCP_HOST` | No | `0.0.0.0` | Server bind address |
| `CORS_ORIGIN` | No | `*` | CORS allowed origins |
| `ALLOWED_ORIGINS` | No | - | Comma-separated allowed origins |
| `RATE_LIMIT_REQUESTS_PER_MINUTE` | No | `100` | Rate limit per user |
| `RATE_LIMIT_WINDOW_MS` | No | `60000` | Rate limit window |
| `SESSION_TIMEOUT_MINUTES` | No | `120` | Session timeout |
| `ALLOW_DEV_AUTH` | No | `false` | Allow dev auth bypass |

### CORS Configuration

**Development:**
```bash
CORS_ORIGIN=*
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3003
```

**Production:**
```bash
CORS_ORIGIN=https://ai-memory.app,https://www.ai-memory.app
ALLOWED_ORIGINS=https://ai-memory.app,https://www.ai-memory.app,https://clerk.ai-memory.app
```

### Rate Limiting

**Development (Relaxed):**
```bash
RATE_LIMIT_REQUESTS_PER_MINUTE=1000
RATE_LIMIT_WINDOW_MS=60000
```

**Production (Strict):**
```bash
RATE_LIMIT_REQUESTS_PER_MINUTE=100
RATE_LIMIT_WINDOW_MS=60000
```

---

## Security Checklist

### Pre-Deployment Security Checks

- [ ] All environment variables are set in Vercel dashboard (not in code)
- [ ] `.env` files are in `.gitignore` (should already be there)
- [ ] Production uses `ALLOW_DEV_AUTH=false`
- [ ] CORS origins are restricted to production domains
- [ ] Rate limiting is enabled and properly configured
- [ ] Clerk webhook secret is configured
- [ ] HTTPS is enforced (automatic with Vercel)
- [ ] Security headers are enabled in `vercel.json`

### Security Headers (Configured in vercel.json)

- `X-Content-Type-Options: nosniff`
- `X-Frame-Options: DENY`
- `X-XSS-Protection: 1; mode=block`
- `Strict-Transport-Security: max-age=31536000`
- `Content-Security-Policy` with restricted sources
- `Permissions-Policy` with disabled features

### Authentication Flow

1. Client requests authentication from Clerk
2. Client receives session token
3. Client includes token in `Authorization: Bearer <token>` header
4. Server validates token with Clerk
5. Server creates session and allows access

### Rate Limiting

- Per-user rate limiting using email as key
- Token bucket algorithm for smooth rate limiting
- Returns `429 Too Many Requests` when exceeded
- Includes `Retry-After` header

---

## Troubleshooting

### Common Issues

#### 1. Authentication Errors

**Symptom:** 401 Unauthorized errors

**Solutions:**
- Verify Clerk keys are correct for environment (dev vs prod)
- Check Authorization header format: `Bearer <token>`
- Ensure Clerk session is valid and not expired
- Verify `CLERK_SECRET_KEY` is set correctly

#### 2. CORS Errors

**Symptom:** Browser blocks requests with CORS error

**Solutions:**
- Check `CORS_ORIGIN` includes your domain
- Verify `ALLOWED_ORIGINS` is set correctly
- Ensure request includes credentials if needed
- Check Vercel deployment has correct CORS headers

#### 3. Rate Limiting

**Symptom:** 429 Too Many Requests errors

**Solutions:**
- Check `RATE_LIMIT_REQUESTS_PER_MINUTE` setting
- Verify rate limiter is using correct user key
- Implement exponential backoff in client
- Check `Retry-After` header for wait time

#### 4. Database Connection Errors

**Symptom:** Failed to connect to Turso database

**Solutions:**
- Verify `TURSO_URL` and `TURSO_AUTH_TOKEN` are correct
- Check Turso database is active
- Ensure auth token has not expired
- Verify network connectivity to Turso

#### 5. Embedding Generation Failures

**Symptom:** Memories stored without embeddings

**Solutions:**
- Verify `OPENAI_API_KEY` is valid
- Check OpenAI account has sufficient credits
- Monitor API rate limits
- Run `update_missing_embeddings` tool to regenerate

### Debug Mode

Enable debug logging in development:

```bash
LOG_LEVEL=debug
MCP_DEBUG=1
ENABLE_REQUEST_LOGGING=true
```

### Monitoring

**Health Check Endpoint:**
```bash
curl https://your-deployment.vercel.app/health
```

**Session Monitoring:**
```bash
curl https://your-deployment.vercel.app/health | jq .activeSessions
```

**Vercel Logs:**
```bash
vercel logs
```

---

## Support

For issues and questions:

1. Check this deployment guide
2. Review [CLAUDE.md](./CLAUDE.md) for project details
3. Check Vercel deployment logs
4. Verify environment variables in Vercel dashboard
5. Test with development environment first

---

## Deployment Checklist

### Pre-Deployment

- [ ] All tests passing (`npm test`)
- [ ] Type checking successful (`npm run type-check`)
- [ ] Linting clean (`npm run lint`)
- [ ] Build successful (`npm run build`)
- [ ] Environment variables configured
- [ ] Security checklist completed

### Deployment

- [ ] Deployed to Vercel
- [ ] Health check passing
- [ ] API endpoints responding
- [ ] Authentication working
- [ ] CORS headers correct
- [ ] Rate limiting active

### Post-Deployment

- [ ] Clerk webhook configured
- [ ] Production domains added to CORS
- [ ] Monitoring set up
- [ ] Error tracking enabled
- [ ] Documentation updated
- [ ] Team notified

---

**Last Updated:** 2025-10-01
**Version:** 1.1.2
