ClipSense MCP Server

# Handoff Document - Session 2025-12-05 **Date**: December 5, 2025 **Context**: Continued session after context limit **Previous Handoff**: Session context was lost, conversation continued from summary --- ## Session Overview This session focused on: 1. Understanding complete end-to-end ClipSense functionality 2. Clarifying payment upgrade flow and API key management 3. Market research on MCP servers and mobile debugging tools 4. Competitive analysis and ecosystem comparison 5. Identifying ClipSense's unique market positioning --- ## Critical Context Corrections ### ✅ Website Status (CORRECTED) **Initial Error**: Stated that clipsense.app website doesn't exist and needs to be built **User Correction**: Website ALREADY EXISTS at clipsense.app, domain purchased **Current Reality**: - Website: https://clipsense.app (live) - Frontend: Next.js at `/Users/jerlitaburanday/clipsense/frontend/` - Pages: Homepage, Upload, Auth, History, Settings - Authentication: Clerk integration - Backend API: https://api.clipsense.app ### ✅ API Key Management (CLARIFIED) **Confusion**: API key issuance vs regenerate/rotate features **Clarification**: 1. **Upgrade Scenario** (FREE → PRO): - User keeps SAME API key - Database updates `user.subscription_tier` from FREE to PRO - Same API key now has higher limits (3/mo → 50/mo) 2. **Regenerate Feature** (DOCUMENTED, NOT IMPLEMENTED): - Purpose: Emergency key replacement (compromised key) - Behavior: Immediately invalidates old key, issues new key - Use case: Key leaked in public repo, sharing violation 3. **Rotate Feature** (DOCUMENTED, NOT IMPLEMENTED): - Purpose: Gradual key migration - Behavior: Issues new key, old key expires in 7 days - Use case: Updating multiple CI/CD configs safely **Files**: - Implementation plan: `/Users/jerlitaburanday/clipsense/docs/CORRECTED-IMPLEMENTATION-PLAN.md:243-246` - Current API routes: `/Users/jerlitaburanday/clipsense/backend/app/api/routes/keys.py` --- ## Complete Payment Upgrade Flow (Designed) ### Current State: No Payment System - Stripe integration: ❌ Not implemented - `user.stripe_customer_id`: Always NULL - Schema exists but unused ### Designed Flow (To Be Implemented) #### Step 1: User Hits Limit ``` User in Claude Code → Makes 4th analysis request ↓ MCP Server Error: { "error": "Monthly limit reached (3/3)", "current_tier": "FREE", "upgrade_url": "https://clipsense.app/pricing", "next_tier": "PRO (50 analyses/month for $29/mo)" } ``` #### Step 2: User Upgrades on Website ``` User clicks upgrade_url ↓ Opens browser → clipsense.app/pricing ↓ User clicks "Upgrade to PRO" button ↓ Redirected to Stripe Checkout ↓ User completes payment ↓ Stripe redirects to clipsense.app/billing/success ``` #### Step 3: Webhook Updates Database ``` Stripe sends webhook to api.clipsense.app/webhooks/stripe ↓ Backend verifies webhook signature ↓ Updates database: - user.subscription_tier = "PRO" - user.stripe_customer_id = "cus_xyz123" - user.stripe_subscription_id = "sub_abc789" ↓ Resets monthly_analyses_used = 0 ``` #### Step 4: User Returns to Claude Code ``` User returns to Claude Code ↓ Makes analysis request with SAME API key ↓ Backend checks user.subscription_tier → "PRO" ↓ Limit check: 0/50 (passes) ↓ Analysis proceeds successfully ``` **Key Point**: Same API key, different limits based on `subscription_tier` --- ## Payment Gateway Research ### Stripe (RECOMMENDED) ✅ - **Pricing**: 2.9% + $0.30 per transaction - **Integration Cost**: $0 (free) - **Monthly Cost**: $0 (no subscription) - **Pros**: - Lowest fees - Best developer experience - Excellent documentation - Webhook system for automation - Customer portal (self-service billing) - **Cons**: Users handle their own tax compliance - **Implementation Time**: 1-2 days ### Paddle (Merchant of Record) - **Pricing**: 5% + $0.50 per transaction - **Integration Cost**: $0 - **Pros**: Handles all tax/VAT compliance globally - **Cons**: Higher fees, less control ### LemonSqueezy (Merchant of Record) - **Pricing**: 5-6.5% + $0.50 per transaction - **Pros**: Handles tax compliance, indie-friendly - **Cons**: Highest fees ### Braintree (PayPal) - **Pricing**: 2.59% + $0.49 per transaction - **Pros**: PayPal integration - **Cons**: More complex API than Stripe **Decision**: Stripe for lowest fees and best DX --- ## Missing Features Identified ### 1. Payment System (PRIORITY 1) **Components to Build**: #### Backend (`/backend/app/api/routes/billing.py`) ```python @router.post("/create-checkout-session") async def create_checkout_session(...) # Create Stripe checkout session # Return checkout URL @router.post("/webhooks/stripe") async def stripe_webhook(...) # Verify webhook signature # Update user.subscription_tier # Update user.stripe_customer_id # Reset monthly_analyses_used @router.post("/create-portal-session") async def create_portal_session(...) # Create Stripe customer portal session # For managing subscription, payment methods ``` #### Frontend Pages - `/pricing` - Pricing tiers with Stripe checkout buttons - `/billing/success` - Post-payment success page - `/billing/cancel` - Payment cancelled page - `/dashboard/billing` - Usage stats, manage subscription #### Environment Variables ```bash STRIPE_SECRET_KEY=sk_live_xxx STRIPE_PUBLISHABLE_KEY=pk_live_xxx STRIPE_WEBHOOK_SECRET=whsec_xxx STRIPE_PRICE_ID_PRO=price_xxx # $29/mo STRIPE_PRICE_ID_TEAM=price_xxx # $99/mo ``` ### 2. API Key Security Endpoints (PRIORITY 2) **Endpoints to Build**: #### Regenerate Key (`POST /api/v1/keys/regenerate`) ```python async def regenerate_key( current_key: str, db: AsyncSession ): # Validate current key # Mark old key as is_active=False immediately # Generate new key # Send email with new key # Return new key ``` #### Rotate Key (`POST /api/v1/keys/rotate`) ```python async def rotate_key( current_key: str, db: AsyncSession ): # Validate current key # Generate new key # Set old key expiry = NOW() + 7 days # Send email with new key + expiry notice # Return new key and expiry date ``` **Frontend Pages**: - `/dashboard/keys` - Show current key, regenerate/rotate buttons ### 3. Enhanced Error Messages (PRIORITY 3) **File**: `/Users/jerlitaburanday/clipsense/backend/app/api/routes/analyze.py:29-40` **Current Code**: ```python if user.monthly_analyses_used >= limit: raise HTTPException(429, f"Monthly limit reached ({limit})") ``` **Enhanced Version**: ```python if user.monthly_analyses_used >= limit: raise HTTPException( status_code=429, detail={ "error": "Monthly limit reached", "current_usage": f"{user.monthly_analyses_used}/{limit}", "current_tier": user.subscription_tier.value, "upgrade_url": "https://clipsense.app/pricing", "next_tier_info": { "tier": "PRO", "limit": 50, "price": "$29/month" } if user.subscription_tier == SubscriptionTier.FREE else { "tier": "TEAM", "limit": 300, "price": "$99/month" } } ) ``` --- ## Market Research Findings ### MCP Server Market - **Market Size**: $2.7B (2025) → $5.6B (2034) - **CAGR**: 8.3% - **Growth Drivers**: AI adoption, enterprise automation, integration needs **Most Popular MCP Servers** (by usage): 1. **GitHub MCP** - Repository access, PR management, code search 2. **Filesystem MCP** - File operations (most fundamental) 3. **PostgreSQL MCP** - Database queries and management 4. **Slack MCP** - Team communication integration 5. **Google Drive MCP** - Document access **Key Insight**: Utility servers (filesystem, databases) have highest adoption ### Mobile Debugging Market - **Market Size**: $1.12B (2026) → $2.68B (2033) - **CAGR**: 13.5% - **Crash Reporting Segment**: $239M (2025) → $400M+ (2033) **Major Players**: 1. **Sentry** - $3B valuation (2022), 100K+ organizations 2. **Instabug** - Used by Lyft, PayPal, Samsung 3. **Firebase Crashlytics** - Google-backed, largest user base 4. **Bugsnag** - Stability Monitoring, acquired by SmartBear 5. **UXCam** - Session replay specialist 6. **Zipy** - AI-powered log analysis --- ## Competitive Analysis (CRITICAL FINDING) ### Key Discovery: Zero Direct Competitors ⚡ **Research Question**: Which mobile debugging tools do AI-powered video analysis like ClipSense? **Answer**: **NONE** ### Competitor Capabilities Breakdown #### Sentry - **What it does**: Session replay (reconstructed UI from SDK data) - **Video support**: Manual video attachments (no AI analysis) - **AI capabilities**: Stack trace grouping, error pattern detection - **Limitation**: Session replay != actual video (misses visual bugs, timing issues, UI glitches) #### Instabug - **What it does**: Bug reporting with screenshots/videos - **Video support**: Manual attachments, developers watch manually - **AI capabilities**: None - **Limitation**: No AI analysis, no OCR, no audio transcription #### UXCam - **What it does**: Session replay for UX analysis - **Video support**: Reconstructed UI from touch events - **AI capabilities**: Heatmaps, user journey analysis - **Limitation**: Not actual video, no bug root cause analysis #### Firebase Crashlytics - **What it does**: Crash reporting with stack traces - **Video support**: None - **AI capabilities**: Crash grouping - **Limitation**: Stack traces only, no visual analysis #### Bugsnag - **What it does**: Stability monitoring - **Video support**: None - **AI capabilities**: Error grouping - **Limitation**: No visual debugging #### Zipy - **What it does**: AI-powered log analysis - **Video support**: Session replay - **AI capabilities**: Analyzes logs and network traces - **Limitation**: Analyzes logs, NOT video ### What Competitors DON'T Have (ClipSense Advantages) | Feature | Sentry | Instabug | UXCam | Firebase | Zipy | ClipSense | |---------|--------|----------|--------|----------|------|-----------| | Actual video analysis | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | | AI-powered root cause | ❌ | ❌ | ❌ | ❌ | Logs only | ✅ Video | | Audio transcription | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | | OCR on video frames | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | | IDE integration | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ MCP | | AI code generation | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ Claude | | No SDK required | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | | Pre-production use | ❌ | Limited | ❌ | ❌ | ❌ | ✅ | ### Market Positioning **Traditional Tools**: Observability (show you the problem) **ClipSense**: Actionability (analyze problem + suggest fix + implement fix) **Category Creation**: ClipSense is creating a NEW category: **"AI-Powered Video Debugging Analysis + Implementation"** **Reference Document**: See `/Users/jerlitaburanday/clipsense-mcp-server/docs/COMPETITOR-ANALYSIS.md` for complete comparison --- ## Ecosystem Comparison ### ClipSense Workflow (Zero Context Switching) ``` Record bug video (QuickTime/OBS) ↓ Claude Code: "analyze bug.mp4 - submit button not working" ↓ ClipSense analyzes with Claude Sonnet 4.5 ↓ Returns: Root cause + affected file + fix recommendation ↓ Claude Code implements fix immediately ↓ Claude Code runs tests ↓ Claude Code commits ``` **Tools Used**: 1 (Claude Code) **Time**: ~10 minutes ### Sentry Workflow (Multiple Context Switches) ``` Bug occurs in production ↓ Developer gets email alert ↓ Opens browser → sentry.io dashboard ↓ Watches session replay ↓ Reads stack trace ↓ Switches to VS Code ↓ Searches for affected file ↓ Manually implements fix ↓ Manually tests ↓ Commits ``` **Tools Used**: 3 (Email, Browser/Sentry, IDE) **Time**: ~60-80 minutes **ClipSense Advantage**: 85% faster, zero context switching, AI-assisted implementation --- ## Technical Implementation Details ### Current Architecture ``` MCP Server (npm: @clipsense/mcp-server) ↓ (API call) Backend API (FastAPI on Railway) ↓ (Celery task) Worker (Python + FFmpeg + Claude API) ↓ (Store) PostgreSQL (Railway) + Cloudflare R2 (storage) ``` ### Database Schema (Relevant Tables) #### `users` table ```sql id VARCHAR(36) PRIMARY KEY email VARCHAR(255) UNIQUE subscription_tier ENUM('free', 'pro', 'team') DEFAULT 'free' monthly_analyses_used INTEGER DEFAULT 0 monthly_reset_date TIMESTAMP stripe_customer_id VARCHAR(255) UNIQUE -- ⚠️ Currently always NULL stripe_subscription_id VARCHAR(255) -- ⚠️ Currently always NULL ``` #### `api_keys` table ```sql id VARCHAR(36) PRIMARY KEY key VARCHAR(255) UNIQUE NOT NULL user_id VARCHAR(255) REFERENCES users(id) tier ENUM('free', 'pro', 'team') monthly_analyses_used INTEGER DEFAULT 0 is_active BOOLEAN DEFAULT TRUE last_used_at TIMESTAMP created_at TIMESTAMP ``` ### Subscription Limits ```python TIER_LIMITS = { SubscriptionTier.FREE: 3, # 3 analyses/month SubscriptionTier.PRO: 50, # 50 analyses/month ($29) SubscriptionTier.TEAM: 300 # 300 analyses/month ($99) } ``` --- ## Pending Tasks (Priority Order) ### Priority 1: Payment Integration (CRITICAL) - [ ] Set up Stripe account and get API keys - [ ] Create Stripe products (PRO: $29/mo, TEAM: $99/mo) - [ ] Backend: Implement `billing.py` routes - [ ] `POST /create-checkout-session` - [ ] `POST /webhooks/stripe` - [ ] `POST /create-portal-session` - [ ] Frontend: Build pricing page - [ ] Frontend: Build billing dashboard - [ ] Frontend: Build success/cancel pages - [ ] Add Stripe environment variables to Railway - [ ] Test full payment flow (FREE → PRO upgrade) - [ ] Test webhook updates user tier correctly ### Priority 2: API Key Security - [ ] Backend: Implement `POST /api/v1/keys/regenerate` - [ ] Backend: Implement `POST /api/v1/keys/rotate` - [ ] Backend: Add expiry checking for rotated keys - [ ] Frontend: Build `/dashboard/keys` page - [ ] Frontend: Add regenerate/rotate buttons with confirmation modals - [ ] Email: Create templates for key regeneration notifications ### Priority 3: Error Enhancement - [ ] Update analyze endpoint error response format - [ ] Include upgrade URL in limit errors - [ ] Test MCP server displays helpful upgrade message ### Priority 4: MCP Server Polish - [ ] Create 30-second demo GIF showing analysis workflow - [ ] Add GIF to npm README - [ ] Add badges (npm version, downloads, license) - [ ] Add FAQ section - [ ] Add troubleshooting section ### Priority 5: npm Token Migration - [ ] **DEADLINE: December 9, 2025** - [ ] Migrate from classic tokens to granular access tokens - [ ] Update GitHub Actions workflow if applicable --- ## Files Modified/Created This Session ### No code changes this session This session was primarily research, planning, and clarification. ### Documentation Created 1. This handoff document 2. Competitor analysis reference document (separate file) --- ## Important URLs - **Website**: https://clipsense.app - **API**: https://api.clipsense.app - **npm Package**: https://www.npmjs.com/package/@clipsense/mcp-server - **Railway Dashboard**: (user has access) --- ## Key Decisions Made 1. ✅ **Payment Gateway**: Stripe (2.9% + $0.30, best DX) 2. ✅ **API Key on Upgrade**: Keep same key, update tier in database 3. ✅ **Regenerate vs Rotate**: Separate security features (not upgrade features) 4. ✅ **Market Positioning**: ClipSense creates new category (zero direct competitors) 5. ✅ **Ecosystem Strategy**: IDE integration (MCP) as primary differentiator --- ## Questions Answered This Session ### Q: How do users upgrade from FREE to PRO? **A**: Via Stripe checkout on clipsense.app/pricing, webhook updates database ### Q: Do users get a new API key when upgrading? **A**: No, same API key, just higher limits based on `subscription_tier` ### Q: What is regenerate vs rotate? **A**: - **Regenerate**: Emergency replacement (immediate invalidation) - **Rotate**: Gradual migration (7-day grace period) ### Q: Which MCP servers have highest subscriptions? **A**: GitHub, Filesystem, PostgreSQL, Slack (utility servers) ### Q: Which competitors do video debugging analysis? **A**: NONE. All do "session replay" (reconstructed UI), not actual video analysis ### Q: Can users implement fixes in Claude Code? **A**: YES - this is ClipSense's biggest advantage. Analysis + implementation in one tool. --- ## Next Session Priorities 1. **Start Stripe Integration** - Create Stripe account - Set up products and pricing - Implement backend billing routes - Build frontend pricing page 2. **Test Payment Flow End-to-End** - Test FREE user hitting limit - Test upgrade to PRO - Test webhook updates database - Test PRO user can analyze again 3. **Security Endpoints** - Implement regenerate/rotate after payment works --- ## Context Warnings for Next Session ⚠️ **DO NOT ASSUME**: - Website needs to be built (IT ALREADY EXISTS) - Users get new API keys on upgrade (THEY DON'T) - Competitors do video analysis (THEY DON'T) ✅ **REMEMBER**: - Same API key throughout user lifetime (unless regenerate/rotate) - ClipSense has ZERO direct competitors in AI video analysis - IDE integration (MCP) is the strategic differentiator - Payment system is the #1 missing piece for monetization --- ## Session Metadata - **Date**: December 5, 2025 - **Duration**: Extended session (context limit recovery) - **Code Changes**: 0 files modified - **Documentation**: 2 files created - **Research Completed**: Market analysis, competitive analysis, ecosystem comparison - **Next Milestone**: Stripe integration implementation --- **End of Handoff Document**