omnigraffle-bindcraft

OmniGraffle automation skill + MCP server for AI coding agents. Create publication-quality scientific diagrams, flowcharts, and architecture diagrams via natural language.

<p align="center"> <img src="https://img.shields.io/badge/platform-macOS-blue" alt="macOS only"> <img src="https://img.shields.io/badge/OmniGraffle-7.x-purple" alt="OmniGraffle 7"> <img src="https://img.shields.io/badge/MCP-compatible-green" alt="MCP compatible"> <img src="https://img.shields.io/badge/icons-2658-teal" alt="2658 icons"> <img src="https://img.shields.io/badge/license-MIT-orange" alt="MIT License"> </p>

<p align="center"> <img src="examples/demo_rag_pipeline.png" alt="Demo: RAG Pipeline" width="800"> </p> <p align="center"><em>Example output — RAG-Enhanced LLM Pipeline diagram with Nature Standard palette, smart arrow routing, and semantic color categories</em></p>

Features

• 36 MCP tools for full OmniGraffle control: shapes, connections, layout, export
• Smart arrow routing — auto-selects straight / orthogonal / curved based on shape positions; hop-over arcs at crossings
• 6 journal color palettes — Nature, Science, Cell, Lancet, Minimal, Vibrant
• 6 diagram templates — experimental workflow, data pipeline, PRISMA, system architecture, ML pipeline, clinical trial
• 2658 IconPark icons across 38 categories
• Batch operations — create dozens of shapes and connections in single calls
• Hub magnets — distribute connection points to prevent arrow pile-ups
• Dual automation — Omni Automation JS + JXA/AppleScript

Requirements

• macOS (OmniGraffle is macOS-only)
• OmniGraffle 7 (Pro recommended for full scripting support)
• Node.js >= 18
• Python 3 with cairosvg — for icon SVG-to-PNG conversion (optional, only needed for icons)

Installation

Quick install (auto-detects runtime)

git clone https://github.com/Youn-17/omnigraffle-bindcraft.git
cd omnigraffle-bindcraft
npm install
bash scripts/install.sh

The install script auto-detects Claude Code, Codex, and WorkBuddy, then:

• Builds the project
• Adds the MCP server to each runtime's config
• Copies the skill file to each runtime's skills directory

Manual install

<details> <summary><b>Claude Code</b></summary>

npm run build

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "omnigraffle": {
      "command": "node",
      "args": ["/absolute/path/to/omnigraffle-bindcraft/dist/index.js"]
    }
  }
}

Install the skill:

cp .claude/skills/sci-diagram.md ~/.claude/skills/omnigraffle-bindcraft.md

</details>

<details> <summary><b>WorkBuddy</b></summary>

npm run build

Add to ~/.workbuddy/.mcp.json:

{
  "mcpServers": {
    "omnigraffle": {
      "command": "node",
      "args": ["/absolute/path/to/omnigraffle-bindcraft/dist/index.js"]
    }
  }
}

Install the skill:

cp .claude/skills/sci-diagram.md ~/.workbuddy/skills/omnigraffle-bindcraft.md

</details>

<details> <summary><b>Codex</b></summary>

npm run build

Add to ~/.codex/config.json:

{
  "mcpServers": {
    "omnigraffle": {
      "command": "node",
      "args": ["/absolute/path/to/omnigraffle-bindcraft/dist/index.js"]
    }
  }
}

</details>

<details> <summary><b>Other MCP-compatible agents</b></summary>

Any agent supporting the Model Context Protocol can use this server. Add the MCP entry to your agent's config — the format is the same across runtimes.

</details>

Set up IconPark icons (optional)

git clone https://github.com/bytedance/IconPark.git resources/iconpark
pip install cairosvg

Quick start

Once installed, just describe what you want in natural language:

Create a RAG pipeline diagram in OmniGraffle with 10 components:
User Query, Query Analyzer, Intent Router, Knowledge Retrieval,
LLM Reasoning Core, Tool Executor, Evidence Checker,
Response Generator, Safety Filter, Final Response.
Use Nature palette. Export to Desktop.

See examples/demo_rag_pipeline.md for a full walkthrough.

Tools (36)

Document & Canvas (8)

Tool	Description
get_document_info	Get document name, path, canvases
create_document	Create new document (optionally from template)
save_document	Save current document
list_templates	List all available OmniGraffle templates
create_canvas	Create a new canvas
list_canvases	List all canvases
switch_canvas	Switch to a canvas by index
set_canvas_size	Set canvas dimensions

Shapes (6)

Tool	Description
create_shape	Create a shape with type, position, size, text, and full styling
create_shapes_batch	Create multiple shapes in one call
update_graphic	Update any property of an existing graphic
delete_graphics	Delete graphics by ID
get_graphics	List all graphics with properties
clear_canvas	Remove all graphics from canvas

Connections (4)

Tool	Description
connect_shapes	Connect two shapes with styled, auto-routed line
connect_shapes_batch	Batch connect with smart routing (line_type: "auto")
create_line	Create a standalone line between points
set_magnets	Set connection points on a shape for clean arrow distribution

Layout & Organization (6)

Tool	Description
auto_layout	Apply automatic layout
align_graphics	Align graphics (left/center/right/top/bottom)
create_layer	Create a new layer
list_layers	List all layers
group_graphics	Group graphics together
ungroup	Ungroup a group

Icons (5)

Tool	Description
search_icons	Search 2658 IconPark icons by keyword
list_icon_categories	List all 38 icon categories
suggest_icons	Get icon suggestions for a scientific context
insert_icon	Insert a colored icon onto the canvas
create_node_with_icon	Create a labeled shape with an icon inside

Palettes & Templates (4)

Tool	Description
list_palettes	List all 6 scientific color palettes
get_palette	Get a palette's full color values
list_diagram_templates	List all 6 diagram templates
get_diagram_template	Get a template's nodes, icons, and palette

Export & Scripting (4)

Tool	Description
export_canvas	Export to PNG, PDF, or SVG
run_omni_js	Execute Omni Automation JavaScript
run_jxa	Execute JXA code
run_applescript	Execute AppleScript

Smart arrow routing

The connect_shapes_batch tool supports line_type: "auto" which automatically picks the best routing:

Shape relationship	Auto-selected type	Why
Same column (Δx < 60px)	straight	Clean vertical drop
Same row (Δy < 30px)	straight	Direct horizontal
Cross-column & cross-row	orthogonal	Right-angle turns
Target above source	curved	Avoids overlap with forward flow

All connections automatically get HopType.Round for clean crossing arcs.

Color palettes

Palette	Best for	Style
nature	General science papers	Clean, high-contrast, colorblind-safe
science	Bold research graphics	Vivid but balanced
cell	Biology, life sciences	Elegant muted tones
lancet	Clinical, medical	Professional ocean blue + orange
minimal	Grayscale print	Maximum print compatibility
vibrant	Posters, presentations	High-saturation, eye-catching

Architecture

AI Agent  <── MCP Protocol ──>  MCP Server (Node.js)
                                      │
                        ┌─────────────┼─────────────┐
                        │             │             │
                  Omni Automation   JXA/AS      IconPark
                  (evaluateJS)    (osascript)   (cairosvg)
                        │             │             │
                        └──────┬──────┘      SVG → PNG
                               │
                          OmniGraffle 7

Development

npm run dev    # Watch mode — recompiles on changes
npm run build  # One-time build
npm start      # Run the server directly

License

MIT

Credits

• IconPark by ByteDance — 2658 high-quality SVG icons
• OmniGraffle by The Omni Group
• Model Context Protocol by Anthropic