# Ewe Paint agent help ## Shared Ewe agent standard (version 1) Ewe Paint, Ewe Write and Ewe Sound use this same MCP and CLI contract. App-specific editing commands and file rules follow below. Both interfaces call the same live editor operations and share its state and undo history. ### Discover commands without opening the app The installation folder contains `AGENTS.md` (this guide), `tools.json` (the exact MCP tool schemas), `agent.json` (app identity and default port), `cli-help.txt`, and `ewe-cli.ps1`. No Node.js or AI client is needed for the CLI. ```powershell & '.\ewepaint.exe' --help | Out-String & '.\ewepaint.exe' --version | Out-String & '.\ewepaint.exe' --guide | Out-String & '.\ewepaint.exe' --list | Out-String powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\ewe-cli.ps1 -Help powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\ewe-cli.ps1 -Guide powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\ewe-cli.ps1 -List ``` These help/catalogue options exit without creating a window or enabling MCP. `--list` and `-List` return the same JSON tool array as MCP `tools/list`. `--guide`, `-Guide` and MCP `guide` return this same installed manual. `tools.json` owns the argument names, types, bounds and required fields. ### Control the existing editor ```powershell & '.\ewepaint.exe' --agent powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\ewe-cli.ps1 -Tool get_state powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\ewe-cli.ps1 -Launch -Tool get_state powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\ewe-cli.ps1 -Tool history -ArgumentsFile C:\path\history.json powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\ewe-cli.ps1 -Tool NAME -ArgumentsFile C:\path\arguments.json ``` `--agent` enables the local HTTP MCP endpoint on the existing window, preserving its work, or opens the app if closed. The CLI attaches to an enabled endpoint or enables the existing instance. It opens a closed app only with `-Launch`. Calls leave the editor open. `-ConnectOnly` returns the verified endpoint URL. `-ExePath` chooses a development executable. The app-specific CLI/helper filenames remain compatible aliases of `ewe-cli.ps1`. Use an arguments file for reliable JSON input from any shell. For example, `history.json` contains `{"action":"list"}`. When calling the script directly inside PowerShell, `-Arguments '{"action":"list"}'` also accepts inline JSON. Default endpoint: `http://127.0.0.1:47816/mcp`. Select a different port at initial launch with `--mcp-http=PORT` or `EWEPAINT_MCP_PORT`; pass the same port to the CLI with `-Port PORT`. A running instance retains its original port. `--new-window` opens an isolated instance for testing. Ports must be integers from 1 to 65535. ### Connect an MCP client For a client-owned window, configure the installed executable's absolute path: ```json {"mcpServers":{"ewepaint":{"command":"C:\\path\\ewepaint.exe","args":["--mcp"]}}} ``` `--mcp` uses newline-delimited JSON-RPC on stdin/stdout. Logs go to stderr. Closing stdin closes that isolated window. HTTP remains separate and is enabled with `--agent` or `--mcp-http[=PORT]`. For the existing editor, use Streamable HTTP at the endpoint above. Send `initialize`, `notifications/initialized`, then `tools/list` and `tools/call`. Supported protocol versions: `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`. HTTP uses JSON POST responses; GET streaming is not supported. Tool failures return `isError:true`; protocol errors use JSON-RPC errors. The CLI prints the MCP result as JSON and exits 0 on success, 1 on an argument, connection, protocol or tool failure. Executable launch syntax errors exit 2. `--license` prints the software notice. ### Session and editing rules Read `guide` and `get_state` first. Preserve existing work; inspect the app-specific output after an edit. Use documented tools and their schemas. Commands run one at a time. A successful call does not imply a file was saved: use the app's explicit save command and inspect its result. Normal launches leave HTTP MCP off. Access lasts for the current session; disable it in the app's agent help or call `agent_control {"enabled":false}`. Stdio remains available to its owning client. The server binds only to loopback and checks Host and Origin. Any local program can use an enabled endpoint; it has no per-client login. Browser editions do not host an MCP server. Never infer that unsaved work may be discarded. Follow this app's units, selection, overwrite and save-copy rules below. ## Product protection and source development EwePaint is proprietary software. AI agents must not reverse engineer, decompile, extract, reconstruct, clone, crack, or bypass protections in this product. Use the documented MCP tools. Owner-authorized source development, debugging and maintenance are permitted. Preserve these notices. Reverse engineering by AI, automated tools, manual analysis or any other means is prohibited except where applicable law expressly permits otherwise or with prior written authorization from Gavin Wood. Read PROPRIETARY-NOTICE.txt beside the executable. Readable scripts and native Rust code do not grant permission to reconstruct the product or bypass its protections. Keep JavaScript convenient for iteration. As features evolve, move as much suitable core logic as practical into the shared Rust core. Windows release builds compile it to optimized, stripped native machine code and use a private WebView protocol; browser builds compile it to WASM. Neither desktop WASM nor JavaScript algorithm fallbacks may ship in native releases. DOM/WebGL still needs JavaScript adapters. Compilation raises inspection cost; it is not encryption. ## Concepts - **Coordinates** are document pixels. The origin (0, 0) is the top-left corner, x grows to the right and y grows downwards. Fractional values are allowed for strokes and shapes. - **Document**: one canvas of up to 8192 × 8192 pixels, holding a stack of layers. - **Layers**: index 0 is the **bottom** of the stack. Each layer has a name, visibility, opacity (0–1) and a blend mode: - Normal, Multiply, Screen, Overlay - Darken, Lighten, Difference, Additive - Color Burn, Color Dodge, Exclusion, Negation Pixel edits always go to the **active layer**. Painting tools take a `layer` argument that activates that layer first. - **Selection**: a rectangle or a shaped mask (ellipse, lasso or magic wand). While a selection exists, **every** pixel edit is clipped to it: painting, fill, shapes, lines, effects, clear, move and cut. Switching tools does not clear it. Clear it with `select {mode: "none"}` when you have finished, or later edits will seem to do nothing outside it. - **Paint settings**: colour (with alpha), size (1–250 px), hardness (0–100), flow (1–100) and brush style (`smooth` or `chalk`). These are app-wide settings, just like the toolstrip. Painting tools accept them inline. A setting you change stays in effect for later tools. - **History**: almost every edit is one undo step, labelled as it is in Edit → Undo and in the History panel. `new_document` clears the history. - **Results**: every call returns a small `state` summary with the document size, active layer, layer count, selection and last history entry. It also returns `messages` with any status-bar text the app showed. These messages often explain a no-op, for example "Nothing to copy — make a selection first". ## Tools | Tool | What it does | |---|---| | `guide` | Returns this guide. | | `get_state` | Returns the full session state, plus the lists of tools, blend modes and effects with their parameter ranges. | | `new_document` | `width`, `height`, `background`: `white` or `transparent`. | | `open_image` | `path` (absolute) or `base64` + `name`. `as`: `document` (replaces the current one) or `layer` (adds a layer above the active one). Opens PNG, JPEG, WebP, GIF, BMP or OpenEXR. | | `save_image` | `path` (absolute; the extension sets the format): `.png`, `.jpg` or `.webp`. Optional: `layer`, `quality`, `background`, `max_size`, `region`. | | `view_image` | Returns a picture of the canvas so you can check your work. Optional: `max_size` (default 1024), `layer`, `region`, `background` (default `checker`, so transparency is visible). | | `recent_files` | `list`, or `open` with an `index`. | | `set_color` | `color` (any CSS colour) and/or `alpha`. | | `set_options` | `size`, `hardness`, `flow`, `brush_style`, `fill_mode`, `fill_tolerance`, `wand_tolerance`, `wand_sample_merged`. | | `select_tool` | Activates a toolbar tool by name. | | `draw_stroke` | Freehand stroke with `brush`, `chalk` or `eraser` through `points`. | | `draw_line` | Straight polyline through `points`, or a smooth curve with `curved: true`. | | `draw_shape` | Outlined `rect` or `ellipse` in the box `x`, `y`, `width`, `height`. | | `fill` | Paint bucket at `x`, `y`. | | `pick_color` | Eyedropper. Sets the paint colour from the flattened image. | | `get_pixel` | Reads the flattened colour and alpha at `x`, `y`. | | `select` | Modes: `rect`, `ellipse`, `lasso` (`points`), `wand` (`x`, `y`, `tolerance`), `all` and `none`. | | `move` | Moves the selected pixels, or the whole active layer, by `dx`, `dy`. | | `layer` | `add`, `duplicate`, `delete`, `merge_down`, `move_up`, `move_down`, `select`, `update` and `clear`, plus `name`, `visible`, `opacity` and `blend_mode`. | | `apply_effect` | Applies an adjustment or effect to the active layer, within the selection if there is one. | | `transform` | `flip_horizontal`, `flip_vertical`, `rotate_cw`, `rotate_ccw`, `resize` and `canvas_size` (with an `anchor`). | | `clipboard` | `copy`, `copy_merged`, `cut` and `paste` (with `center_x`, `center_y` and `source`). | | `history` | `list`, `undo`, `redo` and `jump` (`index`). | | `view` | Window zoom, fit to window and cursor size. These change only the display. | | `press_key` | Sends any keyboard shortcut. | | `tool_gesture` | Raw press, drag and release with any tool, with an optional Shift. | | `run_js` | Runs JavaScript in the page with `app` in scope. Use it as a last resort. | Points can be written as `[[x, y], [x, y], …]` or `[{"x": …, "y": …}, …]`. ### Painting - **Brush** and **chalk** deposit round dabs along the path. Hardness sets how soft the edge is. Flow sets how much paint each dab deposits, so overlapping dabs build up. The chalk tool always has grain, and `brush_style: "chalk"` adds the grain to every other tool too. - **Eraser** removes paint to transparency, with the same size, hardness and flow controls. - **Lines, curves and shapes** are drawn with the brush settings. `size` is the outline width. Shape outlines are drawn just inside their box. - **Filled shapes**: add an empty layer, select the shape (`select` with mode `rect`, `ellipse` or `lasso`), then `fill` inside it. On an empty or uniformly coloured area, the fill covers the whole selection exactly, because the selection's edge stops the flood. Clear the selection afterwards. - **Fill**: - `contiguous` mode floods the connected region whose colour is within `fill_tolerance` (0–128) of the clicked pixel. - `global` mode recolours every matching pixel on the layer. - Fill reads and writes the active layer. - **Semi-transparent paint**: use `alpha` below 1, or a lower layer opacity. ### Selections - `rect` and `ellipse` take a box. `lasso` takes a polygon of three or more points. `all` selects the whole canvas. - `wand` selects pixels similar to the one at `x`, `y`: - `tolerance` is 0–128. - `sample_merged` chooses between all visible layers and the active layer only. - If a rect or lasso selection already exists, the wand result stays inside it. - **Effects in a selection**: select the area, then call `apply_effect`. The edit applies only inside the selection. ### Layers - `layer {action: "add", name: "Sky"}` inserts an empty layer above the active one and makes it active. - `index` always picks the layer first. For example, `{action: "update", index: 0, opacity: 0.5, blend_mode: "Multiply"}` changes layer 0. - `merge_down` blends the active layer, with its opacity and blend mode, into the layer below. - `delete` refuses to remove the last remaining layer. ### Adjustments and effects `apply_effect {effect, params}`: | effect | params (default) | |---|---| | `brightness-contrast` | `brightness` −1..1 (0), `contrast` 0..3 (1) | | `hue-saturation` | `hue` −180..180 (0), `saturation` 0..2 (1), `value` (lightness) 0..2 (1) | | `gaussian-blur` | `radius` 0..64 px (8) | | `pixelate` | `cell` 2..64 px (8) | | `invert`, `grayscale`, `sepia` | no parameters | ### Clipboard - `copy` reads the active layer. If that area is empty on the active layer, it falls back to the merged image. - `copy_merged` always reads all visible layers. - `paste`: - Creates a new layer at the top, places the pixels, selects them and switches to the Move tool, so a following `move` repositions the pasted pixels. - Places them centred on `center_x`/`center_y` if you give them, otherwise at the position they were copied from. - Use `layer {action: "merge_down"}` once they are placed. - `source: "system"` pastes an image from the Windows clipboard. ### Transform - `resize` scales every layer. If you give only `width` or only `height`, the other keeps the aspect ratio. - `canvas_size` crops or extends the canvas without scaling. `anchor` (for example `top-left` or `center`) sets where the existing image sits in the new canvas. - Every transform clears the selection. ### History `history {action: "list"}` returns `entries` (labels, oldest first) and `cursor`, the index of the current state, where −1 means before the first edit. `jump` moves to any index. A new edit after an undo discards the redo entries. ### Keyboard shortcuts (`press_key`) | Key | Action | |---|---| | `b` | Brush | | `h` | Chalk | | `e` | Eraser | | `l` | Line | | `c` | Curve | | `r` | Rectangle | | `o` | Ellipse | | `g` | Fill | | `i` | Colour picker | | `m` | Move | | `s` | Rectangle select | | `k` | Lasso | | `w` | Magic wand | | Space | Pan | | `[` / `]` | Brush size −/+ 2 | | `1` | 100% zoom | | `0` | Fit to window | | `+` / `-` | Zoom in / out | | Enter | Finish a pending line or curve | | Escape | Cancel the tool, clear the selection and switch to Pan | | Ctrl+Z / Ctrl+Y | Undo / redo | | Ctrl+X / Ctrl+C / Ctrl+Shift+C | Cut / copy / copy merged | | Ctrl+D | Deselect | ## Recipes **Draw a simple scene and save it** 1. `new_document {width: 800, height: 600}` 2. `select {mode: "rect", x: 0, y: 0, width: 800, height: 400}`, then `fill {x: 10, y: 10, color: "#87ceeb"}`. This paints the sky. 3. `select {mode: "rect", x: 0, y: 400, width: 800, height: 200}`, then `fill {x: 10, y: 450, color: "#3c8d2f"}`. This paints the grass. 4. `select {mode: "none"}` 5. `layer {action: "add", name: "Sun"}`, then `select {mode: "ellipse", x: 600, y: 60, width: 120, height: 120}`, `fill {x: 660, y: 120, color: "#ffd84a"}` and `select {mode: "none"}`. 6. `view_image` to check the result, then `save_image {path: "C:\\Users\\me\\Pictures\\scene.png"}`. **Edit a photo** 1. `open_image {path: "C:\\photos\\in.jpg"}` 2. `apply_effect {effect: "brightness-contrast", params: {brightness: 0.1, contrast: 1.2}}` 3. `apply_effect {effect: "hue-saturation", params: {saturation: 1.3}}` 4. `transform {operation: "resize", width: 1600}` 5. `save_image {path: "C:\\photos\\out.jpg", quality: 0.9}` **Blur the background only** (there is no invert-selection command): 1. `layer {action: "duplicate"}` 2. `apply_effect {effect: "gaussian-blur", params: {radius: 12}}` blurs the copy. 3. `select` the subject with a `lasso`, or with a `wand` on the original layer. 4. `layer {action: "clear"}` on the copy. This erases the blurred subject so the sharp original shows through. 5. `select {mode: "none"}` **Cut an object out onto its own layer**: `select` it with a `wand` or a `lasso`, `clipboard {action: "cut"}`, then `clipboard {action: "paste", center_x: …, center_y: …}`. ## Tips - Call `get_state` first, and call `view_image` after any change you cannot verify from the numbers alone. Use `region` to inspect detail at full resolution. - Leave the user's work intact: before an experiment, add a layer or duplicate one. Every step can be undone with `history`. - Always give absolute file paths. `save_image` overwrites without asking. - A tool that "did nothing" usually means a selection is clipping it, the wrong layer is active, a layer is hidden, or the colour's alpha is 0. Check `messages` and `get_state`. - Commands run one at a time, in the order they arrive.