Improve macOS permission onboarding for host-app installs

[TheGuyWithoutH]

Summary

Make the permission setup story clearer and easier for users who run the MCP server from Terminal, Codex, Cursor, Warp, or similar hosts.

Why

The biggest open-source support burden will be macOS Accessibility and Screen Recording setup.

Scope

• Improve README troubleshooting for permission failures.
• Add clearer host-app-specific guidance.
• Consider adding a lightweight permissions diagnostic command.
• Document common failure modes around Accessibility, Screen Recording, and host app restarts.

Acceptance Criteria

• Permission troubleshooting is easy to find.
• A user can identify whether the host app or helper context is the problem.
• Common setup failures have explicit documented remedies.

[IgorGanapolsky]

This is exactly the right onboarding surface to document. The confusing part for users is that "permission granted" is not one state on macOS; it depends on the host app, helper app, bundle id, launch context, and whether the MCP runtime is actually the one making the request.

The checklist I would put near the top:

# 1. identify the host app that launches the MCP server
ps aux | grep -i 'mcp\\|computer'

# 2. verify Accessibility and Screen Recording for that host/helper pair
# GUI path: System Settings > Privacy & Security > Accessibility / Screen & System Audio Recording

# 3. restart the host app after granting permissions

# 4. test the lowest-risk call first
# list apps / list windows before trying clicks or typing

The docs should also call out that Terminal, Cursor, Warp, Codex Desktop, and a helper app can each need separate permission state. A user can grant the wrong one and still see failures.

I wrote a related Mac Computer Use troubleshooting checklist here:
https://igorganapolsky.github.io/openclaw-mac-ai-workstation-setup/troubleshooting.html

And for people who want a fast setup triage instead of debugging every layer, I opened a $49 same-day triage link:
https://buy.stripe.com/28E7sL3Ug3n0bO935V3sI0r