mac-use-mcp

Instructions

Implementation Reference

• src/tools/window.ts:202-242 (handler)

  The handler function `handleOpenApplication` performs the logic to open an application using the `open` command, supporting both bundle identifiers and application names.

  async function handleOpenApplication(
    args: Record<string, unknown>,
  ): Promise<CallToolResult> {
    const parsed = OpenApplicationInputSchema.parse(args);
    // Skip resolution for bundle IDs — they must be passed verbatim
    const name = isBundleId(parsed.name)
      ? parsed.name
      : await resolveAppName(parsed.name);
  
    // Determine whether to use -a (app name) or -b (bundle ID)
    const flag = isBundleId(name) ? "-b" : "-a";
  
    try {
      await execFileAsync("open", [flag, name], {
        timeout: OPEN_COMMAND_TIMEOUT_MS,
      });
    } catch (error: unknown) {
      const msg = error instanceof Error ? error.message : String(error);
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify({
              success: false,
              error: `Failed to open application "${name}": ${msg}`,
            }),
          },
        ],
        isError: true,
      };
    }
  
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify({ success: true, app: name }),
        },
      ],
    };
  }

• src/tools/window.ts:37-44 (schema)

  Zod schema definition for `open_application` input validation.

  const OpenApplicationInputSchema = z.object({
    name: z
      .string()
      .max(1_000)
      .describe(
        'Application name (e.g. "Safari") or bundle identifier (e.g. "com.apple.Safari").',
      ),
  });

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

  Registration definition for the `open_application` tool.

    {
      name: "open_application",
      description:
        "Launch an application by name or bundle identifier. App name supports fuzzy matching (e.g. 'chrome' → 'Google Chrome').",
      inputSchema: zodToToolInputSchema(OpenApplicationInputSchema),
      annotations: {
        readOnlyHint: false,
        destructiveHint: true,
      },
    },
  ];

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

  Handler mapping where `open_application` is connected to its handler via an enqueue wrapper.

  export const windowToolHandlers: Record<
    string,
    (args: Record<string, unknown>) => Promise<CallToolResult>
  > = {
    list_windows: (args) => enqueue(() => handleListWindows(args)),
    focus_window: (args) => enqueue(() => handleFocusWindow(args)),
    open_application: (args) => enqueue(() => handleOpenApplication(args)),