applescript-mcp

Instructions

Implementation Reference

• src/categories/messages.ts:234-303 (handler)

  Core handler implementation for 'messages_compose_message' tool. The 'script' function generates AppleScript that opens Messages app with pre-filled message or auto-sends it based on 'recipient', 'body', and 'auto' parameters.
  { name: "compose_message", description: "Open Messages app with a pre-filled message to a recipient or automatically send a message", schema: { type: "object", properties: { recipient: { type: "string", description: "Phone number or email of the recipient" }, body: { type: "string", description: "Message body text", default: "" }, auto: { type: "boolean", description: "Automatically send the message without user confirmation", default: false } }, required: ["recipient"] }, script: (args) => ` on run -- Get the recipient and message body set recipient to "${args.recipient}" set messageBody to "${args.body || ''}" set autoSend to ${args.auto === true ? "true" : "false"} if autoSend then -- Automatically send the message using AppleScript tell application "Messages" -- Get the service (iMessage or SMS) set targetService to 1st service whose service type = iMessage -- Send the message set targetBuddy to buddy "${args.recipient}" of targetService send "${args.body || ''}" to targetBuddy return "Message sent to " & "${args.recipient}" end tell else -- Just open Messages app with pre-filled content -- Create the SMS URL with proper URL encoding set smsURL to "sms:" & recipient if messageBody is not equal to "" then -- Use percent encoding for spaces instead of plus signs set encodedBody to "" repeat with i from 1 to count of characters of messageBody set c to character i of messageBody if c is space then set encodedBody to encodedBody & "%20" else set encodedBody to encodedBody & c end if end repeat set smsURL to smsURL & "&body=" & encodedBody end if -- Open the URL with the default handler (Messages app) do shell script "open " & quoted form of smsURL return "Opening Messages app with recipient: " & recipient end if end run ` }
• src/categories/messages.ts:237-256 (schema)

  Input schema defining parameters for the messages_compose_message tool.
  schema: { type: "object", properties: { recipient: { type: "string", description: "Phone number or email of the recipient" }, body: { type: "string", description: "Message body text", default: "" }, auto: { type: "boolean", description: "Automatically send the message without user confirmation", default: false } }, required: ["recipient"] },
• src/framework.ts:221-232 (registration)

  Dynamic registration of all tools including 'messages_compose_message' in the ListToolsRequestHandler by constructing name as `${category.name}_${script.name}`.
  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:243-279 (handler)

  MCP CallToolRequestHandler that resolves 'messages_compose_message' to category 'messages' and script 'compose_message', invokes the script generator with arguments, and prepares AppleScript for execution.
  // 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;
• src/index.ts:34-34 (registration)

  Registers the 'messages' category (containing compose_message script) with the MCP server framework.
  server.addCategory(messagesCategory);