scpl-updated-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,324 @@
+# ScPL MCP Server
+
+Model Context Protocol server for creating macOS Shortcuts using ScPL (Shortcuts Programming Language).
+
+## Features
+
+- **Create Shortcuts**: Convert ScPL code to .shortcut files
+- **Validate Syntax**: Check ScPL code without creating files
+- **Discover Actions**: Browse 294 available actions with descriptions
+- **Documentation**: Access action reference and examples
+
+## ⚠️ Shortcut Signing & Installation
+
+Generated .shortcut files need to be signed before macOS will allow you to run them. You have two options:
+
+### Option 1: Shortcut Source Helper (Free - Recommended)
+
+**Setup (one-time):**
+1. Install required shortcuts from RoutineHub:
+   - [Shortcut Source Helper](https://routinehub.co/shortcut/10060/)
+   - [Shortcut Source Tool](https://routinehub.co/shortcut/5256/)
+   - [Tinycut Builder](https://routinehub.co/shortcut/5217/)
+2. Add **Shortcut Source Helper** to your Dock for easy access
+
+**To install a generated shortcut:**
+1. Drag and drop the `.shortcut` file onto Shortcut Source Helper in your Dock
+2. Follow the prompts to sign and import
+3. The shortcut will be added to your Shortcuts app and ready to use!
+
+### Option 2: Apple Developer Account
+
+If you have an Apple Developer account ($99/year), you can sign shortcuts with your developer certificate for distribution.
+
+**Disclaimer**: We are not associated with Shortcut Source Tool/Helper or their creators. Use third-party tools at your own risk. Always review shortcuts before running them.
+
+## Installation
+
+### Step 1: Install the Package
+
+```bash
+npm install -g scpl-updated-mcp-server
+```
+
+### Step 2: Register with Your AI Assistant
+
+Choose your platform below:
+
+#### Claude Code
+
+**Option 1: CLI command** (may not always work):
+
+```bash
+claude mcp add scpl-shortcuts npx scpl-updated-mcp-server
+```
+
+**Option 2: Manual config** (recommended):
+
+Add this to the `mcpServers` section in `~/.claude.json`:
+
+```json
+"scpl-shortcuts": {
+  "type": "stdio",
+  "command": "npx",
+  "args": [
+    "-y",
+    "scpl-updated-mcp-server"
+  ]
+}
+```
+
+Or for project-specific config, add to `.claude/mcp.json` in your project directory.
+
+#### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "scpl-shortcuts": {
+      "command": "npx",
+      "args": ["scpl-updated-mcp-server"]
+    }
+  }
+}
+```
+
+#### Codex / Code (and forks)
+
+Add to `~/.code/config.toml` (or `~/.codex/config.toml`):
+
+```toml
+[mcp_servers.scpl-shortcuts]
+command = "npx"
+args = ["scpl-updated-mcp-server"]
+startup_timeout_sec = 60.0
+tool_timeout_sec = 120
+```
+
+**For local development:**
+
+```toml
+[mcp_servers.scpl-shortcuts]
+command = "node"
+args = ["/path/to/scpl-updated/mcp-server/index.js"]
+cwd = "/path/to/scpl-updated/mcp-server"
+startup_timeout_sec = 60.0
+tool_timeout_sec = 120
+```
+
+## Tools
+
+### `create_shortcut`
+
+Create a macOS Shortcut from ScPL code.
+
+**Parameters:**
+- `scpl_code` (required): The ScPL code to convert
+- `output_name` (required): Name for the .shortcut file
+- `output_dir` (optional): Output directory (defaults to ~/Documents)
+
+**Example:**
+```json
+{
+  "scpl_code": "Text \"Hello World\"\nShowResult",
+  "output_name": "HelloWorld",
+  "output_dir": "~/Desktop"
+}
+```
+
+### `validate_scpl`
+
+Validate ScPL code syntax without creating a file.
+
+**Parameters:**
+- `scpl_code` (required): The ScPL code to validate
+
+**Example:**
+```json
+{
+  "scpl_code": "GetClipboard\nShowResult"
+}
+```
+
+### `list_actions`
+
+List available ScPL actions with descriptions.
+
+**Parameters:**
+- `category` (optional): Filter by category (e.g., "Scripting", "Files")
+- `search` (optional): Search term to filter actions
+
+**Example:**
+```json
+{
+  "category": "Scripting",
+  "search": "shell"
+}
+```
+
+## Resources
+
+### `scpl://actions/tahoe`
+
+Documentation for 22 new macOS Tahoe actions.
+
+### `scpl://examples`
+
+Example shortcuts demonstrating various ScPL features.
+
+## Usage with Claude Code
+
+Once registered, Claude can create shortcuts for you:
+
+```
+Claude, create a shortcut that:
+1. Gets text from clipboard
+2. Asks ChatGPT to improve it
+3. Copies the result back to clipboard
+```
+
+Claude will:
+1. Write the ScPL code
+2. Validate the syntax
+3. Create the .shortcut file
+4. Provide installation instructions
+
+## Usage with Claude Skill
+
+The included `/create-shortcut` skill provides a guided experience:
+
+```
+/create-shortcut
+```
+
+Then describe what you want your shortcut to do.
+
+## ScPL Syntax Quick Reference
+
+```scpl
+# Comments
+# Single-line comments start with #
+
+# Text and Output
+Text "Hello World"
+ShowResult "My Result"
+ShowAlert title="Title" message="Message"
+
+# Variables
+SetVariable v:myVar
+GetVariable v:myVar
+
+# Clipboard
+GetClipboard
+SetClipboard
+
+# Apple Intelligence (Apple Silicon only)
+AskLLM model="Apple Intelligence" prompt="Your prompt here"
+
+# ChatGPT (requires app installed)
+Text "Your question"
+AskChatGPT
+
+# Shell Scripts (Intel & Apple Silicon)
+RunShellScript shell="/bin/zsh" script="echo 'Hello'"
+
+# Files (Intel & Apple Silicon)
+GetFile path="~/Desktop"
+SaveFile path="~/Documents/file.txt"
+
+# Conditionals
+If condition="Equals" value="test"
+    ShowResult "Match!"
+Otherwise
+    ShowResult "No match"
+End If
+
+# Menus
+ChooseFromMenu items=["Option 1", "Option 2"]
+Case "Option 1"
+    Text "You chose 1"
+Case "Option 2"
+    Text "You chose 2"
+End Menu
+
+# Loops
+RepeatWithEachItem
+    ShowResult
+End Repeat
+```
+
+## Examples
+
+### Simple Notification
+
+```scpl
+Text "Hello from ScPL!"
+ShowResult
+```
+
+### AI Text Improver
+
+```scpl
+GetClipboard
+SetVariable v:originalText
+
+AskLLM model="Apple Intelligence" prompt="Improve this text for clarity: \\(v:originalText)"
+SetClipboard
+ShowAlert title="Done" message="Improved text copied to clipboard"
+```
+
+### Shell Script Runner
+
+```scpl
+RunShellScript shell="/bin/zsh" script="sw_vers"
+ShowResult "macOS Version"
+```
+
+### File Counter
+
+```scpl
+GetFile path="~/Desktop"
+Count
+ShowResult "Files on Desktop"
+```
+
+## Troubleshooting
+
+### "Command not found: scpl-updated-mcp-server"
+
+Make sure you installed globally:
+```bash
+npm install -g scpl-updated-mcp-server
+```
+
+### "Error: Cannot find module 'scpl-macos-updated'"
+
+The MCP server depends on scpl-macos-updated. Ensure it's installed:
+```bash
+npm list -g scpl-macos-updated
+```
+
+### "Permission denied"
+
+Make the script executable:
+```bash
+chmod +x index.js
+```
+
+### ScPL Validation Errors
+
+Check the error message for line numbers and syntax issues. Common mistakes:
+- Forgetting to close `If` with `End If`
+- Forgetting to close `Menu` with `End Menu`
+- Using wrong parameter names (use `list_actions` to check)
+- Missing quotes around text values
+
+## Contributing
+
+Found a bug or want to add features? See [CONTRIBUTING.md](../CONTRIBUTING.md)
+
+## License
+
+MIT - Same as scpl-macos-updated

