Imported from jeandelest/screen-mcp (AGENTS.md). Install upstream with npx skills add jeandelest/screen-mcp. Copyright stays with the author.

AGENTS.md

This file defines the operational rules for contributing to the screen-mcp project.

Project goal

• Expose a FastMCP MCP server for client-side screenshot capture.
• Return compact, stable, and secure responses for LLM usage via tools.

Technical principles

• Use FastMCP (the fastmcp module) as the server API.
• Keep tools synchronous unless there is a real async I/O need.
• Return strict, documented JSON structures (no ambiguous free text).
• Avoid response schema changes without updating the documentation.

Code conventions

• Target Python: 3.10+.
• Use uv as the base command for project Python commands (uv sync, uv run, uvx).
• Require type hints on all public functions.
• Use explicit, actionable error messages.
• Avoid business logic in utility scripts: centralize it in src/screen_mcp/.
• Keep external dependencies to the minimum required.

Expected MCP tools

• list_monitors: stable inventory of detected monitors.
• capture_screenshot: base64 capture with format/resizing options.
• capture_timeline: multi-frame timed capture with chronological metadata.
• start_timeline_capture: start a timeline session with timeline_id.
• get_timeline_manifest: expose chunked timeline metadata.
• get_timeline_chunk: JSON pagination for the timeline.
• release_timeline_capture: explicitly release a timeline session.
• start_screenshot_capture: start a capture session with capture_id.
• get_screenshot_manifest: expose metadata plus ASCII preview for non-vision clients.
• get_screenshot_chunk: base64 pagination for large payloads.
• release_screenshot_capture: explicitly release a capture session.

Security and privacy

• Never enable implicit looped capture without explicit user consent.
• Clearly state that captures may contain secrets.
• Prefer targeted captures (monitor/region) to minimize data exposure.
• Do not persist images to disk by default.

Robustness

• Validate inputs strictly (monitor_index, image_format, max_width, quality).
• Keep errors deterministic (no raw traceback in tool responses).
• Maintain API compatibility across minor versions.

AGENTS governance

• This file is the authoritative source for project rules and must be consulted before any code or tool schema changes.
• For every LLM exchange involving the project MCP tools, apply this file's rules first, then session-specific instructions.
• If instructions conflict, prioritize: security/privacy > API compatibility > robustness > style.

Size budget

• Target size: <= 180 lines.
• Maximum size: 220 lines.
• If an update exceeds the target, compact it before adding: merge duplicates, remove non-critical examples, keep only actionable rules.
• If an update exceeds the maximum, do not add it directly; move details to the README or a dedicated document and keep a short summary here with a link.
• Avoid long narrative blocks; prefer short, testable rule lists.

Recommended workflow

1. Initialize the Python environment: uv sync.
2. Set up the project: task setup.
3. Start the server via mcpm: task server.
4. Start the smoke-test client: task client.
5. Observe exchanges with MCP Inspector: task inspector.

Minimum validation criteria before commit

• The server starts without error.
• The smoke-test client calls list_monitors and capture_screenshot successfully.
• The payload size is reasonable (test max_width).
• The README matches actual behavior.