scpl-updated-mcp-server 1.0.0 → 1.0.2

package/README.md

@@ -6,7 +6,7 @@ Model Context Protocol server for creating macOS Shortcuts using ScPL (Shortcuts
 
 - **Create Shortcuts**: Convert ScPL code to .shortcut files
 - **Validate Syntax**: Check ScPL code without creating files
-- **Discover Actions**: Browse 294 available actions with descriptions
+- **Discover Actions**: Browse 493 available actions with descriptions
 - **Documentation**: Access action reference and examples
 
 ## ⚠️ Shortcut Signing & Installation

package/index.js

@@ -8,10 +8,277 @@ import {
   ListResourcesRequestSchema,
   ReadResourceRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
-import { convert } from "scpl-macos-updated";
-import { writeFileSync, readFileSync } from "fs";
-import { join } from "path";
+import pkg from "scpl-macos-updated";
+const { convert } = pkg;
+import { writeFileSync, readFileSync, existsSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
 import { homedir } from "os";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ============================================================================
+// HELP
+// ============================================================================
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+  console.log(`
+ScPL Updated MCP Server - Create macOS Shortcuts with AI
+
+USAGE:
+  npx scpl-updated-mcp-server [OPTIONS]
+
+OPTIONS:
+  --setup         Auto-install for Claude Code (recommended)
+  --setup-codex   Auto-install for OpenAI Codex CLI
+  --help, -h      Show this help message
+
+EXAMPLES:
+  npx scpl-updated-mcp-server --setup        # Install for Claude Code
+  npx scpl-updated-mcp-server --setup-codex  # Install for Codex
+
+After setup, restart your AI coding tool and ask:
+  "Create a shortcut that starts a timer and plays a sound"
+`);
+  process.exit(0);
+}
+
+// ============================================================================
+// CODEX SETUP: Run with --setup-codex for OpenAI Codex CLI
+// ============================================================================
+if (process.argv.includes("--setup-codex")) {
+  console.log("🚀 Setting up ScPL Shortcuts for Codex...\n");
+
+  const codexConfigPath = join(homedir(), ".codex", "config.toml");
+  const agentsPath = join(homedir(), ".codex", "AGENTS.md");
+
+  // Step 1: Add MCP server to ~/.codex/config.toml
+  console.log("📝 Step 1: Adding MCP server to ~/.codex/config.toml...");
+  try {
+    let config = "";
+    if (existsSync(codexConfigPath)) {
+      config = readFileSync(codexConfigPath, "utf-8");
+    }
+
+    // Check if already configured
+    if (config.includes('[mcp_servers."scpl-shortcuts"]') || config.includes('[mcp_servers.scpl-shortcuts]')) {
+      console.log("   ⏭️  Already configured, skipping...\n");
+    } else {
+      const tomlBlock = `
+[mcp_servers.scpl-shortcuts]
+command = "npx"
+args = ["-y", "scpl-updated-mcp-server"]
+startup_timeout_sec = 60.0
+`;
+      writeFileSync(codexConfigPath, config + tomlBlock);
+      console.log("   ✅ MCP server added!\n");
+    }
+  } catch (error) {
+    console.error("   ❌ Failed to update config:", error.message);
+    console.log("   Add this to ~/.codex/config.toml manually:");
+    console.log(`
+[mcp_servers.scpl-shortcuts]
+command = "npx"
+args = ["-y", "scpl-updated-mcp-server"]
+startup_timeout_sec = 60.0
+`);
+  }
+
+  // Step 2: Add instructions to AGENTS.md
+  console.log("📁 Step 2: Adding skill instructions to AGENTS.md...");
+  try {
+    let agents = "";
+    if (existsSync(agentsPath)) {
+      agents = readFileSync(agentsPath, "utf-8");
+    }
+
+    if (agents.includes("## ScPL Shortcuts")) {
+      console.log("   ⏭️  Already in AGENTS.md, skipping...\n");
+    } else {
+      const agentBlock = `
+
+## ScPL Shortcuts
+
+You have access to the ScPL MCP server with 493 actions for creating macOS Shortcuts.
+
+**Tools available:**
+- \`create_shortcut\` - Generate a .shortcut file from ScPL code
+- \`validate_scpl\` - Check if ScPL code is valid
+- \`list_actions\` - Search available actions
+
+**ScPL syntax example:**
+\`\`\`scpl
+Text "Hello"
+AskLLM model="Apple Intelligence" prompt="Make it fun"
+ShowResult
+\`\`\`
+
+When user asks to create a shortcut, write ScPL code, validate it, then create the file.
+`;
+      writeFileSync(agentsPath, agents + agentBlock);
+      console.log("   ✅ Instructions added!\n");
+    }
+  } catch (error) {
+    console.error("   ❌ Failed to update AGENTS.md:", error.message, "\n");
+  }
+
+  console.log("🎉 Setup complete! Restart Codex to use the shortcuts tools.\n");
+  console.log("Usage: Just ask Codex to create a shortcut!");
+  console.log('  Example: "Create a shortcut that starts a timer and plays a sound"\n');
+  process.exit(0);
+}
+
+// ============================================================================
+// CLAUDE CODE SETUP: Run with --setup to install everything automatically
+// ============================================================================
+if (process.argv.includes("--setup")) {
+  console.log("🚀 Setting up ScPL Shortcuts for Claude Code...\n");
+
+  const claudeJsonPath = join(homedir(), ".claude.json");
+  const pluginsDir = join(homedir(), ".claude", "plugins", "local", "scpl-shortcuts");
+  const installedPluginsPath = join(homedir(), ".claude", "plugins", "installed_plugins.json");
+
+  // Step 1: Add MCP server to ~/.claude.json
+  console.log("📝 Step 1: Adding MCP server to ~/.claude.json...");
+  try {
+    let claudeConfig = {};
+    if (existsSync(claudeJsonPath)) {
+      claudeConfig = JSON.parse(readFileSync(claudeJsonPath, "utf-8"));
+    }
+
+    if (!claudeConfig.mcpServers) {
+      claudeConfig.mcpServers = {};
+    }
+
+    claudeConfig.mcpServers["scpl-shortcuts"] = {
+      type: "stdio",
+      command: "npx",
+      args: ["-y", "scpl-updated-mcp-server"]
+    };
+
+    writeFileSync(claudeJsonPath, JSON.stringify(claudeConfig, null, 2));
+    console.log("   ✅ MCP server added!\n");
+  } catch (error) {
+    console.error("   ❌ Failed to update ~/.claude.json:", error.message);
+    console.log("   You can manually add this to ~/.claude.json under mcpServers:");
+    console.log(`   "scpl-shortcuts": { "type": "stdio", "command": "npx", "args": ["-y", "scpl-updated-mcp-server"] }\n`);
+  }
+
+  // Step 2: Create plugin directory and files
+  console.log("📁 Step 2: Installing plugin files...");
+  try {
+    mkdirSync(join(pluginsDir, "skills"), { recursive: true });
+
+    // Write plugin.json
+    const pluginJson = {
+      name: "scpl-shortcuts",
+      version: "1.0.0",
+      description: "Create macOS Shortcuts using natural language and ScPL",
+      skills: [
+        {
+          name: "create-shortcut",
+          description: "Create a macOS Shortcut using natural language. Guides you through the process and generates a .shortcut file.",
+          path: "skills/create-shortcut.md"
+        }
+      ]
+    };
+    writeFileSync(join(pluginsDir, "plugin.json"), JSON.stringify(pluginJson, null, 2));
+
+    // Write skill file
+    const skillContent = `---
+description: Create macOS Shortcuts using natural language. Converts your request into ScPL code and generates a .shortcut file.
+tags: [shortcuts, automation, macos, scpl]
+---
+
+# Create Shortcut Skill
+
+You have access to the ScPL MCP server with 493 actions for creating macOS Shortcuts.
+
+## Available Tools
+
+1. **create_shortcut** - Generate a .shortcut file from ScPL code
+2. **validate_scpl** - Check if ScPL code is valid before creating
+3. **list_actions** - Search available actions by category or keyword
+
+## Popular Action Categories
+
+- **AI**: AskLLM (Apple Intelligence), AskChatGPT, AskClaude
+- **Clock**: StartStopwatch, CreateAlarm, GetCurrentTime
+- **Voice Memos**: CreateRecording, PlayRecording
+- **System**: SetDarkMode, TakeScreenshot, LockScreen
+- **Files**: GetFile, SaveFile, RenameFile, RevealInFinder
+- **Scripting**: RunShellScript, RunAppleScript
+
+## ScPL Syntax Examples
+
+\`\`\`scpl
+# Simple notification
+ShowResult "Hello World!"
+
+# Use Apple Intelligence
+Text "Summarize this for me"
+AskLLM model="Apple Intelligence" prompt="Make it shorter"
+ShowResult
+
+# Shell script
+RunShellScript shell="/bin/zsh" script="echo Hello"
+ShowResult
+
+# Variables
+Text "Hello"
+SetVariable v:greeting
+ShowResult v:greeting
+\`\`\`
+
+## Workflow
+
+1. User describes what they want
+2. Use \`list_actions\` if you need to find specific actions
+3. Write ScPL code for the shortcut
+4. Use \`validate_scpl\` to check syntax
+5. Use \`create_shortcut\` to generate the .shortcut file
+6. Tell user to drag the file onto Shortcut Source Helper to install
+`;
+    writeFileSync(join(pluginsDir, "skills", "create-shortcut.md"), skillContent);
+    console.log("   ✅ Plugin files created!\n");
+  } catch (error) {
+    console.error("   ❌ Failed to create plugin files:", error.message, "\n");
+  }
+
+  // Step 3: Register plugin in installed_plugins.json
+  console.log("📋 Step 3: Registering plugin...");
+  try {
+    let installedPlugins = { version: 2, plugins: {} };
+    if (existsSync(installedPluginsPath)) {
+      installedPlugins = JSON.parse(readFileSync(installedPluginsPath, "utf-8"));
+    }
+
+    installedPlugins.plugins["scpl-shortcuts@local"] = [
+      {
+        scope: "user",
+        installPath: pluginsDir,
+        version: "1.0.0",
+        installedAt: new Date().toISOString(),
+        lastUpdated: new Date().toISOString(),
+        isLocal: true
+      }
+    ];
+
+    writeFileSync(installedPluginsPath, JSON.stringify(installedPlugins, null, 2));
+    console.log("   ✅ Plugin registered!\n");
+  } catch (error) {
+    console.error("   ❌ Failed to register plugin:", error.message, "\n");
+  }
+
+  console.log("🎉 Setup complete! Restart Claude Code to use the shortcuts tools.\n");
+  console.log("Usage: Just ask Claude to create a shortcut!");
+  console.log('  Example: "Create a shortcut that starts a timer and plays a sound"\n');
+  process.exit(0);
+}
+
+// ============================================================================
+// MCP SERVER
+// ============================================================================
 
 const server = new Server(
   {
@@ -46,7 +313,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             output_dir: {
               type: "string",
-              description: "Optional output directory (defaults to ~/Downloads)",
+              description: "Optional output directory (defaults to ~/Documents)",
             },
           },
           required: ["scpl_code", "output_name"],
@@ -68,7 +335,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "list_actions",
-        description: "List available ScPL actions with descriptions. Filter by category or search term.",
+        description: "List available ScPL actions (493 total). Filter by category or search term.",
         inputSchema: {
           type: "object",
           properties: {
@@ -95,7 +362,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const { scpl_code, output_name, output_dir } = args;
 
       // Convert ScPL to shortcut
-      // Note: parse() returns a Buffer directly when makeShortcut: true
       const shortcutBuffer = convert(scpl_code, {
         makePlist: true,
         makeShortcut: true,
@@ -112,7 +378,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         content: [
           {
             type: "text",
-            text: `✅ Shortcut created successfully!\n\nPath: ${outputPath}\n\n📝 To install and sign it:\n\n1. Install Shortcut Source Helper from RoutineHub (if you haven't already)\n   - Also install: Shortcut Source Tool, Tinycut Builder\n2. Add Shortcut Source Helper to your Dock\n3. Drag and drop ${output_name}.shortcut onto it\n4. Follow the prompts to sign and import\n\nThe shortcut will be added to your Shortcuts app and ready to use!`,
+            text: `✅ Shortcut created successfully!\n\nPath: ${outputPath}\n\n📝 To install:\n1. Download "Shortcut Source Helper" from RoutineHub\n2. Drag ${output_name}.shortcut onto it\n3. Follow the prompts to sign and import\n\nThe shortcut will be added to your Shortcuts app!`,
           },
         ],
       };
@@ -122,7 +388,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const { scpl_code } = args;
 
       try {
-        // Just parse to validate, don't generate output
         convert(scpl_code, {
           makePlist: false,
           makeShortcut: false,
@@ -152,59 +417,71 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (name === "list_actions") {
       const { category, search } = args || {};
 
-      // Read the actions data
-      const actionsPath = join(
-        process.cwd(),
-        "..",
-        "src",
-        "Data",
-        "OutActions.json"
-      );
-      const actions = JSON.parse(readFileSync(actionsPath, "utf-8"));
+      // Embedded action list (top actions for quick reference)
+      const topActions = {
+        // AI
+        "is.workflow.actions.askllm": { Name: "Ask LLM", Category: "AI" },
+        "is.workflow.actions.askchatgpt": { Name: "Ask ChatGPT", Category: "AI" },
+        "com.anthropic.claudeforipad.AskClaudeIntentExtension": { Name: "Ask Claude", Category: "AI" },
+        // Clock
+        "com.apple.clock.StartStopwatchIntent": { Name: "Start Stopwatch", Category: "Clock" },
+        "com.apple.clock.StopStopwatchIntent": { Name: "Stop Stopwatch", Category: "Clock" },
+        "com.apple.clock.CreateAlarmIntent": { Name: "Create Alarm", Category: "Clock" },
+        // Voice Memos
+        "com.apple.VoiceMemos.CreateRecordingIntent": { Name: "Create Recording", Category: "Voice Memos" },
+        "com.apple.VoiceMemos.PlayRecordingIntent": { Name: "Play Recording", Category: "Voice Memos" },
+        // System
+        "is.workflow.actions.appearance": { Name: "Set Dark/Light Mode", Category: "System" },
+        "is.workflow.actions.takescreenshot": { Name: "Take Screenshot", Category: "System" },
+        "is.workflow.actions.lockscreen": { Name: "Lock Screen", Category: "System" },
+        // Scripting
+        "is.workflow.actions.runshellscript": { Name: "Run Shell Script", Category: "Scripting" },
+        "is.workflow.actions.runapplescript": { Name: "Run AppleScript", Category: "Scripting" },
+        "is.workflow.actions.runjavascriptforautomation": { Name: "Run JavaScript", Category: "Scripting" },
+        // Files
+        "is.workflow.actions.file.getfile": { Name: "Get File", Category: "Files" },
+        "is.workflow.actions.file.savefile": { Name: "Save File", Category: "Files" },
+        "is.workflow.actions.file.renamefile": { Name: "Rename File", Category: "Files" },
+        "is.workflow.actions.file.revealfile": { Name: "Reveal in Finder", Category: "Files" },
+        // Text
+        "is.workflow.actions.gettext": { Name: "Get Text", Category: "Text" },
+        "is.workflow.actions.showresult": { Name: "Show Result", Category: "Text" },
+        "is.workflow.actions.alert": { Name: "Show Alert", Category: "Text" },
+        // Variables
+        "is.workflow.actions.setvariable": { Name: "Set Variable", Category: "Variables" },
+        "is.workflow.actions.getvariable": { Name: "Get Variable", Category: "Variables" },
+        // Clipboard
+        "is.workflow.actions.getclipboard": { Name: "Get Clipboard", Category: "Clipboard" },
+        "is.workflow.actions.setclipboard": { Name: "Set Clipboard", Category: "Clipboard" },
+      };
 
-      let filtered = Object.entries(actions);
+      let filtered = Object.entries(topActions);
 
-      // Filter by category
       if (category) {
         filtered = filtered.filter(
-          ([_, action]) =>
-            action.Category?.toLowerCase() === category.toLowerCase()
+          ([_, action]) => action.Category?.toLowerCase() === category.toLowerCase()
         );
       }
 
-      // Filter by search term
       if (search) {
         const searchLower = search.toLowerCase();
         filtered = filtered.filter(
           ([id, action]) =>
             id.toLowerCase().includes(searchLower) ||
             action.Name?.toLowerCase().includes(searchLower) ||
-            action.Description?.DescriptionSummary?.toLowerCase().includes(
-              searchLower
-            )
+            action.Category?.toLowerCase().includes(searchLower)
         );
       }
 
-      // Format the results
       const results = filtered
-        .slice(0, 50) // Limit to 50 results
-        .map(([id, action]) => {
-          return `• **${action.Name || id}**\n  ID: \`${id}\`\n  ${
-            action.Description?.DescriptionSummary || "No description"
-          }\n  Category: ${action.Category || "Unknown"}`;
-        })
-        .join("\n\n");
-
-      const total = filtered.length;
-      const showing = Math.min(50, total);
+        .map(([id, action]) => `• **${action.Name}** - \`${id}\` (${action.Category})`)
+        .join("\n");
 
       return {
         content: [
           {
             type: "text",
-            text: `Found ${total} action${
-              total !== 1 ? "s" : ""
-            } (showing ${showing}):\n\n${results}`,
+            text: `Found ${filtered.length} actions:\n\n${results}\n\n💡 This is a subset of 493 total actions. For the full list, see: https://github.com/cavingraves/scpl-macos-updated`,
           },
         ],
       };
@@ -224,22 +501,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 });
 
-// Resource handlers (for documentation)
+// Resource handlers
 server.setRequestHandler(ListResourcesRequestSchema, async () => {
   return {
     resources: [
-      {
-        uri: "scpl://actions/all",
-        name: "All Available Actions",
-        description: "Complete list of all 294 ScPL actions",
-        mimeType: "text/markdown",
-      },
-      {
-        uri: "scpl://actions/tahoe",
-        name: "macOS Tahoe New Actions",
-        description: "22 new actions added for macOS Tahoe",
-        mimeType: "text/markdown",
-      },
       {
         uri: "scpl://examples",
         name: "ScPL Examples",
@@ -253,83 +518,48 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
 server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
   const { uri } = request.params;
 
-  if (uri === "scpl://actions/tahoe") {
-    const content = readFileSync(
-      join(process.cwd(), "..", "MACOS_TAHOE_UPDATES.md"),
-      "utf-8"
-    );
-    return {
-      contents: [
-        {
-          uri,
-          mimeType: "text/markdown",
-          text: content,
-        },
-      ],
-    };
-  }
-
   if (uri === "scpl://examples") {
     const examples = `# ScPL Examples
 
-## Apple Intelligence Example
+## Apple Intelligence
 \`\`\`scpl
-# Ask Apple Intelligence to summarize text
-Text "The quick brown fox jumps over the lazy dog. This is a sample text."
-AskLLM model="Apple Intelligence" prompt="Summarize this in 5 words"
+Text "Summarize this document"
+AskLLM model="Apple Intelligence" prompt="Make it concise"
 ShowResult
 \`\`\`
 
-## Shell Script Example
-\`\`\`scpl
-# Run a shell script and show the result
-RunShellScript shell="/bin/zsh" script="sw_vers"
-ShowResult "macOS Version"
-\`\`\`
-
-## File Operations Example
+## Timer with Sound
 \`\`\`scpl
-# Get files from Desktop and show count
-GetFile path="~/Desktop" errorIfNotFound=false
-Count
-ShowResult "Files on Desktop"
+# Start a 5-minute timer
+StartTimer minutes=5
+ShowAlert title="Timer Started" message="5 minutes"
 \`\`\`
 
-## ChatGPT Integration Example
+## Shell Script
 \`\`\`scpl
-# Ask ChatGPT a question
-Text "What is the meaning of life?"
-AskChatGPT
+RunShellScript shell="/bin/zsh" script="echo Hello World"
 ShowResult
 \`\`\`
 
-## Combined Workflow Example
+## Clipboard Workflow
 \`\`\`scpl
-# Get clipboard, ask AI to improve it, copy back
 GetClipboard
-SetVariable v:originalText
-
-AskLLM model="Apple Intelligence" prompt="Improve this text for clarity and grammar: \\(v:originalText)"
+SetVariable v:text
+AskChatGPT prompt="Improve this: \\(v:text)"
 SetClipboard
-ShowAlert title="Text Improved" message="The improved text has been copied to your clipboard"
+ShowAlert title="Done" message="Improved text copied!"
 \`\`\`
 `;
 
     return {
-      contents: [
-        {
-          uri,
-          mimeType: "text/markdown",
-          text: examples,
-        },
-      ],
+      contents: [{ uri, mimeType: "text/markdown", text: examples }],
     };
   }
 
   throw new Error(`Unknown resource: ${uri}`);
 });
 
-// Start the server
+// Start server
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "scpl-updated-mcp-server",
-  "version": "1.0.0",
-  "description": "MCP server for creating macOS Shortcuts using ScPL (macOS Tahoe updated fork)",
+  "version": "1.0.2",
+  "description": "AI-powered Apple Shortcuts creation with Claude Code! Generate macOS shortcuts using natural language. 493 actions available. MCP server for text-based shortcut programming. Vibe code your automation workflows.",
   "type": "module",
   "main": "index.js",
   "bin": {
-    "scpl-updated-mcp-server": "./index.js"
+    "scpl-updated-mcp-server": "index.js"
   },
   "scripts": {
     "start": "node index.js"