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