docs: the MCP preview is the web app's canvas; get_selection, DRAWIO_BASE_URL and the classic page

2026-10-12 04:29:51 +08:00 · 2026-10-11 20:56:07 +09:00
parent 27c49a68d0
commit 58cef00873
5 changed files with 36 additions and 17 deletions
@@ -24,17 +24,18 @@ claude mcp add drawio -- npx @next-ai-drawio/mcp-server@latest

 ## Features

- **Real-time Preview**: Diagrams appear and update in your browser as Claude creates them
+- **Real-time Preview**: Diagrams appear and update in your browser as Claude creates them. The preview is the web app's canvas: a change Claude makes to the page on screen is outlined, and one Ctrl+Z takes it back
+- **Selection**: Select shapes in the preview and say "move these"; Claude reads what you selected with `get_selection`
 - **Drawing Rules and Shape Libraries**: Claude gets the web app's layout and style rules and the icon docs for AWS, Azure, GCP, Kubernetes and more
 - **Self-check**: Claude can take a screenshot of the rendered diagram and fix what looks wrong
 - **Draw from Your Files**: ask Claude to draw from a document, image or web page; it reads the source with its own tools and draws. Existing .drawio files open with load_diagram
- **Version History**: Restore one of the last 20 versions from the **History** button, shown as thumbnails
+- **Version History**: The last 20 versions appear as cards next to the canvas, with thumbnails; restore one, undo the latest, or compare a version with the canvas
 - **Natural Language**: Describe diagrams in plain text - flowcharts, architecture diagrams, etc.
 - **Edit Support**: Modify existing diagrams with natural language instructions, including your own edits in the browser
 - **Export**: Save diagrams as `.drawio`, `.png`, `.svg`, or `.drawio.svg` files
 - **Auto-save**: Each diagram is saved to `~/.next-ai-drawio/`, so `claude --resume` can pick it up again
 - **Custom Instructions**: keep your own drawing rules in `~/.next-ai-drawio/instructions.md` (for example "Always draw in minimal style"); they are appended to the drawing guide on every call
- **Self-contained**: Embedded server, no external dependencies required
+- **Self-contained**: Embedded server and the draw.io editor in one package; the preview works offline after install

 ## Use Case Examples

@@ -97,6 +98,7 @@ Recreate the whiteboard photo at ~/Desktop/sketch.jpg as a clean draw.io diagram
 | `load_diagram` | Load a `.drawio` or `.drawio.svg` file from disk |
 | `edit_diagram` | Edit diagram by ID-based operations; all or nothing |
 | `get_diagram` | Get the current diagram XML |
+| `get_selection` | Return the shapes and edges you selected in the preview, so Claude can act on "these" |
 | `screenshot_diagram` | Return a PNG of a page so Claude can check the result |
 | `export_diagram` | Save diagram to a `.drawio`, `.png`, `.svg`, or `.drawio.svg` file |
 | `list_pages`, `add_page`, `rename_page`, `delete_page` | Work with multi-page diagrams |
@@ -118,11 +120,12 @@ Claude Code <--stdio--> MCP Server <--http--> Browser (draw.io)
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `PORT` | `6002` | Port for the embedded HTTP server |
-| `DRAWIO_BASE_URL` | `https://embed.diagrams.net` | Base URL for draw.io (for self-hosted deployments) |
+| `DRAWIO_BASE_URL` | unset (the bundled draw.io) | An external draw.io, such as a self-hosted instance. With it Claude's changes are not outlined on the canvas, Ctrl+Z does not take them back and `get_selection` cannot read the selection |
 | `DRAWIO_DATA_DIR` | `~/.next-ai-drawio` | Folder for auto-saved diagrams and your `instructions.md`; `off` turns auto-save off (`instructions.md` is then read from the default folder) |
 | `DRAWIO_LANG` | unset | Language of the draw.io editor, such as `en`, `zh`, `zh-tw`, `ja` or `de`. Unset, draw.io chooses (the browser language on `embed.diagrams.net`, English on a self-hosted draw.io) and the user can change it under **Extras > Language** |
 | `DRAWIO_UI` | unset | draw.io theme: `kennedy`, `atlas`, `dark`, `min`, `sketch` or `simple`. Unset, the user picks one under **Extras > Theme** |
