Documentation

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 13 tools organized into four 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.

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.

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.

Effective Prompts

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

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.