# Requirements: Screen Timelapse MCP Server

**Defined:** 2026-04-12
**Core Value:** Agents can visually observe how a screen region changes over time in a single digestible image

## v1 Requirements

Requirements for initial release. Each maps to roadmap phases.

### MCP Server Foundation

- [x] **MCP-01**: Server starts via stdio transport and responds to MCP protocol handshake
- [x] **MCP-02**: Server exposes tools for capture configuration and triggering
- [x] **MCP-03**: Server exposes resources for retrieving compiled grid images
- [x] **MCP-04**: All logging goes to stderr only -- zero stdout pollution outside MCP protocol
- [x] **MCP-05**: Server returns structured metadata (timestamps, window title, region, frame count) alongside results

### Capture Targeting

- [x] **CAPT-01**: User can capture the full desktop screen
- [x] **CAPT-02**: User can capture a specific application window by title or handle
- [x] **CAPT-03**: User can capture a rectangular screen region (x, y, width, height)
- [x] **CAPT-04**: User can capture a region defined relative to a window's position
- [x] **CAPT-05**: User can list all visible windows with title, handle, and process info

### Timed Capture

- [x] **TIME-01**: User can set the time interval between screenshots (e.g., every 500ms, 1s, 5s)
- [x] **TIME-02**: User can set a maximum number of screenshots to capture
- [x] **TIME-03**: User can set a total capture duration as an alternative to max count
- [x] **TIME-04**: Capture uses self-correcting timers to prevent drift over long sessions
- [x] **TIME-05**: Capture handles target window closing/minimizing gracefully (skip frame, report)

### Grid Compilation

- [x] **GRID-01**: All captured screenshots are compiled into a single square grid image
- [x] **GRID-02**: Grid dimensions are auto-calculated based on frame count (e.g., 3x3 for 9 frames)
- [x] **GRID-03**: Grid image is auto-resized to stay within LLM vision constraints (1568px max edge)
- [x] **GRID-04**: Each grid cell has a timestamp overlay showing when the frame was captured
- [x] **GRID-05**: Grid output uses JPEG compression with configurable quality for size optimization

### Diagnostic Features

- [x] **DIAG-01**: User can enable delta highlighting to show regions that changed between consecutive frames
- [x] **DIAG-02**: Idle frame compression collapses sequences of identical frames into one with "unchanged for Ns" label
- [x] **DIAG-03**: User can optionally export the capture sequence as an animated GIF

### Distribution

- [x] **DIST-01**: Tool is packaged as a cplugs marketplace plugin
- [x] **DIST-02**: Plugin installs via `/plugin install screen-timelapse@cplugs`
- [x] **DIST-03**: Plugin includes MCP server configuration for automatic registration

## v2 Requirements

Deferred to future release. Tracked but not in current roadmap.

### Advanced Features

- **ADV-01**: Smart capture triggers -- only capture when screen content actually changes
- **ADV-02**: Concurrent capture sessions with independent named sessions
- **ADV-03**: Frame annotations -- agents can label specific frames (e.g., "before click", "after click")
- **ADV-04**: Multi-monitor selection -- choose which monitor to capture
- **ADV-05**: Configurable grid layouts (force 2x3, 4x4, etc.) overriding auto-calculation

## Out of Scope

Explicitly excluded. Documented to prevent scope creep.

| Feature | Reason |
|---------|--------|
| Video recording / streaming | Too heavy for diagnostic use; LLMs cannot consume video |
| OCR / text extraction | LLMs already have vision capabilities; duplicating adds no value |
| Real-time live preview | Capture-and-review tool, not a monitoring dashboard |
| Cross-machine remote capture | Networking/auth complexity; local-only keeps it simple |
| Browser tab capture via DevTools | Existing Playwright/Chrome MCP tools handle this |
| Multi-monitor stitching | Rare use case; support monitor selection but not stitching |
| Lossless full-resolution archival | Wastes disk space and exceeds LLM input limits |

## v1.1 Requirements

Requirements for native DWM window capture milestone.

### Native Capture Addon

- [ ] **DWM-01**: Native C++ NAPI addon compiles on Windows with cmake-js and produces a loadable .node binary
- [ ] **DWM-02**: Addon can capture a specific window by HWND using DWM composition APIs (no PrintWindow/WM_PRINT)
- [ ] **DWM-03**: Captured frames are returned as PNG buffers to JavaScript with correct RGBA pixel data
- [ ] **DWM-04**: Capture does not cause visible flicker or rendering disruption in the target window
- [ ] **DWM-05**: Capture ignores overlapping windows (reads from DWM composition, not screen buffer)

