# Deployment Guide
## Overview
This guide covers deploying the YouTube KB MCP server to Vercel and publishing the Claude Code plugin.
---
## Architecture Recap
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Supabase │◄───►│ Vercel │◄───►│ Claude Code │
│ (Database) │ │ (MCP Server) │ │ (Plugin) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
pgvector StreamableHTTP .mcp.json
```
---
## Part 1: MCP Server Deployment (Vercel)
### Prerequisites
- GitHub account
- Vercel account (free)
- Node.js 20+
- pnpm (recommended)
### Step 1: Prepare Repository
```bash
# Clone or create the server package
cd packages/server
# Ensure package.json is correct
cat package.json
# Should show name: "@youtube-kb/server"
# Install dependencies
pnpm install
# Build to verify no errors
pnpm build
```
### Step 2: Configure Vercel
Create `vercel.json`:
```json
{
"framework": "nextjs",
"functions": {
"app/api/mcp/route.ts": {
"maxDuration": 60,
"memory": 1024
}
},
"rewrites": [
{
"source": "/mcp",
"destination": "/api/mcp"
}
],
"headers": [
{
"source": "/api/mcp",
"headers": [
{
"key": "Access-Control-Allow-Origin",
"value": "*"
},
{
"key": "Access-Control-Allow-Methods",
"value": "GET, POST, DELETE, OPTIONS"
}
]
}
]
}
```
### Step 3: Set Environment Variables
```bash
# Install Vercel CLI
npm i -g vercel
# Login
vercel login
# Link project
vercel link
# Add environment variables
vercel env add SUPABASE_URL production
# Enter: https://xxxxx.supabase.co
vercel env add SUPABASE_ANON_KEY production
# Enter: eyJ...
vercel env add OPENAI_API_KEY production
# Enter: sk-...
```
### Step 4: Deploy
```bash
# Deploy to preview
vercel
# If preview works, deploy to production
vercel --prod
```
### Step 5: Verify Deployment
```bash
# Test the endpoint
curl https://your-project.vercel.app/api/mcp
# Should return MCP server info
# Test with MCP Inspector
npx @modelcontextprotocol/inspector
# Connect to: https://your-project.vercel.app/api/mcp
```
### Step 6: Custom Domain (Optional)
```bash
# Add custom domain
vercel domains add api.youtubkb.dev
# Configure DNS (add CNAME record)
# api.youtubkb.dev → cname.vercel-dns.com
```
---
## Part 2: Plugin Publishing
### Option A: GitHub Distribution
1. **Create Public Repository**
```bash
# Initialize repo
cd packages/plugin
git init
git remote add origin git@github.com:unisone/youtube-kb-plugin.git
# Push
git add .
git commit -m "Initial release v1.0.0"
git tag v1.0.0
git push origin main --tags
```
2. **Users Install Via**
```bash
claude plugin install github:unisone/youtube-kb-plugin
```
### Option B: Claude Marketplace (Recommended)
1. **Prepare Submission**
Ensure plugin meets requirements:
- [ ] Valid `plugin.json` with all fields
- [ ] README.md with documentation
- [ ] No security vulnerabilities
- [ ] Tested on multiple systems
2. **Submit to Marketplace**
```bash
# Use Claude Code's submission command
claude plugin submit ./packages/plugin
```
Or submit via:
- Anthropic Developer Portal (when available)
- GitHub PR to marketplace repo (if open)
3. **Users Install Via**
```bash
claude plugin install youtube-kb
```
### Option C: npm Package
1. **Prepare package.json**
```json
{
"name": "@youtube-kb/plugin",
"version": "1.0.0",
"files": [
".claude-plugin",
".mcp.json",
"skills",
"commands",
"README.md"
]
}
```
2. **Publish**
```bash
npm publish --access public
```
3. **Users Install Via**
```bash
npm install -g @youtube-kb/plugin
claude plugin install @youtube-kb/plugin
```
---
## Part 3: CI/CD Setup
### GitHub Actions Workflow
Create `.github/workflows/deploy.yml`:
```yaml
name: Deploy
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v2
with:
version: 8
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'pnpm'
- run: pnpm install
- run: pnpm test
- run: pnpm lint
deploy-server:
needs: test
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: amondnet/vercel-action@v25
with:
vercel-token: ${{ secrets.VERCEL_TOKEN }}
vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
vercel-args: '--prod'
working-directory: ./packages/server
release-plugin:
needs: test
if: startsWith(github.ref, 'refs/tags/v')
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Create Release
uses: softprops/action-gh-release@v1
with:
files: |
packages/plugin/**
generate_release_notes: true
```
### Environment Secrets
Add to GitHub repository settings:
- `VERCEL_TOKEN`
- `VERCEL_ORG_ID`
- `VERCEL_PROJECT_ID`
- `NPM_TOKEN` (if publishing to npm)
---
## Part 4: Monitoring
### Vercel Analytics
Enable in Vercel dashboard:
- Real-time logs
- Function invocations
- Latency metrics
- Error tracking
### Custom Monitoring (Optional)
Add to MCP server:
```typescript
// src/utils/metrics.ts
export function logMetric(name: string, value: number, tags?: Record<string, string>) {
// Send to your analytics service
console.log(JSON.stringify({
metric: name,
value,
tags,
timestamp: new Date().toISOString(),
}));
}
// Usage in tools
const start = Date.now();
const results = await search(query);
logMetric('search_latency_ms', Date.now() - start, { domain });
```
### Uptime Monitoring
Options:
- Vercel built-in monitoring
- UptimeRobot (free)
- Better Uptime
- Checkly
```bash
# Simple health check endpoint
# app/api/health/route.ts
export function GET() {
return Response.json({ status: 'ok', timestamp: new Date().toISOString() });
}
```
---
## Part 5: Rollback Procedures
### Vercel Rollback
```bash
# List deployments
vercel ls
# Rollback to previous deployment
vercel rollback [deployment-url]
```
### Database Rollback
```bash
# Supabase point-in-time recovery (Pro tier)
# Or restore from daily backup via dashboard
```
### Plugin Rollback
```bash
# Users can install specific version
claude plugin install youtube-kb@0.9.0
# Or from GitHub tag
claude plugin install github:unisone/youtube-kb-plugin#v0.9.0
```
---
## Part 6: Security Checklist
### Pre-Deployment
- [ ] No secrets in code
- [ ] Environment variables configured
- [ ] HTTPS enforced
- [ ] Input validation implemented
- [ ] SQL injection prevented (parameterized queries)
### Post-Deployment
- [ ] Test all endpoints
- [ ] Verify CORS settings
- [ ] Check error handling
- [ ] Monitor for anomalies
### Ongoing
- [ ] Regular dependency updates
- [ ] Security scanning enabled
- [ ] Access logs reviewed
- [ ] Rate limiting in place (if needed)
---
## Part 7: Cost Management
### Vercel Free Tier Limits
| Resource | Limit |
|----------|-------|
| Bandwidth | 100 GB/month |
| Function invocations | 100,000/month |
| Function duration | 10s (Hobby), 60s (Pro) |
### Supabase Free Tier Limits
| Resource | Limit |
|----------|-------|
| Database | 500 MB |
| Storage | 1 GB |
| Bandwidth | 2 GB |
| Auth users | 50,000 |
### OpenAI Costs
| Model | Cost |
|-------|------|
| text-embedding-3-small | $0.02/1M tokens |
Estimated monthly cost for 1,000 queries/day:
- ~30,000 queries × ~100 tokens = 3M tokens
- Cost: ~$0.06/month
### Cost Alerts
Set up in Vercel/Supabase dashboards:
- Alert at 80% of free tier
- Auto-pause on limit (Supabase)
---
## Deployment Checklist
### Server Deployment
- [ ] Code pushed to GitHub
- [ ] Vercel project linked
- [ ] Environment variables set
- [ ] Deploy to preview
- [ ] Test all endpoints
- [ ] Deploy to production
- [ ] Custom domain configured
- [ ] SSL verified
### Plugin Publishing
- [ ] Plugin tested locally
- [ ] README complete
- [ ] Version tagged
- [ ] Published to distribution channel
- [ ] Installation tested
### Post-Deployment
- [ ] Monitoring enabled
- [ ] Alerts configured
- [ ] Rollback tested
- [ ] Documentation updated
