ipe-bindcraft

Ipe automation skill + MCP server for AI coding agents. Create and iteratively edit native Ipe vector figures for academic papers via natural language — with transactional batches, stable object IDs, LaTeX-measured text, and native undo in the live GUI.

Features

• 15 MCP tools for document lifecycle, semantic editing, routing, layout, lint, preview, export

• Two authoritative backends — the .ipe file on disk, or a bound live Ipe window's in-memory document; never a second scene.json

• Transactional batches — typed operations with stable IDs, optimistic revision checks, request deduplication, atomic commits, and per-operation failure details

• Semantic connections — edges bind to real node outlines (rect / rounded / ellipse / diamond ports), auto re-route when endpoints move; straight / orthogonal / auto / manual routing, with hop-over arcs baked at edge crossings (the higher z-order edge jumps)

• Academic presets — semantic palettes (paper-muted, paper-vivid, paper-ocean, paper-monochrome), 3 starter templates (system_overview, algorithm_pipeline, parallel_workers), and 15 curated native-path icons (database, cloud, gear, …)

• LaTeX-aware text — labels are measured through real ipescript + doc:runLatex(); node resize never shrinks fonts

• Native undo in Live mode — every batch is a single model:register transaction (one Ctrl-Z), verified end-to-end

• Preserve-everything editing — unknown Ipe objects, human regrouping, and manual edits survive round-trips

• Honest errors — stable machine-readable codes (REVISION_CONFLICT, LATEX_FAILED, GUI_BUSY, COMMIT_STATUS_UNKNOWN, …) as isError=true tool results

Related MCP server: Rayzia MCP

Requirements

• Windows 10/11 (the live backend and tests/windows_live are Windows-only)

• Ipe 7.2.x — verified on 7.2.29 (winget OtfriedCheong.Ipe)

• A local TeX distribution for label measurement — verified on MiKTeX 26.2

• Python 3.13 + uv

Installation

git clone https://github.com/LHaiC/ipe-bandcraft.git
cd ipe-bandcraft
uv sync --locked            # creates .venv with locked dependencies

For live (GUI) mode, install the bridge ipelet once per user:

.venv/Scripts/ipe-bindcraft.exe install-ipelet

This copies ipelet/ipebindcraft.lua into %USERPROFILE%\Ipelets\. It does not touch any global Ipe or system configuration.

MCP configuration

Any MCP-compatible agent can use the server over stdio:

{
  "mcpServers": {
    "ipe-bindcraft": {
      "command": "C:\\path\\to\\ipe-bandcraft\\.venv\\Scripts\\python.exe",
      "args": ["-m", "ipe_bindcraft", "serve"]
    }
  }
}

Quick start

ipe-bindcraft doctor                  # probe Ipe/TeX/MCP + live bridge
ipe-bindcraft create fig.ipe --width 504 --height 300
ipe-bindcraft create fig.ipe --template algorithm_pipeline --palette paper-vivid
ipe-bindcraft apply fig.ipe @ops.json --revision sha256:... --request-id r1
ipe-bindcraft inspect fig.ipe --geometry
ipe-bindcraft lint fig.ipe --target-width 252
ipe-bindcraft preview fig.ipe -o fig.png
ipe-bindcraft export fig.ipe --formats pdf svg png -o out/
ipe-bindcraft open fig.ipe --backend live    # bound GUI session
ipe-bindcraft serve                          # stdio MCP server

Or just ask your agent: "Create a system-overview figure in fig.ipe with 8 nodes, orthogonal edges, Nature-muted palette; export PDF + PNG."

Tools (15)

Live mode

open_document(path, backend="live") launches ipe.exe bound to a private session directory; the bundled ipelet applies each batch via ipe.Page + doc:set inside one model:register transaction:

• one batch = one native undo item (Ctrl-Z / Ctrl-Y verified)

• manual edits in the GUI are authoritative — conflicting batches get REVISION_CONFLICT instead of overwriting

• GUI exit mid-request surfaces COMMIT_STATUS_UNKNOWN; never silently falls back to writing the file

Architecture

AI Agent  <-- MCP stdio -->  ipe-bindcraft service
                                  │
                    ┌─────────────┴─────────────┐
                FileBackend                 LiveBackend
             (.ipe authoritative)      (bound GUI doc authoritative)
                    │                           │
              atomic write + lock    ipelet: ipe.Page + doc:set
                                    inside one model:register

One Python candidate compiler serves both backends — Lua only validates the baseline and submits the candidate page; it contains no second router or layout engine.

Testing

pytest tests/unit            # 58 tests — no external deps
pytest tests/integration     # real Ipe + TeX (skips when absent)
pytest tests/windows_live    # real ipe.exe windows (Windows only)

70 tests currently pass on the target machine; see docs/acceptance-report.md for the A01–A23 evidence matrix, and docs/capability-report.md for the M0 probe results.

Known limitations

• Ipe 7.2.29 CLI tools cannot open non-ASCII paths on zh-CN Windows; documents must live on ASCII paths (internal temp dirs are already ASCII-safe).

• Single page / single view documents only.

• Icons are a curated set of 15 native-path glyphs — arbitrary SVG icon import is intentionally out of scope. Hop-over arcs are generated for managed semantic edges only (manual edits to an edge's path are kept until its hop set changes). No arbitrary code execution — by design.

Development

uv sync --locked --group dev
pytest tests -q
ipe-bindcraft schema > schemas/apply_operations.schema.json

Credits

• Ipe by Otfried Cheong — the extensible drawing editor this project automates

• omnigraffle-bindcraft by Youn-17 — conceptual reference for batch operations, semantic connections, and the MCP + skill split

• Model Context Protocol by Anthropic

License

MIT — see docs/third-party-notices.md for dependency and tool notices.