ComposeLint AI
Rebranded to ComposeLint AI. Repository has been moved to TechsOneAi/ComposeLintAI.
Use ComposeLintAI's MCP server to give AI agents phone-free inspection, governance, refactoring, and verification of Jetpack Compose design tokens and Kotlin source.
Discover and analyze design tokens: colors, dimensions, strings, token groups, siblings, naming conventions, orphans, hardcoded scatter, impact, conditional variants, and split suggestions.
Surgically edit source: set text, set token values, add new tokens, auto-migrate hardcoded strings, and replace recurring patterns with dry-run support.
Manage changes safely: list modified files, view unified diffs, approve/reject whole files, hunks, or all changes, and roll back last edits or applied patterns.
Verify builds: run whitelisted Gradle tasks asynchronously, poll job status, and list allowed Gradle tasks.
Sync and inspect state: trigger queued device edits, check sync status, and configure design file mappings for non-standard project layouts.
Diagnose code: fetch IDE diagnostics and scan Kotlin project diagnostics without running Gradle.
Maintain workspace hygiene: safely clean temporary cache, state files, and logs without touching source code or backups.
Enables live UI tuning and design token syncing on a running Android app, allowing AI agents to edit Compose UI properties and persist changes back to Kotlin source.
Provides tools for running Gradle builds and listing allowed Gradle tasks, enabling AI agents to build and validate Android/KMP projects after making UI changes.
Provides tools for interacting with Jetpack Compose UI, including token discovery, pattern refactoring, and live editing of composable properties with AST-guided source splicing.
ComposeLintAI 🌉
Enterprise AI Governance, Architecture Diagnostics & AST Refactoring Platform for Jetpack Compose + MCP Server.
Govern AI coding agent technical debt, enforce design systems, diagnose architectural health, and execute surgical source code modifications with zero-rebuild live device inspection.
📰 Featured In
📥 Direct Downloads (v1.1.9)
Package | Asset | Purpose |
IDE Plugin (Android Studio / IntelliJ) | 🚀 Install from JetBrains Marketplaceor 📦 ComposeLintAI-1.1.9.zip | Official Marketplace install (One-click) or manual install via |
Compose Runtime Library (Release & Debug) | Core registries (~9KB). Required in | |
Compose Agent Library (Debug Only) | Visual overlays, touch inspector, and WebSocket bridge. Put in |
Related MCP server: Vibgrate AI Context
📸 Visual Demo
Watch ComposeLintAI visually edit a running Jetpack Compose UI live:
📸 Visual Demos
⚡ Zero-Gradle AST Governance Demo | 📱 On-Device Live UI Tuning |
|
|
Screenshots
1. Studio ToolWindow & Token Scanner | 2. Surgical Pattern Refactoring & Diff | 3. Live On-Device Preview & Inspector |
|
|
|
🔄 Upgrading from v1.1.x to v1.1.9
Upgrading from ComposeLintAI v1.1.x to v1.1.9 is straightforward and involves zero breaking changes in your codebase or Gradle configurations:
Update the IDE Plugin: Install the latest
dist/ComposeLintAI-1.1.9.zipin Android Studio (Settings ➔ Plugins ➔ Install Plugin from Disk...) and restart the IDE.Update Android AAR: Replace
composebridge-agent-release.aarin your app module'slibs/folder with the updated build fromdist/composebridge-agent-release.aar, then re-sync Gradle.Update Python Server: If running standalone, re-run
pip install -r requirements.txt --upgradeinserver/.Breaking Changes: None. All protocol messages, runtime registries, and MCP tool signatures remain 100% backward-compatible.
⚡ Quick Start in 60 Seconds
Step 1: Install IDE Plugin
Download ComposeLintAI-1.1.9.zip.
In Android Studio, go to Settings (Preferences) ➔ Plugins ➔ Click the ⚙️ gear icon ➔ Install Plugin from Disk....
Select the zip file and restart Android Studio.
Step 2: Add Dependencies to your Android App
Copy composebridge-runtime-release.aar and composebridge-agent-release.aar into your app module's libs/ folder:
// app/build.gradle.kts
dependencies {
// 1. Runtime registries: compiles cleanly in both Debug & Release
implementation(files("libs/composebridge-runtime-release.aar"))
// 2. Interactive visual inspector: debug builds only
debugImplementation(files("libs/composebridge-agent-release.aar"))
}⚠️ Kotlin Multiplatform (KMP) Projects
If your project targets both Android and Desktop (KMP) and you use ComposeLintAI registries inside commonMain, DO NOT use the .aar files (as the desktop compiler cannot read Android .aar binaries). Instead, use the source modules as follows:
Copy the
agent/runtimefolder into your project (e.g.composebridge-agent/runtime).In
settings.gradle.kts(orsettings.gradle), include the runtime module:include(":composebridge-runtime") project(":composebridge-runtime").projectDir = file("composebridge-agent/runtime")In
composebridge-agent/build.gradle.kts, expose runtime as an API dependency:kotlin { sourceSets { commonMain.dependencies { api(project(":composebridge-runtime")) } } }In
composeApp/build.gradle.kts, implement the agent module incommonMain:kotlin { sourceSets { commonMain.dependencies { implementation(project(":composebridge-agent")) } } }
Step 3: Initialize in MainActivity (Debug)
// MainActivity.kt
import com.composebridge.agent.ComposeLintAIAgent
class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Start bridge connection (automatically connects to local hub)
ComposeLintAIAgent.start(context = this, serverUrl = "ws://127.0.0.1:8711")
setContent {
// Wrap root content in ComposeLintAIAgent.Root
ComposeLintAIAgent.Root {
MyApplicationTheme {
MainScreen()
}
}
}
}
}Step 4: Start the Bridge & Tune Live
In Android Studio, open the ComposeLintAI tool window on the right sidebar and click ▶ Start Bridge (this starts the local server and runs
adb reverse tcp:8711 tcp:8711automatically).Run your app on your device or emulator.
Tap the floating 🔧 FAB on screen to toggle Design Mode.
Tap any text, color, or dimension to adjust values in real-time!
🌐 Remote Connection (Experimental)
Tune your running Compose UI over the internet (cellular data, separate Wi-Fi networks, or remote testing) without a physical USB cable using Tailscale Funnel:
Prerequisites
Install Tailscale on your PC and mobile device.
Sign up for a Tailscale account (free for personal use).
Step-by-Step Setup:
Step 1: Configure Tailscale ACLs (Crucial!)
By default, Tailscale disables Funnel unless granted by your Access Control Lists (ACL). Before running the funnel command:
In the JSON policy editor, add the following
nodeAttrsblock inside the root{ ... }:"nodeAttrs": [ { "target": ["*"], "attr": ["funnel"] } ]Click Save.
This step is required to grant your devices permission to expose Funnel ports. Skipping this step will causetailscale funnel 8711 to fail with: funnel not allowed by ACLs.
Step 2: Start Tailscale Funnel on your Computer
Launch Tailscale on your PC and sign in.
Open a Terminal or PowerShell prompt and run:
tailscale funnel 8711(Or:
tailscale serve https / http://127.0.0.1:8711)Leave this terminal open (Tailscale Funnel must remain active).
Step 3: Get Connection Link in Android Studio / IntelliJ Plugin
Open the ComposeLintAI tool window on the right sidebar.
Click the "Share Remote" button.
A dialog will open displaying a QR Code and your secure connection URL (
wss://...).
Step 4: Connect on your Mobile Device
Launch your app (with ComposeLintAI Agent enabled).
Tap the floating Design Mode button 🎨 -> Connection Settings.
Select "Remote":
Tap "Scan QR" and scan the code directly from your computer screen, OR
Paste the URL via "Paste from Clipboard".
Tap "Connect Remote" to establish the live bridge.
Honest Notice: Remote connections are experimental. The session may disconnect due to network changes (switching between Wi-Fi and mobile data), restrictive corporate firewalls, carrier NATs, or phone battery-saver/sleep modes. For maximum stability and guaranteed sub-50ms latency, a physical USB connection (adb reverse tcp:8711 tcp:8711) remains the gold standard. For technical boundaries, see LIMITATIONS.md.
⚙️ How It Works (Under the Hood)
ComposeLintAI operates as a tri-part system coordinating an IDE extension, a surgical AST engine, and an on-device Compose observer:
Android Studio / IntelliJ Plugin: Manages background Python server processes, displays real-time connection status, generates Tailscale WireGuard QR codes for remote WAN tunnels, and provides visual tabs (
Changes,Tokens,Orphans,Patterns,Status) with unified diff review.Python Server & Tree-sitter AST Engine: Runs an asynchronous WebSocket hub on port
8711. When an edit arrives, Tree-sitter parses the Kotlin syntax tree and performs surgical code splicing without disturbing un-targeted code, formatting, or comments. Employs atomic file locks (_atomic_write_text) with CRLF line-ending preservation.Android Agent (
:composebridge-agent): Renders a zero-overhead hit-testing overlay viaComposeLintAIAgent.Root. Evaluates touch gestures, maps coordinates to semantic node bounds usingCompositionRegistry, and applies overrides locally (<50ms) throughBridgeThemeRegistry,BridgeDimensionRegistry, andBridgeTextRegistryso the UI responds instantaneously.PatternJournal & Rollback Engine: Before touching any source file, a pristine snapshot is verified with Tree-sitter and preserved as
.bridge.bak. Rollbacks prioritize Git tracking (git checkout -- <file>), safely falling back to byte-level.bridge.bakrestoration for untracked files.Model Context Protocol (MCP Server): Exposes 36 structured tools over stdio/JSON-RPC, enabling autonomous AI coding assistants (Antigravity, Cursor, Claude) to discover design tokens, detect orphans, suggest splits, and validate builds independently without requiring a physical phone connected.
📐 Architecture & Communication Flow
ComposeLintAI coordinates three interconnected components over a fast local loopback interface:
+--------------------------+ +----------------------------+
| Android Phone / AVD | | Local WebSocket Hub |
| | | (Python 3.10+ Daemon) |
| [App UI in Compose] | | |
| | | WebSocket | server.py (:8711) |
| [:composebridge-agent] |<===============>| ├── Message Router |
| - Visual Touch Overlay| (Port 8711) | ├── AST Splicer |
| - Semantic Inspector | | └── PatternJournal |
| | | +----------------------------+
| [:composebridge-runtime]| ||
| - TextRegistry | || JSON-RPC
| - ThemeRegistry | || (stdio / TCP)
| - DimensionRegistry | \/
+--------------------------+ +----------------------------+
| Developer Tools & AI |
| |
| [Android Studio Plugin] |
| - Live Changes Diff |
| - Token Split / Scanner |
| [Autonomous MCP Agents] |
| - Antigravity / Claude |
| - 36 Standard MCP Tools |
+----------------------------+On-Device Agent (
:composebridge-agent): Injected viaComposeLintAIAgent.Root. Renders non-intrusive hit-testing overlays, extracts semantic metadata, and transmits change requests over local WebSocket (ws://127.0.0.1:8711).Decoupled Runtime (
:composebridge-runtime): Standalone ~9KB runtime containing registry singletons (BridgeTextRegistry,BridgeThemeRegistry,BridgeDimensionRegistry). Ensures production Release builds compile with zero overhead without packaging debug overlays.Local Bridge Server (
server.py): Acts as the central event hub and Kotlin AST manipulation engine. Applies deterministic changes using file write-locks, atomic rewrites, and maintains a byte-level.bridge.bakrollback journal.Model Context Protocol (MCP Server): Exposes 36 structured tools allowing AI pair programmers (Antigravity, Claude, Cursor) to autonomously analyze token usage, suggest token splits, and execute multi-file refactorings.
🚀 Core Capabilities
Capability | Description |
⚡ Instant Live Tuning | Tweak colors, paddings, and string contents with sub-50ms latency. Changes update dynamically without waiting for Gradle rebuilds. |
🧠 Semantic Token Intelligence | Detects whether a modified color or dimension is shared globally. Offers Split (create an isolated token for this widget) or Global (update theme-wide). |
📝 Text Editing & Auto-Migration | Tap any text element to edit wording directly on device. The AST engine automatically wraps raw strings into |
💾 Safe Rollbacks (PatternJournal) | Every surgical edit is backed up byte-for-byte. The Studio Changes tab allows reviewing unified diffs and reverting individual files or all edits with one click. |
🤖 Full MCP Server for AI Agents | 36 tools supporting token discovery, impact analysis, orphan detection, surgical pattern replacement, and safe Gradle compilation validation. |
🤖 AI Agent Integration (MCP)
ComposeLintAI exposes 36 deep-inspection and code refactoring tools to any AI assistant supporting the Model Context Protocol (MCP). No physical phone is required to use MCP tools.
💡 Ultra-Lightweight Context Window: ComposeLintAI uses Lazy Loading, so 36 MCP tools consume only ~176 tokens (<1% of context window).
Compatible AI Clients:
✅ Google Antigravity IDE
✅ Cursor
✅ Claude Desktop
✅ Windsurf / Continue
Integration Steps:
Step 1: Run the MCP Server
Make sure server dependencies are installed and the server is executable from your server directory:
cd server
pip install -r requirements.txtStep 2: Configure mcp_config.json
Add the ComposeLintAI server configuration to your AI agent's config file (e.g. in ~/.gemini/config/mcp_config.json or your IDE configuration):
{
"mcpServers": {
"composebridge": {
"command": "python",
"args": ["-u", "/path/to/compose-bridge/server/mcp_server.py"],
"env": {
"COMPOSEBRIDGE_ROOT": "/absolute/path/to/your/android/project",
"PYTHONIOENCODING": "utf-8"
}
}
}
}⚠️ Important: Any changes made to
mcp_config.jsonrequire starting a New Chat in your AI agent interface so that all 36 MCP tools are freshly discovered and initialized.
How to set it up in Android Studio / Antigravity:
Open Android Studio / IntelliJ IDEA.
Go to Settings (or Preferences on macOS) ➔ Tools ➔ AI ➔ MCP Servers.
Click on the Installed tab.
Click on the "Import JSON file" button (or "...Add via JSON" depending on your IDE version).
Paste the JSON configuration provided above.
Click OK or Apply.
⚠️ Crucial: Start a New Chat (or restart the agent) for the new 36 MCP tools to load and become visible.
Overview of MCP Tools (36 Tools):
Token Discovery & Analysis:
list_tokens,find_token_by_color,get_token_impact,get_token_siblings,get_all_token_groups,list_orphans,get_naming_convention.Surgical Code Editing:
set_token,set_text,add_token,rollback_last.Pattern Refactoring:
replace_pattern,list_applied_patterns,rollback_pattern,suggest_token_split,detect_conditional_variants.Change Management:
list_modified_files,get_file_diff,approve_file_changes,reject_file_changes,approve_all_files,reject_all_files,reject_all_files_force.Build Verification & Sync:
run_gradle_build,list_allowed_gradle_tasks,trigger_user_sync,get_sync_status.
⚠️ Honest Limitations & Operational Boundaries
📖 Full Technical Disclosure: For an exhaustive, unvarnished disclosure of operational edge cases and architectural constraints, see LIMITATIONS.md.
⚠️ Key Notice: Remote Connection is experimental. The tool will safely pause (
NEEDS_MANUAL_MAPPING) and refuse to modify code if it cannot find design files (Colors, Dimensions, Strings) until you map them in the Discovery tab, protecting your project from accidental code pollution.
Remote Tunnel Stability: Remote access via Tailscale is experimental. Mobile cellular handoffs or network firewalls can interrupt socket connectivity. USB tethering (
127.0.0.1) remains recommended for mission-critical zero-latency editing.Design System Mapping Required: If the tool cannot locate your design system files automatically, it safely stops and asks for configuration in the Discovery tab rather than writing to arbitrary files.
Live Preview Connection: Edits applied when the device is disconnected are saved safely to disk, but the mobile screen requires an active connection to recompose.
AI Agent Review: Always review AI refactorings in the IDE Changes tab before approving.
Concurrent External Edits: Editing the same line in your IDE while an unapproved bridge edit is pending will trigger an external conflict warning dialog.
Rate Limiting: High-frequency continuous slider movements are rate-limited (100 msgs/10s) to prevent thread congestion over slow Wi-Fi.
General Platform Constraints
Platform Target: Live on-device inspection currently supports Android (API 24+). Kotlin Multiplatform Desktop and iOS overlays are in active development.
Python Requirement: The local bridge server requires Python 3.10 or newer.
USB Port Forwarding: When testing on a physical device over USB, port forwarding is required (
adb reverse tcp:8711 tcp:8711). The Studio plugin runs this automatically on startup.Initial Rebuild on New Tokens: When converting a hardcoded literal to an entirely new named token for the first time, one standard Gradle compile is required so the Kotlin compiler emits the new getter bytecode. Subsequent live tweaks to that token are instantaneous.
🔧 Troubleshooting & FAQ
1. The phone shows [WS] Connection failed
Ensure the bridge server is running (
🟢 Bridge Runningin Studio orpython server.pyin terminal).If using USB, verify ADB reverse is active by running:
adb reverse tcp:8711 tcp:8711If using Wi-Fi without USB, specify your workstation's LAN IP when calling
ComposeLintAIAgent.start(serverUrl = "ws://192.168.1.X:8711").
2. Build error: Duplicate class found in modules
Make sure
composebridge-runtime-release.aaris added underimplementation(...)andcomposebridge-agent-release.aaris added underdebugImplementation(...). Do not include the agent in release configurations.
3. Edits do not show in Android Studio
Ensure you have the project root properly set in
composebridge.jsonor pass--project <path>when launchingserver.py.Check the Changes tab in the ComposeLintAI tool window to review pending file diffs.
🤝 Contributing & Community
We welcome contributions! Please review our:
Contributing Guidelines: Development setup, coding standards, and PR process.
Security Policy: Supported versions and vulnerability disclosure guidelines.
Architectural Vision (RFC-001): Technical roadmap and core invariants.
📄 License
Distributed under the Apache License 2.0.
🌐 Remote Access via Tailscale (WireGuard Secure Tunnel)
ComposeLintAI v1.1.6 introduces zero-configuration remote access using Tailscale Funnel. You can now inspect, tweak, and live-preview Compose UI on physical Android devices over cellular data or remote Wi-Fi networks securely.
1. Prerequisites
Install Tailscale on your workstation: https://tailscale.com/download
Log in and enable Tailscale:
tailscale upEnsure Tailscale Funnel is enabled for your tailnet node.
2. Share Remote from Android Studio
Open the ComposeLintAI tool window in Android Studio.
Click ▶ Start Bridge to launch the local WebSocket hub with dynamic 64-character token authentication.
Click 🌐 Share Remote in the toolbar:
The plugin initiates
tailscale funnel 8711 --bg.A QR Code modal appears with your secure
wss://<node>.<tailnet>.ts.netendpoint and session auth token.
(Optional) You can copy the URL or Token, or click Stop Sharing to turn off the funnel.
3. Connect from Android Device
Open your debug app with
ComposeLintAIAgent.Tap the floating 🎨 design button to open the toolbar, then tap the 🌐 remote button.
Tap 📷 Scan QR (or paste connection JSON from clipboard).
The agent immediately connects securely via TLS/WSS (
wss://...), validates credentials, and begins live streaming UI edits.To return to USB/local development, tap Local (127.0.0.1) in the remote dialog.
Available Tools
36 toolsadd_tokenCDestructive
Convert a hardcoded value to a design token.
Inputs: file (required), line (required), value (required), token_name (required), +3 more. Returns: result
analyze_design_scatterARead-onlyIdempotent
Analyzes scattered hardcoded design tokens (colors, dimensions, strings) across the project.
Returns a compact, categorized report to avoid context window exhaustion.
When to use:
- Call during project onboarding, architecture audits, or before major UI refactorings.
- Call to locate hardcoded color literals, raw Dp values, and string literals across Jetpack Compose files.
When NOT to use:
- Do not use if you already know the exact token name or file (use find_token_by_color or list_tokens instead).
- Do not use for applying code changes directly (use set_token, add_token, or set_text instead).
Side effects:
- None (strictly read-only AST inspection, does not modify any source code or configuration).
Args:
category: 'all', 'colors', 'dimensions', or 'strings'.
limit: Maximum number of files to return per category (default: 10).
project_root: Optional path to project root.
Inputs: limit, category, project_root. Returns: result
approve_all_filesADestructiveIdempotent
Destructive: Approves ALL pending changes permanently. Removes them from journal.
What it does: Permanently accepts all pending changes in the journal across all modified files.
When to use: When all modifications from recent operations are verified and accepted.
When NOT to use: No rollback after this action. Use approve_file_changes for single files. Use reject_all_files to discard instead.
Side effects: Destructive: Permanently clears all backups and journal entries. Changes cannot be rolled back.
Parameters: None.
Returns:
JSON string confirming all files approved.
Inputs: no named parameters. Returns: result
approve_changeADestructiveIdempotent
Approves a single granular change (hunk) in a file.
What it does: Incorporates the specific change into the file's baseline backup, leaving other changes pending.
When to use: When one specific change in a file is approved, but other changes need further inspection or rejection.
Parameters:
- file_path: relative path to project root
- change_id: hunk ID (e.g. "h1", "h2") or line number
Returns:
JSON string with operation result and remaining changes.
Inputs: change_id (required), file_path (required). Returns: result
approve_file_changesADestructiveIdempotent
Approves pending changes for a SPECIFIC file. Removes its entry from journal.
What it does: Marks changes as accepted and discards the backup so the file is no longer in pending state.
When to use: When changes to a specific file have been inspected (via get_file_diff) and verified correct.
When NOT to use: File must be modified. To approve all files use approve_all_files.
Side effects: Clears the journal entry and backup for this file. Modifications remain permanently on disk.
Parameters:
- file_path: relative to project root (e.g., 'QuickActionsWidget.kt' or 'ui/theme/AppStrings.kt').
Returns:
JSON string confirming file approval.
Inputs: file_path (required). Returns: result
clean_cacheADestructiveIdempotent
Safely cleans temporary cache, state files, and logs (.composebridge-state, .composebridge-journal.json, *.tmp)
without touching source code or .bridge.bak backups.
Inputs: no named parameters. Returns: result
detect_conditional_variantsCRead-onlyIdempotent
Detect repeated conditional patterns.
Inputs: token_name. Returns: result
find_token_by_colorARead-onlyIdempotent
Reverse lookup: Find token(s) matching an exact hex color.
Inputs: hex_color (required). Returns: result
get_all_token_groupsARead-onlyIdempotent
Read-only. Returns ALL semantic token groups in the project.
Inputs: no named parameters. Returns: result
get_design_file_mappingsARead-onlyIdempotent
Returns current design/registry file mappings configured in .composebridge/config.json.
When to use:
- Call before modifying design tokens to inspect which files are mapped for colors, dimensions, and strings.
- Call to verify current target files when debugging token resolution issues.
When NOT to use:
- Do not use to configure or modify file mappings (use set_design_file_mapping instead).
- Do not use to list token names and values (use list_tokens instead).
Side effects:
- None (strictly read-only configuration lookup, does not modify any files).
Args:
project_root: Optional path to project root.
Inputs: project_root. Returns: result
get_file_diffARead-onlyIdempotent
Read-only. Returns before/after content and unified diff for a specific modified file.
What it does: Computes unified diff comparing original backup (.bridge.bak) with current on-disk content.
When to use: To inspect exact changes before approving (approve_file_changes) or rejecting (reject_file_changes).
When NOT to use: Use list_modified_files first to get valid paths. file_path should match the entry from list_modified_files (relative to project root).
Side effects: Read-only. No files modified.
Parameters:
- file_path: relative path to project root (e.g., 'QuickActionsWidget.kt' or 'ui/theme/AppStrings.kt').
Returns:
JSON string with original content, modified content, and unified diff.
Inputs: file_path (required). Returns: result
get_gradle_statusARead-onlyIdempotent
Check the status and result of a Gradle build job.
When to use:
- Call to poll background Gradle build status returned by run_gradle_build.
When NOT to use:
- Do not use if no Gradle job was started.
Side effects:
- None (strictly read-only job status query).
Args:
job_id: ID returned by run_gradle_build.
Returns:
JSON with {job_id, status: 'queued'|'running'|'completed'|'failed', result: {...}}.
Inputs: job_id (required). Returns: result
get_ide_diagnosticsARead-onlyIdempotent
Fetches real-time compilation, unresolved reference, and syntax errors directly from Android Studio / IntelliJ IDE without running Gradle.
Inputs: file_path, timeout_seconds, include_warnings. Returns: result
get_naming_conventionBRead-onlyIdempotent
Read-only analysis. Detects if project uses camelCase, snake_case, or PascalCase for tokens.
Inputs: token_type. Returns: result
get_sync_statusARead-onlyIdempotent
Get the current sync status from the Bridge Server.
When to use:
- Call to inspect agent_busy, queue_count, and snapshot_version before running batch operations.
When NOT to use:
- Do not use to apply changes (use trigger_user_sync instead).
Side effects:
- None (strictly read-only state inspection).
Inputs: no named parameters. Returns: result
get_token_impactCRead-onlyIdempotent
Get impact analysis for a specific token.
Inputs: token_name (required), project_path. Returns: result
get_token_siblingsCRead-onlyIdempotent
Read-only. Returns semantically related tokens.
Inputs: token_name (required). Returns: result
list_allowed_gradle_tasksARead-onlyIdempotent
List gradle tasks that can be run via run_gradle_build.
When to use:
- Call to check which Gradle tasks are whitelisted for safe execution.
When NOT to use:
- Do not use to run builds (use run_gradle_build instead).
Side effects:
- None (strictly read-only whitelist listing).
Inputs: no named parameters. Returns: result
list_applied_patternsARead-onlyIdempotent
List all applied patterns that can be rolled back.
When to use:
- Call to inspect history of pattern refactorings before deciding to roll back.
- Call to retrieve valid pattern_ids for rollback_pattern.
When NOT to use:
- Do not use to revert changes (use rollback_pattern instead).
Side effects:
- None (strictly read-only journal lookup).
Inputs: no named parameters. Returns: result
list_modified_filesARead-onlyIdempotent
Read-only. Lists files modified by recent replace_pattern operations in the current session.
What it does: Queries the session journal to return all files currently in a modified state.
When to use: To see what files have unapproved changes before approving or rejecting.
When NOT to use: Does NOT persist across sessions. For git-based modifications use get_file_diff. Returns files in journal (not git status).
Side effects: Read-only. No files modified.
Parameters: None.
Returns:
JSON string with list of relative file paths.
Inputs: no named parameters. Returns: result
list_orphansBRead-onlyIdempotent
List all orphan tokens (registered but never used).
Inputs: project_path. Returns: result
list_tokensBRead-onlyIdempotent
List all design tokens in the project.
Inputs: project_path. Returns: result
reject_all_filesADestructive
Destructive: Reverts ALL pending changes using byte-level backup (.bridge.bak).
What it does: Rolls back byte-for-byte all files modified in the current journal session.
When to use: To completely discard all recent changes and return every file to its exact prior state.
When NOT to use: Use reject_file_changes for a single file. Use reject_all_files_force if some rollbacks may fail.
Side effects: Destructive rollback. Overwrites all modified files with their .bridge.bak backups and clears journal.
Parameters: None.
Returns:
JSON string with list of reverted files and status.
Inputs: no named parameters. Returns: result
reject_all_files_forceADestructive
Destructive + Forceful. Clears the entire journal EVEN IF some rollbacks fail.
What it does: Forcefully attempts rollback and clears the journal unconditionally.
When to use: Use only when reject_all_files fails due to missing backups or file corruption.
When NOT to use: May leave files in inconsistent state. For safe rollback use reject_all_files.
Side effects: Destructive + Forceful: Clears all journal tracking regardless of whether every file reverted cleanly.
Parameters: None.
Returns:
JSON string with forced rollback results.
Inputs: no named parameters. Returns: result
reject_changeADestructive
Reverts a single granular change (hunk) in a file while keeping other changes intact.
What it does: Reverts only the specified hunk back to its original baseline on disk.
When to use: When one specific change in a file is unwanted, but other changes in the file should be kept.
Parameters:
- file_path: relative path to project root
- change_id: hunk ID (e.g. "h1", "h2") or line number
Returns:
JSON string with operation result and remaining changes.
Inputs: change_id (required), file_path (required). Returns: result
reject_file_changesADestructive
Destructive: Reverts pending changes for a SINGLE file using .bridge.bak backup.
What it does: Rolls back byte-for-byte to the state before the recent surgical edit or replace_pattern.
When to use: When modifications to a specific file are incorrect and need to be discarded.
When NOT to use: File must be currently modified. Use reject_all_files for all files.
Side effects: Destructive rollback. Overwrites file with original backup and removes entry from journal.
Parameters:
- file_path: relative path to project root (e.g., 'QuickActionsWidget.kt' or 'ui/theme/AppStrings.kt').
Returns:
JSON string confirming rollback of the file.
Inputs: file_path (required), force. Returns: result
replace_patternADestructive
DESTRUCTIVE BATCH OPERATION: Replaces ALL occurrences of a pattern across the project.
What it does: Creates new token + replaces usages. Can be rolled back via rollback_pattern(pattern_id).
When to use: When replacing a recurring conditional or hardcoded pattern across all files.
When NOT to use: USE dry_run=True FIRST to preview affected files. pattern_id must come from detect_conditional_variants.
Side effects: DESTRUCTIVE: Modifies multiple .kt files simultaneously. Records changes in journal.
Parameters:
- pattern_id: Unique pattern identifier from detect_conditional_variants.
- dry_run: If True (recommended first), previews changes without writing to disk.
Returns:
JSON string with replacements made, modified files, and created token name.
Inputs: pattern_id (required), dry_run. Returns: result
rollback_lastADestructive
Reverts the LAST surgical edit made in the current session.
Inputs: no named parameters. Returns: result
rollback_patternADestructive
Rolls back ALL changes made by a specific replace_pattern call.
When to use:
- Call when a pattern replacement resulted in unexpected UI behavior or compilation issues.
- Call to safely undo all file changes associated with a pattern_id.
When NOT to use:
- Do not use to revert single token edits (use rollback_last or reject_change instead).
- Do not use without a valid pattern_id from list_applied_patterns.
Side effects:
- DESTRUCTIVE: Modifies source files on disk to restore their pre-replacement states.
What it does: Requires pattern_id from the original replace_pattern response. All files are reverted byte-for-byte.
When to use: When a replace_pattern operation caused regressions and needs complete reversal.
When NOT to use: Cannot undo if files were modified externally. Use rollback_last for single-edit undo.
Side effects: Destructive rollback. Modifies all files touched by the pattern back to their prior state.
Parameters:
- pattern_id: The exact pattern_id from the original replace_pattern response.
Returns:
JSON string with list of reverted files and status.
Inputs: pattern_id (required). Returns: result
run_gradle_buildA
Run a Gradle task with async tracking support.
When to use:
- Call to verify that surgical edits or token refactorings compile without errors.
- Call after batch changes before approving or completing a task.
When NOT to use:
- Do not use for arbitrary shell execution; tasks are strictly whitelist-restricted.
- Do not use for simple file reading or AST validation (use check_syntax_cli or ast_finder instead).
Side effects:
- Executes a Gradle build process in background; may write build artifacts to build/ directories.
This lets the agent verify that code changes compile successfully
before continuing with more changes, without locking the MCP connection.
Args:
task: gradle task to run (whitelist enforced: assembleDebug, assembleRelease, test, lint, clean, etc.).
timeout_seconds: max execution time (default 5 min).
async_mode: if true (default), returns job_id immediately so agent can poll with get_gradle_status.
Returns:
JSON with job_id and status, or execution result if sync.
Inputs: task, async_mode, timeout_seconds. Returns: result
scan_project_diagnosticsBRead-onlyIdempotent
Sequentially scans all Kotlin files in the project workspace to collect compilation errors and technical debt warnings without running Gradle.
Inputs: max_files, timeout_seconds, include_warnings. Returns: result
set_design_file_mappingADestructiveIdempotent
Sets a designated design/registry file in .composebridge/config.json for a token type.
When to use:
- Call when ComposeBridge stops with NEEDS_MANUAL_MAPPING because design system files are in non-standard paths.
- Call to lock designated target files for colors, dimensions, or strings.
When NOT to use:
- Do not use if the project uses standard design file locations (e.g., Color.kt, AppStrings.kt).
- Do not use for reading existing token mappings (use get_design_file_mappings instead).
Side effects:
- Modifies .composebridge/config.json on disk to persist file mappings.
Args:
token_type: 'color', 'dimension', 'string', or 'all'.
file_path: Relative path to the Kotlin file (e.g. 'composeApp/src/commonMain/kotlin/.../Color.kt').
project_root: Optional path to project root.
Inputs: file_path (required), token_type (required), project_root. Returns: result
set_textADestructive
DESTRUCTIVE: Modifies .kt files. Surgically edit text content with automatic BridgeTextRegistry wrapping.
What it does: Modifies .kt files. Auto-migrates hardcoded text to BridgeTextRegistry for live preview.
When to use: When editing UI text strings, whether defined in AppStrings or hardcoded in Composable Text("...") elements.
When NOT to use: Do not use for colors or dimensions (use set_token or add_token).
Side effects: DESTRUCTIVE: Modifies source code on disk. Requires approve_file_changes before changes take effect in git. Can be reverted via reject_file_changes.
Parameters:
- token_name: reference key (e.g., 'AppStrings.Dashboard.title') OR exact old text content to replace.
- new_value: The new text string to set.
- file_path: relative path to source file (e.g., 'QuickActionsWidget.kt' or 'ui/theme/AppStrings.kt').
- line: optional line number for disambiguation if text appears multiple times.
Returns:
JSON string with success status, old_text, new_text, and modified file location.
Inputs: new_value (required), token_name (required), line, file_path. Returns: result
set_tokenCDestructive
DESTRUCTIVE: Modifies .kt files. Surgically edit a design token value in source code.
Inputs: value (required), token_name (required). Returns: result
suggest_token_splitCRead-onlyIdempotent
Read-only analysis. Suggests splitting tokens used in multiple contexts.
Inputs: token_name, project_path. Returns: result
trigger_user_syncADestructive
Trigger user_sync on the Bridge Server.
When to use:
- Call to flush and apply pending queued edits (dimensions and colors) from the Android device to source files.
When NOT to use:
- Do not use if the AI agent is actively modifying source files (agent_busy lock).
Side effects:
- Modifies source files on disk by applying pending changes from the queue.
Applies all queued edits (dimension + color) to the files.
Only works when the AI agent is not busy.
Returns:
JSON with {success, applied, skipped, errors}.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 36 tools
Most analysis tools (list_orphans, get_token_impact, detect_conditional_variants, get_token_siblings) are clearly distinct, and the descriptions include explicit 'when NOT to use' cross-references. However, the undo/approval surface is crowded and genuinely confusable: approve_change/reject_change (hunk-level), approve_file_changes/reject_file_changes (file-level), approve_all_files/reject_all_files/reject_all_files_force (project-level), plus rollback_last and rollback_pattern. Similarly get_ide_diagnostics, scan_project_diagnostics and run_gradle_build all answer 'does this compile?' with no crisp default.
Names are uniformly snake_case with a leading verb (get_, list_, set_, add_, detect_, suggest_, replace_, approve_, reject_, rollback_), which is predictable and readable. Minor deviations exist: rollback_last has no noun object, and the verb choice between get_/list_/find_ isn't systematically applied, but nothing is chaotic.
36 tools is heavy for a design-token lint/refactor server and the count is inflated by parallel families: three rollback variants, four approval variants, three diagnostics/build tools, three sync/config tools. Several could collapse (e.g. scope parameter on approve/reject instead of six tools).
The lifecycle is broadly covered: discover (list_tokens, list_orphans, find_token_by_color, analyze_design_scatter), mutate (add_token, set_token, set_text), batch apply, undo/approve, build verification, and server sync. Notable gaps: no delete/remove_token and no rename_token, both core to a refactoring tool, leaving dead tokens orphaned once added.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Deterministic memory & code intelligence MCP for 15 IDEs (100% LongMemEval in 12.9ms, 0 LLM tokens).
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceLocal-first code intelligence and safety layer for AI coding agents. MCP server exposes dependency graph, impact analysis, and AST-compressed repo context, backed by typed local memory, patch-scope safety gates, and git-independent transaction rollback.1MIT

Vibgrate AI Contextofficial
AlicenseNot gradedqualityBmaintenanceLocal-first MCP server that gives AI assistants codebase intelligence—code graph, drift analysis, vulnerability attribution, and version-correct library docs—all from the user's machine.1,121 npm6Apache 2.0- FlicenseNot gradedqualityAmaintenanceMCP server that provides AI coding agents real Android development tools—Gradle, adb, logcat, lint, crash triage—through a local, permissioned interface. Enables agents to inspect projects, run safe Gradle tasks, capture logs/screenshots, and triage crashes.1-
- FlicenseNot gradedqualityBmaintenanceA local-first MCP server that gives AI coding agents durable project memory, dependency graphs, and impact analysis to answer team knowledge and cross-file change questions before editing.9 npm1-




