Iterating With AI And MCP

# Iterating with AI and MCP: let the agent edit, reload, screenshot, and iterate

Compose HotSwan ships an embedded HTTP MCP server inside the IntelliJ plugin. Any MCP-compatible AI client (Claude Code, Cursor, any tool that speaks Model Context Protocol) can call its tools to drive the iteration loop. The agent edits a Kotlin file, calls `hotswan_reload`, captures a screenshot of the running device, evaluates the result against the design intent, and decides the next change. Cycle time is comparable to the human loop, a few seconds per iteration, so the agent can converge on a UI tweak without a human steering each step.

This skill teaches the canonical agent loop, the seven MCP tools (verbatim names), and the safety habits (status check first, snapshot wrapping for rollback, fallback to full install for schema changes) that keep the loop reliable.

## When to use this skill

- The developer wants AI-driven UI iteration: "tune this screen until it matches the mock", "let the agent pick a colour".
- The developer wants the AI to verify its own edits visually instead of guessing whether the change worked.
- The developer is wiring up a Claude Code or Cursor workflow that needs MCP tool access to a running app.
- The user asks "can the AI see what changed?", "can the AI screenshot the device?", "how does Claude Code drive HotSwan?".
- The user mentions "MCP server", "hotswan_reload", "hotswan_take_screenshot", "agent loop", or "snapshot rollback".

## When NOT to use this skill

- Pure code review without runtime feedback (no need for MCP tools at all).
- Release-grade visual regression testing. Use Macrobenchmark plus a screenshot diff harness, not HotSwan snapshots. Cross-link `../../measurement/generating-baseline-profiles/SKILL.md`.
- The change in question would force a full rebuild (parameter add, constructor change, new resource ID). Read `../understanding-hot-reload-limits/SKILL.md` first to classify the edit before reaching for the MCP loop.
- The reload keeps escalating to tier 2 or tier 3 and losing state. Fix that with `../preserving-state-across-reloads/SKILL.md` before adding an autonomous loop on top.

## Prerequisites

- Compose HotSwan installed and the IDE plugin active. Setup lives in `../setting-up-compose-hotswan/SKILL.md`.
- The target app is already running on a connected device or emulator with the HotSwan watcher state reported as `WATCHING`.
- An MCP-capable AI client (Claude Code, Cursor) with MCP server discovery enabled and pointed at the HotSwan plugin's HTTP MCP endpoint.

## MCP tools (verbatim names)

The HotSwan MCP server exposes exactly these seven tools. The agent **MUST NOT** invent additional tool names.

- `hotswan_get_status()`: returns device, app, and watcher state. Call once at the start of every loop to confirm the agent has a connected target and that the watcher is `WATCHING`.
- `hotswan_reload(filePaths)`: explicit reload trigger for the listed file paths. Returns the tier (1 / 2 / 3) that ran. The agent reads the tier to decide whether the previous edit kept the loop fast.
- `hotswan_take_screenshot()`: capture the current device screen. Returns image bytes or a path the agent can read back and inspect.
- `hotswan_start_snapshot()`: begin a snapshot session. After this call, HotSwan auto-captures a screenshot and source state after every reload, so the agent can roll back to any intermediate variant.
- `hotswan_stop_snapshot()`: end the current snapshot session and finalise the history.
- `hotswan_select_variant()`: pick a preferred snapshot from the recorded history. Used to roll the source code back to the chosen variant when the agent decides an earlier iteration was the best one.
- `hotswan_build_and_install()`: fall back to a full install. Used when the agent detects a schema change (new parameter, constructor change, new resource ID) that the hot reload pipeline cannot handle. Treat this as a fallback, not a default.

## Workflow

The canonical agent loop:

### 1. Check status before issuing any edit

Call `hotswan_get_status()`. If `watcher` is not `WATCHING`, surface the issue back to the human and stop. The reload tool will silently no-op if the watcher is not running and the agent will burn cycles wondering why nothing changed on screen.

### 2. Open a snapshot session

Call `hotswan_start_snapshot()` so the loop has a visual record. Each reload inside the session auto-captures, which lets the agent (or the human reviewing afterwards) compare iterations and roll back to any variant.