# BLUEPRINT: Stack Video [MCP]
# Version: 3.0.0
# URL: https://stackvideo.app
# Updated: 2026-05-19

## IDENTITY
name: Stack Video
description: Generates per-feature animated how-to videos from StackLaunch sweep data — enter an app URL, get a feature intelligence report, and produce grounded how-to videos from real screenshots.
category: developer-tools
contact: https://stackvideo.app

## SUMMARY
tagline: Turn any app's sweep data into animated how-to videos — one per feature, grounded in real screenshots.
audience: Developers and content creators using StackLaunch sweep data to produce product documentation and promotional videos.
capabilities:
  - gather-intelligence: Check if sweep data exists and get the full feature list for an app
  - generate-feature-video: Generate a step-by-step how-to video for a specific feature
  - classify-sweep: Bucket raw sweep screenshots into per-feature groups
  - augment-steps: Extend a feature guide with AI-generated steps
  - export-video-mp4: Download the finished video as an MP4

## AUTH
provider: firebase
methods: email-password, oauth-google

## MCP
server: stack-video-mcp
install: claude mcp add stack-video -- npx stack-video-mcp --api-key <<api-key>>
auth: STACK_VIDEO_API_KEY — user's Stack Video API key from Account Settings at stackvideo.app

## ACCESS
preferred: mcp
fallback: api
last-resort: ui

## TIMING
# Format: <operation-label>: <observed-range> — use max: <N>s
feature-video-generation: 60–120s — use max: 180s
sweep-classification: 30–90s — use max: 120s
intelligence-gather: 2–5s — use max: 30s

## CAPABILITY: gather-intelligence
name: Gather app intelligence
description: Primary entry point. Accepts an app URL, reads sweep screenshots, market analysis, and blueprint in parallel, and returns a structured intelligence report. If sweepRequestNeeded is true, no sweep data exists — tell the user to run a sweep in StackLaunch first.
auth-required: true
scope: read-only
input:
  - name: appUrl
    type: string
    required: true
    description: App URL to analyze
  - name: appId
    type: string
    required: false
    description: App id override; auto-derived from the URL hostname when omitted
output:
  - type: json
    description: AppIntelligence report with source badges, features list, and sweepRequestNeeded flag

### MCP
tool: gather_intelligence

### API
method: POST
endpoint: /api/app/intelligence
body:
  appUrl: string
  appId: string (optional)
response:
  found: boolean
  intelligence: AppIntelligence

### UI
steps:
  1. ASSERT-AUTH
  2. NAVIGATE /
  3. INPUT [data-agent-id="url-input"] <<app-url>>
  4. CLICK [data-agent-id="analyze-btn"]
  5. WAIT [data-agent-id="intelligence-report"] (max: 30s)
  6. VERIFY selector_exists [data-agent-id="feature-grid"]

## CAPABILITY: generate-feature-video
name: Generate per-feature how-to video
description: Generates a per-feature how-to video from classified sweep data. Requires a prior classify-sweep to have completed.
auth-required: true
scope: form-submit
input:
  - name: appId
    type: string
    required: true
    description: App id (from gather-intelligence)
  - name: featureId
    type: string
    required: true
    description: Feature id from the intelligence report, or "__overview__" for an overview reel
  - name: appUrl
    type: string
    required: true
    description: App URL
output:
  - type: json
    description: jobId for polling; final payload includes AnalysisResult when status is complete

### MCP
tool: generate_feature_video

### API
method: POST
endpoint: /api/analyze/from-sweep
body:
  appId: string
  featureId: string
  appUrl: string
response:
  jobId: string

method: GET
endpoint: /api/analyze/jobs/<jobId>
response:
  status: string
  result: object (when complete)
  error: string (when failed)

### UI
steps:
  1. ASSERT-AUTH
  2. Complete gather-intelligence first
  3. CLICK [data-agent-id="generate-feature-btn"] on the desired feature card, OR
     CLICK [data-agent-id="generate-overview-btn"] for an overview reel
  4. WAIT [data-agent-id="video-player"] (max: 180s)
  5. VERIFY selector_exists [data-agent-id="step-list"]

## CAPABILITY: classify-sweep
name: Classify sweep screenshots
description: Classifies raw StackLaunch sweep screenshots into per-feature buckets with readiness status and error flagging. Run this if gather-intelligence shows sweepFound true but classifiedFeaturesFound false.
auth-required: true
scope: form-submit
input:
  - name: appId
    type: string
    required: true
    description: App id
  - name: appUrl
    type: string
    required: true
    description: App URL
  - name: model
    type: string
    required: false
    description: Sweep run to classify ("gemini" or "claude"); defaults to gemini
