MCP Server

The HotSwan MCP Server connects any AI assistant to your running Android app through the Model Context Protocol. All your AI tools can edit Compose code, trigger hot reloads, capture device screenshots, and explore design variants, all driven by natural language.

Overview

Instead of passively watching AI generated file changes, the MCP Server gives AI assistants direct control over the hot reload pipeline. The AI can trigger reloads on demand, capture screenshots to see the result, compare multiple variants, and make decisions about which design works best.

This transforms AI assisted development from a one way “edit and hope” workflow into a closed feedback loop: the AI sees exactly what its changes look like on a real device and can iterate autonomously.

How It Works

The MCP Server runs as an embedded HTTP bridge inside the IntelliJ plugin. When an AI tool calls an MCP tool, the request flows through three stages:

AI Edits Code

The AI assistant reads and modifies Kotlin/Compose files using its built in file editing tools.

Hot Reload Applies

HotSwan compiles the changed code and swaps it into your running app in memory. No restart needed.

AI Sees the Result

Screenshots are captured and stored as snapshots. The AI and you can review, compare, and iterate.

Setup

Copy the MCP configuration from IntelliJ, then add it to your AI tool.

1. Copy the config

Navigate to Settings → Tools → Compose HotSwan and click Copy MCP Config to Clipboard.

Copy MCP Config button in IntelliJ settings

2. Add to your AI tool

Select your tool below for the config path and setup command. Replace placeholder paths with your actual plugin installation and project directories.

Available Tools

The MCP Server exposes 17 tools organized into five categories.

CoreHot Reload Controls

hotswan_get_status

Get current state: emulator, app, watcher, snapshot capturing, device connection.

hotswan_start

Start file watching and enable hot reload.

hotswan_reload(filePaths: string[])

Trigger hot reload for specified file paths. Edit files first, then call this.

hotswan_revert_change(filePaths: string[])

Revert files to git HEAD and trigger hot reload.

hotswan_build_and_install

Full Gradle build, APK install, and auto start watcher.

SnapshotScreenshot Capture

hotswan_take_screenshot

Capture a device screenshot and save it as a snapshot in the IDE.

hotswan_start_snapshot

Start snapshot capturing mode.

hotswan_stop_snapshot

Stop snapshot capturing mode.

PaletteDesign Variant Iteration

hotswan_explore_palette(axes: string[], variantCount?: int, scopeFile?: string, scopeFunction?: string)

Auto mode for standard Material 3 themes. Plugin generates 5 curated color variants, applies each via the literal-patching path, captures a screenshot per variant, and returns a browser comparison grid.

hotswan_show_palette_grid(variants: { name, description, screenshotPath, swatches?, edits[] }[])

Manual mode. The agent owns the iteration loop (edit → reload → screenshot → revert) and then calls this tool to display N variants in a click-to-apply browser grid. Use when the project doesn't fit the auto-detection pattern (custom theme data class, KMP shared theme, XML colors).

hotswan_apply_palette_variant(variantId: string, reason?: string)

Permanently rewrite source literals to match a variant chosen via hotswan_explore_palette. Records the choice in decision history.

hotswan_palette_status

Get the current Palette session state: axes already explored, current shortlist, whether the comparison grid is open, last applied variant.

DecisionVariant Selection

hotswan_select_variant(snapshotId: int, reason: string)

Select a UI variant by snapshot ID. Rejected variants are cleaned up.

hotswan_get_decision_history

Review the full decision chain: selected, rejected, and reasons.

hotswan_clear_decisions

Clear decision history when starting a new exploration.

DebugDiagnostics

hotswan_get_logs(count?: int)

Get recent compilation and reload logs.

hotswan_list_devices

List connected Android devices and emulators.

hotswan_select_devices(serials: string[])

Select which devices to broadcast hot reload to simultaneously.

hotswan_get_connected_devices

Get multi-device connection status with per-device details.

HotSwan Palette

Palette turns visual design iteration on color, spacing, corner radius, typography, and density into a side-by-side pick. The AI generates N variants of whatever screen you currently have on the device, every variant lands in well under a second through HotSwan's literal patching path without rebuilding the app, and the variant you choose is written back to source as the new canonical value.

The hard guarantee is the most useful part: every edit Palette can ever propose passes through the literal patching pipeline by construction. The worst case for any single variant is a “weird color, pick another” decision rather than a broken app, a compile error, or a structural recovery cycle. Compare this to free-form code generation where a non trivial fraction of edits hit some failure path on every interaction.

Two operating modes ship at MVP:

Auto Mode

hotswan_explore_palette

For projects with a standard Material 3 theme file (lightColorScheme / darkColorScheme with named Color literals). The plugin auto detects the theme, generates 5 curated palettes, applies each through the literal patch path, captures a screenshot per variant, and opens the comparison grid. You pick one in the browser, the plugin rewrites the literals atomically through the IDE Document API.

