# whitelabel-fleet-mcp

> MCP server that exposes the whitelabel fleet to remote Claude clients.
> Plug your iPhone (or another laptop's Claude Desktop) into this and you
> get the same coding power you have on the host Mac: read/write files,
> run shell commands, drive git, read [whitelabel-memory](https://github.com/whitelabel-dev/whitelabel-memory).

## Why

Coding from a phone usually means SSH + a terminal app — passable but
clunky, and Claude has no idea what the fleet looks like. Model Context
Protocol fixes that: the iOS Claude app speaks MCP as a first-class
client, so once this server is exposed, your phone's Claude can call
`list_dir`, `git_status`, `run_shell`, etc., as native tools.

## Architecture

```
iPhone Claude
    ↓ HTTPS (Streamable HTTP transport)
Tailscale Serve (or Funnel)
    ↓
127.0.0.1:8473  ← this server
    ↓
Fleet tools:
  • files       read_file, write_file, list_dir, search_code
  • shell       run_shell
  • git         git_status, git_diff, git_log, git_commit
  • memory      read_memory, append_journal
```

Auth: bearer token in the `Authorization` header. The token is the
perimeter — guard it like a password.

## Setup (local)

```sh
cd whitelabel-fleet-mcp
npm install
cp .env.example .env
echo "FLEET_MCP_TOKEN=$(openssl rand -hex 32)" >> .env
npm start
```

Verify:
```sh
curl http://127.0.0.1:8473/healthz
# → {"ok":true,"version":"0.1.0","sessions":0}
```

Full end-to-end smoke test (boots server, runs every tool, prints results):
```sh
FLEET_MCP_TOKEN=$(grep FLEET_MCP_TOKEN .env | cut -d= -f2) \
  node scripts/smoke.mjs
```

## Setup (iPhone Claude)

1. Install **Tailscale** on your iPhone and log in to the same tailnet as
   the host Mac.
2. On the host Mac, expose the server over HTTPS:
   ```sh
   bash scripts/serve.sh
   ```
   This prints your tailnet hostname, e.g.
   `https://mac1.tail1234.ts.net/mcp`.
3. In the **iPhone Claude** app:
   - Settings → **Connectors** → **Add custom connector**
   - URL: the tailnet `/mcp` URL from step 2
   - Auth: **Bearer token** → paste your `FLEET_MCP_TOKEN`
4. Open a new chat. Claude will list the tools it picked up
   (`read_file`, `git_status`, `run_shell`, …). Try: *"list the
   whitelabel-flow repo, then show me the most recent commits."*

## Setup (start at login)

```sh
bash scripts/install-launchd.sh
```

Installs `dev.whitelabel.fleet-mcp` as a user LaunchAgent that runs at
login and restarts on crash. Logs at
`~/Library/Logs/whitelabel-fleet-mcp/{stdout,stderr}.log`.

Uninstall:
```sh
launchctl unload ~/Library/LaunchAgents/dev.whitelabel.fleet-mcp.plist
rm ~/Library/LaunchAgents/dev.whitelabel.fleet-mcp.plist
```

## Tools

| Tool | What it does |
|---|---|
| `read_file` | Read a UTF-8 file (up to 1 MB). |
| `write_file` | Create or overwrite a file. Makes parent dirs. |
| `list_dir` | List immediate children of a directory. |
| `search_code` | `rg` (or `grep -r`) across the workspace. |
| `run_shell` | Execute a shell command via `zsh -lc`. Capped at 600 s and 200 KB output. |
| `git_status` | `git status --short --branch` for any repo. |
| `git_diff` | Unstaged or staged diff, optionally narrowed to paths. |
| `git_log` | Last N commits, oneline. |
| `git_commit` | Stage + commit, with optional push. |
| `read_memory` | Fetch `whitelabel-memory/HANDOFF.md` + most-recent journal. |
| `append_journal` | Drop a new journal entry into `whitelabel-memory`. |

All file/repo paths must resolve inside `WORKSPACE_ROOT` (set in `.env`,
default `~/Documents`). Paths outside are rejected.

## Security notes

- The bearer token is the only auth. **Rotate it** if you suspect leakage.
- `run_shell` runs anything — gating is intentional only against
  Cloudflare/Tailscale-level mishaps, not the authenticated client. If
  you give the token to a friend they can do anything you can.
- Tailscale Serve binds to your tailnet only; Funnel would expose it to
  the public internet (HTTPS-auth'd by token, not network ACL). Prefer
  Serve unless you need outside access.

## Roadmap

| Version | Adds |
|---|---|
| v0.1 (here) | core tools, bearer auth, Tailscale Serve, LaunchAgent |
| v0.2 | `dispatch_to_worker` (call `whitelabel-orchestrator` API to fire long-running jobs on mac1-4) |
| v0.3 | `summon_claude_code` (spawn a fleet `claude -p` for heavy refactors) |
| v0.4 | per-tool ACLs (some clients get read-only, some can shell) |
| v1.0 | replaces `dispatch.sh` entirely as the fleet's RPC layer |