feat: MCP server for waking and driving IDE / agent tmux sessions

[ThinkOffApp]

Summary

Adds an MCP server (src/mcp-server.mjs + bin/iak-mcp.mjs) that exposes IAK's tmux-backed wake / list / run primitives as MCP tools. Any MCP-aware client (Claude Desktop / Code, Cursor, custom agents) can now drive the agent fleet directly without re-implementing the nudge / send-keys protocol.

Per @Petrus's room request "use MCP to wake up IDEs".

Tools exposed

Tool	Args	Notes
wake_ide	session, text? (default \"check rooms\")	Sends nudge text and presses Enter in the named tmux session.
list_sessions	(none)	Returns every live tmux session with attach state + window count.
wake_all	text? (default \"check rooms\")	Sends the same nudge to every session IAK knows about. Per-session pass/fail.
tmux_run	cmd, session?, cwd?, timeoutSec?	Runs an allowlisted command in a tmux session. Same allowlist as the CLI's tmux run.

Wiring example (Claude Desktop / Code)

{
  \"mcpServers\": {
    \"ide-agent-kit\": {
      \"command\": \"node\",
      \"args\": [\"/absolute/path/to/ide-agent-kit/bin/iak-mcp.mjs\"]
    }
  }
}

Restart the client → the 4 tools appear in the tool picker.

Smoke test (already done)

$ printf '...initialize, tools/list, tools/call list_sessions...' | node bin/iak-mcp.mjs
[iak-mcp] ready on stdio
{\"result\":{\"protocolVersion\":\"2025-03-26\",...}}
{\"result\":{\"tools\":[{\"name\":\"wake_ide\",...},{\"name\":\"list_sessions\",...},...]}}
{\"result\":{\"content\":[{\"type\":\"text\",\"text\":\"tmux sessions (6):\\n  antigravity\\tdetached\\t1 window(s)\\n  claude\\tdetached\\t1 window(s)\\n  ...\"}]}}

Files

• src/mcp-server.mjs (new) — server, all 4 tool handlers
• bin/iak-mcp.mjs (new) — stdio CLI entry point, registered as the ide-agent-kit-mcp bin
• package.json — adds the bin entry, the npm run mcp script, the mcp keyword, and @modelcontextprotocol/sdk@^1.29.0
• package-lock.json — locked
• README.md — new "MCP server" subsection under Integrations

Implementation notes

• wake_all is config-aware: pulls sessions from tmux.ide_session, tmux.default_session, and any per-adapter session keys. Sessions that aren't live are reported with not running rather than failed silently.
• list_sessions uses | as the tmux format delimiter rather than \\t — single-quoted shell strings don't interpret \\t, so tmux would emit literal backslash-t. | is safe for IAK's session naming.
• All tool handlers wrap errors and return isError: true with a text message rather than crashing the server.
• tmux_run reuses the existing tmuxRun from src/ide/tmux-runner.mjs so the allowlist + receipt behavior is identical to the CLI.

Test plan

• node bin/iak-mcp.mjs boots and emits [iak-mcp] ready on stdio.
• JSON-RPC initialize → server returns protocolVersion + serverInfo.
• tools/list → returns all 4 tools with correct schemas.
• tools/call name=list_sessions → returns live tmux sessions on the host.
• @Petrus / @claudemm / @CodexMB to install in their MCP client and verify wake_ide actually nudges a target tmux session end-to-end.
• Try wake_all with the live IAK config and verify per-session pass/fail.

Out of scope

• Adding mcp as a subcommand of bin/cli.mjs (kept separate via dedicated bin so MCP clients can spawn it cleanly without parsing CLI args).
• Auth on the MCP transport. stdio-only for now; if exposed over HTTP later, that needs revisiting.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

To use Codex here, create an environment for this repo.

[ThinkOffApp]

Reviewed src/mcp-server.mjs and the new bin/iak-mcp.mjs. Reuses nudgeTmux + tmuxRun cleanly, stdio transport via official @modelcontextprotocol/sdk 1.29.0, schemas + descriptions are well-shaped, config-load failure degrades gracefully. Approve in spirit, with a few items worth addressing before merge:

Security (high): src/ide/tmux-runner.mjs:21 opens with if (!allowlist || allowlist.length === 0) return true; — if config.tmux.allow is missing or empty, tmux_run becomes arbitrary shell execution. Fine for the CLI where the operator chose to invoke it, but the MCP surface can be driven by any client over stdio. Suggest the MCP server fail closed when config.tmux.allow is empty (refuse to register tmux_run and log a warning), or require an explicit mcp.allow_unrestricted=true opt-in.

configuredAgentSessions is fragile (medium): scans every top-level config key for objects with a .session string. Will pick up unrelated future keys (e.g. sentry: { session: "warn" }). Cleaner to add an explicit mcp.sessions: ["claudemb", "antigravity", ...] config key.

Hardcoded version (low): server name advertises version: "0.6.1". Will drift from package.json on future bumps. Read it from ../package.json once at boot.

Missing read tool (medium, scope): agents calling wake_ide have no way to peek at the session output before/after. A read_session(session, lines=50) tool that runs tmux capture-pane -p -t <session> -S -lines would make the toolset much more useful — without it, MCP clients have to wake-and-pray.

No tests: the diff is +1423 / -4 with no test/ delta. The tmux_run wrapper especially deserves a unit test asserting the fail-closed behavior once it lands.

Otherwise solid. Reusing existing allowlist + nudge primitives instead of forking them was the right call.