# Phase 1: Core Capture Pipeline - Context

**Gathered:** 2026-04-12
**Status:** Ready for planning

<domain>
## Phase Boundary

MCP server with desktop capture, timed scheduling, and grid image compilation. Agents can trigger a timed desktop capture session via MCP tools and retrieve a properly-sized grid image with timestamps via MCP resources. Covers: MCP-01..05, CAPT-01, TIME-01..04, GRID-01..05.

</domain>

<decisions>
## Implementation Decisions

### Tool interface design
- **D-01:** Async two-tool pattern: `start_capture` returns a session ID immediately, `get_capture_status` returns progress or completed grid image
- **D-02:** `start_capture` accepts: target (desktop for Phase 1), interval_ms, max_frames, duration_ms, jpeg_quality
- **D-03:** `get_capture_status` accepts session_id, returns: status (capturing/complete/error), progress (frames captured / total), and resource URI when complete
- **D-04:** Results exposed as MCP resources at URI `capture://{session_id}/grid` returning base64 JPEG image content
- **D-05:** Structured metadata returned with results: timestamps per frame, capture duration, target info, frame count, grid dimensions

### Grid image sizing
- **D-06:** Individual frames downscaled BEFORE grid assembly to control sharp memory usage
- **D-07:** Grid auto-fits to square-ish layout within 1568x1568px max (Claude Vision optimal size)
- **D-08:** JPEG output at quality 80 by default (configurable via jpeg_quality parameter)
- **D-09:** Grid dimensions auto-calculated: ceil(sqrt(frame_count)) for square-ish layout (e.g., 9 frames = 3x3, 7 frames = 3x3 with 2 empty)

### Timestamp overlay
- **D-10:** Relative offset format: "+0.0s", "+0.5s", "+1.0s" (relative to capture start, not wall-clock)
- **D-11:** White text on semi-transparent dark background rectangle for readability on any screenshot
- **D-12:** Positioned at bottom-left of each grid cell

### Capture scheduling
- **D-13:** interval_ms (required): milliseconds between captures
- **D-14:** max_frames (optional, default 20): hard cap on frame count to prevent runaway captures
- **D-15:** duration_ms (optional): total capture duration; if both max_frames and duration_ms set, whichever limit hits first stops capture
- **D-16:** Self-correcting setTimeout pattern (not setInterval) to prevent timer drift over long sessions
- **D-17:** Captures stored in memory as PNG buffers; grid compilation happens once capture completes

### MCP server foundation
- **D-18:** All logging to stderr via a dedicated logger module -- zero stdout outside MCP JSON-RPC
- **D-19:** Stdout guard: override console.log/warn/info to redirect to stderr at server startup
- **D-20:** TypeScript with MCP SDK (@modelcontextprotocol/sdk), StdioServerTransport
- **D-21:** node-screenshots for desktop capture, sharp for image processing

### Claude's Discretion
- Exact sharp concurrency settings for memory management
- Internal buffer format (raw RGBA vs PNG between capture and grid assembly)
- Error message wording and format
- Project scaffolding structure (src/ layout, tsconfig settings)

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### MCP Protocol
- `.planning/research/STACK.md` -- MCP SDK version, API patterns, tool/resource registration
- `.planning/research/ARCHITECTURE.md` -- Component structure, data flow, async capture pattern

### Image Pipeline
- `.planning/research/STACK.md` -- sharp and node-screenshots versions, API patterns
- `.planning/research/FEATURES.md` -- LLM vision constraints (1568px max, token cost formula)

### Risk Mitigation
- `.planning/research/PITFALLS.md` -- stdout corruption, memory management, timer drift, DPI scaling

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- None -- greenfield project, no existing code

### Established Patterns
- None yet -- this phase establishes the foundational patterns

### Integration Points
- MCP server entry point (stdio transport)
- npm package.json with bin entry for MCP server invocation

</code_context>

<specifics>
## Specific Ideas

- Grid image should be optimized for Claude Vision consumption (1568px max edge, JPEG compressed)
- Timestamps should use relative offsets (+0.0s, +0.5s) not wall-clock times -- more useful for debugging
- Async capture pattern: agents start capture, do other work, then retrieve results
- Stdout guard is critical -- must be established before any other code runs

</specifics>

<deferred>
## Deferred Ideas

None -- discussion stayed within phase scope

</deferred>

---

*Phase: 01-core-capture-pipeline*
*Context gathered: 2026-04-12*