applescript-mcp

Instructions

Implementation Reference

• src/categories/notifications.ts:13-26 (handler)

  AppleScript implementation that executes the tool logic by sending a specific keyboard shortcut (Cmd+Opt+Ctrl+Z) to toggle Do Not Disturb mode in System Events.

  {
    name: "toggle_do_not_disturb",
    description: "Toggle Do Not Disturb mode using keyboard shortcut",
    script: `
      try
        tell application "System Events"
          keystroke "z" using {control down, option down, command down}
        end tell
        return "Toggled Do Not Disturb mode"
      on error errMsg
        return "Failed to toggle Do Not Disturb: " & errMsg
      end try
    `,
  },

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

  Registers all tools in the listTools handler, constructing the tool name as '{category}_{script}', resulting in 'notifications_toggle_do_not_disturb'.

  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/framework.ts:275-279 (handler)

  Executes the specific script for the tool by calling executeScript on the script content from the matching category and script.

  const scriptContent =
    typeof script.script === "function"
      ? script.script(request.params.arguments)
      : script.script;

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

  Helper function that executes the AppleScript code using osascript, handling execution and errors.

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

• src/index.ts:6-29 (registration)

  Imports and registers the notifications category containing the toggle_do_not_disturb script.

  import { notificationsCategory } from "./categories/notifications.js";
  import { itermCategory } from "./categories/iterm.js";
  import { mailCategory } from "./categories/mail.js";
  import { pagesCategory } from "./categories/pages.js";
  import { shortcutsCategory } from "./categories/shortcuts.js";
  import { messagesCategory } from "./categories/messages.js";
  import { notesCategory } from "./categories/notes.js";
  
  const server = new AppleScriptFramework({
    name: "applescript-server",
    version: "1.0.4",
    debug: false,
  });
  
  // Log startup information using stderr (server isn't connected yet)
  console.error(`[INFO] Starting AppleScript MCP server - PID: ${process.pid}`);
  
  // Add all categories
  console.error("[INFO] Registering categories...");
  server.addCategory(systemCategory);
  server.addCategory(calendarCategory);
  server.addCategory(finderCategory);
  server.addCategory(clipboardCategory);
  server.addCategory(notificationsCategory);