applescript-mcp

Instructions

Implementation Reference

• src/categories/clipboard.ts:17-27 (schema)

  Input schema for the clipboard_get_clipboard tool, specifying the optional 'type' parameter (text or file_paths).
  schema: { type: "object", properties: { type: { type: "string", enum: ["text", "file_paths"], description: "Type of clipboard content to get", default: "text", }, }, },
• src/categories/clipboard.ts:28-62 (handler)

  Handler function that generates the appropriate AppleScript code to retrieve clipboard content based on the input 'type'. For 'file_paths', it processes file URLs into POSIX paths; otherwise, returns text content.
  script: (args) => { if (args?.type === "file_paths") { return ` tell application "System Events" try set theClipboard to the clipboard if theClipboard starts with "file://" then set AppleScript's text item delimiters to linefeed set filePaths to {} repeat with aPath in paragraphs of (the clipboard as string) if aPath starts with "file://" then set end of filePaths to (POSIX path of (aPath as alias)) end if end repeat return filePaths as string else return "No file paths in clipboard" end if on error errMsg return "Failed to get clipboard: " & errMsg end try end tell `; } else { return ` tell application "System Events" try return (the clipboard as text) on error errMsg return "Failed to get clipboard: " & errMsg end try end tell `; } },
• src/index.ts:28-28 (registration)

  Registers the clipboard category (imported from src/categories/clipboard.ts), which defines the get_clipboard script used as clipboard_get_clipboard tool.
  server.addCategory(clipboardCategory);
• src/framework.ts:224-224 (registration)

  Tool name construction logic that creates 'clipboard_get_clipboard' from category 'clipboard' and script 'get_clipboard' when listing available tools.
  name: `${category.name}_${script.name}`, // Changed from dot to underscore
• src/framework.ts:234-331 (helper)

  General tool execution handler that resolves 'clipboard_get_clipboard' to the clipboard category and get_clipboard script, invokes the handler function, executes the generated AppleScript, and returns the result.
  // Handle tool execution this.server.setRequestHandler(CallToolRequestSchema, async (request) => { const toolName = request.params.name; this.log("info", "Tool execution requested", { tool: toolName, hasArguments: !!request.params.arguments }); try { // Split on underscore instead of dot const [categoryName, ...scriptNameParts] = toolName.split("_"); const scriptName = scriptNameParts.join("_"); // Rejoin in case script name has underscores const category = this.categories.find((c) => c.name === categoryName); if (!category) { this.log("warning", "Category not found", { categoryName }); throw new McpError( ErrorCode.MethodNotFound, `Category not found: ${categoryName}`, ); } const script = category.scripts.find((s) => s.name === scriptName); if (!script) { this.log("warning", "Script not found", { categoryName, scriptName }); throw new McpError( ErrorCode.MethodNotFound, `Script not found: ${scriptName}`, ); } this.log("debug", "Generating script content", { categoryName, scriptName, isFunction: typeof script.script === "function" }); const scriptContent = typeof script.script === "function" ? script.script(request.params.arguments) : script.script; const result = await this.executeScript(scriptContent); this.log("info", "Tool execution completed successfully", { tool: toolName, resultLength: result.length }); return { content: [ { type: "text", text: result, }, ], }; } catch (error) { if (error instanceof McpError) { this.log("error", "MCP error during tool execution", { tool: toolName, errorCode: error.code, errorMessage: error.message }); throw error; } let errorMessage = "Unknown error occurred"; if (error && typeof error === "object") { if ("message" in error && typeof error.message === "string") { errorMessage = error.message; } else if (error instanceof Error) { errorMessage = error.message; } } else if (typeof error === "string") { errorMessage = error; } this.log("error", "Error during tool execution", { tool: toolName, errorMessage }); return { content: [ { type: "text", text: `Error: ${errorMessage}`, }, ], isError: true, }; } });