docs(mcp): add macOS setup and gotchas to Fortress MCP README

Native macOS engine binary isn't published yet, so on a Mac the engine
runs via the tilion/fortress:149 Docker image. Document the Colima path,
the FORTRESS_CHANNEL=latest / :151-not-on-Hub trap, the stale
credsStore=desktop failure, the harmless amd64/arm64 platform warning,
the port 9222 collision, and the headless-only constraint.

Author: Arman-Luthra

mcp/README.md

@@ -19,7 +19,56 @@ tilion-mcp                       # or:  python -m tilion.mcp   (stdio transport)
 ```
 
 The MCP server is a thin, open wrapper (BSD-3) over the `tilion` framework, which drives the
-Fortress engine. The stealth Chromium downloads on first run and is cached locally.
+Fortress engine. On Linux and Windows the stealth Chromium downloads on first run and is cached
+locally. On macOS the engine runs as a Docker image instead. Read the macOS section below before
+you start.
+
+## macOS setup (Apple Silicon and Intel)
+
+There is no native macOS engine binary yet, so on a Mac the Fortress engine runs as the official
+Docker image (`tilion/fortress:149`). `tilion-mcp` itself runs natively in Python. Only the
+browser engine is containerised, and the server starts and stops that container for you. All you
+supply is a running Docker daemon.
+
+### Setup
+
+1. Install the MCP and engine wrapper:
+   ```bash
+   pip install "tilion[mcp]"
+   ```
+2. Give it a Docker daemon. Colima is lighter than Docker Desktop and needs no license or GUI:
+   ```bash
+   brew install colima docker
+   # Apple Silicon: vz + Rosetta runs the amd64 engine image fast.
+   colima start --cpu 4 --memory 6 --disk 30 --vm-type=vz --vz-rosetta
+   # Intel Macs: plain `colima start` works. Docker Desktop is also fine if you already run it.
+   ```
+   Give the VM at least 4 CPUs and 4 GB of RAM, since it runs a real Chromium.
+3. Register the server with your client. For Claude Code:
+   ```bash
+   claude mcp add fortress -- tilion-mcp
+   ```
+4. The first tool call pulls the image once (about 300 MB), then the container stays warm and
+   calls are fast. Call `get_egress_info` to confirm the engine is alive; it returns the public
+   IP the target sees.
+
+### What not to do on macOS
+
+| Pitfall | What happens, and the fix |
+|---|---|
+| Setting `FORTRESS_CHANNEL=latest` | That channel points at `tilion/fortress:151`, which is not published to Docker Hub, so the pull 404s and the engine never starts. Stay on the default `stable` channel, `tilion/fortress:149`. Native Linux and Windows are unaffected, since they fetch the GitHub release rather than the image. |
+| A leftover Docker Desktop credential helper | `docker pull` fails with `docker-credential-desktop … executable file not found`. Open `~/.docker/config.json` and delete the `"credsStore": "desktop"` line. |
+| Worrying about the platform warning | `The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8)` is expected on Apple Silicon and harmless. The amd64 engine runs under Rosetta, a little slower than native Linux. |
+| Running two `tilion-mcp` servers at once | Each launches a Fortress container on host port `9222`, so the second fails with `docker … exit status 125` (port already allocated). Run one server per machine. |
+| Assuming Colima survives a reboot | If tool calls fail with a Docker error after a reboot, run `colima start`. To start it at login, run `brew services start colima`. |
+| Setting `TILION_MCP_HEADLESS=0` for a visible window | This has no effect on macOS. The containerised engine is headless only. A visible window needs the native Linux or Windows binary. |
+
+### Still getting blocked on a hard target
+
+Your Mac's home or office IP is residential, which suits most sites. For the hardest targets, or
+when running from a datacenter, route the engine through a residential proxy. Set
+`TILION_PROXY=http://user:pass@host:port` (and optionally `TILION_REGION=us`) before starting the
+server, then confirm with `get_egress_info`.
 
 ## Add to your client