# Local Video Scenes MCP

Local Video Scenes MCP extracts timestamped screenshots from local videos so Claude can produce a visual walkthrough. It does not use Whisper, audio transcription, or any hosted video-processing service.

## What Stays Local

- The original video stays on your machine.
- `ffmpeg` and `ffprobe` run locally.
- The MCP returns local screenshot paths and metadata.
- Claude analyzes only the screenshots you provide through the MCP result.
- Audio is not extracted or analyzed in V1.

## Requirements

- Node.js 18.18+
- `ffmpeg` and `ffprobe`

The server includes `video.check_ffmpeg`, which reports whether `ffmpeg`/`ffprobe` are available and gives platform-specific install guidance. It also includes `video.install_ffmpeg`, which dry-runs by default and only runs package-manager commands when called with `execute: true`.

When a package manager is detected, it suggests commands such as:

```bash
brew install ffmpeg
winget install --id Gyan.FFmpeg -e
choco install ffmpeg -y
sudo apt-get install -y ffmpeg
```

## MCP Configuration

After installing or building the package, configure your MCP client to run:

```json
{
  "mcpServers": {
    "local-video-scenes": {
      "command": "npx",
      "args": ["local-video-scenes-mcp"]
    }
  }
}
```

For local development from this repository:

```json
{
  "mcpServers": {
    "local-video-scenes": {
      "command": "node",
      "args": ["/absolute/path/to/local-video-scenes-mcp/dist/server.js"]
    }
  }
}
```

## Tools

### `video.extract_scenes`

Input:

```json
{
  "path": "/path/to/bug-demo.mp4",
  "sensitivity": 0.3,
  "minGapSeconds": 1.5,
  "mode": "auto"
}
```

Optional fields:

- `sensitivity`: scene-change threshold between `0` and `1`; default `0.3`.
- `maxFrames`: maximum returned frames; default `min(80, max(12, ceil(durationSeconds / 3)))`.
- `minGapSeconds`: minimum gap between returned frames; default `1.5`.
- `outputDir`: output folder; default is a temp folder.
- `mode`: `auto`, `scene`, or `sample`; default `auto`.

Output includes:

- `duration`
- `sourcePath`
- `outputDir`
- `extractionMode`
- `maxFrames`
- `performanceEstimate`
- `warnings`
- `frames[]` with `timestamp`, `path`, `index`, and optional `sceneScore`

### `video.cleanup`

Removes the generated frame directory:

```json
{
  "outputDir": "/tmp/video-context/abc123"
}
```

### `video.check_ffmpeg`

Checks local `ffmpeg`/`ffprobe` availability and returns install guidance if either is missing.

### `video.install_ffmpeg`

Returns the detected install commands by default:

```json
{
  "execute": false
}
```

To run the detected package-manager command, call it explicitly with:

```json
{
  "execute": true
}
```

## Performance Defaults

The default frame budget is tuned for 1-minute screen recordings:

```text
maxFrames = min(80, max(12, ceil(durationSeconds / 3)))
```

For a 60-second video, this returns about 20 frames by default. On an M2 with 16GB RAM, expected V1 behavior is:

- ffmpeg extraction: usually 1-5 seconds
- Claude visual walkthrough over 12-25 screenshots: roughly 10-30 seconds
- target end-to-end time for a 1-minute video: under about 30 seconds in normal cases

## Claude Usage Guidance

When a user provides a video path:

1. Call `video.extract_scenes`.
2. Inspect the returned image paths as visual context.
3. Produce a timestamped walkthrough of visible UI states, actions, errors, code, logs, and important text.
4. Mention that audio was not analyzed.
5. Use `video.cleanup` when the generated screenshots are no longer needed.

Example:

```text
The video shows the user opening the dashboard, navigating to Export, clicking the export action, and reaching a visible HTTP 500 error around 00:01:42. Audio was not analyzed.
```

## Development

```bash
npm install
npm test
npm run typecheck
npm run build
```