-| `DRAWIO_DARK` | `auto` | Dark mode of the draw.io editor: `auto` follows the system, `1` forces dark, `0` forces light |
+| `DRAWIO_DARK` | `auto` | Dark mode of the preview and the editor until the user switches it with the button at the top right: `auto` follows the system, `1` starts dark, `0` starts light |
+| `DRAWIO_PREVIEW_UI` | `shell` | The preview page; `classic` opens the previous preview page for one more release |
 | `DRAWIO_AUTO_SCREENSHOT` | unset | Set to `true` to attach a screenshot to every `create_new_diagram` and `edit_diagram` result (costs 2 to 10 s per call) |
 | `DEBUG` | unset | Set to `true` to log debug messages |

@@ -2,7 +2,7 @@

 MCP (Model Context Protocol) server that enables AI agents like Claude Desktop and Cursor to generate and edit draw.io diagrams with **real-time browser preview**.

-**Self-contained** - includes an embedded HTTP server, no external dependencies required.
+**Self-contained**: the embedded HTTP server and the draw.io editor are in the package, so after install the preview works offline.

 ## Quick Start

@@ -105,19 +105,20 @@ Use the standard MCP configuration with:

 ## Features

- **Real-time Preview**: Diagrams appear and update in your browser as the AI creates them
+- **Real-time Preview**: Diagrams appear and update in your browser as the AI creates them. The preview is the web app's canvas: a change the AI makes to the page on screen is outlined, and one Ctrl+Z takes it back
+- **Selection**: Select shapes in the preview and say "move these" or "connect this box to that one"; the AI reads what you selected with `get_selection`
 - **Drawing Rules**: The AI gets the same layout, edge and style rules as the web app, plus the shape library docs (AWS, Azure, GCP, Kubernetes, Cisco and more), so it uses real icon names instead of guessing
 - **Self-check**: The AI can take a screenshot of the rendered diagram (`screenshot: true` on `create_new_diagram` or `edit_diagram`, or `screenshot_diagram`) and fix overlapping shapes or edges that cross shapes
 - **Draw from Your Files**: ask the AI to draw from a document, image or web page; it reads the source with the host's own tools and draws. Existing .drawio files open with load_diagram
 - **Edit Support**: Modify existing diagrams with natural language instructions. If any change in an edit fails, nothing is written and the AI gets the reason and the current page XML
 - **Your Edits Are Kept**: Changes you make in the browser are read before the AI edits again. If the AI overwrites a change you were still making, your version is saved in History
- **Version History**: Click **History** at the top right of the preview page to restore one of the last 20 versions, shown as thumbnails, or ask the AI to undo (`restore_version`)
- **Download and Export**: Save as `.drawio`, `.png`, `.svg`, or `.drawio.svg` (an SVG with the diagram embedded, which draw.io and `load_diagram` can open again), from the **Download** button or through `export_diagram`
+- **Version History**: The last 20 versions appear as cards next to the canvas, with a thumbnail and what changed. Restore one, undo and redo the latest, or compare a version with the canvas; or ask the AI to undo (`restore_version`)
+- **Export**: Save as `.drawio`, `.png`, `.svg`, or `.drawio.svg` (an SVG with the diagram embedded, which draw.io and `load_diagram` can open again) through `export_diagram`, or export an image from draw.io's **File > Export as** menu in the preview
 - **Multi-page**: List, add, rename, and delete pages, and edit any page
 - **Auto-save**: Each session's diagram is saved to `~/.next-ai-drawio/<session-id>.drawio`, and its last 20 versions to `<session-id>.history.json`, so the diagram, History and undo survive a restart of the MCP client
 - **Custom Instructions**: keep your own drawing rules in `~/.next-ai-drawio/instructions.md` (for example "Always draw in minimal style"); they are appended to the drawing guide on every call
