mac-use-mcp

Instructions

Implementation Reference

• src/tools/menu.ts:88-122 (handler)

  The handleClickMenu function processes the input, builds an AppleScript command to click the menu item, and executes it.

  async function handleClickMenu(
    args: Record<string, unknown>,
  ): Promise<CallToolResult> {
    const parsed = ClickMenuInputSchema.parse(args);
    const parts = parsed.path.split(PATH_DELIMITER);
  
    if (parts.length < MIN_PATH_SEGMENTS) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Invalid menu path: expected at least ${MIN_PATH_SEGMENTS} segments separated by "${PATH_DELIMITER}", got ${parts.length}. Example: "File > Save As..."`,
          },
        ],
        isError: true,
      };
    }
  
    const app = await resolveAppName(parsed.app);
    const script = buildMenuClickScript(app, parts);
    await runAppleScript(script);
  
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify({
            success: true,
            app: parsed.app,
            path: parsed.path,
          }),
        },
      ],
    };
  }

• src/tools/menu.ts:13-16 (schema)

  The ClickMenuInputSchema defines the expected input structure for the click_menu tool.

  const ClickMenuInputSchema = z.object({
    app: z.string().max(1_000).describe("Application name"),
    path: z.string().max(1_000).describe('Menu path, e.g. "File > Save As..."'),
  });

• src/tools/menu.ts:28-39 (registration)

  The menuToolDefinitions array contains the MCP tool definition for click_menu.

  export const menuToolDefinitions: Tool[] = [
    {
      name: "click_menu",
      description:
        'Click a menu bar item in an application. Specify the menu path as "Menu > Submenu > Item" (e.g., "File > Save As...", "View > Sort By > Name").',
      inputSchema: zodToToolInputSchema(ClickMenuInputSchema),
      annotations: {
        readOnlyHint: false,
        destructiveHint: true,
      },
    },
  ];

• src/tools/menu.ts:58-83 (helper)

  The buildMenuClickScript helper constructs the AppleScript command used to perform the menu click.

  export function buildMenuClickScript(app: string, parts: string[]): string {
    const safeApp = escapeAppleScriptString(app);
    const escaped = parts.map(escapeAppleScriptString);
  
    const root = escaped[0];
    const leaf = escaped[escaped.length - 1];
  
    // Start with the leaf item
    let chain = `click menu item "${leaf}"`;
  
    // Traverse intermediate submenus from second-to-last down to index 1
    for (let i = escaped.length - 2; i >= 1; i--) {
      chain += ` of menu "${escaped[i]}" of menu item "${escaped[i]}"`;
    }
  
    // Attach to root menu bar item
    chain += ` of menu "${root}" of menu bar item "${root}" of menu bar 1`;
  
    return [
      'tell application "System Events"',
      `  tell process "${safeApp}"`,
      `    ${chain}`,
      "  end tell",
      "end tell",
    ].join("\n");
  }