package/index.js

@@ -0,0 +1,342 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { convert } from "scpl-macos-updated";
+import { writeFileSync, readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+const server = new Server(
+  {
+    name: "scpl-updated-mcp-server",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+      resources: {},
+    },
+  }
+);
+
+// Tool handlers
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "create_shortcut",
+        description: "Create a macOS Shortcut from ScPL code. Returns the path to the generated .shortcut file.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            scpl_code: {
+              type: "string",
+              description: "The ScPL code to convert to a shortcut",
+            },
+            output_name: {
+              type: "string",
+              description: "Name for the output .shortcut file (without extension)",
+            },
+            output_dir: {
+              type: "string",
+              description: "Optional output directory (defaults to ~/Downloads)",
+            },
+          },
+          required: ["scpl_code", "output_name"],
+        },
+      },
+      {
+        name: "validate_scpl",
+        description: "Validate ScPL code syntax without creating a file",
+        inputSchema: {
+          type: "object",
+          properties: {
+            scpl_code: {
+              type: "string",
+              description: "The ScPL code to validate",
+            },
+          },
+          required: ["scpl_code"],
+        },
+      },
+      {
+        name: "list_actions",
+        description: "List available ScPL actions with descriptions. Filter by category or search term.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            category: {
+              type: "string",
+              description: "Optional category filter (e.g., 'Scripting', 'Files', 'AI')",
+            },
+            search: {
+              type: "string",
+              description: "Optional search term to filter actions",
+            },
+          },
+        },
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    if (name === "create_shortcut") {
+      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,
+      });
+
+      // Determine output path (default to ~/Documents)
+      const dir = output_dir || join(homedir(), "Documents");
+      const outputPath = join(dir, `${output_name}.shortcut`);
+
+      // Write the file
+      writeFileSync(outputPath, shortcutBuffer);
+
+      return {
+        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!`,
+          },
+        ],
+      };
+    }
+
+    if (name === "validate_scpl") {
+      const { scpl_code } = args;
+
+      try {
+        // Just parse to validate, don't generate output
+        convert(scpl_code, {
+          makePlist: false,
+          makeShortcut: false,
+        });
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: "✅ ScPL code is valid!",
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `❌ ScPL validation failed:\n\n${error.message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+
+    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"));
+
+      let filtered = Object.entries(actions);
+
+      // Filter by category
+      if (category) {
+        filtered = filtered.filter(
+          ([_, 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
+            )
+        );
+      }
+
+      // 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);
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Found ${total} action${
+              total !== 1 ? "s" : ""
+            } (showing ${showing}):\n\n${results}`,
+          },
+        ],
+      };
+    }
+
+    throw new Error(`Unknown tool: ${name}`);
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: ${error.message}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// Resource handlers (for documentation)
+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",
+        description: "Example shortcuts written in ScPL",
+        mimeType: "text/markdown",
+      },
+    ],
+  };
+});
+
+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
+\`\`\`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"
+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
+\`\`\`scpl
+# Get files from Desktop and show count
+GetFile path="~/Desktop" errorIfNotFound=false
+Count
+ShowResult "Files on Desktop"
+\`\`\`
+
+## ChatGPT Integration Example
+\`\`\`scpl
+# Ask ChatGPT a question
+Text "What is the meaning of life?"
+AskChatGPT
+ShowResult
+\`\`\`
+
+## Combined Workflow Example
+\`\`\`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)"
+SetClipboard
+ShowAlert title="Text Improved" message="The improved text has been copied to your clipboard"
+\`\`\`
+`;
+
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "text/markdown",
+          text: examples,
+        },
+      ],
+    };
+  }
+
+  throw new Error(`Unknown resource: ${uri}`);
+});
+
+// Start the server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("ScPL Updated MCP server running on stdio");
+}
+
+main().catch((error) => {
+  console.error("Server error:", error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "scpl-updated-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for creating macOS Shortcuts using ScPL (macOS Tahoe updated fork)",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "scpl-updated-mcp-server": "./index.js"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "shortcuts",
+    "scpl",
+    "macos",
+    "automation"
+  ],
+  "author": "Cavin Graves",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^0.5.0",
+    "scpl-macos-updated": "^2.0.0"
+  }
+}