scpl-updated-mcp-server 1.0.17 → 1.1.0

package/README.md

@@ -248,10 +248,41 @@ Case "Option 2"
     Text "You chose 2"
 End Menu
 
-# Loops
-RepeatWithEachItem
-    ShowResult
-End Repeat
+# Loops - IMPORTANT: name the loop variable!
+List ["a", "b", "c"]
+RepeatWithEach -> mv:Item
+    ShowResult "\(mv:Item)"
+End RepeatWithEach
+```
+
+### ⚠️ Common Gotchas
+
+```scpl
+# ❌ WRONG: mv:RepeatItem doesn't exist
+RepeatWithEach
+    Text "\(mv:RepeatItem)"
+
+# ✅ CORRECT: Name your loop variable
+RepeatWithEach -> mv:Item
+    Text "\(mv:Item)"
+
+# ❌ WRONG: Multi-line text can't use ->
+Text
+| Line 1
+| Line 2
+-> v:MyVar
+
+# ✅ CORRECT: Use SetVariable on next line
+Text
+| Line 1
+| Line 2
+SetVariable v:MyVar
+
+# ❌ WRONG: Wait only takes integers
+Wait 0.5
+
+# ✅ CORRECT: Use whole numbers
+Wait 1
 ```
 
 ## Examples
@@ -320,6 +351,31 @@ Check the error message for line numbers and syntax issues. Common mistakes:
 - Using wrong parameter names (use `list_actions` to check)
 - Missing quotes around text values
 
+## Skill Architecture (For AI Maintainers)
+
+The ScPL skills are distributed through **three different mechanisms**:
+
+| Platform | Skill Source | Update Process |
+|----------|--------------|----------------|
+| **Claude Code** | `.claude/shortcuts-creator/skills/create-shortcut.md` | Edit file directly |
+| **Claude Desktop** | `claude-desktop-skill/scpl-shortcuts.zip` (contains Skill.md + REFERENCE.md) | Edit files, regenerate zip |
+| **Codex** | Generated dynamically from `SCPL_REFERENCE.md` by `index.js` | Edit SCPL_REFERENCE.md |
+
+### Source of Truth
+- **`SCPL_REFERENCE.md`** - The master reference document. Codex skill is generated from this.
+- **`claude-desktop-skill/scpl-shortcuts/REFERENCE.md`** - Should match SCPL_REFERENCE.md
+- All platforms should have the same gotcha documentation (RepeatWithEach, multi-line text, etc.)
+
+### Updating Skills
+1. Edit `SCPL_REFERENCE.md` and `create-shortcut.md` with fixes
+2. Copy changes to `claude-desktop-skill/scpl-shortcuts/REFERENCE.md`
+3. Update `claude-desktop-skill/scpl-shortcuts/Skill.md` if needed
+4. Regenerate zip: `cd claude-desktop-skill && zip -r scpl-shortcuts.zip scpl-shortcuts/`
+5. Bump version in `package.json` and publish to npm
+
+### How Codex Skill Works
+The `setupCodex()` function in `index.js` (line ~315) reads `SCPL_REFERENCE.md` at runtime and wraps it with YAML frontmatter to create `~/.codex/skills/scpl-shortcuts/SKILL.md`. There is no separate Codex skill file in the repo.
+
 ## Contributing
 
 Found a bug or want to add features? See [CONTRIBUTING.md](../CONTRIBUTING.md)

package/SCPL_REFERENCE.md

@@ -113,9 +113,19 @@ End Repeat
 
 ### Repeat with Each
 
+**IMPORTANT:** You must name the loop variable using `->` syntax. `mv:RepeatItem` is NOT a predefined variable.
+
 ```scpl
-RepeatWithEach [item1, item2, item3]
-    ShowResult "Processing: \(mv:RepeatItem)"
+# Correct: Name the loop variable with arrow
+List ["item1", "item2", "item3"]
+RepeatWithEach -> mv:Item
+    ShowResult "Processing: \(mv:Item)"
+End RepeatWithEach
+
+# Also works: Use bare RepeatItem as direct reference (not in interpolation)
+List ["a", "b", "c"]
+RepeatWithEach
+    ShowResult RepeatItem
 End RepeatWithEach
 ```
 
@@ -341,7 +351,8 @@ End If
 URL "https://api.example.com/items"
 GetContentsOfURL -> mv:Response
 GetDictionaryValue key="items"
-RepeatWithEach
+RepeatWithEach -> mv:Item
+    GetVariable mv:Item
     GetDictionaryValue key="name" -> mv:ItemName
     Text "\(mv:ItemName)" -> mv:Output
     AddToVariable v:AllItems
@@ -523,13 +534,19 @@ ShowResult
 
 ```scpl
 GetSelectedFiles -> mv:Files
-RepeatWithEach mv:Files
+GetVariable mv:Files
+RepeatWithEach -> mv:CurrentFile
+    GetVariable mv:CurrentFile
     GetDetailsOfFiles detail="File Extension" -> mv:Ext
 
