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

```bash
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>

```bash
npm run build
```

Add to `~/.claude/settings.json`:

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

Install the skill:
```bash
cp .claude/skills/sci-diagram.md ~/.claude/skills/omnigraffle-bindcraft.md
```

</details>

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

```bash
npm run build
```

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

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

Install the skill:
```bash
cp .claude/skills/sci-diagram.md ~/.workbuddy/skills/omnigraffle-bindcraft.md
```

</details>

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

```bash
npm run build
```

Add to `~/.codex/config.json`:

```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](https://modelcontextprotocol.io/) 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)

```bash
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`](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

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

## License

MIT

## Credits

- [IconPark](https://github.com/bytedance/IconPark) by ByteDance — 2658 high-quality SVG icons
- [OmniGraffle](https://www.omnigroup.com/omnigraffle) by The Omni Group
- [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic