drawio-scientific-illustrator

# Draw.io Scientific Illustrator [English guide](#english-guide) · [MIT License](LICENSE) A Codex plugin that lets an AI agent draw scientific figures **live inside the visible draw.io desktop canvas**. You can watch shapes, labels, arrows, styling, and layout appear step by step. The live workflow calls draw.io's own graph API through a localhost-only MCP server; it does not automate the operating-system mouse or keyboard and does not create XML first and merely open it afterward. > Status: Windows is tested. macOS and Linux executable discovery is included, but live behavior can vary with draw.io/Electron packaging. Reports and pull requests are welcome. ## English guide ### What this repository contains - `drawio-live` MCP server: launches/connects to the visible draw.io desktop editor and edits its active graph model in real time. - `drawio-file-utils` MCP server: validates saved `.drawio` documents and exports PNG, SVG, PDF, or JPG deliverables. - A Codex skill: teaches the agent to inspect a reference, decompose it into editable primitives, draw with pacing, visually review sections, refine the live graph, and save only after the visible drawing exists. - A repository-local Codex marketplace so the complete plugin can be installed as one unit. This is therefore both an **MCP implementation** and a **Codex plugin**. MCP provides the callable tools; the plugin is the installable package containing the MCP servers, skill, and presentation metadata. ### Requirements 1. Codex desktop app or Codex CLI with plugin support. 2. [draw.io desktop](https://www.drawio.com/) installed locally. 3. Git. 4. Node.js available as `node` when running the MCP servers outside the bundled Codex runtime. Node.js 22 or newer is recommended. The plugin auto-detects common draw.io locations on Windows, macOS, and Linux. For a custom installation, set `DRAWIO_PATH` to the executable before starting Codex. ### Install — easiest methods #### Ask Codex to install it Paste this into a Codex task that has terminal access: ```text Install the public Codex plugin from https://github.com/icebird1998/drawio-scientific-illustrator. Clone it locally, register its repository root as a Codex marketplace, install drawio-scientific-illustrator@drawio-scientific-tools, then tell me when to restart Codex. ``` #### Windows one-command installer Review [`install.ps1`](install.ps1), then run: ```powershell $p="$env:TEMP\drawio-scientific-install.ps1"; Invoke-WebRequest https://raw.githubusercontent.com/icebird1998/drawio-scientific-illustrator/main/install.ps1 -OutFile $p; powershell -ExecutionPolicy Bypass -File $p ``` #### macOS/Linux one-command installer Review [`install.sh`](install.sh), then run: ```bash curl -fsSL https://raw.githubusercontent.com/icebird1998/drawio-scientific-illustrator/main/install.sh | bash ``` Restart Codex and start a new task after installation so the new skill and MCP tools are loaded. ### Install — manual and auditable ```bash git clone https://github.com/icebird1998/drawio-scientific-illustrator.git cd drawio-scientific-illustrator codex plugin marketplace add "$(pwd)" codex plugin add drawio-scientific-illustrator@drawio-scientific-tools ``` On PowerShell, replace `"$(pwd)"` with `(Get-Location).Path`: ```powershell git clone https://github.com/icebird1998/drawio-scientific-illustrator.git Set-Location drawio-scientific-illustrator codex plugin marketplace add (Get-Location).Path codex plugin add drawio-scientific-illustrator@drawio-scientific-tools ``` ### How to use it 1. Restart Codex after installation and create a new task. 2. Attach a PNG, JPEG, SVG, or a rendered PDF page as the reference. 3. Mention **Draw.io Scientific Illustrator** or select the plugin in the composer. 4. State the desired pacing and output formats. Recommended prompt: ```text Use Draw.io Scientific Illustrator. Launch the live draw.io canvas and recreate this reference scientific figure step by step with a 100 ms delay. Control only draw.io's own graph API; do not use OS mouse/keyboard automation and do not generate XML first. Keep all labels, arrows, panels, and legends editable. Visually inspect and refine each section, then save the final .drawio file and export a 2000 px PNG preview. ``` ### Live tool workflow The agent normally uses the tools in this order: 1. `drawio_live_launch` — launch or connect to a visible draw.io editor. 2. `drawio_live_status` — confirm that the graph is ready. 3. `drawio_live_add_shape`, `drawio_live_add_edge`, or paced `drawio_live_draw_sequence` — construct editable content visibly. 4. `drawio_live_screenshot` — inspect the draw.io renderer after logical sections. 5. `drawio_live_inspect` and `drawio_live_update_cell` — correct labels, styles, positions, and sizes. 6. `drawio_live_fit` — keep the evolving figure in view. 7. `drawio_live_save_snapshot` — serialize the already-visible graph to `.drawio`. 8. `drawio_validate` and `drawio_export` — validate and export deliverables. ### Configuration Optional environment variables: | Variable | Purpose | Default | |---|---|---| | `DRAWIO_PATH` | Explicit draw.io executable path | Auto-detected | | `DRAWIO_LIVE_PORT` | Preferred localhost debugging port | `9333`; a nearby free port is selected when needed | | `DRAWIO_LIVE_PROFILE` | Dedicated draw.io/Electron profile directory | `~/.drawio-live-mcp/<port>` | Example on Windows: ```powershell $env:DRAWIO_PATH = "D:\Apps\draw.io\draw.io.exe" ``` ### Update Run the same installer again. It performs a fast-forward `git pull` and reinstalls the plugin. Restart Codex and start a new task afterward. ### Troubleshooting - **`node` not found**: install Node.js 22+ or make sure the Codex runtime exposes Node to plugin MCP servers. - **draw.io not found**: install the desktop app or set `DRAWIO_PATH`. - **Port already in use**: omit an explicit port and the server will select a nearby localhost port, or set `DRAWIO_LIVE_PORT` to a free port. - **Graph not ready**: close stale draw.io windows launched by the plugin, retry, and ensure the desktop app accepts Electron remote-debugging flags. - **Plugin not visible**: restart Codex and create a new task after installation. - **Export fails**: confirm that draw.io desktop can export the same file manually and that the output directory is writable. ### Security and privacy - The live debugging endpoint binds to `127.0.0.1`, not a public network interface. - Target discovery accepts only pages identified as draw.io/diagrams.net; it does not attach to arbitrary browser pages. - The plugin does not use OS-level mouse or keyboard automation. - No telemetry or hosted backend is included. See [PRIVACY.md](PRIVACY.md). - Only install software from repositories and revisions you trust. Review the installer scripts before executing them. ### Known limitations - The live API currently emphasizes editable draw.io primitives. Dense microscopy images, photographs, heatmaps, and complex plots may need a future dedicated live image-insertion operation. - Visual fidelity depends on reference resolution and how well the content can be represented by draw.io primitives. - Windows is the tested platform for v1.0.0; macOS/Linux support is best effort until community testing expands. ### Manual Installation PowerShell: ```powershell git clone https://github.com/icebird1998/drawio-scientific-illustrator.git Set-Location drawio-scientific-illustrator codex plugin marketplace add (Get-Location).Path codex plugin add drawio-scientific-illustrator@drawio-scientific-tools ``` macOS/Linux: ```bash git clone https://github.com/icebird1998/drawio-scientific-illustrator.git cd drawio-scientific-illustrator codex plugin marketplace add "$(pwd)" codex plugin add drawio-scientific-illustrator@drawio-scientific-tools ``` ### Usage 1. Restart Codex and create a new task; 2. Upload PNG, JPEG, SVG, or a reference page rendered from PDF; 3. Select or mention **Draw.io Scientific Illustrator** in the input box; 4. Specify the drawing step interval, image size, and desired export format. Recommended prompts: ```text Use Draw.io Scientific Illustrator. Launch live draw.io with a 100 ms step interval to redraw this reference image. Directly control draw.io's canvas API without controlling system mouse and keyboard, and do not generate XML first. Keep all text, arrows, sections, and legends editable. Check and correct after completing each logical area, and finally save .drawio and export a PNG preview with a width of 2000 px. ``` ### Workflow Normally, Codex will complete the following steps: 1. Launch a visible draw.io; 2. Confirm the internal graph is ready; 3. Add editable shapes and connections one by one or at set intervals; 4. Capture the draw.io rendering area for inspection after completing each logical area; 5. Modify text, style, position, and size directly in the live canvas; 6. Save the `.drawio` snapshot only after completion; 7. Validate the file structure and export PNG, SVG, PDF, or JPG. ### Optional Configuration | Environment Variable | Effect | Default Value | |---|---|---| | `DRAWIO_PATH` | Specify draw.io executable file | Auto-detect | | `DRAWIO_LIVE_PORT` | Preferred local debugging port | `9333`, automatically find nearby ports in case of conflict | | `DRAWIO_LIVE_PROFILE` | draw.io/Electron independent user directory | `~/.drawio-live-mcp/<port>` | Windows example: ```powershell $env:DRAWIO_PATH = "D:\Apps\draw.io\draw.io.exe" ``` ### Update Run the installation script again. The script will perform a safe fast-forward update and reinstall the plugin. Then restart Codex and create a new task. ### Frequently Asked Questions - **Node not found**: Install Node.js 22+, or ensure the Codex plugin runtime environment can call `node`. - **draw.io not found**: Install the desktop version or set `DRAWIO_PATH`. - **Port occupied**: Do not force-specified port, let the plugin choose automatically; or modify `DRAWIO_LIVE_PORT`. - **Graph model not ready**: Close the previously launched but invalid draw.io window and try again. - **Plugin not visible after installation**: Restart Codex and create a new task. - **Export failure**: Confirm that the draw.io desktop version can manually export the file and check the output directory write permissions. ### Security and Privacy - The live debugging port only binds to `127.0.0.1`; - Only accepts pages identifiable as draw.io/diagrams.net, without connecting to arbitrary browser pages; - Does not use system-level mouse and keyboard automation; - Does not include telemetry or cloud services, see [PRIVACY.md](PRIVACY.md) for details; - Before executing remote installation scripts, please check the script content and version. ### Current Limitations - The live tool currently mainly targets editable draw.io elements. Microscopic images, heatmaps, and complex data graphs may require subsequent addition of specialized live image insertion tools; - The final reduction degree depends on the reference image resolution and whether the content is suitable for expression with draw.io elements; - v1.0.0 has been tested on Windows, with macOS/Linux currently supported as much as possible, and welcome submission of test feedback. ## Contributing Issues and pull requests are welcome. Please include operating system, draw.io version, Codex version, reproduction steps, and relevant MCP error text. Do not upload confidential reference images. ## License MIT &copy; 2026 [icebird1998](https://github.com/icebird1998)