conductor-remote 1.41.0 → 1.42.0

package/README.md

@@ -198,6 +198,80 @@ RELAY_TOKEN=$(openssl rand -hex 16) yarn start
 - ✅ **Push notifications** when an agent finishes its turn or hits an error —
   see below.
 
+## MCP: let your agents drive Conductor
+
+`conductor-remote mcp` is an MCP server on stdio. It gives a coding agent the same
+control the phone has, over the same relay.
+
+Two transports, same ten tools.
+
+**stdio** — for an agent running on this Mac. The client spawns it as a child process;
+there is no URL and nothing is exposed.
+
+```bash
+claude mcp add conductor -- conductor-remote mcp
+```
+
+**HTTP** — for an agent that can only reach a URL, at `POST /mcp` on the relay, gated by
+the same token as `/api/*`.
+
+```bash
+claude mcp add --transport http conductor https://<your-magicdns>/mcp \
+  --header "Authorization: Bearer $(cat ~/Library/Application\ Support/conductor-remote/token)"
+```
+
+Either way the relay must be running (`conductor-remote service status`). The stdio
+server reads the persisted token itself, so it needs no configuration at all.
+
+**Who can reach the HTTP endpoint depends on `EXPOSE`**, and this is the decision worth
+making deliberately:
+
+| `EXPOSE` | fronted by | who reaches `/mcp` |
+|---|---|---|
+| `tailnet` | `tailscale serve` | any device signed into your tailnet, from any network |
+| `public` (default) | `tailscale funnel` | anyone on the internet holding the token |
+
+`tailnet` is not LAN-only — a laptop on hotel wi-fi reaches it fine, over WireGuard. But
+a *hosted* client is not on your tailnet: an agent running on someone else's servers
+needs `public`, where the token is the only thing between the internet and
+`create_workspace` / `send_prompt`. Prefer stdio when the agent is local, which is most
+of the time.
+
+| tool | what it does |
+|---|---|
+| `search_chats` | full-text search every chat on the Mac, archived included |
+| `read_chat` | a transcript by `session_id` — works for archived workspaces |
+| `list_workspaces` | what is running right now, with status and model |
+| `list_chats` | the chat tabs in a workspace |
+| `workspace_diff` | a workspace's diff against its target branch |
+| `list_repos` | repos a workspace can be created in |
+| `create_workspace` | start a new workspace, optionally with a first prompt |
+| `send_prompt` | send into an existing chat (drives the real UI) |
+| `stop_turn` | cancel a running answer (drives the real UI) |
+| `set_workspace_status` | set the sidebar status (drives the real UI) |
+
+The first six touch nothing. `create_workspace` opens a Conductor deep link, so it
+needs no Accessibility and steals no focus. The last three drive Conductor's real
+window for a few seconds.
+
+The HTTP transport is deliberately minimal: the server never initiates a message, so
+there is no SSE stream and `GET /mcp` answers 405, which the spec allows. It keeps no
+session either. A request carrying an `Origin` header is refused outright — a real MCP
+client sends none and a browser cannot omit one, which closes the DNS-rebinding hole
+without the relay having to know its own hostname behind Tailscale's TLS.
+
+**Two agents cannot collide.** Conductor has one window, so every UI write in the
+relay is serialized by a single process-local lock — which is exactly why these
+tools call the relay instead of driving AppleScript themselves. Agents are marked
+background priority, so they always yield to whoever is holding the phone, and past
+four queued operations a caller is refused with "busy, retry shortly" rather than
+joining a line it would only time out waiting in.
+
+Worth knowing before you wire it up: `send_prompt` into a chat that is already
+working **steers that agent** rather than starting a new turn, and `stop_turn`
+destroys work in flight. The tool descriptions say so, and both ask the caller to
+confirm with you first.
+
 ## Notifications
 
 Turn them on from the **Connect sheet** (the QR button in the workspace list

package/bin/cli.js

@@ -58,6 +58,8 @@ function usage() {
 			'',
 			'Usage:',
 			'  conductor-remote [start]                 run the relay (default)',
+			'  conductor-remote mcp                     MCP server on stdio — lets an agent search chats,',
+			'                                           read transcripts and drive workspaces via the relay',
 			'  conductor-remote service <subcommand>    manage the login LaunchAgent',
 			'      install | uninstall | restart | status',
 			'  conductor-remote logs [-n N] [--no-follow]  tail the running relay’s logs (follows by default)',
@@ -89,6 +91,10 @@ switch (cmd) {
 	case 'start':
 		await import(resolveEntry('../dist-node/src/server.js', '../src/server.ts'))
 		break
+	case 'mcp':
+		// MCP server on stdio: stdout is the JSON-RPC wire, so nothing else may print there.
+		await import(resolveEntry('../dist-node/src/mcp.js', '../src/mcp.ts'))
+		break
 	case 'service':
 		// service.ts reads its subcommand from argv[2]; re-shape argv so `service install` → `install`.
 		process.argv = [process.argv[0], process.argv[1], ...rest]