mac-use-mcp

Instructions

Implementation Reference

• src/tools/keyboard.ts:104-151 (handler)

  The handler function for the 'type_text' tool, which performs a copy-to-clipboard and paste operation to simulate typing.

  async function handleTypeText(
    args: Record<string, unknown>,
  ): Promise<CallToolResult> {
    const parsed = TypeTextInputSchema.parse(args);
  
    // Save current clipboard contents (best-effort)
    let oldClipboard = "";
    try {
      oldClipboard = await clipboardRead();
    } catch {
      // Clipboard may be empty or contain non-text data
    }
  
    // Write target text to clipboard
    await clipboardWrite(parsed.text);
  
    // Paste via AppleScript Cmd+V
    await execFileAsync(
      "osascript",
      [
        "-e",
        `tell application "System Events" to key code ${KEY_CODES.v} using command down`,
      ],
      { timeout: APPLESCRIPT_TIMEOUT_MS },
    );
  
    // Brief delay for paste to settle before restoring clipboard
    await new Promise((resolve) => setTimeout(resolve, PASTE_SETTLE_MS));
  
    // Restore previous clipboard contents (best-effort)
    try {
      await clipboardWrite(oldClipboard);
    } catch {
      // Best-effort restore
    }
  
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify({
            success: true,
            typed_length: parsed.text.length,
          }),
        },
      ],
    };
  }

• src/tools/keyboard.ts:53-59 (schema)

  Zod input schema definition for the 'type_text' tool.

  const TypeTextInputSchema = z.object({
    text: z
      .string()
      .min(1)
      .max(100_000)
      .describe("Text to type. Supports full Unicode including CJK and emoji."),
  });

• src/tools/keyboard.ts:74-83 (registration)

  Registration of the 'type_text' tool definition.

  {
    name: "type_text",
    description:
      'Type text at the current cursor position using clipboard paste. Supports full Unicode including CJK characters and emoji. Temporarily replaces clipboard contents. Non-text clipboard content (images, files) will be lost permanently. If secure input is active (e.g. password fields), returns a note suggesting clipboard_write + press_key("cmd+v") as an alternative.',
    inputSchema: zodToToolInputSchema(TypeTextInputSchema),
    annotations: {
      readOnlyHint: false,
      destructiveHint: true,
    },
  },