- **Themes and Dark Mode**: Pick a draw.io theme under **Extras > Theme**; the page follows the system dark mode, or fix them with `DRAWIO_UI`, `DRAWIO_DARK` and `DRAWIO_LANG`
- **Self-contained**: Embedded server, works offline (except draw.io UI which loads from `embed.diagrams.net` by default, configurable via `DRAWIO_BASE_URL`)
+- **Themes and Dark Mode**: Pick a draw.io theme under **Extras > Theme**; the button at the top right switches the page and the editor between light and dark (the system setting until you choose). `DRAWIO_UI`, `DRAWIO_DARK` and `DRAWIO_LANG` fix them
+- **Self-contained**: The draw.io editor ships inside the package and is served from the preview's own origin, so after install the preview works offline. `DRAWIO_BASE_URL` points it at another draw.io instead

 ## Available Tools

@@ -131,6 +132,7 @@ Use the standard MCP configuration with:
 | `load_diagram` | Load a `.drawio` or `.drawio.svg` file into the session, from a `path` on disk or from its `xml` content (handles compressed files) |
 | `edit_diagram` | Edit diagram by ID-based operations (update/add/delete cells); all or nothing |
 | `get_diagram` | Get the current diagram XML, including your edits in the browser |
+| `get_selection` | Return the shapes and edges you selected in the preview (ids, labels, positions), so the AI can act on "these" |
 | `screenshot_diagram` | Return a PNG of a page so the AI can check the rendered diagram |
 | `export_diagram` | Save diagram to a `.drawio`, `.png`, `.svg`, or `.drawio.svg` file |
 | `list_pages` | List every page (tab) with id, name, index, and cell count |
@@ -145,7 +147,7 @@ After every change, the diagram is saved as a normal `.drawio` file in `~/.next-

 To continue a diagram in a later conversation (for example after `claude --resume`, or in a new chat), the AI calls `start_session` with `session_id` set to that id: the same preview URL opens, the saved diagram is shown, and auto-save keeps writing to the same file. If the id is no longer in the conversation, `list_saved_diagrams` returns every saved diagram, newest first, with the names and cell counts of its pages, so you can ask for "the architecture diagram from yesterday" and let the AI pick it. `load_diagram` with the file path still works too, and you can open the file in draw.io yourself.

-History comes back with the diagram: the last 20 versions are saved next to it in `<session-id>.history.json` (without thumbnails). When the AI continues the session with `start_session` and its `session_id`, or a preview tab is still open after a restart, the **History** button shows them again and `restore_version` can undo to them.
+History comes back with the diagram: the last 20 versions are saved next to it in `<session-id>.history.json` (without thumbnails). When the AI continues the session with `start_session` and its `session_id`, or a preview tab is still open after a restart, the version cards show them again and `restore_version` can undo to them.

 The newest 50 files are kept, each with its History file. Set `DRAWIO_DATA_DIR` to use another folder, or to `off` to turn auto-save off.

@@ -175,20 +177,22 @@ To give the AI your own drawing rules, write them in `~/.next-ai-drawio/instruct
 ```

 1. **MCP Server** receives tool calls from Claude via stdio
-2. **Embedded HTTP Server** serves the draw.io UI and handles state
+2. **Embedded HTTP Server** serves the preview page and the draw.io editor, and handles state
 3. **Browser** shows real-time diagram updates via polling

+The server listens on `127.0.0.1` only. Every `/api` request must carry a token that the server generates at start and writes into the preview page, so another website open in the same browser cannot read or change the diagram; the preview page also refuses to be embedded in other pages. Opening the preview URL in another browser on the same machine works, since the page comes with the token.
+
 ## Configuration

 | Variable | Default | Description |
 |----------|---------|-------------|
 | `PORT` | `6002` | Port for the embedded HTTP server |
-| `DRAWIO_BASE_URL` | `https://embed.diagrams.net` | Base URL for the draw.io embed. Set this to use a self-hosted draw.io instance for private deployments. |
+| `DRAWIO_BASE_URL` | unset (the bundled draw.io) | An external draw.io for the preview, such as a self-hosted instance (see below). The page cannot reach into an editor from another origin, so with it the AI's changes are not outlined, Ctrl+Z does not take them back and `get_selection` cannot read the selection. The version cards and everything else keep working. |
 | `DRAWIO_DATA_DIR` | `~/.next-ai-drawio` | Folder for the auto-saved `.drawio` files and your `instructions.md`. Set to `off` to turn auto-save off (`instructions.md` is then read from the default folder). |
