krita-mcp 1.4.0__tar.gz

krita_mcp-1.4.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+
+# Local client configuration
+/.codex/
+
+# Package build output
+dist/
+build/
+
+# Output from the example scripts
+poster.png
+poster_preview.png
+banner.png
+docs/banner_preview.png
+
+# Krita
+*.kra~
+*.kra-autosave.kra
+
+# Local verification captures and receipts
+artifacts/
+native/build/
+pykrita/krita_mcp/libkrita_mcp_native.*
+pykrita/krita_mcp/libkrita_mcp_native_*.so
+pykrita/krita_mcp/native_manifest.json

krita_mcp-1.4.0/LICENSE

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

krita_mcp-1.4.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: krita-mcp
+Version: 1.4.0
+Summary: MCP server that lets agents drive Krita
+Project-URL: Homepage, https://github.com/thuanlm215/krita-mcp
+Project-URL: Repository, https://github.com/thuanlm215/krita-mcp
+Project-URL: Issues, https://github.com/thuanlm215/krita-mcp/issues
+Author: thuanlm215
+License-Expression: CC0-1.0
+License-File: LICENSE
+Keywords: krita,mcp,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# Krita MCP
+
+Give an agent a real Krita file. It can build the layer stack, select a part, turn it around a pivot, lay down a pressure stroke, step through raster frames, and look at the PNG it just made.
+
+![A desk still life: layered lantern studies, a dashed selection around a handle, a bristle stroke, four animation cells, and a cracked pane beside a repaired one](docs/capabilities.jpg)
+
+Read the picture from the back of the desk forward. The three sheets are a layer stack: wash, line, color. The dashed loop and the pins are a selection swung around a pivot. The bristle mark is one native stroke that starts light and ends heavy. The four cells are raster frames. The split lens is a repair: the crack on one side, the same pane whole on the other.
+
+[thuanlm215](https://github.com/thuanlm215) maintains this tree. The stdio transport and the first document tools come from [SanSaSane/krita-mcp](https://github.com/SanSaSane/krita-mcp) at `93f485d`. Version **1.4.0** adds native Undo, brushes, transforms, animation frames, and bounded repair. Fifty-two tools, sixty-one bridge operations. The full list is in [docs/usage.md](docs/usage.md). The call order for a pose, a warp, a frame, and a repair is in [docs/workflows.md](docs/workflows.md).
+
+## What has to be installed
+
+Krita 5.2 or newer covers documents, layers, geometric drawing, filters, and export. Brush pressure, native pixel Undo, warp, batches, and exact raster frames need **Linux, Krita 6.0.4, Qt6, little-endian**, plus the helper in [native/README.md](native/README.md). Anywhere else those calls return `unsupported`.
+
+The server is Python 3.8 or newer and the standard library. Krita loads a plugin in its own process. The MCP client runs `krita-mcp` beside it. Install the plugin once.
+
+Close Krita before the installer writes `kritarc`. Krita rewrites that file on exit.
+
+```bash
+# pure Python plugin, no clone
+uvx --from git+https://github.com/thuanlm215/krita-mcp krita-mcp install
+
+# Linux / Krita 6.0.4, from a clone, when you need the native helper
+python3 build_native.py
+python3 mcp_server.py install
+```
+
+`./install.sh` and `install.ps1` call the same installer. `--force` writes the enable flag while Krita is still open. By hand, copy `pykrita/krita_mcp/` and `pykrita/krita_mcp.desktop` into Krita's `pykrita` folder and enable **MCP Bridge** under *Settings → Configure Krita → Python Plugin Manager*.
+
+Start Krita. *Tools → Scripts* should show **Start/Stop MCP Bridge** and **MCP Bridge Status…**.
+
+```bash
+uvx --from git+https://github.com/thuanlm215/krita-mcp krita-mcp --selftest
+```
+
+A GitHub release publishes the package. After `krita-mcp` is on PyPI, drop the `--from` argument and use `uvx krita-mcp`. The release steps are in [docs/development.md](docs/development.md#release).
+
+## Point a client at it
+
+Restart the client after editing its config. Krita has to be running before a tool can touch a document.
+
+Codex, `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.krita]
+command = "uvx"
+args = ["--from", "git+https://github.com/thuanlm215/krita-mcp", "krita-mcp"]
+startup_timeout_sec = 30
+tool_timeout_sec = 360
+enabled = true
+```
+
+Claude Code:
+
+```bash
+claude mcp add krita -- uvx --from git+https://github.com/thuanlm215/krita-mcp krita-mcp
+```
+
+Claude Desktop and any other JSON config:
+
+```json
+{
+  "mcpServers": {
+    "krita": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/thuanlm215/krita-mcp", "krita-mcp"]
+    }
+  }
+}
+```
+
+A checkout works the same way with `python3` and an absolute path to `mcp_server.py`.
+
+## A session
+
+Ask for the open layer tree and set the top layer to multiply at 60%. Ask to cut a forearm onto its own layer, rotate it around the elbow, and paint the seam with a dry bristle. Ask to duplicate three raster keys, export an atlas, then repair one cracked pane on the held frame and show the before and after.
+
+Reconnect the client after a plugin update. An open chat keeps the schema it saw at startup.
+
+`close_document` can still bring Krita down on some teardown paths. *File → Close* can hit the same fault. Leave the file open and close it yourself when the session matters. [docs/usage.md](docs/usage.md#closing-documents) has the rest: colour space, filter types, the recovery dialog, and what a lost response means.
+
+Build and tests: [docs/development.md](docs/development.md).
+
+## License
+
+The Python server, the Krita plugin, and the upstream work are [CC0 1.0](LICENSE). `native/bridge.cpp` is GPL-2.0-or-later. Vendored Krita headers keep their own GPL and LGPL notices. See [native licensing](native/README.md#sources-and-licensing) and `native/LICENSES/`.
+
+The wheel that `uvx` installs is the CC0 server and plugin. It does not contain the helper binary or the vendored headers.

krita_mcp-1.4.0/README.md

@@ -0,0 +1,88 @@
+# Krita MCP
+
+Give an agent a real Krita file. It can build the layer stack, select a part, turn it around a pivot, lay down a pressure stroke, step through raster frames, and look at the PNG it just made.
+
+![A desk still life: layered lantern studies, a dashed selection around a handle, a bristle stroke, four animation cells, and a cracked pane beside a repaired one](docs/capabilities.jpg)
+
+Read the picture from the back of the desk forward. The three sheets are a layer stack: wash, line, color. The dashed loop and the pins are a selection swung around a pivot. The bristle mark is one native stroke that starts light and ends heavy. The four cells are raster frames. The split lens is a repair: the crack on one side, the same pane whole on the other.
+
+[thuanlm215](https://github.com/thuanlm215) maintains this tree. The stdio transport and the first document tools come from [SanSaSane/krita-mcp](https://github.com/SanSaSane/krita-mcp) at `93f485d`. Version **1.4.0** adds native Undo, brushes, transforms, animation frames, and bounded repair. Fifty-two tools, sixty-one bridge operations. The full list is in [docs/usage.md](docs/usage.md). The call order for a pose, a warp, a frame, and a repair is in [docs/workflows.md](docs/workflows.md).
+
+## What has to be installed
+
+Krita 5.2 or newer covers documents, layers, geometric drawing, filters, and export. Brush pressure, native pixel Undo, warp, batches, and exact raster frames need **Linux, Krita 6.0.4, Qt6, little-endian**, plus the helper in [native/README.md](native/README.md). Anywhere else those calls return `unsupported`.
+
+The server is Python 3.8 or newer and the standard library. Krita loads a plugin in its own process. The MCP client runs `krita-mcp` beside it. Install the plugin once.
+
+Close Krita before the installer writes `kritarc`. Krita rewrites that file on exit.
+
+```bash
+# pure Python plugin, no clone
+uvx --from git+https://github.com/thuanlm215/krita-mcp krita-mcp install
+
+# Linux / Krita 6.0.4, from a clone, when you need the native helper
+python3 build_native.py
+python3 mcp_server.py install
+```
+
+`./install.sh` and `install.ps1` call the same installer. `--force` writes the enable flag while Krita is still open. By hand, copy `pykrita/krita_mcp/` and `pykrita/krita_mcp.desktop` into Krita's `pykrita` folder and enable **MCP Bridge** under *Settings → Configure Krita → Python Plugin Manager*.
+
+Start Krita. *Tools → Scripts* should show **Start/Stop MCP Bridge** and **MCP Bridge Status…**.
+
+```bash
+uvx --from git+https://github.com/thuanlm215/krita-mcp krita-mcp --selftest
+```
+
+A GitHub release publishes the package. After `krita-mcp` is on PyPI, drop the `--from` argument and use `uvx krita-mcp`. The release steps are in [docs/development.md](docs/development.md#release).
+
+## Point a client at it
+
+Restart the client after editing its config. Krita has to be running before a tool can touch a document.
+
+Codex, `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.krita]
+command = "uvx"
+args = ["--from", "git+https://github.com/thuanlm215/krita-mcp", "krita-mcp"]
+startup_timeout_sec = 30
+tool_timeout_sec = 360
+enabled = true
+```
+
+Claude Code:
+
+```bash
+claude mcp add krita -- uvx --from git+https://github.com/thuanlm215/krita-mcp krita-mcp
+```
+
+Claude Desktop and any other JSON config:
+
+```json
+{
+  "mcpServers": {
+    "krita": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/thuanlm215/krita-mcp", "krita-mcp"]
+    }
+  }
+}
+```
+
+A checkout works the same way with `python3` and an absolute path to `mcp_server.py`.
+
+## A session
+
+Ask for the open layer tree and set the top layer to multiply at 60%. Ask to cut a forearm onto its own layer, rotate it around the elbow, and paint the seam with a dry bristle. Ask to duplicate three raster keys, export an atlas, then repair one cracked pane on the held frame and show the before and after.
+
+Reconnect the client after a plugin update. An open chat keeps the schema it saw at startup.
+
+`close_document` can still bring Krita down on some teardown paths. *File → Close* can hit the same fault. Leave the file open and close it yourself when the session matters. [docs/usage.md](docs/usage.md#closing-documents) has the rest: colour space, filter types, the recovery dialog, and what a lost response means.
+
+Build and tests: [docs/development.md](docs/development.md).
+
+## License
+
+The Python server, the Krita plugin, and the upstream work are [CC0 1.0](LICENSE). `native/bridge.cpp` is GPL-2.0-or-later. Vendored Krita headers keep their own GPL and LGPL notices. See [native licensing](native/README.md#sources-and-licensing) and `native/LICENSES/`.
+
+The wheel that `uvx` installs is the CC0 server and plugin. It does not contain the helper binary or the vendored headers.

krita_mcp-1.4.0/docs/development.md

@@ -0,0 +1,90 @@
+# Development
+
+Work from a checkout when you change the plugin, the native helper, or the tests. `uvx` runs the packaged server. It is not the edit loop.
+
+## Layout
+
+```
+mcp_server.py              stdio server, CLI, and plugin installer
+painter_schema.py          stroke, target, and frame schemas
+pyproject.toml             package metadata for uvx / pip
+install.sh / install.ps1   wrappers around `mcp_server.py install`
+build_native.py            content-addressed Linux helper build
+dev_reload.py              private Krita/Xvfb runner
+pykrita/krita_mcp/         plugin loaded by Krita
+native/                    GPL helper and vendored headers
+examples/                  animation player and painter demos
+test_*.py                  live and offline suites
+```
+
+`dev_reload.py` starts a fresh private installation. It does not copy into the desktop plugin and it does not execute arbitrary Python inside Krita. Deploy to the desktop by saving work, closing Krita, running the installer, and starting Krita again.
+
+## Native helper
+
+On Linux with Krita 6.0.4:
+
+```bash
+python3 build_native.py
+python3 mcp_server.py install
+```
+
+The build writes a checksummed `.so` and `native_manifest.json` under `pykrita/krita_mcp/`. Those files are gitignored and are excluded from the Python wheel. Dependencies, the ABI pin, and the GPL/LGPL split are in [native/README.md](../native/README.md).
+
+Do not overwrite a `.so` that a running Krita has mapped. Rebuild, then start a new Krita process.
+
+## Tests
+
+```bash
+python3 mcp_server.py --selftest
+python3 test_mcp.py
+python3 test_mcp.py -v
+python3 test_workflow.py
+python3 test_advanced.py
+python3 test_shutdown.py
+python3 -m unittest -v test_core test_shutdown test_transport
+python3 run_isolated_tests.py
+python3 example_poster.py
+python3 example_banner.py
+```
+
+`test_mcp.py` speaks JSON-RPC to a real `mcp_server.py` process, so a pass covers the handshake and the basic operation set against live Krita. Workflow, advanced, painter, and repair suites cover their fixtures. They do not cover every preset, mask, or platform.
+
+Isolated examples:
+
+```bash
+python3 run_isolated_tests.py --output artifacts/my-warp -- \
+  python3 example_deformation_workflow.py --output artifacts/my-warp
+```
+
+The runner uses a private home, Xvfb, and a copy of this checkout. It does not modify the desktop Krita installation. Do not run two UI suites at the same time.
+
+Offline suites do not need Krita. `test_shutdown.py` needs system PyQt6. The painter demos in a full isolated run also expect Pillow and ffmpeg when they encode review media. The MCP server stays on the standard library.
+
+## Package
+
+The wheel contains `mcp_server.py`, `painter_schema.py`, and `pykrita/`. It does not contain the native helper.
+
+```bash
+uv build
+uvx --from dist/krita_mcp-1.4.0-py3-none-any.whl krita-mcp --list-tools
+```
+
+## Release
+
+Publishing uses PyPI trusted publishing. GitHub Actions requests a short-lived token. There is no API token in the repository.
+
+The workflow is `.github/workflows/publish.yml`. It runs when a GitHub release is published, and only if the tag matches `version` in `pyproject.toml`. A release tagged `v1.4.0` publishes version `1.4.0`. PyPI keeps that file set forever, so the next release needs a new version.
+
+Before the first release, register a pending publisher at <https://pypi.org/manage/account/publishing/>:
+
+| Field | Value |
+| --- | --- |
+| PyPI project name | `krita-mcp` |
+| Owner | `thuanlm215` |
+| Repository name | `krita-mcp` |
+| Workflow name | `publish.yml` |
+| Environment name | `pypi` |
+
+On GitHub, create an environment named `pypi` under Settings → Environments. Then draft a release whose tag is `v` plus the version in `pyproject.toml`.
+
+After that release is on PyPI, clients use `uvx krita-mcp`. The plugin install remains `krita-mcp install`, because Krita loads Python from its own resource folder.

krita_mcp-1.4.0/docs/usage.md

@@ -0,0 +1,128 @@
+# Using Krita MCP
+
+Version 1.4 exposes 52 tools and 61 bridge operations. Reconnect the MCP client after a plugin update. A running chat keeps the schema it discovered at startup.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `status` | Krita version and every open document |
+| `dismiss_recovery_dialog` | Cancel the native Recover Files dialog and keep autosaves. Other modals stay open |
+| `inspect_document` | Canvas, colour space, layer tree, selection |
+| `create_document` / `open_document` | Make or load a document |
+| `save_document` / `export_document` | Save in place or save-as; export PNG, JPEG, and other formats Krita supports |
+| `close_document` | Close a document. See [Closing documents](#closing-documents) |
+| `transform_image` | Resize canvas, scale, rotate, crop, flatten |
+| `create_layer` / `set_layer` / `delete_layer` | Layer stack |
+| `duplicate_layer` / `move_layer` / `merge_layer_down` | Restack and merge |
+| `get_image` | Render the canvas and return a PNG |
+| `get_pixel` | Colour at one pixel |
+| `draw` | Shapes, text, gradients, and bitmaps on a paint layer |
+| `list_brushes` / `draw_brush` | Native presets and undoable brush or eraser strokes |
+| `plan_stroke` / `paint_stroke` | Versioned geometry and one native pressure stroke |
+| `sample_colors` / `compare_images` | Linear-light palette samples and aligned geometric diagnostics |
+| `prepare_repair` / `render_repair` / `inspect_repair` | Frozen baseline and bounded candidates |
+| `commit_repair` / `repair_status` / `discard_repair` | Idempotent commit, outcome lookup, snapshot release |
+| `select_polygon` / `selection_to_layer` | Polygon or lasso; copy or cut the selection to a layer |
+| `transform_layer` | Preview or apply a native transform mask around a pivot |
+| `warp_layer` | Preview or apply one local raster pull on a preserved-source duplicate |
+| `select_content` | Alpha, colour, contiguous region, and imported masks |
+| `texture_patch` / `clone_stamp` | Masked texture placement and sampled cloning |
+| `mask_layer` / `bake_layer` | Transparency masks and baked paint layers |
+| `edit_batch` / `preview_changes` | One Undo group with rollback, and before/after/difference |
+| `animation_frame` / `export_animation` | Raster keyframes, onion skin, FPS, PNG sequence, atlas, manifest |
+| `import_animation` / `animation_review` | Registered PNG import and previous/current/next panels |
+| `undo` / `redo` | Native history for the requested document |
+| `apply_filter` | A Krita filter on a layer or a region |
+| `set_selection` | rect, all, none, invert, grow, shrink, feather |
+| `list_capabilities` | Filter parameters, blend-mode ids, and real helper support |
+| `trigger_action` | Allowlisted native history and selection actions |
+| `self_test` | End-to-end health check |
+
+Sequences for extraction, brushes, warp, animation, and repair are in [workflows.md](workflows.md).
+
+## Drawing
+
+`draw` paints a list of commands, in order, onto an RGBA/8-bit paint layer:
+
+`fill_rect`, `rect` (optional corner radius), `ellipse`, `circle`, `line`, `polyline`, `polygon`, `text`, `linear_gradient`, `radial_gradient`, `image` (base64 PNG), and `clear`.
+
+The active selection constrains these commands, including feathered alpha. Colours accept `#rrggbb`, `#rrggbbaa`, SVG names, or `[r, g, b, a]`.
+
+Geometry uses `w` and `h`. Outline thickness is `stroke_width`. Only the union of affected pixels is read, painted, and written back.
+
+## Addressing layers
+
+Listings use docker order, top first. Name a layer by its name (`"Sky"`), a path through groups (`"Background/Sky"`), an index path (`"#0/#1"`), or `"uuid:…"`. Omit the layer to use the active one. Listings return all of these forms.
+
+## How it works
+
+```
+MCP client  --stdio JSON-RPC-->  krita-mcp  --HTTP-->  Krita plugin  -->  libkis
+                                  (stdlib)   loopback   (GUI thread)
+```
+
+Krita runs Python only inside itself, and an MCP server is a separate process. The two halves find each other through a small file in Krita's data folder. That file holds the port and a random per-session token. The bridge binds loopback only and requires the token.
+
+libkis is not thread-safe. The HTTP server accepts connections on worker threads and marshals every Krita call onto the GUI thread, with a deadline. A modal dialog or a long filter returns `krita_busy` at the deadline. Requests do not wait forever.
+
+## Behaviour that affects edits
+
+**Native Undo.** On the tested Linux/Krita 6.0.4 helper, drawing and regional filters enter Krita's image command scheduler. A batch can mix those edits with brush, selection, extraction, and transform commands, then undo the group once. A new edit discards the existing redo branch, as a manual edit does. Rollback cannot restore that earlier redo branch.
+
+**Blending modes.** Krita 5.3 has no API that enumerates composite ops, and it accepts any string. Unknown ids render as Normal. `set_layer` canonicalises the ids it knows and warns on anything else.
+
+**Colour space.** `draw`, `get_pixel`, and per-layer `get_image` require RGBA/8-bit. The merged `get_image` works in other colour spaces.
+
+**Filter parameters.** Call `list_capabilities(kind="filters", include_parameters=true)` and use each entry's `parameters` and `parameter_info`. QColor is `{"type":"QColor","rgba":[1,0,0,1]}` with normalized components. QByteArray is `{"type":"QByteArray","base64":"...","byte_length":123}`. Primitives keep their types. Unknown Qt types are read-only. A malformed setting leaves pixels and history intact.
+
+A serialization fault returns HTTP 500 with `response_serialization_error`, the operation, and the exception type. The bridge keeps serving. A send/read timeout, reset, or truncated response returns `incomplete_response` with `execution_outcome: "unknown"` and is not retried, because the edit may already have completed. The client rediscovers the bridge only when TCP fails before any HTTP bytes are sent, or when it receives HTTP 401 before dispatch.
+
+**Startup recovery.** `dismiss_recovery_dialog` with `{}` cancels the native `KisAutoSaveRecoveryDialog` and keeps the autosaves. It matches the dialog class, not a translated label. Other modals stay open. With no recovery dialog, the call is a no-op. It does not recover or discard files.
+
+**Masked layers.** Native brush work, geometric draw, extraction, patches, clone, and warp reject masks and transformed ancestors before editing. Put a Cleanup layer at the document root above the masked ancestor, or `bake_layer` that ancestor and edit the unmasked copy. Bake preserves and hides the source. See [workflows.md](workflows.md).
+
+## Closing documents
+
+`close_document` can take Krita down. A fresh or lightly edited document usually closes. A long session fails more often. The fault is in Krita's C++ teardown after `Document.close()` returns, and *File → Close* can hit the same path.
+
+The 1.2 helper drains pending `KisNodeModel` updates before view teardown on Krita 6.0.4. That covers the layer-model timer crash observed here. Other teardown faults remain possible.
+
+Prefer to leave documents open and close them in Krita. If Krita exits, the next call returns a clear "could not reach Krita" error.
+
+## Configuration
+
+Krita reads these keys from `kritarc` under `[krita_mcp]`:
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `autostart` | `true` | Start the bridge when Krita starts |
+| `port` | `9797` | First port to try. The bridge scans upward if it is taken |
+
+| Variable | Meaning |
+| --- | --- |
+| `KRITA_MCP_STATE_DIR` | Override the discovery-file directory |
+| `KRITA_MCP_TRACE` | Set to `1` before starting Krita to log every operation |
+| `KRITA_MCP_PORT` / `KRITA_MCP_TOKEN` | Skip discovery and connect directly |
+
+Trace lines go to `krita_mcp_trace.log` in Krita's data folder, flushed per line. Krita has no console. An entry with no matching completion names the operation that stopped the process.
+
+## Troubleshooting
+
+**Could not reach the Krita MCP bridge.** Krita may be stopped, or the plugin may be disabled. Check *Tools → Scripts → MCP Bridge Status…*. If the menu entries are missing, enable MCP Bridge in the Python Plugin Manager and restart Krita.
+
+**`response_serialization_error` or `incomplete_response`.** Inspect `status` and the document before repeating an edit. These errors do not mean Krita has exited. Filter metadata requires plugin 1.3 or newer. HTTP handler changes require a Krita restart.
+
+**Tools are missing in the client.** Restart the client after editing its config. `uvx` must be on `PATH`. A checkout config must use an absolute path to `mcp_server.py`.
+
+**Port already in use.** The bridge scans upward from 9797 and writes the chosen port into the discovery file. Set another start port with `port=` under `[krita_mcp]` in `kritarc`.
+
+## Diagnostics
+
+```bash
+krita-mcp --list-tools
+krita-mcp --call status
+krita-mcp --call draw --params-file commands.json
+```
+
+From a checkout, `python3 mcp_server.py` accepts the same flags. With no flag, the process speaks MCP on stdin/stdout.