### Integration

- [ ] **DWM-06**: WindowTarget automatically uses DWM capture when the native addon is available
- [ ] **DWM-07**: WindowTarget falls back to monitor-crop when the native addon is unavailable or DWM capture fails
- [ ] **DWM-08**: WindowRegionTarget also benefits from DWM capture (window capture + crop)
- [ ] **DWM-09**: Fallback is transparent — agents see no difference in the MCP tool interface

### Robustness

- [ ] **DWM-10**: Native addon crash does not terminate the MCP server process
- [ ] **DWM-11**: Addon handles minimized, cloaked, and destroyed windows gracefully (returns error, does not crash)
- [ ] **DWM-12**: COM/DirectX resources are properly released after each capture (no GDI handle leaks)

### Distribution

- [ ] **DWM-13**: Prebuilt Windows x64 binary is included in the npm package (no build tools required at install time)
- [ ] **DWM-14**: Updated cplugs marketplace plugin includes the native addon

### v1.1 Out of Scope

| Feature | Reason |
|---------|--------|
| ARM64 Windows prebuilt binary | Rare target; can be added later if demand exists |
| Linux/macOS DWM equivalent | DWM is Windows-only; other platforms keep monitor-crop |
| Persistent capture sessions (keep DWM session alive between captures) | Adds lifecycle complexity; per-capture sessions are sufficient for 500ms+ intervals |
| Yellow border removal consent flow | If WGC is chosen, accept the border rather than adding interactive consent |

## Traceability

Which phases cover which requirements. Updated during roadmap creation.

### v1.0 (Phases 1-4) -- Complete

| Requirement | Phase | Status |
|-------------|-------|--------|
| MCP-01 | Phase 1 | Complete |
| MCP-02 | Phase 1 | Complete |
| MCP-03 | Phase 1 | Complete |
| MCP-04 | Phase 1 | Complete |
| MCP-05 | Phase 1 | Complete |
| CAPT-01 | Phase 1 | Complete |
| CAPT-02 | Phase 2 | Complete |
| CAPT-03 | Phase 2 | Complete |
| CAPT-04 | Phase 2 | Complete |
| CAPT-05 | Phase 2 | Complete |
| TIME-01 | Phase 1 | Complete |
| TIME-02 | Phase 1 | Complete |
| TIME-03 | Phase 1 | Complete |
| TIME-04 | Phase 1 | Complete |
| TIME-05 | Phase 2 | Complete |
| GRID-01 | Phase 1 | Complete |
| GRID-02 | Phase 1 | Complete |
| GRID-03 | Phase 1 | Complete |
| GRID-04 | Phase 1 | Complete |
| GRID-05 | Phase 1 | Complete |
| DIAG-01 | Phase 3 | Complete |
| DIAG-02 | Phase 3 | Complete |
| DIAG-03 | Phase 3 | Complete |
| DIST-01 | Phase 4 | Complete |
| DIST-02 | Phase 4 | Complete |
| DIST-03 | Phase 4 | Complete |

### v1.1 (Phases 5-7) -- In Progress

| Requirement | Phase | Status |
|-------------|-------|--------|
| DWM-01 | Phase 5 | Pending |
| DWM-02 | Phase 5 | Pending |
| DWM-03 | Phase 5 | Pending |
| DWM-04 | Phase 5 | Pending |
| DWM-05 | Phase 5 | Pending |
| DWM-06 | Phase 6 | Pending |
| DWM-07 | Phase 6 | Pending |
| DWM-08 | Phase 6 | Pending |
| DWM-09 | Phase 6 | Pending |
| DWM-10 | Phase 6 | Pending |
| DWM-11 | Phase 6 | Pending |
| DWM-12 | Phase 6 | Pending |
| DWM-13 | Phase 7 | Pending |
| DWM-14 | Phase 7 | Pending |

**Coverage:**
- v1.0 requirements: 26 mapped, 26 complete
- v1.1 requirements: 14 total, 14 mapped, 0 unmapped
- Overall: 40/40 mapped

---
*Requirements defined: 2026-04-12*
*Last updated: 2026-04-12 after v1.1 roadmap creation*