-| `DRAWIO_LANG` | unset | Language of the draw.io editor. Unset, draw.io chooses: the browser language on `embed.diagrams.net`, English on a self-hosted draw.io until the user picks one under **Extras > Language**. A code such as `en`, `zh`, `zh-tw`, `ja` or `de` fixes it and hides that submenu. |
+| `DRAWIO_LANG` | unset | Language of the draw.io editor and of the preview's own texts. Unset, the preview's texts follow the browser language, and draw.io chooses: English on the bundled copy until the user picks one under **Extras > Language**, the browser language on `embed.diagrams.net`. A code such as `en`, `zh`, `zh-tw`, `ja` or `de` fixes both and hides that submenu. |
 | `DRAWIO_UI` | unset | draw.io theme. Unset, the user picks one under **Extras > Theme** and draw.io remembers it. `kennedy`, `atlas`, `dark`, `min`, `sketch` or `simple` fixes the theme and hides that menu. |
-| `DRAWIO_DARK` | `auto` | Dark mode of the draw.io editor: `auto` follows the system, `1` forces dark, `0` forces light. The page header keeps following the system. |
-| `DRAWIO_PREVIEW_UI` | `classic` | The preview page `start_session` opens. `shell` opens the new canvas page built from the web app's canvas: it syncs with the server like the classic page, and an AI change of the page on screen is marked and undone with one Ctrl+Z (in progress: no History panel or download yet). |
+| `DRAWIO_DARK` | `auto` | Dark mode of the preview and the editor until the user switches it with the button at the top right (the browser remembers that choice): `auto` follows the system, `1` starts dark, `0` starts light. |
+| `DRAWIO_PREVIEW_UI` | `shell` | The preview page `start_session` opens. `classic` opens the previous preview page (see [Classic preview page](#classic-preview-page)). |
 | `DRAWIO_AUTO_SCREENSHOT` | unset | Set to `true` to attach a screenshot to every `create_new_diagram` and `edit_diagram` result, so the AI checks each drawing. Costs 2 to 10 s per call; the preview tab must be open and in front. A call can still pass `screenshot: false`. |
 | `BROWSER` | unset | Set to `none` and `start_session` does not open the preview in the system browser (the convention of Vite and Create React App dev servers); the result still names the URL. |
 | `DEBUG` | unset | Set to `true` to log debug messages to stderr. |
@@ -219,10 +223,16 @@ docker run -d -p 8080:8080 jgraph/drawio

 Then set `DRAWIO_BASE_URL=http://localhost:8080` (or your server's URL). The preview page loads nothing else from the internet, so with a local draw.io it works offline. One exception: shapes from the Material Design library show icons from `fonts.gstatic.com`.

+With an external draw.io the preview cannot reach into the editor (browsers keep pages and frames from other origins apart), so the AI's changes are not outlined on the canvas, Ctrl+Z does not take them back (use the version cards or `restore_version`), and `get_selection` cannot read what you selected. `start_session` tells the AI about this mode.
+
 Without `DRAWIO_BASE_URL` the preview uses the trimmed draw.io copy bundled with this package. It has the editor, the shape libraries, the templates, PlantUML and Mermaid; features that load more code when used (the org chart layout, for example) are not included. Set `DRAWIO_BASE_URL` to a full draw.io if you need them.

 Like the web app's bundled copy, it has no image proxy (`/drawio/proxy`): images from other websites, including the avatars in the Org Chart and Mind Map templates and the Arista icons in the network templates, show on the canvas only when online and are left out of PNG and SVG exports and version thumbnails. Insert such images from a file instead, or set `DRAWIO_BASE_URL` to a full draw.io (the `jgraph/drawio` Docker image includes the proxy). See [Offline deployment](https://github.com/DayuanJiang/next-ai-draw-io/blob/main/docs/en/offline-deployment.md).

+### Classic preview page
+
+`DRAWIO_PREVIEW_UI=classic` opens the preview page of the previous releases: draw.io with a **History** dialog and a **Download** button, without the outline of the AI's changes, Ctrl+Z for them, the version cards and `get_selection`. It stays for one more release and is then removed.
+
 ## Troubleshooting

 ### Port already in use