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,
      };
    }
  });