Manual Mode

hotswan_show_palette_grid

For projects that don't fit auto detection (custom theme data class, KMP shared theme library, XML colorResource setups). The agent owns the iteration loop (edit → reload → screenshot → revert) and then calls this tool with N variant entries. Each entry carries its own find/replace edits so a click on a card live applies that variant on the device.

Five iteration axes shipped at MVP:

color

Material 3 dynamic color schemes seeded from the user's current primary, plus curated palette sets (Earthy / Vibrant / Monochrome / Pastel / High-Contrast).

spacing

Compact / regular / spacious scales applied multiplicatively, snapped to a 4dp grid.

radius

Sharp (0dp), rounded (8-16dp), pill (24-50dp). Literal swap of the radius dp argument.

typography

Compact / default / comfortable type scales with optional weight axis (Regular / Medium / SemiBold).

density

Composite macro: combines spacing × 0.75 + typography × 0.875 + tighter line height as a single click.

Recommended Workflow

The ideal tool calling sequence for exploring UI variants with the MCP Server:

// 1. Check status and start
hotswan_get_status()        -> emulator running, app installed
hotswan_start()             -> WATCHING
hotswan_start_snapshot()    -> capturing enabled (optional)

// 2. Explore variants (repeat for each)
Edit file (variant A)
hotswan_reload([...])       -> SUCCESS
hotswan_take_screenshot()   -> Snapshot #1

Edit file (variant B)
hotswan_reload([...])       -> SUCCESS
hotswan_take_screenshot()   -> Snapshot #2

Edit file (variant C)
hotswan_reload([...])       -> SUCCESS
hotswan_take_screenshot()   -> Snapshot #3

// 3. Select the best variant
hotswan_select_variant(snapshotId: 2, reason: "best balance")
hotswan_stop_snapshot()

The key principle is explicit capture: editing and reloading does not automatically take screenshots. The AI calls hotswan_take_screenshot only when the change is complete and ready for review. This prevents intermediate edits from cluttering the snapshot gallery.

To teach your AI assistant this workflow automatically, copy the MCP Agent Skill into your project's instruction file.

Effective Prompts

Well crafted prompts help the AI use MCP tools efficiently. Here are proven patterns for common scenarios.

Palette Auto Mode (Material 3)

“Use hotswan_explore_palette to generate 5 color variants for the home screen and open the comparison grid in my browser. The project has a standard Material 3 theme.”

One tool call. Plugin handles theme detection, variant generation, screenshot capture, and the browser grid. You pick visually.

Palette Manual Mode (Custom Theme)

“My theme uses a custom data class, not Material 3. For the details screen, generate 4 color variants yourself: (1) capture baseline, (2) for each variant edit the relevant Color() literals, hotswan_reload, screenshot, revert. Then call hotswan_show_palette_grid with the 4 entries (include the find/replace edits so I can click to apply).”

Use when hotswan_explore_palette returns 'no theme detected'. The find/replace edits in each entry power click-to-apply.

UI Variant Exploration

“Show me 3 different visual styles for the details screen background. For each variant: edit the source file, call hotswan_reload, then hotswan_take_screenshot. After all 3 are captured, I'll pick one.”

The AI edits, reloads, and captures for each style. You compare snapshots in the IDE.

Quick Tweak

“Change the card corner radius to 24dp and the shadow elevation to 8dp, then reload and take a screenshot so I can see it.”

Single edit, reload, screenshot. Fast iteration on specific values.

Color Theme Exploration

“Try 3 color palettes for this screen: warm sunset, cool ocean, dark moody. Edit the theme colors, reload each, and capture screenshots. Don't revert between variants.”

Batch variant exploration with explicit no-revert instruction.

Animation Tuning

“Experiment with the entry animation: try a fade-in with 300ms, a slide-up with spring physics, and a scale-in with overshoot. Reload and screenshot each.”

Great for tuning parameters that are hard to judge from code alone.

Build & Start from Scratch

“Build and install the app, then start hot reload. Once it's running, change the top bar color to a gradient and show me a screenshot.”

Full setup flow: build_and_install, start, edit, reload, screenshot.

Debug a Reload Failure

“The last reload failed. Check the logs and status to figure out what went wrong.”

Uses hotswan_get_logs and hotswan_get_status for diagnostics.

Layout Comparison

“Show me this list as: 1) vertical scroll, 2) grid with 2 columns, 3) staggered grid. Capture each layout as a snapshot.”

Structural layout changes may trigger full rebuild if the change is too large.

Revert & Iterate

“That last change didn't look good. Revert it and try a more subtle approach with just opacity changes instead.”

Uses hotswan_revert_change to roll back, then iterates with a new direction.