The MCP server

npx edityy mcp is a stdio MCP server. It hands the saved edits and the variation requests to a coding agent.

Adding the server

Claude Code

terminal

claude mcp add edityy -- npx edityy mcp

Cursor, or any client configured with JSON

mcp.json

{
  "mcpServers": {
    "edityy": { "command": "npx", "args": ["edityy", "mcp"] }
  }
}

The server reads from the directory it is started in. Pass --root <dir> to read from another one.

The tools

There are seven.

get_visual_changes

Returns the edits in .edityy/changes.json, as the same Markdown that Copy for an agent copies. Each edited element comes with a CSS selector, its source location when it is known, every property and text change as before and after, and any comment you wrote about it.

Apply them to the source code, then call clear_visual_changes.

clear_visual_changes

Deletes the saved visual edits, so they are not applied twice. Call it only after the code holds the change.

get_variation_request

Returns what you asked for on one element: the number of variations, their optional comment, the element’s tag, its selector and its current values. The agent never sees your code for this.

Read it at the start of every vartest. You may have asked again since the last one, and an answer for an old request is refused.

place_variations

Takes the answer: that many variations of plain CSS declarations, for you to try on the live element.

Each variation is a label and a list of declarations.

{
  "requestId": "the id get_variation_request returned",
  "variations": [
    {
      "label": "thin grey",
      "props": [
        { "property": "scrollbar-width", "value": "thin" },
        { "property": "scrollbar-color", "value": "#8a8a8a transparent" }
      ]
    },
    {
      "label": "notched",
      "props": [
        {
          "property": "background",
          "value": "#f43f5e",
          "on": "::-webkit-scrollbar-thumb"
        }
      ]
    }
  ]
}

on is a state or a pseudo-element, such as :hover, :focus-visible or ::before.
when is a media condition, such as (max-width: 640px).
A custom property, an at-rule in place of when, !important or url() is refused.

Place exactly what was asked for

Fewer variations than the request is refused. More is not a refusal, but the first ones are the ones you see.

place_preview

The user typed edityy:: in the agent chat. Place that change on the live canvas only. Do not edit files for it.

Each preview is an instruction, an action, and the payload that action needs:

styles restyles one element: a selector and 1 to 10 labeled variations.
insert adds allowlisted markup near an anchor, or at the end of main.
update changes one element: its styles, its words or its markup.
remove takes one element away.

{
  "instruction": "add a pricing section",
  "action": "insert",
  "position": "inside-end",
  "html": "<section class="pricing"><h2>Plans</h2></section>"
}

The page shows the preview with Keep and Discard. Keys 1 to 0 try each look of a styles preview, and Escape discards.

Ask before you guess

If the user names no place and the place is unclear, ask them first. A preview that lands somewhere they did not mean is worse than a question.

Safety

Markup is allowlisted twice: once on the server, and again in the page before it paints. A script tag, an event attribute, an iframe, a form or a javascript: link is refused. So is a style attribute.

get_preview

Returns one preview by its id, or the active one, with its instruction, action and payload. Apply a kept preview by reading its saved edit with get_visual_changes.

decide_preview

Marks one preview keep or discard, once the user says implement <id> or discard <id>.

The files

The server and the page share four files in your project.

.edityy/
  changes.json             the saved edits
  variation-request.json   what you asked for
  variation-response.json  what the agent answered
  previews.json            the canvas previews and their history

The folder gets its own .gitignore, so pending edits never end up in a commit. Your agent reads the same files the page writes.