## Project **Screen Timelapse MCP Server** An MCP (Model Context Protocol) server that enables AI agents to capture sequences of screenshots over time from specific windows, screen regions, or the full desktop, and compile them into a single grid image for visual comparison. Designed for agents debugging timing-based issues like app hangs, UI flicker, or transient visual bugs. **Core Value:** Agents can visually observe how a screen region changes over time in a single digestible image, enabling diagnosis of timing-based issues that a single screenshot cannot capture. ### Constraints - **Platform**: Windows 11 primary target -- must use Windows-compatible screenshot APIs - **Protocol**: Must implement MCP server spec (tools + resources over stdio) - **Distribution**: Must be publishable as a cplugs marketplace plugin - **Performance**: Screenshot capture should not noticeably slow the target application - **Image Size**: Grid images must be reasonable size for LLM consumption (not excessively large) ## Technology Stack ## Recommended Stack ### Runtime & Language | Technology | Version | Purpose | Why | Confidence | |------------|---------|---------|-----|------------| | Node.js | 20 LTS | Runtime | MCP SDK target runtime; LTS stability; native addon support for node-screenshots | HIGH | | TypeScript | 5.5+ | Language | Type safety for MCP protocol types; standard for MCP servers | HIGH | ### MCP Framework | Technology | Version | Purpose | Why | Confidence | |------------|---------|---------|-----|------------| | @modelcontextprotocol/sdk | ^1.29.0 | MCP server framework | Official SDK; McpServer class with registerTool/registerResource; StdioServerTransport for CLI integration | HIGH | | zod | ^3.25.0 | Schema validation | Required by MCP SDK for tool input schemas; SDK imports from zod/v4 internally but works with v3.25+ | HIGH | ### Screen Capture | Technology | Version | Purpose | Why | Confidence | |------------|---------|---------|-----|------------| | node-screenshots | ^0.2.8 | Desktop/window/region capture | Native library (no external deps); provides Monitor, Window, and Image classes; supports window enumeration, individual window capture, and region cropping; async + sync APIs; cross-platform | HIGH | - `screenshot-desktop` (v1.15.3): Only captures full desktop, no window targeting or region cropping. Shells out to external tools (nircmd on Windows). No window enumeration API. - `win-screenshot`: Windows-only, less maintained, no cross-platform path. - `node-screenshots` provides exactly what we need: `Window.all()` to enumerate windows, `window.captureImage()` to capture specific windows, `image.crop(x, y, w, h)` for region capture, and `Monitor.all()` for full desktop capture. ### Image Processing | Technology | Version | Purpose | Why | Confidence | |------------|---------|---------|-----|------------| | sharp | ^0.34.5 | Grid compilation, timestamp overlay, resize, delta highlighting | Fastest Node.js image processor (libvips); composite() API for placing multiple images on a canvas; text overlay support; handles PNG/JPEG/WebP | HIGH | - `jimp`: Pure JS, significantly slower. For a grid of 16+ screenshots, performance matters. - `canvas` (node-canvas): Requires Cairo native deps; harder Windows install; overkill for compositing. - sharp's `composite()` method directly supports placing multiple images at calculated grid positions on a created canvas. This is the exact operation needed for grid compilation. ### GIF Generation (Optional Feature) | Technology | Version | Purpose | Why | Confidence | |------------|---------|---------|-----|------------| | @skyra/gifenc | ^1.0.1 | Animated GIF export | Fast server-side GIF encoding; drop-in modern replacement for gifencoder; chainable API; actively maintained | MEDIUM | - `gifencoder` (v2.0.1): Last published 7+ years ago, effectively unmaintained. - `gif-encoder-2`: Less active community. - `@skyra/gifenc` is the modern actively-maintained option with the same API shape. ### Build & Dev Tools | Technology | Version | Purpose | Why | Confidence | |------------|---------|---------|-----|------------| | tsx | ^4.0.0 | TypeScript execution | Fast dev execution without separate compile step; esbuild-based | HIGH | | tsup | ^8.0.0 | Build/bundle | Simple bundler for TypeScript libraries; produces CJS/ESM; zero-config for most cases | HIGH | | @types/node | ^20.0.0 | Node.js type definitions | TypeScript support for Node.js APIs | HIGH | ## Alternatives Considered | Category | Recommended | Alternative | Why Not | |----------|-------------|-------------|---------| | Screen Capture | node-screenshots | screenshot-desktop | No window targeting, no region crop, shells out to external tools | | Screen Capture | node-screenshots | win-screenshot | Windows-only, less maintained, smaller community | | Image Processing | sharp | jimp | 10-50x slower for compositing operations; pure JS | | Image Processing | sharp | node-canvas | Harder native dep install on Windows; Cairo required; API overkill | | GIF Encoding | @skyra/gifenc | gifencoder | Unmaintained (7+ years old) | | MCP Framework | @modelcontextprotocol/sdk | fastmcp | Official SDK is the standard; fastmcp adds abstraction but less control | | Bundler | tsup | esbuild direct | tsup wraps esbuild with better DX for library output | ## Key Integration Patterns ### MCP Tool Registration Pattern ### Screen Capture Pattern ### Grid Compilation Pattern ## Installation # Core dependencies # Optional: GIF export # Dev dependencies ## Project Configuration ### package.json (key fields) ### tsconfig.json (key fields) ## Native Dependency Notes - **node-screenshots**: Ships prebuilt binaries for Windows x64/arm64, macOS, Linux. No build tools required at install time. Uses NAPI for native bindings. - **sharp**: Ships prebuilt libvips binaries. Auto-downloads correct platform binary during `npm install`. No manual setup on Windows 11. - Both libraries handle their native deps automatically -- no C++ compiler or Windows Build Tools needed. ## Sources - [@modelcontextprotocol/sdk on npm](https://www.npmjs.com/package/@modelcontextprotocol/sdk) - v1.29.0, MCP server framework - [MCP TypeScript SDK server docs](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/server.md) - McpServer API patterns - [node-screenshots on GitHub](https://github.com/nashaofu/node-screenshots) - v0.2.8, native screen capture - [sharp official site](https://sharp.pixelplumbing.com/) - v0.34.5, image processing - [sharp composite API](https://sharp.pixelplumbing.com/api-composite/) - Grid/montage compositing - [@skyra/gifenc on npm](https://www.npmjs.com/package/@skyra/gifenc) - GIF encoding - [screenshot-desktop on npm](https://www.npmjs.com/package/screenshot-desktop) - v1.15.3, considered and rejected ## Conventions Conventions not yet established. Will populate as patterns emerge during development. ## Architecture Architecture not yet mapped. Follow existing patterns found in the codebase. ## Project Skills No project skills found. Add skills to any of: `.claude/skills/`, `.agents/skills/`, `.cursor/skills/`, or `.github/skills/` with a `SKILL.md` index file. ## GSD Workflow Enforcement Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync. Use these entry points: - `/gsd-quick` for small fixes, doc updates, and ad-hoc tasks - `/gsd-debug` for investigation and bug fixing - `/gsd-execute-phase` for planned phase work Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it. ## Developer Profile > Profile not yet configured. Run `/gsd-profile-user` to generate your developer profile. > This section is managed by `generate-claude-profile` -- do not edit manually.