mac-use-mcp

Instructions

Implementation Reference

• src/tools/keyboard.ts:159-221 (handler)

  The handler function `handlePressKey` executes the tool logic by parsing the input, validating the keys/modifiers, and executing an AppleScript command to simulate the key press on macOS.

  async function handlePressKey(
    args: Record<string, unknown>,
  ): Promise<CallToolResult> {
    const parsed = PressKeyInputSchema.parse(args);
  
    const parts = parsed.key.split("+");
    const baseKeyName = parts[parts.length - 1];
    const modifierNames = parts.slice(0, -1);
  
    // Look up the base key code (case-insensitive)
    const code = KEY_CODES_LOWER[baseKeyName.toLowerCase()];
    if (code === undefined) {
      return {
        isError: true,
        content: [
          {
            type: "text" as const,
            text: `Unknown key name: "${baseKeyName}". Valid key names include: ${KEY_NAME_EXAMPLES.join(", ")}`,
          },
        ],
      };
    }
  
    // Build AppleScript modifier clause
    const asModifiers: string[] = [];
    for (const mod of modifierNames) {
      const canonical = MODIFIER_ALIASES[mod.toLowerCase()];
      if (canonical === undefined) {
        return {
          isError: true,
          content: [
            {
              type: "text" as const,
              text: `Unknown modifier: "${mod}". Valid modifiers: cmd, ctrl, shift, opt (or alt).`,
            },
          ],
        };
      }
      asModifiers.push(`${canonical} down`);
    }
  
    // Build and execute AppleScript
    const script =
      asModifiers.length > 0
        ? `tell application "System Events" to key code ${code} using {${asModifiers.join(", ")}}`
        : `tell application "System Events" to key code ${code}`;
  
    await execFileAsync("osascript", ["-e", script], {
      timeout: APPLESCRIPT_TIMEOUT_MS,
    });
  
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify({
            success: true,
            key: parsed.key,
          }),
        },
      ],
    };
  }

• src/tools/keyboard.ts:61-69 (schema)

  The Zod schema `PressKeyInputSchema` defines the expected input format for the `press_key` tool.

  const PressKeyInputSchema = z.object({
    key: z
      .string()
      .min(1)
      .max(200)
      .describe(
        'Key combo string. Examples: "Return", "cmd+c", "ctrl+shift+F5", "alt+Tab".',
      ),
  });

• src/tools/keyboard.ts:84-94 (registration)

  Registration of the `press_key` tool within the `keyboardToolDefinitions` array.

    {
      name: "press_key",
      description:
        'Simulate a key press with optional modifiers. Accepts a key combo string like "cmd+c", "ctrl+shift+F5", or "Return". Modifiers: cmd, ctrl, shift, opt/alt.',
      inputSchema: zodToToolInputSchema(PressKeyInputSchema),
      annotations: {
        readOnlyHint: false,
        destructiveHint: true,
      },
    },
  ];