Editor Tools

Driving the editor: the tools, and the rules that keep them honest

The end state: an MCP client holding a live connection to the real editor, with the user's project open, making precise edits that land as real undo steps in a project file the user can open in the app afterwards.

Nothing here is a reimplementation. Every call lands in the same function a click in the UI lands in, inside the real editor page. That is why an edit you make is indistinguishable from an edit the user made by hand.

Starting the server

npx -y open-screenshot-generator@0 install

install detects the agent configs on this machine and writes the server entry. Prefer it over hand editing, especially on Windows where several clients need the command wrapped.

The manual form, for a config it did not know about:

{
  "mcpServers": {
    "open-screenshot-generator": {
      "command": "npx",
      "args": ["-y", "open-screenshot-generator@0", "mcp", "--stdio"]
    }
  }
}

--stdio is the default and the right choice: no port, no firewall prompt, no shared secret. Use --http --port 8722 only when the client cannot spawn a process, and it then speaks Streamable HTTP at http://127.0.0.1:8722/mcp.

Two behaviours worth knowing so the server does not feel broken:

• initialize, ping and tools/list are answered from a manifest generated at build time, with no browser at all. Every client calls tools/list at session start and paying a browser boot for a handshake would be unacceptable.
• The browser starts on the first tools/call and stays warm for the life of the connection. So the first real call is slow and every one after it is not.

One capability exists here that no other transport has: export_png and export_all with save: true actually write files. In a browser tab that throws, because a tab cannot write to disk.

For one off calls without a client, the CLI is the same surface:

npx -y open-screenshot-generator@0 call list_artboards
npx -y open-screenshot-generator@0 edit --script osg/edits.json

osg call prints the raw JSON result on stdout, so it pipes into jq. osg edit --script runs a list of calls in order, which is the quoting proof form on Windows.

The mutation rules

These are not style preferences. Each one is a way to make a call that returns success and changes nothing.

1. One call in flight, always. The tool api closes over the artboards of the render that produced it. Two mutations dispatched in the same tick both read the pre change state and the second silently clobbers the first. The CLI serializes every bridge call for exactly this reason. If you are driving the page yourself, await each response fully before sending the next. The desktop app and the web relay also put concurrent calls in one line, but a call that waits there past its time budget is refused rather than run, so a burst of parallel calls turns into errors, not speed.

2. There is one door, and it is the same door the UI uses. Every mutating tool commits through the app's single update path, which repositions the boards, writes the project, and pushes one undo entry. That is why one tool call is one Ctrl+Z, and why add_elements is strictly better than a loop of add_element: one round trip, one undo step, and nothing is added at all if any entry is rejected, so you never end up with a half built board.

3. An artboard's position is derived. It is recomputed and overwritten on every update. Authoring it does nothing. Move a board along the canvas with update_artboard index instead, 0 being leftmost.

4. x/y and width/height are not symmetric. position is written if either x or y is present, filling the missing one with 0, so update_element with only x also slams the element to y=0. size is written only when both width and height are present, so a lone width is dropped with no error at all. Always pass the pairs together.

5. An explicit null clears a property. Omitting it leaves it alone. null is the only way to remove a shadow, a fillGradient, an animation enter or exit, or a preview duration override.

6. An unknown fontFamily is rejected, not substituted. The error names the closest available families. This is deliberate: a browser silently falls back to a default serif, which looks like the design changed for no reason. list_fonts is the allowlist, filterable by script (latin, arabic, urdu, hebrew, cjk, thai, devanagari, bengali, multilingual).

7. Text does not measure the way you expect. Glyphs render at roughly 3.3x the stored fontSize and wrap inside the element box, which clips. So ~48 is a phone headline, not 96, and the real ink bounds cannot be predicted from the props. measure_element returns what the element actually occupies on the rendered canvas. Use it before aligning anything to a headline's edge.

8. Elements paint in list order, first at the back, and adding one always puts it on top. Use reorder_element to slide a background behind work you already placed, rather than rebuilding the board.

9. export_png, export_all and measure_element read the live DOM. They fail if the project is not open on screen. open_project waits two animation frames before returning for exactly this reason.

10. Upload an image once. upload_asset returns an asset:<id> reference you can pass to imageSrc or screenshotSrc as many times as you like, instead of repeating a data URL in every call. Elements keep the reference and the editor resolves it when it draws, so the bytes are stored once. A reference that does not exist is refused when you pass it, never drawn as an empty frame. Pass the whole asset:<id>, not the bare id.

11. A recording is not an asset. upload_asset probes bytes as an image and refuses a video. Screen recordings go through upload_recording and elements carry only the mediaId it returns. Prefer an http(s) URL over base64 for anything large: a request body is capped at 32 MiB.

12. Every language tool except two writes the base document. Only set_locale and the locale arguments read a per language projection. See the store-localization skill.

13. Adding a video-device, video or gesture element, or any animation, switches the whole project to the video export path. Never put one on a screenshot board.

14. delete_artboard refuses the last board. A project with zero artboards leaves the canvas stuck loading.

15. Errors come back as data. An unknown tool is a JSON-RPC -32602. A tool that rejected your arguments is a normal result with isError and a sentence saying what to do. Read the sentence, it usually names the tool to call instead.

16. Slow tools get a longer budget. export_png, export_all, apply_template, create_project_from_template, open_project, add_elements, duplicate_artboard, update_artboard, translate_locales, add_locales, upload_asset and upload_recording are allowed minutes. Everything else answers in seconds, and a hang means a dialog is open in the page.

The tools, by job

Find out what is there (start every session here)

Boards

create_artboard (width and height, or a preset id like ios-6-3, the required iPhone size at 1206x2622), duplicate_artboard, update_artboard (rename, resize, reorder), delete_artboard, set_active_artboard, set_background (solid or a two stop gradient, and a half filled gradient is refused rather than stored).

The fastest way to build a store set: build one board properly, duplicate_artboard per screen, then change only the headline and the screenshot. Rename every board, because the name becomes the exported file name and a board left as "Blank Artboard" exports as one.