omnigraffle-bindcraft

English | 简体中文

Agent-assisted, editable monochrome academic diagrams in OmniGraffle.

omnigraffle-bindcraft combines an MCP server with a semantic workflow skill for thesis figures, research frameworks, technology roadmaps, and other clean print-oriented diagrams. Agents can create the complete diagram, inspect the real OmniGraffle canvas, make precise corrections, and preserve later human edits.

Why this fork

The original project provides broad diagram automation, palettes, templates, and icon tools. This fork adds a workflow specialized for academic figures:

• monochrome, white-background, print-safe defaults;
• native OmniGraffle shapes, lines, and editable Bezier paths;
• semantic round-trip updates that preserve manual canvas edits;
• editable side annotations and SVG ornaments;
• real-application inspection, persistence, and export verification;
• iterative correction instead of handing visual defects to the user.

The server still exposes the original general-purpose palettes, templates, icons, and direct scripting tools. Academic workflow mode keeps those capabilities optional.

Requirements

• macOS
• OmniGraffle 7.x; Pro is recommended for full automation support
• Node.js 18 or newer
• A compatible MCP client such as Codex, Claude Code, or WorkBuddy

Python and CairoSVG are needed only for the optional IconPark conversion workflow.

Focus policy

By default the automation does not call activate, so agent runs do not steal macOS focus from your current app.

OMNIGRAFFLE_ACTIVATE	Behavior
unset / never	Never steal focus (default)
export	Activate only for export, then restore the previous front app when possible
always	Legacy behavior: activate on most operations

export OMNIGRAFFLE_ACTIVATE=never
export OMNIGRAFFLE_ACTIVATE=export
export OMNIGRAFFLE_ACTIVATE=always

Installation

Automatic local setup

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

The installer always installs dependencies and rebuilds the current source. It then:

• configures the omnigraffle MCP server for detected runtimes;
• links the repository skill into $HOME/.agents/skills for Codex;
• installs the complete canonical workflow skill directory for detected Claude Code or WorkBuddy setups;
• runs a post-install self-check covering MCP startup and version, Skill metadata, all five references, and CLI help.

Restart the agent after installation.

Manual Codex setup

git clone https://github.com/Shi1xin/omnigraffle-bindcraft.git
cd omnigraffle-bindcraft
npm install
npm run build

codex mcp add omnigraffle -- node "$(pwd)/dist/index.js"
mkdir -p "$HOME/.agents/skills"
ln -s "$(pwd)/.agents/skills/omnigraffle-workflow" \
  "$HOME/.agents/skills/omnigraffle-workflow"

Codex also discovers the repository skill automatically when a session starts anywhere inside this repository.

Manual Claude Code setup

Build the project, add dist/index.js as a stdio MCP server named omnigraffle, and copy the canonical skill directory:

npm install
npm run build
mkdir -p "$HOME/.claude/skills/omnigraffle-workflow"
cp -R .agents/skills/omnigraffle-workflow/. \
  "$HOME/.claude/skills/omnigraffle-workflow/"
npm run self-check -- \
  --skill-dir "$HOME/.claude/skills/omnigraffle-workflow"

For WorkBuddy, use the same canonical directory at $HOME/.workbuddy/skills/omnigraffle-workflow and pass that path to the self-check.

Example MCP entry for clients that use JSON configuration:

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

Quick start

Open OmniGraffle, start a new agent session, and invoke the workflow skill with task-specific inputs only:

$omnigraffle-workflow

Create a thesis technology roadmap from /path/to/outline.md.
Use /path/to/reference.png as the visual reference.
Save the editable document to /path/to/output.graffle.

The skill loads the model, style, calibration, diagnostics, and verification references needed for the task. Prompts only need task-specific content, source assets, and output paths.

If an already-running session has not loaded the MCP tools yet, the same operations are available through node dist/workflow/cli.js --help.

Semantic workflow

The workflow model is a reviewable JSON document that can be applied, inspected, revised, and edited directly in OmniGraffle. See the canonical semantic workflow model for collections, identity, ownership, routing, and human-edit persistence.

outline or reference image
        ↓
semantic workflow JSON
        ↓
apply_workflow
        ↓
inspect the real OmniGraffle canvas
        ↓
targeted correction and verification
        ↓
human editing remains available

Academic defaults

• white canvas;
• black or neutral-gray strokes and text;
• equal RGB components for every declared color;
• rectangular boxes and dashed section containers;
• no shadows, gradients, icons, or decorative illustrations;
• restrained line weights and readable thesis-scale typography;
• editable side annotations selected from the reference primitive and semantic role;
• external SVG ornaments imported through vectors when needed;
• reference-image comparison with typography and section-whitespace calibration at full-diagram and close-detail scales.

Users can override these defaults when a figure requires a different visual system.

Example model

examples/academic_workflow_zh.json is an original generic Chinese academic roadmap demonstrating the editable semantic workflow.

Tools

The MCP server exposes 39 tools across these groups:

• document and canvas management;
• shape creation and editing;
• connections, magnets, and layout;
• semantic workflow apply and inspection;
• PNG, PDF, and SVG export;
• Omni Automation JavaScript, JXA, and AppleScript;
• optional palettes, templates, and IconPark helpers.

Verification

Repository tests cover schema constraints, routing behavior, snapshot output, SVG parsing, monochrome fixture rules, endpoint magnets, and section transitions.

npm test
npm audit --omit=dev
npm pack --dry-run

Real diagram work follows the canonical application verification procedure.

Security

This server controls a local OmniGraffle application. The run_omni_js, run_jxa, and run_applescript tools can execute supplied automation code on the Mac. Install from a trusted checkout, review agent actions, and use normal MCP approval and sandbox controls.

Development

npm install
npm run dev
npm test

Key implementation files:

• src/workflow/model.ts — semantic model schema
• src/workflow/scripts.ts — apply and inspect automation
• src/workflow/svg.ts — SVG path parsing and native vector import
• .agents/skills/omnigraffle-workflow/ — Codex workflow skill and references
• .agents/skills/omnigraffle-workflow/references/reference-layout-calibration.md — reference typography and geometry calibration

License and credits

The project code is released under the MIT License. Third-party assets keep their own licenses; see THIRD_PARTY_NOTICES.md.

This repository is a fork of Youn-17/omnigraffle-bindcraft. It also integrates with OmniGraffle, the Model Context Protocol, and optional IconPark resources.