apple-shortcut-maker-mcp: Instructions file for Claude Code

Apple Shortcut Maker MCP - Development Notes

Project Overview

This is an MCP (Model Context Protocol) server that allows AI assistants to create Apple Shortcuts programmatically using the Cherri programming language.

Architecture

┌─────────────────────────────────────────┐
│   MCP Client (Claude/Cursor/etc)       │
└─────────────────────┬───────────────────┘
                      │ MCP Protocol
                      ▼
┌─────────────────────────────────────────┐
│   MCP Server (Python)                   │
│   - create_shortcut()                   │
│   - duplicate_shortcut()                │
│   - list_shortcuts()                    │
│   - run_shortcut()                      │
└───────┬───────────────────┬─────────────┘
        │                   │
        ▼                   ▼
┌───────────────┐   ┌──────────────────────┐
│ Cherri CLI    │   │ shortcuts CLI        │
│ (.cherri ->   │   │ (list, run, import)  │
│  .shortcut)   │   │                      │
└───────────────┘   └──────────────────────┘

Key Files

File	Description
src/apple_shortcut_mcp/server.py	Main MCP server implementation
src/apple_shortcut_mcp/cherri_helper.py	Wrapper for Cherri compiler
src/apple_shortcut_mcp/tools/create.py	Create shortcut tool
src/apple_shortcut_mcp/tools/duplicate.py	Duplicate shortcut tool
src/apple_shortcut_mcp/tools/list_shortcuts.py	List shortcuts tool
src/apple_shortcut_mcp/tools/run.py	Run shortcut tool

Development

Running the Server

# Development mode
uv run apple-shortcut-mcp

# With debug output
DEBUG=1 uv run apple-shortcut-mcp

Testing

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov

Cherri Code Reference

Basic Syntax

// Variable assignment - use @
@varName = "value"

// Built-in actions
alert("message", "title")
askText("prompt")
askNumber("prompt")
showResult("text")
calculate(math expression)

// Menu
menu "Title:" {
    item "Option 1":
        // action
    item "Option 2":
        // action
}

// Loops
repeat 3 {
    // actions
}

for @item in @list {
    // actions
}