# Mac Use

Local Mac desktop control for **Grok** and **Cursor** via a bundled stdio MCP server.

HID input matches [Dottie](https://github.com/stevederico/dottie-desktop): `CGEvent` posted on `.cghidEventTap`. Coordinates are **screen points** (main display, origin top-left). Screenshots are resized to that size, so image pixels and clicks share one space.

---

## What it is

| Surface | Use when |
| --- | --- |
| **Mac Use (this plugin)** | Native Mac apps, Finder, system UI on the **user Mac** |
| **Browser Use** | The task is primarily a website |
| **Remote Linux desktop** | Work on a box desktop — not this plugin |

Prefer the smallest surface that fits.

---

## Install

**Grok**

```bash
grok plugin install /path/to/mac-use --trust
```

Or add the folder under `~/.grok/plugins/` (auto-trusted) and enable it.

**Cursor**

```bash
mkdir -p ~/.cursor/plugins/local
ln -s /path/to/mac-use ~/.cursor/plugins/local/mac-use
cd ~/.cursor/plugins/local/mac-use && npm install
```

Then **Developer: Reload Window**. Call `mac_use_status`.

First input/screenshot compiles `server/helper.swift` with `swiftc` (Xcode or CLT).

---

## macOS permissions

Grant **Accessibility** and **Screen Recording** to:

1. `mac-use-helper` (built next to the Swift source)
2. The host that launched the MCP server (Grok, Cursor, or Terminal)

`mac_use_status` requests the TCC prompt and opens the matching Settings pane when a grant is missing. After you flip the toggle, quit and reopen Grok.

---

## Tools

| Tool | Purpose |
| --- | --- |
| `mac_use_status` | Platform, AX / Screen Recording, driver |
| `get_screen_size` | Main display points (origin top-left) |
| `screenshot` | PNG whose pixels match those points |
| `mouse_move` | Absolute `x,y` or relative `dx,dy` |
| `click` | HID click at points (or current cursor) |
| `mouse_drag` | Left-button drag in points |
| `type_text` | Unicode into the focused app (no clipboard) |
| `key` | Key + modifiers; destructive chords need `confirmed` |
| `scroll` | HID wheel at `(x, y)` by `dy` |

Always screenshot after acting. Confirm before destructive actions. Do not paste secrets from chat into `type_text`.

---

## Agent loop

1. `mac_use_status`
2. `screenshot` (or `get_screen_size`)
3. One action in those points
4. Screenshot again

---

## Dev

```bash
cd ~/Desktop/projects/mac-use
npm install
npm run build-helper
npm test
npm start   # stdio MCP
```

- Entry: `server/index.js`
- Driver: `server/driver-impl.js` → `server/helper.swift`
- Cursor: `.cursor-plugin/plugin.json` + `mcp.json`
- Grok: `plugin.json` + `.mcp.json`
- Skill: `skills/mac-use/SKILL.md`

---

## License

MIT / Steve Derico