# mac-sync MCP (`@lilith/mac-sync-mcp`)

A stdio MCP server that exposes mac-sync's own `/my/*` surface as tools. mac-sync
owns the data (iMessage, contacts, prospects, calls, outbox in Postgres), so this
talks to the mac-sync server **directly** — no quinn-api hop. It supersedes the
mac-sync calls that previously lived in `quinn-m-mcp`.

## Env

| var | default | notes |
|-----|---------|-------|
| `MAC_SYNC_BASE_URL` | `http://209.38.51.98:3201` | mac-sync server (DO backend droplet; override to wg `http://10.9.0.5:3201`) |
| `MAC_SYNC_TOKEN` | — | the server's shared **service token** (`/my/*` is `serviceTokenAuth`) |

## Tools

- **Messages** — `search_messages` (hybrid/lexical/semantic), `list_conversations`, `get_thread`
- **Contacts** — `list_contacts`, `search_contacts_by_name`
- **Prospects** (Handoff 01) — `list_prospects`, `get_prospect`
- **Calls** (Handoff 02) — `recent_calls` (`since` window; answers "did this lead also call?")
- **Outbox** (Handoff 03) — `enqueue_reply` (paced, channel-smart, scheduled; `markReadOnSend` option), `outbox_status`, `outbox_stats`
- **Read-state** (Handoff 04) — `mark_conversation_read`, `mark_all_replied_read`, `conversation_read_state` (logical-read; never touches Apple's chat.db)

## Run

```sh
bun install
MAC_SYNC_TOKEN=... bun run src/index.ts   # stdio
bun run typecheck
```

## Register with a client (`.mcp.json`)

```json
{
  "mcpServers": {
    "mac-sync": {
      "type": "stdio",
      "command": "bun",
      "args": ["run", "<abs-path>/@mac-sync/mcp/src/index.ts"],
      "env": {
        "MAC_SYNC_BASE_URL": "http://209.38.51.98:3201",
        "MAC_SYNC_TOKEN": "<service-token>"
      }
    }
  }
}
```

Adjust `<abs-path>` to the host (the repo's `.mcp.json` uses `/var/home/lilith/...`
on the deploy host). The token is a secret — do not commit it.
