feat(mcp): let LLMs drive alacritree via an MCP server

[mathix420]

What

Adds alacritree mcp — a stdio Model Context Protocol server that bridges tool calls to the running app, so LLM agents can browse projects/worktrees, open shells in them, type into terminals, read their output, and inspect git state.

claude mcp add alacritree -- alacritree mcp

How

Two pieces, mirroring upstream alacritty's IPC design (polling/ipc.rs):

• ipc.rs — the app listens on a unix socket at $XDG_RUNTIME_DIR/alacritree/alacritree-<pid>.sock, advertised to child PTYs via ALACRITREE_SOCKET (same trick as ALACRITTY_SOCKET), so an agent running inside an alacritree session automatically targets the instance hosting it. One newline-delimited JSON request per connection with an {"ok"}/{"error"} reply. Requests touching app state hop to the UI thread over an mpsc channel drained once per frame (woken by request_repaint, per the EventProxy contract); slow operations (git-status walks, worktree creation with its git fetch) run on the connection thread so they never stall a frame.
• mcp.rs — hand-rolled newline-delimited JSON-RPC (tools only), no SDK/tokio so the crate stays fully synchronous. Tool names + arguments map 1:1 onto IpcRequest serde tags. Socket discovery: env var → runtime-dir scan, --socket <path> to override.

Tools

Tool	What it does
list_projects	Sidebar projects with worktrees, branches, default branch
list_sessions	Sessions: id, title, workspace, kind, size, active tab, attention flag
select_workspace	Focus a workspace, like clicking it in the sidebar
create_session / close_session	Open/close a shell session in a workspace
send_text	Type into a terminal (control chars pass through; \r submits)
read_screen	Screen text + cursor position + optional scrollback
git_status	Staged/unstaged files and per-file +/- vs the default branch
create_worktree	Same flow as the sidebar's + button (fetch, branch, LLM-config copy)
refresh_project	Re-scan a project's worktrees

Worktree deletion is deliberately not exposed — destructive, and the UI gates it behind a confirm dialog for good reason.

Config / platform

• [general] ipc_socket = false disables the socket — same option name and location as alacritty's.
• IPC is unix-only, matching upstream; on Windows alacritree mcp fails fast with a clear message and the app simply doesn't bind a socket.

Testing

Verified end-to-end against the live app on sway: registered the bridge, listed real projects/sessions, spawned a session, sent echo hello-from-mcp $((6*7))\r, read hello-from-mcp 42 back via read_screen, pulled git_status (correctly reported this branch's own then-uncommitted files), exercised the unknown-worktree error path, and closed the session. Protocol edge cases (unknown tool → -32602, unknown method → -32601, notifications unanswered, ping) covered against a mock socket. cargo fmt + cargo check clean.

🤖 Generated with Claude Code