mac-use-mcp

Instructions

Implementation Reference

• src/tools/window.ts:157-199 (handler)

  The 'handleFocusWindow' function acts as the handler for the 'focus_window' tool. It parses input arguments, resolves the application name, and executes an AppleScript to activate the application and optionally raise a specific window.

  /** Handle focus_window tool call. */
  async function handleFocusWindow(
    args: Record<string, unknown>,
  ): Promise<CallToolResult> {
    const parsed = FocusWindowInputSchema.parse(args);
    const app = await resolveAppName(parsed.app);
    const safeApp = escapeAppleScriptString(app);
  
    // Activate the application
    let script = `tell application "${safeApp}" to activate`;
  
    // If a specific window title is requested, raise it via System Events
    if (parsed.title) {
      const safeTitle = escapeAppleScriptString(parsed.title);
      script += `
  delay 0.3
  tell application "System Events"
    tell process "${safeApp}"
      set frontmost to true
      try
        perform action "AXRaise" of (first window whose name is "${safeTitle}")
      on error
        error "Window titled \\"${safeTitle}\\" not found in ${safeApp}"
      end try
    end tell
  end tell`;
    }
  
    await runAppleScript(script);
  
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify({
            success: true,
            app: parsed.app,
            ...(parsed.title ? { title: parsed.title } : {}),
          }),
        },
      ],
    };
  }

• src/tools/window.ts:26-35 (schema)

  'FocusWindowInputSchema' defines the structure and validation for input arguments required by the 'focus_window' tool.

  const FocusWindowInputSchema = z.object({
    app: z.string().max(1_000).describe("Application name to activate."),
    title: z
      .string()
      .max(1_000)
      .optional()
      .describe(
        "Window title to raise. If omitted, the frontmost window of the application is activated.",
      ),
  });

• src/tools/window.ts:88-97 (registration)

  The 'focus_window' tool is defined within the 'windowToolDefinitions' array, which provides the metadata and schema for the tool.

  {
    name: "focus_window",
    description:
      "Activate an application and optionally raise a specific window by title. App name supports fuzzy matching.",
    inputSchema: zodToToolInputSchema(FocusWindowInputSchema),
    annotations: {
      readOnlyHint: false,
      destructiveHint: false,
    },
  },

• src/tools/window.ts:252-252 (registration)

  The 'focus_window' tool is registered in 'windowToolHandlers', mapping it to its handler function with queuing.

  focus_window: (args) => enqueue(() => handleFocusWindow(args)),