fenestra-mcp

A Model Context Protocol server that lets an AI assistant render and verify native UIs described as fenestra fenestra/1 JSON.

Install

cargo install fenestra-mcp

The server speaks MCP over stdio — point your MCP client at the fenestra-mcp binary.

Tools

• describe_vocabulary — the description grammar: every node type with a minimal example, and the theme color roles a color may name. Call this first.

• describe_schema — the formal JSON Schema for a fenestra/1 description, the machine-checkable complement to describe_vocabulary.

• render_ui — render to a typed access tree, a downscaled preview image, and automatic accessibility warnings.

• query_ui — find nodes by a semantic selector (role, name, value, or id); a miss returns the nearest candidates to guide a retry.

• interact — drive scripted interactions (click, type, key, tab, hover, wheel, drag) by semantic selector, never coordinates.

• check_a11y — theme contrast, labeling of every interactive control, and per-text-node APCA + WCAG 2 legibility.

• focus_order — the keyboard focus order: the refs a Tab cycle visits, in order, honoring a modal focus trap.

• check_layout — layout geometry from the real frame: interactive targets below the minimum hit size, and signal-bearing nodes clipped off-screen.

• match_aria_snapshot — assert an expected accessibility snapshot (partial / strict / regex).

• match_screenshot — compare against a baseline PNG, pixel by pixel, with an optional tolerance, differing-pixel budget, and mask rectangles to ignore.

• validate — validate a description without rendering; problems come back path-pointed.

• run_scenario — drive a description + optional steps through a whole bundle of expectations (emitted intents, a11y, aria, screenshot, queries) in one pass, asserted against the post-interaction frame.

• film_ui — drive optional steps (applied first, so a click can trigger the transition to watch), then capture frames with real motion on and compose them into one captioned filmstrip. The one tool that turns reduced motion off — every other tool stays reduced-motion for deterministic pixels.

Each tool leads with a typed structured result — query_ui, check_a11y, focus_order, check_layout, match_aria_snapshot, and describe_vocabulary carry a formal outputSchema so a client knows the result shape up front. The visual tools also attach a downscaled preview image and a resource_link to the full-resolution PNG (a file:// temp path), so a large image never bloats the response yet stays one fetch away.

Where baselines are read from

Two tools take a path to a PNG on disk: match_screenshot, and run_scenario through its expect.screenshot.baseline. That path arrives inside a tool call, which means it comes from an agent — and an agent is only as trustworthy as whatever it last read. So the server reads baselines from one directory and no further.

By default that directory is the working directory the MCP client launched the server in, which is the project being worked on. Set FENESTRA_MCP_BASELINE_ROOT to point somewhere else. Paths in a tool call may be relative to the root or absolute inside it; anything that resolves outside — including a symlink inside the root pointing out of it — is refused, and the refusal names the root so a legitimate call can be retried. A root that is not a readable directory stops the server from starting rather than silently widening to the default.

The diff image a failed comparison returns draws the rendered pixels, never the baseline's, for the same reason.

Registry

• MCP Registry name: mcp-name: io.github.richer-richard/fenestra-mcp

License

Licensed under either of MIT or Apache-2.0 at your option.