Summary

Implement the MCP (Model Context Protocol) server that exposes 29 RemoteClaw-specific tools to CLI subprocess agents. This is the C2 component — the mechanism by which CLI agents (Claude, Gemini, Codex, OpenCode) can interact with RemoteClaw's sessions, messaging, cron, and gateway systems.

Architecture

Lifecycle Model

ChannelBridge (gateway process)
    |
    | 1. Builds McpServerConfig, passes via AgentExecuteParams.mcpServers
    | 2. Spawns CLI subprocess (runtime handles config format internally)
    v
CLI Agent (claude/gemini/codex/opencode)
    |
    | 3. Reads MCP config, spawns MCP server as child
    v
remoteclaw-mcp-server (stdio subprocess of CLI agent)
    |
    | 4. Connects to gateway via WebSocket RPC
    | 5. Handles MCP tool calls by invoking gateway RPCs
    | 6. Appends side effects to temp file (NDJSON)
    v
Gateway WebSocket RPC (existing infrastructure)

Per-invocation: Each CLI subprocess invocation gets a fresh MCP server. The MCP server starts when the CLI agent spawns it, dies when the CLI agent exits. Clean isolation, no cross-session state.

Transport: Stdio — the only transport supported by all 4 CLIs.

Per-Runtime Config Generation (already implemented)

Per-runtime MCP config generation is already implemented in each runtime's *McpConfigManager class (from ClaudeCliRuntime (#8)–015):

All runtimes accept a uniform McpServerConfig via AgentExecuteParams.mcpServers and handle format translation internally. MCP server (#30) only needs to define the McpServerConfig shape that ChannelBridge passes (env vars for gateway URL, token, session key, side effects path, channel info).

Configuration (environment variables)

The MCP server receives its context via environment variables set by ChannelBridge:

Tool Inventory (29 tools)

Session Management (7 tools)

Channel Messaging (10 tools)

Cron Scheduling (7 tools)

Gateway Admin (5 tools)

NOT Exposed (middleware boundary principle)

Side Effects Protocol

File-based NDJSON protocol for tracking MCP messaging side effects:

{"type":"message_sent","tool":"message","provider":"telegram","to":"group:123","text":"Hello","mediaUrl":null,"ts":1708905600000}
{"type":"cron_added","jobId":"job-xyz","ts":1708905602000}

Why file-based: ChannelBridge creates a temp file path; the MCP server appends side effects as NDJSON lines. After CLI subprocess exits, ChannelBridge reads the file. Robust even if MCP server crashes (partial file is valid NDJSON).

Side effect recording tools:

• Messaging: message_send, message_reply, message_thread_reply, message_broadcast, message_send_attachment, message_send_with_effect, sessions_send → recordMessageSent()
• Cron: cron_add → recordCronAdd()

No race condition: CLI agent blocks on MCP tool responses, so the sequence is always: CLI sends request → MCP processes + writes side effect → MCP responds → CLI continues. When CLI exits, all side effects are on disk.

Tool Policy Integration

The MCP server applies the same tool policy pipeline as the existing /tools/invoke HTTP endpoint:

• Tool allowlisting/denylisting is respected
• Per-agent, per-channel, per-group policies apply
• Subagent tool restrictions are enforced

At startup, the MCP server loads config, resolves policies, and only registers allowed tools.

Implementation Approach

New Files

Modified Files

Test Files

Estimated total: ~755 LoC (not counting tests) + ~500 LoC tests

(Reduced from original ~1,180 estimate — per-runtime config generation (~425 LoC) already exists in ClaudeCliRuntime (#8)–015.)

Tool Implementations

Each MCP tool handler is a thin adapter layer that:

1. Receives MCP tool input (JSON Schema-validated by MCP SDK)
2. Translates to a callGatewayTool() RPC call (using existing gateway RPC infrastructure)
3. Records side effects (for messaging and cron tools)
4. Returns MCP-formatted result

The tool handlers wrap existing src/agents/tools/ code — specifically sessions, messaging, cron, and gateway tools. They do NOT wrap the pi-embedded tools (web, browser, image, TTS) being gutted in M3.

Key Dependencies

Acceptance Criteria

• src/middleware/mcp-server.ts (and supporting files) expose 29 RemoteClaw-specific tools via MCP
• Tool categories: 7 session management, 10 channel messaging, 7 cron scheduling, 5 gateway admin
• Server uses per-invocation stdio lifecycle (spawned per CLI agent invocation, not long-running)
• Side effects recorded via file-based NDJSON protocol for McpSideEffectsCollector consumption
• Tool implementations wrap existing src/agents/tools/ code (thin adapter layer)
• Generic capabilities (web fetch/search, browser, image, TTS) are NOT exposed (middleware boundary principle)
• Unit tests cover tool registration, invocation, and side effects recording
• pnpm build passes