applescript-mcp

Instructions

Implementation Reference

• src/categories/clipboard.ts:86-97 (handler)

  The handler logic for the clear_clipboard tool. This script template is executed as AppleScript to clear the clipboard contents.

  {
    name: "clear_clipboard",
    description: "Clear clipboard content",
    script: `
      try
        set the clipboard to ""
        return "Clipboard cleared successfully"
      on error errMsg
        return "Failed to clear clipboard: " & errMsg
      end try
    `,
  },

• src/framework.ts:220-232 (registration)

  Registers the 'clipboard_clear_clipboard' tool in the MCP listTools response by constructing the name from category 'clipboard' and script 'clear_clipboard'.

  // List available tools
  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: this.categories.flatMap((category) =>
      category.scripts.map((script) => ({
        name: `${category.name}_${script.name}`, // Changed from dot to underscore
        description: `[${category.description}] ${script.description}`,
        inputSchema: script.schema || {
          type: "object",
          properties: {},
        },
      })),
    ),
  }));

• src/index.ts:24-36 (registration)

  Registers the clipboardCategory (containing the clear_clipboard script) with the AppleScriptFramework server.

  console.error("[INFO] Registering categories...");
  server.addCategory(systemCategory);
  server.addCategory(calendarCategory);
  server.addCategory(finderCategory);
  server.addCategory(clipboardCategory);
  server.addCategory(notificationsCategory);
  server.addCategory(itermCategory);
  server.addCategory(mailCategory);
  server.addCategory(pagesCategory);
  server.addCategory(shortcutsCategory);
  server.addCategory(messagesCategory);
  server.addCategory(notesCategory);
  console.error(`[INFO] Registered ${11} categories successfully`);

• src/framework.ts:234-295 (handler)

  The MCP tool call handler that parses 'clipboard_clear_clipboard', retrieves the clear_clipboard script from clipboard category, generates/executes the 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) {

• src/framework.ts:176-214 (helper)

  Helper function that executes the AppleScript generated by the clear_clipboard handler using osascript.

  private async executeScript(script: string): Promise<string> {
    // Log script execution (truncate long scripts for readability)
    const scriptPreview = script.length > 100 ? script.substring(0, 100) + "..." : script;
    this.log("debug", "Executing AppleScript", { scriptPreview });
    
    try {
      const startTime = Date.now();
      const { stdout } = await execAsync(
        `osascript -e '${script.replace(/'/g, "'\"'\"'")}'`,
      );
      const executionTime = Date.now() - startTime;
      
      this.log("debug", "AppleScript executed successfully", { 
        executionTimeMs: executionTime,
        outputLength: stdout.length
      });
      
      return stdout.trim();
    } catch (error) {
      // Properly type check the error object
      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", "AppleScript execution failed", { 
        error: errorMessage,
        scriptPreview
      });
      
      throw new Error(`AppleScript execution failed: ${errorMessage}`);
    }
  }