mcp-server-ios-shortcuts: Instructions file for Codex

Agent notes — ios-shortcuts MCP (v2.9.2)

Purpose

Build, sign, import, list, run, and inspect macOS/iOS Shortcuts (.shortcut) via MCP tools. Zero pip deps. macOS only.

Preferred workflow

1. doctor — confirm CLI + sign probe + allow roots
2. Prefer curated short names for production quality
3. Existing library shortcut (critical):
   • export_library_shortcut or user export to disk
   • extract_signed_shortcut / decompile_shortcut (AEA1 decrypt)
   • clone_shortcut to fork under a new name
   • Diff real identifiers before inventing a “fix”
4. For files you already have: decompile_shortcut → edit → validate_recipe → rebuild
5. After library changes: learn_from_corpus / extract_system_library
   • Needs Full Disk Access for Shortcuts.sqlite
   • Never trust self-bootstrap unless debugging
6. Generic short keys only if accepted map exists (get_learned_params)
7. Remap → schema-aware coercion (enums plain; text may token-wrap)
8. App Intents: type: app_intent with reverse-DNS identifier
9. validate_recipe with target_platform (ios/macos)
10. build_shortcut — keep raw_path for inspect/decompile/learn
11. run_shortcut when installed (safe_mode blocks)

Never improve a real user shortcut by guessing IDs without extract.
Docs: docs/CLONE_AND_EXTRACT.md

Sign before shipping to the user

shortcuts sign -m anyone -i Name_raw.shortcut -o Name.shortcut

Do not use --mode / --input / --output (agents have failed with “incorrect format”).
Do not claim “개선 완료” with only *_raw.shortcut — iPhone needs the signed file.

Build result shape

{
  "ok": true,
  "path": "/…/Name.shortcut",
  "raw_path": "/…/Name_raw.shortcut",
  "signed_path": "/…/Name.shortcut",
  "signed": true,
  "actions_summary": [{ "index": 0, "type": "delay", "…": "…" }],
  "warnings": [],
  "risks": []
}

Import tools report import_status: "import_prompted" — GUI confirm may still be required.