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