AI agents & MCP

ScreenBook is built agents-first: the MCP server gives any MCP client (Claude Code, etc.) a complete authoring surface, and the tool descriptions teach the contract — agents never need to read the engine's source.

Hook it up (Claude Code)

The standard local-MCP form, via npx (no install needed):

claude mcp add screenbook -- npx -y @screenbook/engine mcp --root .

Working from a checkout instead (engine copied into the project)? Point at it directly:

node <path-to-package>/dist/cli/screenbook.js mcp --root .   # rarely needed

--root points at your project directory — the .screenbook/ inside it is found automatically. init has already dropped AGENTS.md (the universal contract) and the screenbook skill into the project, so a fresh Claude session knows the rules the moment it opens the folder.

What agents can do

Read: list_features · list_screens · get_screen · get_data (seed + scenarios + i18n) · get_theme · get_flows · get_review_comments · get_attachment

Write (validated, atomic, manifest-refreshing, date-stamping): add_screen · update_screen · remove_screen · add_feature · add_app · set_data · set_theme · set_flows · resolve_comment · attach_to_comment

Verify: validate {mode: "static"|"full"} · screenshot {feature, screen, …}

Images: generate_image (nano-banana / chatgpt / grok) · list_images · remove_image — the AI Image Playground's engine, callable by agents too. 21 tools in all.

Guardrails built in: add_screen/update_screen lint the screen contract and reject violations with actionable messages; add fails on existing screens and update on missing ones (read-then-write); every write is atomic; manifest.json is regenerated for you.

A working prompt

Add a checkout screen to the shop feature: order summary card, payment method list from the seed, a pay button that toasts. Match the existing screens' style. Validate and give me a screenshot.

A well-behaved agent will list_screens → get_screen (borrow idioms) → add_screen → validate → screenshot. Human taste, machine discipline.

The review loop

Humans leave comments in 💬 Review Mode; each comment carries screen, scenario, theme, mode, direction, device and the clicked element (its CSS path plus the click offset inside it — that's what anchors the marker to its content). Agents read them (get_review_comments {unresolvedOnly: true} — reviewer attachments ride along; read them with get_attachment), fix the screens, optionally attach_to_comment proof, and resolve_comment — a full design-review cycle without a meeting. With the studio open under serve, a resolve_comment shows up live: the screen's count badge drops and the review panel refreshes, no reload.

Serving + MCP together

Run serve while agents work: every MCP write triggers live reload, so you watch screens appear and change in the studio in real time.