+    GetVariable mv:Ext
     If Equals "pdf"
+        GetVariable mv:CurrentFile
         MoveFile destination="~/Documents/PDFs/"
     Otherwise
+        GetVariable mv:Ext
         If Equals "jpg"
+            GetVariable mv:CurrentFile
             MoveFile destination="~/Pictures/"
         End If
     End If
@@ -631,8 +648,11 @@ End If
 URL "https://api.example.com/data"
 GetContentsOfURL -> mv:Response
 GetDictionaryValue key="items"
-RepeatWithEach
-    # Process each item
+RepeatWithEach -> mv:Item
+    # Process each item using mv:Item
+    GetVariable mv:Item
+    GetDictionaryValue key="name" -> mv:Name
+    ShowResult mv:Name
 End RepeatWithEach
 ```
 
@@ -681,7 +701,7 @@ End RepeatWithEach
 - Space-separate params: `a="1" b="2"` not `a="1", b="2"`
 
 ## HTTP API Requests
-**Headers**: Use `headers=true headers2={Key: "value"}` (not `headers={...}`)
+**Headers**: Use `headers={Key: "value"}` (expanding toggles are auto-set)
 **Complex JSON**: Use shell scripts with curl instead of jsonvalues with nested arrays
 ```scpl
 Text "curl -s URL -H 'Auth: Bearer KEY' -d '{...}' | python3 -c 'import sys,json; print(json.load(sys.stdin)[\"key\"])'"
@@ -775,4 +795,80 @@ open MyShortcut_signed.shortcut
 
 ---
 
+# Known Limitations & Workarounds
+
+## Multi-line Text Cannot Use Arrow Assignment
+
+Multi-line text blocks (using `|` syntax) cannot use `->` directly. Use `SetVariable` on the next line instead.
+
+```scpl
+# WRONG - will fail to parse
+Text
+| Line 1
+| Line 2
+-> v:MyVar
+
+# CORRECT - use SetVariable
+Text
+| Line 1
+| Line 2
+
+SetVariable v:MyVar
+```
+
+## Calculate Operand Cannot Use String Interpolation
+
+The `operand` parameter in Calculate must use direct variable reference, not string interpolation.
+
+```scpl
+Number 10 -> v:Base
+Number 5 -> v:Addend
+
+# WRONG - string interpolation fails
+GetVariable v:Base
+Calculate operation="+" operand="\(v:Addend)"
+
+# CORRECT - direct variable reference
+GetVariable v:Base
+Calculate operation="+" operand=v:Addend
+```
+
+## RepeatWithEach Loop Variable
+
+`mv:RepeatItem` is NOT a predefined magic variable. You must name your loop variable explicitly using the `->` syntax.
+
+```scpl
+# WRONG - mv:RepeatItem doesn't exist
+List ["a", "b", "c"]
+RepeatWithEach
+    Text "\(mv:RepeatItem)"  # ERROR: not defined
+End RepeatWithEach
+
+# CORRECT - name the variable
+List ["a", "b", "c"]
+RepeatWithEach -> mv:Item
+    Text "\(mv:Item)"
+End RepeatWithEach
+
+# ALSO WORKS - bare RepeatItem (not in interpolation)
+List ["a", "b", "c"]
+RepeatWithEach
+    ShowResult RepeatItem  # Works as direct reference
+End RepeatWithEach
+```
+
+## Wait/Stepper Fields Require Integers
+
+Stepper fields (like `Wait`) only accept positive integers, not decimals.
+
+```scpl
+# WRONG - decimal fails
+Wait 0.5
+
+# CORRECT - integer only
+Wait 1
+```
+
+---
+
 **495 total actions available.** Use `list_actions` tool to search by category or keyword.

package/index.js

@@ -1140,14 +1140,15 @@ GetDictionaryValue key="result"
 ShowResult
 \`\`\`
 
-## POST with JSON
+## POST with JSON and Headers
 \`\`\`scpl
 URL "https://api.example.com/submit"
 GetContentsOfURL method="POST" headers={
     "Content-Type": "application/json"
-} body={
+    "Authorization": "Bearer my-token"
+} requestbody="JSON" jsonvalues={
     "name": "Test"
-    "value": 123
+    "value": "123"
 }
 \`\`\`
 `,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scpl-updated-mcp-server",
-  "version": "1.0.17",
+  "version": "1.1.0",
   "description": "AI-powered Apple Shortcuts creation with Claude Code! Generate macOS shortcuts using natural language. 495 actions available. MCP server for text-based shortcut programming. Vibe code your automation workflows.",
   "type": "module",
   "main": "index.js",
@@ -27,6 +27,6 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^0.5.0",
-    "scpl-macos-updated": "^2.3.1"
+    "scpl-macos-updated": "^2.4.0"
   }
 }