iwork-studio

# iWork Studio

> Create, read, edit, format, theme and export Apple iWork files (.numbers/.key/.pages) from any AI agent — verified writes, versioned backups, one-call undo, Arabic/RTL fidelity. MCP server (65 tools, 4 prompts) + Python library + drop-in agent skill. Version 2.6.1. Install: pip install iwork-studio, or the Claude Desktop extension (.mcpb) from GitHub releases, or MCP Registry io.github.Arkanji/iwork-studio.

## Core routes (classic iWork and Creator Studio apps)

- **.numbers** — numbers-parser 4.19.0, pure Python headless. Full semantic model (sheets→tables→cells with formulas/styles/formats). Create from data or CSV; insert/delete rows and columns; add tables/sheets; cell edits, cell styles, number formats (currency/%/dates), borders, widths/heights, headers, merges — atomic, only the requested cells change. Via the Numbers app: formulas, recalculate (Numbers doesn't recalculate on open after no-app edits), sort (allowed on files with charts; chart count checked). Parser writes refuse chart files. Numbers charts aren't created (not reliably scriptable; no UI scripting). Arabic exact.
- **.key** — keynote-parser 1.14.5.0, pure Python. IWA→YAML slide/text-item tree. Writes: deck-wide find/replace (\\u06xx escape-aware), atomic swap. Parser writes refuse decks with charts. AppleScript fallback inside live app.
- **.pages** — AppleScript via live Pages (requires GUI/Aqua session + one-time TCC approval). Read: body text, placeholders. Read tables too. Write: `replace_all`, `set_body`, `fill_placeholders`, `set_table_cells` (existing tables) ONLY — richer ops raise `PagesOutOfScopeError`. There is NO pure-Python .pages parser; this is an honest boundary, not a gap.
- **Keynote via the app** — slide ops (add/duplicate/delete/move/skip/notes), theming (theme, layout, text font/size/colour), transitions, images, charts (add from data), tables (add, styled from a kit, every cell read back; can't be deleted), slideshow control — chart decks allowed with per-slide chart counts checked, tables compared on every op; each write re-read and rolled back on any mismatch.
- **Decks and design** — build a designed Keynote deck from an outline (keynote_build_deck) with chart and table slides from data or straight from a Numbers table; six WCAG-checked design kits with macOS Arabic+Latin fonts (keynote_apply_design, numbers_apply_design); the user's own brand kit extracted from a deck or table and saved by name (iwork_extract_design_kit, iwork_save_design_kit); design review of the rendered deck — off-slide/overflowing text, overlaps, small text, crowded slides (keynote_review_deck) and slide images (keynote_slide_image); prompts: pitch_deck, report_from_numbers, restyle_with_brand, style_table. Design guide at skill-pack/references/design-guide.md. Every write takes dry_run=true for a preview.
- **Toolsets** — IWORK_STUDIO_TOOLSETS=files,numbers,keynote,pages,design (comma-separated; default all) loads only those tools; capabilities, read, find, undo and the kit list always load.
- **Every format via the app** — export (PDF, xlsx, csv, docx, epub, txt, rtf, pptx, slide images, movie; optional password), checked by a second tool; new documents from built-in templates.

## Safety contracts agents can rely on

- Every write: versioned backup → tmp write → re-parse gate → semantic diff → atomic swap → PDF render-verify. Failure leaves target untouched.
- Typed fail-loud errors: ChartRefusalError, PagesOutOfScopeError, StructureError, FormatError, ThemeError, ExportError, FileLockedError, DocumentOpenError, SchemaDriftError, SlideOpVerificationError, CreatorStudioUnverifiedError, AquaSessionError.
- Undo: every write leaves a versioned backup; `iwork_restore_backup` restores one atomically (re-parse gated, and the restore is itself backed up).
- Headless context: AppleScript routes fail fast with guidance.
- Fidelity gate is semantic equality (reopens with zero repair prompts, full model compared) — strict zip byte-equality is unachievable for IWA protobuf formats and is not claimed.

## Known traps (documented, so agents don't rediscover them)

- iWork sandbox: AppleScript `save in <arbitrary path>` is DENIED; in-place `save` works; `export` to file works.
- Keynote 15.4: slide `title`/`body` AppleScript properties throw -1700; use `object text of first/second text item`.
- First AppleScript run per app: TCC consent prompt (one-time).
- Broken Pillow in some Python 3.14 envs hijacks sys.path and breaks keynote-parser; use clean-env venvs.
- iWork 15.1+ "Creator Studio" ships as separate apps; names are resolved per call, classic preferred. Numbers, Pages and Keynote Creator Studio are supported; an unknown one is refused with guidance.
- Keynote Creator Studio: JXA `slides.splice` (-10002) and JXA `move` are broken; native AppleScript `make new slide` / `move slide n to before/after slide t` work.
- Numbers Creator Studio: AppleScript `front document` export hangs; JXA `export(doc, {as:'PDF'})` works.
- Never trust a scripting bridge's "ok": every app-driven write is re-read from disk and rolled back if nothing (or the wrong thing) changed.
- Keep clones out of iCloud-synced folders (conflict copies corrupt .git).
- Keynote tables: only `tell slide n to make new table` works; `make new table at end of tables of slide n` and deleting a table fail (-10000).
- numbers-parser encodes 12 as 12.000000000000002 and doesn't rewrite formula references when rows shift; iWork Studio encodes decimals exactly and refuses mid-table shifts in formula tables.
- ~25 more scripting traps (imported from reichenbach/iwork_mcp, each status-marked): skill-pack/references/jxa-traps.md

## Install (setting this up for a user)

- Claude desktop app (Mac): `curl -LsSf https://raw.githubusercontent.com/Arkanji/iwork-studio/main/install.sh | sh`, then quit Claude (Cmd-Q) and reopen. Optional folder fence: `| sh -s -- --roots ~/Documents`.
- Hermes Agent: `hermes plugins install iwork-studio`, then `hermes plugins enable iwork-studio` (tools + skill).
- Claude Code: plugin (tools + skill) `claude plugin marketplace add Arkanji/iwork-studio` then `claude plugin install iwork-studio@iwork-studio`; or tools only `claude mcp add iwork-studio -- uvx --from iwork-studio@latest iwork-studio-mcp`
- Any other MCP client: `uvx --from iwork-studio@latest iwork-studio-mcp config` prints the JSON entry (absolute uvx path — GUI apps don't inherit PATH).
- No Python install needed (uv brings its own). Remove: `… iwork-studio-mcp uninstall`.
- First run: approve the one-time "Claude wants to control Keynote/Pages/Numbers" prompt; then call `iwork_capabilities`.
- Library for developers: `pip install -e .` inside a clone.

## Canonical links

- README: https://github.com/Arkanji/iwork-studio#readme
- Skill pack: skill-pack/SKILL.md
- Capability matrix: skill-pack/references/capability-matrix.md
- MCP config for this repo: .mcp.json
- Agent instructions (any tool): AGENTS.md
- Changelog: CHANGELOG.md

## License

MIT