| name | qcut-mcp-preview-test |
| description | Switch QCut's center Preview Panel between normal video preview and MCP app mode, validate iframe rendering, and debug MCP HTML delivery through IPC and HTTP endpoints. Use when asked to test, demo, or troubleshoot MCP app preview behavior, the "MCP Media App" toggle, `mcp:app-html` events, `/api/claude/mcp/app`, or to craft prompts for Claude that modify the MCP media app UI safely. |
| allowed-tools | Bash(curl *), Read, Grep |
QCut MCP Preview Test
Architecture
QCut's preview panel supports two rendering modes: Video Preview (default) and MCP App (interactive iframe). The MCP system has two independent input paths:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Preview Panel (preview-panel.tsx) โ
โ โ
โ Mode 1: Video Preview (default) โ
โ โ Canvas-based video playback โ
โ โ
โ Mode 2: MCP App (iframe srcDoc) โ
โ โโ Local: built-in PersonaPlex template โ
โ โ toggled by "MCP Media App" button โ
โ โ state: localMcpActive = true โ
โ โ โ
โ โโ External: HTML from Claude MCP tools โ
โ received via IPC mcp:app-html event โ
โ state: activeHtml + toolName set โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Data Flow (External MCP):
Claude Code โ HTTP POST /api/claude/mcp/app
โ claude-http-shared-routes.ts forwards via IPC
โ preview-panel.tsx receives via onAppHtml()
โ useMcpAppStore.setMcpApp({html, toolName})
โ <iframe srcDoc={activeHtml}>
Data Flow (Local Template):
User clicks "MCP Media App" button
โ useMcpAppStore.setLocalMcpActive(true)
โ preview-panel.tsx calls buildMcpMediaAppHtml()
โ Renders MCP_MEDIA_APP_TEMPLATE from preview-panel/mcp-media-app.ts
Key Files
| File | Purpose |
|---|
apps/web/src/components/editor/preview-panel.tsx | Preview panel with MCP toggle and iframe rendering |
apps/web/src/components/editor/preview-panel/mcp-media-app.ts | PersonaPlex template (MCP_MEDIA_APP_TEMPLATE) and HTML builder |
apps/web/src/stores/mcp-app-store.ts | Zustand store: activeHtml, toolName, localMcpActive |
electron/claude/http/claude-http-shared-routes.ts | HTTP endpoint POST /api/claude/mcp/app โ IPC forward |
electron/mcp/qcut-mcp-server.ts | MCP tools: configure-media, show-export-settings, preview-project-stats |
electron/mcp/apps/*.html | HTML templates for each MCP tool |
apps/web/src/types/electron.d.ts | Type: window.electronAPI.mcp.onAppHtml() |
Store State (mcp-app-store.ts)
interface McpAppState {
activeHtml: string | null
toolName: string | null
localMcpActive: boolean
}
setMcpApp(html, toolName)
clearMcpApp()
setLocalMcpActive(active)
When To Use This Skill
Use when the user asks to:
- Test or debug MCP app rendering in the preview panel
- Switch between video preview and MCP app mode
- Modify the built-in PersonaPlex template UI
- Send custom HTML to the preview panel via HTTP
- Troubleshoot why external MCP tools aren't rendering
- Add new controls or change behavior of the MCP media app
Quick Workflow
1. Toggle via UI
- Open a project in QCut editor
- Click
MCP Media App in the preview toolbar โ shows PersonaPlex template
- Click
Video Preview or Return to Preview to switch back
2. Test HTTP Trigger (External MCP)
Send HTML directly to the preview panel:
curl -X POST http://127.0.0.1:8765/api/claude/mcp/app \
-H "Content-Type: application/json" \
-d '{"toolName":"manual-test","html":"<html><body><h1>MCP Manual Test</h1></body></html>"}'
Expected: preview switches to iframe, toolbar shows MCP App: manual-test.
3. Test MCP Server Tools
If Claude has the QCut MCP server registered:
claude mcp list
Then ask Claude to call: configure-media, show-export-settings, or preview-project-stats.
How To Modify The MCP App Template
Rules
- Target file:
apps/web/src/components/editor/preview-panel/mcp-media-app.ts
- Template variable:
MCP_MEDIA_APP_TEMPLATE (PersonaPlex speech-to-speech UI)
- Do NOT change: toggle button behavior in
preview-panel.tsx, clearMcpApp() logic, IPC listener
- Keep intact:
PATCH /api/claude/project/{projectId}/settings endpoint usage
- Keep intact:
try/catch error handling in inline scripts
- Verify after changes:
cd apps/web && bunx tsc --noEmit
Example Prompts
Visual redesign:
In preview-panel/mcp-media-app.ts, redesign MCP_MEDIA_APP_TEMPLATE layout:
- Two-column on desktop, single-column on mobile
- Add card backgrounds for each control group
- Keep all existing controls and API payload keys unchanged
- Preserve try/catch around interactions
Run: cd apps/web && bunx tsc --noEmit
Add new control:
In preview-panel/mcp-media-app.ts, extend MCP_MEDIA_APP_TEMPLATE with a "Background Type" select (color|blur).
On Apply, include backgroundType in PATCH payload to /api/claude/project/{projectId}/settings.
Keep current controls and behavior unchanged.
Run type check: cd apps/web && bunx tsc --noEmit
Behavior tweak:
Update MCP media app behavior in preview-panel/mcp-media-app.ts:
- Disable Apply button while request is in flight
- Show success/error status messages
- Keep endpoint and payload schema unchanged
Run: cd apps/web && bunx tsc --noEmit
Debugging Checklist
Preview doesn't switch to MCP mode
- Check
useMcpAppStore state in DevTools: __ZUSTAND_STORES__ or React DevTools
- Verify
window.electronAPI?.mcp?.onAppHtml exists (preload exposed)
- Check console for IPC errors
External MCP app doesn't render
- Verify QCut MCP server registered:
claude mcp list
- Test HTTP endpoint directly with curl (see above)
- Check
electron/claude/http/claude-http-shared-routes.ts route at POST /api/claude/mcp/app
- Check that
win.webContents.send("mcp:app-html", ...) is called
Local template renders but iframe is blank
- Check
MCP_MEDIA_APP_TEMPLATE is valid HTML
- Look for CSP (Content Security Policy) errors in console
- Verify
srcDoc attribute is set on iframe
DevTools Debug Snippet
try {
window.electronAPI?.mcp?.onAppHtml?.((payload) => {
console.log("mcp payload received:", payload);
});
console.log("mcp listener attached");
} catch (error) {
console.error("failed to attach mcp listener:", error);
}
Verification Commands
cd apps/web && bunx tsc --noEmit
cd electron && bunx tsc --noEmit
bunx vitest run electron/claude/__tests__/claude-http-server.test.ts --reporter=dot