output:
  - type: json
    description: jobId for polling; final payload includes ClassifiedSweep when status is complete

### MCP
tool: classify_sweep

### API
method: POST
endpoint: /api/sweep/classify
body:
  appId: string
  appUrl: string
  model: string (optional, "gemini" | "claude")
response:
  jobId: string

method: GET
endpoint: /api/sweep/classify/<jobId>
response:
  status: string
  result: ClassifiedSweep (when complete)
  error: string (when failed)

## CAPABILITY: export-video-mp4
name: Export session as MP4
description: Render and download an MP4 for the active feature in a saved session.
auth-required: false
scope: file-download
input:
  - name: sessionId
    type: string
    required: true
    description: Session document id from save-session
output:
  - type: file
    description: MP4 binary stream

### API
method: POST
endpoint: /api/export/<sessionId>
response:
  Content-Type: video/mp4 (file download)

### UI
steps:
  1. NAVIGATE /session/<sessionId>
  2. WAIT [data-agent-id="video-player"] (max: 30s)
  3. CLICK [data-agent-id="export-mp4-btn"]
  4. VERIFY file_type == ".mp4"

## CAPABILITY: augment-steps
name: Augment guide steps with AI
description: Ask AI to append new steps to the current feature guide using an instruction and optional screenshots.
auth-required: false
scope: form-submit
input:
  - name: featureTitle
    type: string
    required: true
    description: Title of the active feature
  - name: existingSteps
    type: json
    required: true
    description: Current HowToStep array
  - name: instruction
    type: string
    required: true
    description: Natural language instruction for new steps
output:
  - type: json
    description: newSteps array to merge into the guide

### MCP
tool: augment_steps

### API
method: POST
endpoint: /api/augment
body:
  featureTitle: string
  existingSteps: Step[]
  instruction: string
response:
  newSteps: Step[]

### UI
steps:
  1. NAVIGATE /session/<sessionId>
  2. WAIT [data-agent-id="step-list"] (max: 30s)
  3. INPUT [data-agent-id="augment-input"] <<instruction>>
  4. CLICK [data-agent-id="augment-btn"]
  5. WAIT [data-agent-id="step-list"] (max: 60s)
  6. VERIFY selector_exists [data-agent-id="step-list"]

## CAPABILITY: save-session
name: Save workspace session
description: Persist analysis result, images, URL, and active feature index to the backend.
auth-required: false
scope: form-submit
input:
  - name: result
    type: json
    required: true
    description: Full analysis result object
  - name: url
    type: string
    required: false
    description: Source app URL
  - name: activeFeatureIndex
    type: number
    required: false
    description: Index of the active feature
output:
  - type: json
    description: id of the saved session

### API
method: POST
endpoint: /api/sessions
body:
  result: object
  url: string (optional)
  activeFeatureIndex: number (optional)
response:
  id: string

## CAPABILITY: get-session
name: Load session by id
description: Retrieve a saved session including result, images, url, and activeFeatureIndex.
auth-required: false
scope: read-only
input:
  - name: sessionId
    type: string
    required: true
    description: Session id from save-session or share link
output:
  - type: json
    description: Full session object

### MCP
tool: get_session

### API
method: GET
endpoint: /api/sessions/<sessionId>
response:
  id: string
  result: object
  images: array
  url: string
  activeFeatureIndex: number

### UI
steps:
  1. NAVIGATE /session/<sessionId>
  2. WAIT [data-agent-id="video-player"] (max: 30s)
  3. VERIFY selector_exists [data-agent-id="step-list"]

## CAPABILITY: generate-demo-video
name: Generate demo video (legacy)
description: Legacy direct-scrape path. Prefer gather-intelligence + generate-feature-video for sweep-grounded results.
auth-required: false
scope: read-only
input:
  - name: url
    type: string
    required: true
    description: Product or app URL to analyze
  - name: images
    type: string
    required: false
    description: Optional base64 data URLs for supplementary screenshots
output:
  - type: json
    description: jobId for polling; final payload includes result when status is complete

### API
method: POST
endpoint: /api/analyze
body:
  url: string
  images: string[] (optional)
response:
  jobId: string

method: GET
endpoint: /api/analyze/jobs/<jobId>
response:
  status: string
  result: object (when complete)
  error: string (when failed)