npm package: @gburanda/clipsense-mcp-server
Description: MCP server for mobile debugging with video analysis and follow-up Q&A
Author: ClipSense
Latest version: 0.2.0

# ClipSense MCP Server

![npm version](https://img.shields.io/npm/v/@gburanda/clipsense-mcp-server)
![downloads](https://img.shields.io/npm/dm/@gburanda/clipsense-mcp-server)
![license](https://img.shields.io/npm/l/@gburanda/clipsense-mcp-server)
![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)

Model Context Protocol (MCP) server for **ClipSense** - AI-powered mobile debugging through video analysis.

Analyze screen recordings of mobile app bugs with AI coding assistants. Get instant insights into crashes, UI issues, and unexpected behavior in React Native, iOS, and Android apps.

## Compatibility

**Works with multiple AI coding assistants** that support MCP (Model Context Protocol):

- **Claude Code** (VS Code extension) - Full filesystem access, handles videos up to 500MB
- **Cursor** - Full MCP support via `.cursor/mcp.json`
- **Windsurf** - MCP support via `.windsurf/mcp.json`
- **Cline** - Full MCP support with integrated marketplace
- **Roo-Cline/Roo Code** - MCP support with manual configuration
- **Continue.dev** - MCP support for VS Code and JetBrains IDEs
- **OpenAI Codex** - Comprehensive MCP support

**Important Limitations:**

- **Claude Desktop**: Does NOT work due to 31MB file upload limit (99.99% of videos exceed this)
- **One-time analysis**: Each analysis is independent; follow-up questions require re-analyzing the video

## Features

- **Video Bug Analysis**: Analyze local screen recordings showing mobile app issues
- **AI-Powered Debugging**: Claude Sonnet 4.5 analyzes videos frame-by-frame to identify problems
- **Multi-Platform Support**: Works with React Native, iOS (Swift/Objective-C), Android (Kotlin/Java)
- **Code Fix Suggestions**: Get actionable recommendations to fix bugs
- **Fast Processing**: Results in ~2 minutes for most videos

## Why ClipSense?

| Feature | ClipSense MCP | Claude Desktop | Manual Debugging | Screen Recording Tools |
|---------|---------------|----------------|------------------|------------------------|
| Video file size limit | 500MB | 31MB | N/A | Varies |
| AI analysis | ✅ Claude Sonnet 4.5 | ✅ (limited by file size) | ❌ Manual review | ❌ No analysis |
| Works in AI coding assistants | ✅ All MCP-compatible | ❌ Desktop only | ❌ | ❌ |
| Code fix suggestions | ✅ Contextual | ✅ (limited) | ❌ | ❌ |
| Timeline breakdown | ✅ Automatic | ❌ | ❌ Manual | ❌ |
| Root cause analysis | ✅ Automatic | ✅ (limited) | ❌ Manual | ❌ |
| Multi-format support | ✅ 9 formats | ✅ (limited) | ✅ | ✅ |
| Integration with workflow | ✅ Native in IDE | ❌ Separate app | ❌ | ❌ |
| Processing time | 2-3 minutes | Instant (upload limited) | Hours | N/A |

**Bottom line**: ClipSense is the only tool that brings AI-powered video analysis directly into your development workflow, with support for realistic file sizes and multiple video formats.

## Demo

*Demo GIF coming soon - see [ClipSense MCP Server Video.mp4](https://github.com/clipsense/clipsense-mcp-server/blob/main/demo/ClipSense-MCP-Server-Video.mp4) for now*

**From crash video to root cause in under 3 minutes**

## Quick Start

### 1. Get Your Free API Key

Visit [clipsense.app](https://clipsense.app) to:
1. Sign up with your email
2. Generate your API key (starts with `cs_sk_`)
3. Get 3 free analyses per month - no credit card required

### 2. Install via npm

```bash
npm install -g @gburanda/clipsense-mcp-server
```

### 3. Configure Your AI Coding Assistant

#### Claude Code (VS Code Extension)

Add to your MCP settings file:

**macOS/Linux**: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
**Windows**: `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`

```json
{
  "mcpServers": {
    "clipsense": {
      "command": "npx",
      "args": ["-y", "@gburanda/clipsense-mcp-server"],
      "env": {
        "CLIPSENSE_API_KEY": "cs_sk_YOUR_API_KEY_HERE"
      }
    }
  }
}
```

#### Cursor

Create or edit `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "clipsense": {
      "command": "npx",
      "args": ["-y", "@gburanda/clipsense-mcp-server"],
      "env": {
        "CLIPSENSE_API_KEY": "cs_sk_YOUR_API_KEY_HERE"
      }
    }
  }
}
```

#### Windsurf

Create or edit `.windsurf/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "clipsense": {
      "command": "npx",
      "args": ["-y", "@gburanda/clipsense-mcp-server"],
      "env": {
        "CLIPSENSE_API_KEY": "cs_sk_YOUR_API_KEY_HERE"
      }
    }
  }
}
```

#### Continue.dev

Add to your Continue configuration (VS Code or JetBrains):

```json
{
  "mcpServers": {
    "clipsense": {
      "command": "npx",
      "args": ["-y", "@gburanda/clipsense-mcp-server"],
      "env": {
        "CLIPSENSE_API_KEY": "cs_sk_YOUR_API_KEY_HERE"
      }
    }
  }
}
```

#### Cline, Roo-Cline, OpenAI Codex

Refer to your IDE's MCP configuration documentation. The server configuration follows the same pattern shown above.

### 4. Restart Your IDE

The ClipSense MCP tool will now be available in your AI coding assistant.

## Usage

In your AI coding assistant, simply ask to analyze a bug video:

```
Analyze this bug video: /Users/me/Desktop/app-crash.mp4
```

Your AI assistant will use the ClipSense MCP server to:
1. Upload your video
2. Process it with AI vision (Claude Sonnet 4.5)
3. Identify the bug and suggest fixes

### Follow-up Questions

**Each analysis is independent.** To ask follow-up questions about the same video:

```
Analyze /Users/me/Desktop/app-crash.mp4 and focus on the network request flow
```

The video will be re-analyzed with your new question. Follow-up questions without re-specifying the video path will not have access to the previous analysis context.

### Supported Video Formats

**All common formats supported:**
- MP4, MOV, WebM, AVI, MKV, FLV, MPEG/MPG, 3GP, WMV
- Max file size: 500MB
- Max duration: 10 minutes
- All formats automatically converted to MP4 for processing

## Real-World Examples

### Example 1: React Native Crash

**Prompt:**
```
Analyze this crash video: ~/Desktop/app-crash.mp4
```

**ClipSense Output:**
```markdown
Root Cause: TypeError at ProfileScreen.tsx:42
user.profile.avatar is undefined when user data hasn't loaded

Timeline:
- 0:00-0:05: User taps "Profile" tab
- 0:05-0:08: Loading spinner (API call in progress)
- 0:08: Crash - "Cannot read property 'avatar' of undefined"

Fix:
Add null check: const avatarUrl = user?.profile?.avatar ?? DEFAULT_AVATAR
```

### Example 2: iOS UI Glitch

**Prompt:**
```
Analyze ~/Videos/ios-layout-bug.mov and focus on the navigation bar
```

**ClipSense Output:**
```markdown
Root Cause: Layout constraint conflict in HeaderView.swift:78
Navigation bar height animates incorrectly during keyboard appearance

Timeline:
- 0:00-0:03: User taps search field
- 0:03: Keyboard animates up
- 0:03-0:05: Navigation bar "jumps" - constraint conflict visible

Fix:
Update constraint priority: headerHeightConstraint.priority = .defaultHigh
Add keyboard animation: UIView.animate(withDuration: 0.3, ...)
```

### Example 3: Android Network Error

**Prompt:**
```
Why does my Android app show "No data" after login? Video: ~/android-login-bug.mp4
```

**ClipSense Output:**
```markdown
Root Cause: API token not persisted after login
HTTP 401 errors on /api/feed endpoint (seen in logcat at 0:12)

Timeline:
- 0:00-0:08: User enters credentials and taps "Login"
- 0:08-0:10: Success toast appears, navigates to home
- 0:10-0:12: "No data" screen (API call failed with 401)

Fix:
Persist auth token: SharedPreferences.edit().putString("auth_token", token).apply()
Or use Room database for token storage
```

## Example Prompts

**Crash Analysis**
- "Why does my app crash when I tap the login button?"
- "Analyze this crash video: ~/crashes/prod-crash-v1.2.mp4"
- "What's causing this IndexOutOfBoundsException?"

**UI Issues**
- "What's causing this UI glitch on the profile screen?"
- "Why is my bottom sheet not animating smoothly?"
- "Analyze this layout bug in dark mode"

**Performance**
- "Why is my list scrolling slowly?"
- "What's causing this memory leak?"
- "Analyze this ANR (Application Not Responding) video"

**Navigation**
- "Why does deep linking navigate to the wrong screen?"
- "What's breaking the back button navigation?"
- "Analyze this navigation flow bug"

**Network**
- "Why is this API call failing?"
- "What's causing these timeout errors?"
- "Analyze the network request flow in this video"

## Example Analysis Output

When you analyze a video, ClipSense provides:

```markdown
# ClipSense Analysis Complete 🔍

## Root Cause
Null pointer exception when accessing user.profile.avatar at ProfileScreen.tsx:142

## Timeline
- 0:00-0:15 - User navigates to profile screen
- 0:15-0:18 - App attempts to load avatar image
- 0:18 - Crash occurs (NullPointerException)

## Visual Evidence
127 frames analyzed
Key moments:
- 0:15 (Frame 23): Profile screen rendered, avatar placeholder visible
- 0:18 (Frame 24): White screen (crash)

## Recommended Fix
Add null check before accessing avatar:

```javascript
const avatarUrl = user?.profile?.avatar ?? DEFAULT_AVATAR;
```

## Next Steps
1. Add null safety checks in ProfileScreen.tsx
2. Implement error boundary for profile component
3. Add fallback UI for missing user data

---
💬 **Have follow-up questions?** Continue this conversation with your AI assistant
📊 **View full details:** https://clipsense.app/results/job_abc123
📝 **Analysis ID:** job_abc123
```

## Pricing

| Plan | Price | Analyses/Month | Best For |
|------|-------|----------------|----------|
| **FREE** | $0 | 3 | Testing ClipSense, personal projects |
| **PRO** | $29/mo | 50 | Individual developers |
| **TEAM** | $99/mo | 300 | Small teams (up to 5 developers) |
| **ENTERPRISE** | Custom | Unlimited | Large teams, custom requirements |

**All plans include:**
- ✅ Up to 500MB video files
- ✅ All 9 video formats
- ✅ Claude Sonnet 4.5 AI analysis
- ✅ 24-hour video retention
- ✅ Secure encrypted storage

**Need more?** Contact [support@clipsense.app](mailto:support@clipsense.app) for custom plans or enterprise pricing.

## FAQ

### General

#### What video formats are supported?
All common video formats: **MP4, MOV, WebM, AVI, MKV, FLV, MPEG/MPG, 3GP, and WMV** files up to 500MB and 10 minutes duration. All formats are automatically converted to MP4 for processing.

#### How long does analysis take?
- **Short videos (< 2 min)**: 2-3 minutes
- **Medium videos (2-5 min)**: 3-4 minutes
- **Long videos (5-10 min)**: 4-5 minutes

Processing time includes upload, frame extraction, OCR, audio transcription, and AI analysis.

#### Is my video data secure?
Yes. All videos are:
- ✅ Encrypted during upload (TLS 1.3)
- ✅ Encrypted at rest (Firebase Storage)
- ✅ Automatically deleted after 24 hours
- ✅ Never used for AI training
- ✅ GDPR and SOC 2 compliant storage

#### What if I run out of free analyses?
You have three options:
1. **Wait**: Free tier resets on the 1st of each month
2. **Upgrade to PRO ($29/mo)**: Get 50 analyses per month
3. **Upgrade to TEAM ($99/mo)**: Get 300 analyses per month

### Usage & Features

#### Can I ask follow-up questions about an analysis?
Each analysis is independent. To explore different aspects of the same video, re-analyze it with a more specific prompt:

```
Analyze /path/to/video.mp4 and focus on the network request flow
```

The AI will have access to the full video context again with your new focus area.

#### What types of bugs can ClipSense detect?
ClipSense excels at:
- ✅ **Crashes** (null pointer, out of bounds, type errors)
- ✅ **UI glitches** (layout shifts, rendering issues, flickering)
- ✅ **Navigation bugs** (wrong screen, broken deep links)
- ✅ **Network errors** (failed API calls, timeouts)
- ✅ **Performance issues** (slow loading, ANR, memory leaks)
- ✅ **Input validation bugs** (form errors, keyboard issues)

#### Does it work with simulator/emulator recordings?
**Yes!** ClipSense works with recordings from:
- iOS Simulator (macOS)
- Android Emulator
- Physical devices (iPhone, Android phones)
- Screen mirroring tools (Reflector, AirServer)

#### What frameworks are supported?
- ✅ **React Native** (Expo, bare workflow)
- ✅ **iOS** (Swift, Objective-C, SwiftUI)
- ✅ **Android** (Kotlin, Java, Jetpack Compose)
- ✅ **Flutter** (Dart)
- ✅ **Ionic** (Capacitor, Cordova)
- ✅ **Native hybrid apps**

#### Can I analyze the same video multiple times?
Yes! Each analysis is billed separately. Useful for:
- Exploring different aspects ("focus on state management")
- Getting a second opinion with a different prompt
- After making code changes to verify the fix

#### How does ClipSense handle different screen resolutions?
ClipSense automatically processes all resolutions:
- **Mobile**: 320x568 to 1440x3200 (iPhone SE to high-end Android)
- **Tablets**: Up to 2048x2732 (iPad Pro)
- **Desktop simulators**: Any resolution

Videos are intelligently scaled during processing to optimize AI analysis without losing detail.

### Best Practices

#### How should I record videos for best results?
**Do:**
- ✅ Start recording 10 seconds before the bug occurs
- ✅ Show the full user interaction (taps, swipes, inputs)
- ✅ Include 5 seconds after the bug for context
- ✅ Keep screen brightness high for better OCR
- ✅ Record at native resolution (don't zoom)

**Avoid:**
- ❌ Recording only the crash moment (no context)
- ❌ Shaky camera recordings (use screen recording)
- ❌ Low brightness or dark mode (harder to read text)
- ❌ Covering UI elements with fingers

#### How can I reduce video file size?
If your video exceeds 500MB, try:

```bash
# Reduce resolution (1080p → 720p)
ffmpeg -i input.mp4 -vf scale=1280:720 -c:a copy output.mp4

# Reduce bitrate
ffmpeg -i input.mp4 -b:v 2M -c:a copy output.mp4

# Trim to relevant section only
ffmpeg -i input.mp4 -ss 00:00:30 -to 00:01:45 -c copy output.mp4
```

Or use online tools like [HandBrake](https://handbrake.fr/) for a GUI option.

### Technical

#### Does ClipSense work offline?
No. ClipSense requires internet connection to:
- Upload videos to secure cloud storage
- Process videos with Claude Sonnet 4.5 AI
- Return analysis results to your IDE

#### What data does ClipSense collect?
We collect only what's necessary:
- ✅ Video files (deleted after 24 hours)
- ✅ Analysis results (retained for your reference)
- ✅ Usage metrics (for billing and rate limiting)
- ❌ No source code access
- ❌ No personal data beyond email

See [Privacy Policy](https://clipsense.app/privacy-policy) for full details.

#### Can I self-host ClipSense?
Not currently. ClipSense is a managed service. For enterprise self-hosting inquiries, contact [support@clipsense.app](mailto:support@clipsense.app).

#### What happens if analysis fails?
Failed analyses don't count toward your monthly limit. Check:
- Video format is supported (see list above)
- File size is under 500MB
- Video duration is under 10 minutes
- Your API key is valid and has remaining analyses

If issues persist, contact support with your job ID for troubleshooting.

## Troubleshooting

### Error: "CLIPSENSE_API_KEY not found"
**Solution:** Ensure your MCP settings file has the correct `env` section with your API key:
```json
"env": {
  "CLIPSENSE_API_KEY": "cs_sk_YOUR_KEY_HERE"
}
```
Restart your IDE after updating.

### Error: "Command not found: npx"
**Solution:** Install Node.js (v18+) from [nodejs.org](https://nodejs.org). Then restart your terminal and IDE.

### Error: "Upload failed" or "File too large"
**Solution:**
- Ensure video is under 500MB
- Trim video to show only the relevant bug (crash moment + 10 seconds before)
- Compress with: `ffmpeg -i input.mp4 -vcodec h264 -acodec aac output.mp4`

### Analysis stuck at "processing"
**Solution:**
- Check status at https://clipsense.app/results/[job_id]
- If stuck for 10+ minutes, contact support@clipsense.app with the job ID

### Claude Code doesn't see the ClipSense tool
**Solution:**
1. Verify MCP settings file location matches your IDE
2. Check for JSON syntax errors in your MCP config
3. Restart VS Code completely (Cmd+Q, not just window close)
4. Try `npx @gburanda/clipsense-mcp-server` manually to test installation

### Error: "Rate limit exceeded"
**Solution:**
You've used all your monthly analyses. Options:
- Wait until next month (free tier resets on the 1st)
- Upgrade to PRO or TEAM plan at https://clipsense.app/pricing
- Contact support if you believe this is an error

### Video processing never completes
**Solution:**
1. Check video meets requirements:
   - Under 500MB file size
   - Under 10 minutes duration
   - Valid format (MP4, MOV, WebM, AVI, MKV, FLV, MPEG, 3GP, WMV)
2. Check job status: https://clipsense.app/results/[job_id]
3. If stuck >10 minutes, contact support with job ID

### Analysis quality is poor
**Tips to improve:**
- Record at higher resolution (1080p recommended)
- Ensure good screen brightness (not dark mode if possible)
- Include 10 seconds before and 5 seconds after the bug
- Show full user interaction (don't skip steps)
- Avoid covering UI with fingers or notifications
- Use screen recording (not camera pointed at screen)

### Need to cancel/delete an analysis
**Solution:**
Videos are automatically deleted after 24 hours. If you need immediate deletion:
- Email support@clipsense.app with the job ID
- Include reason for deletion request
- We'll process within 24 hours

## Support & Resources

**Documentation**
- 📚 Full Docs: [clipsense.app/docs](https://clipsense.app/docs)
- 🎥 Video Tutorials: [clipsense.app/tutorials](https://clipsense.app/tutorials)
- 📖 API Reference: [clipsense.app/api](https://clipsense.app/api)

**Community & Help**
- 🐛 Bug Reports: [github.com/clipsense/clipsense-mcp-server/issues](https://github.com/clipsense/clipsense-mcp-server/issues)
- 💬 Discussions: [github.com/clipsense/clipsense-mcp-server/discussions](https://github.com/clipsense/clipsense-mcp-server/discussions)
- 📧 Email Support: [support@clipsense.app](mailto:support@clipsense.app)
- 🐦 Twitter: [@clipsense_app](https://twitter.com/clipsense_app)

**Response Times**
- Email: Within 24 hours (business days)
- Critical issues: Within 4 hours
- Enterprise customers: Priority support with SLA

## License

MIT