# shortcuts-playground-mcp

MCP server for Apple Shortcuts generation, inspired by [viticci/shortcuts-playground-plugin](https://github.com/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`](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:

| Plugin | MCP |
|---|---|
| One generic write + validator repair loop | `add_conditional(condition, then_actions, else_actions)` owns `GroupingIdentifier` (H1) |
| Model juggles `OutputUUID` / `OutputName` + `U+FFFC` positions | Model names variables in human-readable form; server resolves to UUID/magic-variable at serialization (`serializer.py`) (H2) |
| Full catalog in context (365 WF* + 2,731 v78 ids + 7 MD refs + 19 golden XMLs) | Hierarchical, on-demand navigation `list_categories` → `search_actions(limit=20)` → `get_action_schema` + `resource://examples/*.md` tool-call flows, not XML (H2) |

## Tools

| Tool | Purpose |
|---|---|
| `search_actions(query)` / `list_categories()` | Hierarchical catalog navigation |
| `get_action_schema(action_id)` | Parameter / enum schema for one action |
| `add_action(action_id, params)` | Simple, non-nesting actions |
| `add_conditional(...)` / `add_repeat(...)` / `add_menu(...)` | Compound, structurally-safe builders for control flow |
| `validate()` | Round-trip check before signing (shells out to their `validate-shortcut`) |
| `sign()` | Shells out to their `sign-shortcut` |
| `export_readable()` | Dumps in-progress shortcut as human-readable XML/summary |

## Installation

Configure in your MCP client:

```json
{
  "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](https://github.com/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](https://github.com/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.