icebird1998/drawio-scientific-illustrator

Live MCP control of the visible draw.io canvas for step-by-step scientific illustration in Codex.

Draw.io Scientific Illustrator (legacy)

What it is – A Codex plugin that lets an AI agent create scientific diagrams live inside the desktop version of draw.io (also known as diagrams.net). The plugin talks to draw.io through a local MCP (Multi‑Channel Plugin) server that calls draw.io’s own graph‑model API, so the agent can add shapes, labels, arrows, style them and see the result instantly on the canvas. It does not use OS‑level mouse/keyboard automation or generate an XML file first.

Why it matters – It demonstrates a concrete way to couple a large‑language‑model‑based agent (Codex) with a real‑time graphical editor, turning a textual prompt into an editable, vector‑based scientific illustration step‑by‑step.

Core components

Component	Role
`drawio-live` MCP server	Starts or connects to a visible draw.io window and manipulates its graph model in real time (add shapes, edges, update cells, take screenshots, save snapshots).
`drawio-file-utils` MCP server	Validates a saved `.drawio` file and exports it to PNG, SVG, PDF or JPG.
Codex skill	Encodes the workflow the agent follows: inspect a reference image, decompose it into primitives, draw them with a configurable pacing, review, refine, and finally save/export.
Local Codex marketplace entry	Packages the above tools so they can be installed with a single `codex plugin add` command.

Requirements

Codex desktop app or CLI with plugin support.
draw.io desktop installed locally (Windows, macOS or Linux).
Git.
Node.js (v22 or newer) if you run the MCP servers outside Codex’s bundled runtime.

Installation (quick‑start)

# Windows – one‑liner (review install.ps1 first)
$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‑liner (review install.sh first)
curl -fsSL https://raw.githubusercontent.com/icebird1998/drawio-scientific-illustrator/main/install.sh | bash

Both scripts install the legacy plugin. The README advises choosing the newer project scientific-illustrator for active development.

Manual install (auditable)

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.)

After installing, restart Codex and start a new task so the skill and MCP tools are loaded.

Typical workflow

Launch – drawio_live_launch starts or attaches to a visible draw.io window.
Ready check – drawio_live_status ensures the graph model is ready.
Draw – use drawio_live_add_shape, drawio_live_add_edge or drawio_live_draw_sequence (paced) to create editable primitives.
Inspect – drawio_live_screenshot captures the canvas; the agent can reason about the image.
Refine – drawio_live_inspect / drawio_live_update_cell modify labels, styles, positions.
Fit view – drawio_live_fit keeps the evolving diagram in view.
Save – drawio_live_save_snapshot writes the live graph to a .drawio file.
Validate & export – drawio_validate and drawio_export produce PNG, SVG, PDF or JPG.

A recommended prompt (English) is provided in the README; an equivalent Chinese version is also supported.

Configuration (optional env vars)

Variable	Meaning	Default
`DRAWIO_PATH`	Explicit path to the draw.io executable.	Auto‑detected
`DRAWIO_LIVE_PORT`	Preferred localhost port for the MCP server.	`9333` (or a nearby free port)
`DRAWIO_LIVE_PROFILE`	Separate Electron profile directory for the live instance.	`~/.drawio-live-mcp/<port>`

Limitations & known issues

Legacy – No further updates; Windows v1.0.0 is the only officially tested platform. macOS/Linux work on a best‑effort basis.
Content scope – The live API is geared toward editable draw.io primitives. Dense microscopy images, heat‑maps, or complex plots may require future image‑insertion tools.
Fidelity – Final visual quality depends on the resolution of the reference image and how well the figure can be expressed with draw.io shapes.
Port conflicts – If DRAWIO_LIVE_PORT is already in use, the server will pick a nearby free port.

Security & privacy

The MCP server binds only to 127.0.0.1; it never exposes a public endpoint.
It connects exclusively to draw.io/diagrams.net windows, not arbitrary browser tabs.
No telemetry or cloud backend is shipped.
Users are urged to review the installer scripts and only run trusted revisions.

License

Note: This repository is archived in favor of the actively maintained scientific-illustrator. For new projects, use that repository instead of this legacy version.