shortcuts-playground-mcp

MCP server for Apple Shortcuts generation, inspired by viticci/shortcuts-playground-plugin.

The plugin generates valid, signed .shortcut files from natural language as a Claude Code / Codex in-chat skill. This repo explores the same job through an MCP server, with two core hypotheses:

1) Structural safety: MCP's schema-validated tool-call layer can make the GroupingIdentifier / WFControlFlowMode class of error structurally impossible, instead of catching it after the fact in a validate-and-repair loop

Beyond safety/error reduction, I think the structured set of tools can also help agents with reasoning by forcing the build into logical steps like a human would when using the UI. Skills can certainly encourage this, but the tools enforce it. I think that this prevents an agent from trying to one-shot the XML.

2) Context reduction: MCP's on-demand, hierarchical tool surface (list_categories → search_actions → get_action_schema, plus {{Var}} name resolution and resource:// tool-call-flow examples) can meaningfully reduce per-turn context vs. putting the full 600+ action catalog + 19 golden XMLs in context, while preserving first-attempt correctness

I'm sort of building an API for building Shortcuts, which is not that useful as is for developers imo, since Apple already provides a nice UI for it, and I can't think of a good scripted use case. Packaged as an MCP though, this gives AI agents a nice toolkit from converting a natural language description to a working shortucut.

Architecture

Reuse:

• skills/shortcuts-playground/ from the plugin — the action catalog: verified action identifiers, parameter-key schemas, enum-case catalogs, automation triggers, versioned per OS (ToolKit v63 for macOS 26, v78 for macOS/iOS 27). ~1,794 ids (v63) → 2,731 ids (v78).

• bin/validate-shortcut and bin/sign-shortcut — standalone Python 3.10+ CLI wrappers for structural validation and Apple's native signing step. Reuse by shelling out.

See docs/CATALOG_CONSUMPTION.md for how the catalog is consumed without forking wholesale.

Divergence (experimental):

With the plugin, agents write raw XML and rely on the Craig Loop (post-hoc validate-shortcut → repair → re-validate, up to 5 iterations) to catch malformed GroupingIdentifier / WFControlFlowMode pairing errors in If/Otherwise/Repeat blocks. The MCP implementation instead exposes compound, schema-validated tools that mutate the state of the shortuct deterministically as its built:

Related MCP server: Apple Shortcuts MCP Server

Tools

Installation

Configure in your MCP client:

{
  "mcpServers": {
    "shortcuts-playground": {
      "command": "shortcuts-mcp",
      "env": {
        "SHORTCUTS_CATALOG_DIR": "./catalog",
        "SHORTCUTS_TARGET_MACOS": "26"
      }
    }
  }
}

Architecture

catalog/                  ← vendored ToolKit snapshots + markdown refs
src/shortcuts_mcp/
  catalog.py              ← search/list/get backed directly by catalog JSON
  builder.py              ← session state: UUID allocation, name→UUID map, GroupingIdentifier ownership
  serializer.py           ← name-resolved → plist XML, WFTextTokenString/Attachment wiring
  validator.py            ← shells out to bin/validate-shortcut
  signer.py               ← shells out to bin/sign-shortcut
  server.py               ← MCP tool definitions
tests/
  test_control_flow_compare.py

Evaluation

We evaluate both hypotheses:

• 1) (structural safety): If compound tools do not reduce first-attempt validate() errors vs. raw-XML + Craig Loop, that means determinism of MCP can't meaningfully abstract the construction of a shortcut. Test is tests/test_control_flow_compare.py — same shortcut both ways, nontrivial nesting (If inside Repeat, Otherwise If, Menu 3 cases), counted errors on first attempt.

• 2) (context reduction): If on-demand tools do not reduce per-turn context vs. full-catalog-in-context, that's also an indication the MCP isn't useful. Test is tokens per turn (not total turns): a search_actions("Show Result") → showresult (1–2 ids, <1k tokens) vs. pasting 2,731 v78 ids + CONTROL_FLOW.md:327 table + golden XML in context (5–10k), and the fact that {{Name}} + resource://examples/greeter.md tool-call flows replace OutputUUID juggling + 19 XML pastes. Total turns increase slightly (search + get_schema + add_* + validate), but per-turn context and repair-loop re-feeds shrink; we report both.

Credits

This project builds directly on the work of two prior open-source efforts:

• viticci/shortcuts-playground-plugin - the Claude Code / Codex plugin that pioneered generating valid, signed .shortcut files from natural language. This repo reuses its skills/shortcuts-playground/ action catalog (verified ToolKit v63/v78 identifiers, parameter-key and enum schemas, trigger metadata) and its bin/validate-shortcut / bin/sign-shortcut wrappers, avoids re-deriving/engineering the schema from scratch. The plugin's Craig Loop (post-hoc validate-and-repair) is the baseline this MCP's compound-tool hypothesis is tested against.

• drewocarr/generate-shortcuts-skill a Claude Code skill that documents the Shortcuts plist format (SKILL.md, ACTIONS.md, CONTROL_FLOW.md, VARIABLES.md, etc., 427 WF* + 728 AppIntents). Its SKILL.md + 7-MD pattern is the direct inspiration for this repo's resources/ packaging (see docs/SKILL_RESOURCES.md), where examples are exposed as read-only resource:// MD showing how to call tools rather than the exact XML to emit.