Skip to main content
Glama
This server has been deprecated

Rebranded to ComposeLint AI. Repository has been moved to TechsOneAi/ComposeLintAI.

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.

Kotlin Jetpack Compose Status DevEx Latency Version License JetBrains Marketplace Glama MCP M8ven Score compose-bridge on DevHunt Listed on MCP Market

English | العربية


📥 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 Settings ➔ Plugins ➔ ⚙️ ➔ Install Plugin from Disk...

Compose Runtime Library (Release & Debug)

📦 composebridge-runtime-release.aar

Core registries (~9KB). Required in implementation for production-safe APK builds

Compose Agent Library (Debug Only)

📦 composebridge-agent-release.aar

Visual overlays, touch inspector, and WebSocket bridge. Put in debugImplementation


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

Zero-Gradle AST Governance

Live On-Device Demo

Screenshots

1. Studio ToolWindow & Token Scanner

2. Surgical Pattern Refactoring & Diff

3. Live On-Device Preview & Inspector

Studio ToolWindow

Pattern Refactoring

Live Device Sync


🔄 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:

  1. Update the IDE Plugin: Install the latest dist/ComposeLintAI-1.1.9.zip in Android Studio (Settings ➔ Plugins ➔ Install Plugin from Disk...) and restart the IDE.

  2. Update Android AAR: Replace composebridge-agent-release.aar in your app module's libs/ folder with the updated build from dist/composebridge-agent-release.aar, then re-sync Gradle.

  3. Update Python Server: If running standalone, re-run pip install -r requirements.txt --upgrade in server/.

  4. 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

  1. Download ComposeLintAI-1.1.9.zip.

  2. In Android Studio, go to Settings (Preferences) ➔ Plugins ➔ Click the ⚙️ gear icon ➔ Install Plugin from Disk....

  3. 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:

  1. Copy the agent/runtime folder into your project (e.g. composebridge-agent/runtime).

  2. In settings.gradle.kts (or settings.gradle), include the runtime module:

    include(":composebridge-runtime")
    project(":composebridge-runtime").projectDir = file("composebridge-agent/runtime")
  3. In composebridge-agent/build.gradle.kts, expose runtime as an API dependency:

    kotlin {
        sourceSets {
            commonMain.dependencies {
                api(project(":composebridge-runtime"))
            }
        }
    }
  4. In composeApp/build.gradle.kts, implement the agent module in commonMain:

    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

  1. 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:8711 automatically).

  2. Run your app on your device or emulator.

  3. Tap the floating 🔧 FAB on screen to toggle Design Mode.

  4. 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:

  1. Open the Tailscale Admin Console - Access Controls.

  2. In the JSON policy editor, add the following nodeAttrs block inside the root { ... }:

    "nodeAttrs": [
      {
        "target": ["*"],
        "attr": ["funnel"]
      }
    ]
  3. Click Save.

IMPORTANT

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
  1. Launch Tailscale on your PC and sign in.

  2. Open a Terminal or PowerShell prompt and run:

    tailscale funnel 8711

    (Or: tailscale serve https / http://127.0.0.1:8711)

  3. Leave this terminal open (Tailscale Funnel must remain active).

  1. Open the ComposeLintAI tool window on the right sidebar.

  2. Click the "Share Remote" button.

  3. A dialog will open displaying a QR Code and your secure connection URL (wss://...).

Step 4: Connect on your Mobile Device
  1. Launch your app (with ComposeLintAI Agent enabled).

  2. Tap the floating Design Mode button 🎨 -> Connection Settings.

  3. Select "Remote":

    • Tap "Scan QR" and scan the code directly from your computer screen, OR

    • Paste the URL via "Paste from Clipboard".

  4. Tap "Connect Remote" to establish the live bridge.

WARNING

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 via ComposeLintAIAgent.Root. Evaluates touch gestures, maps coordinates to semantic node bounds using CompositionRegistry, and applies overrides locally (<50ms) through BridgeThemeRegistry, BridgeDimensionRegistry, and BridgeTextRegistry so 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.bak restoration 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 |
                                              +----------------------------+
  1. On-Device Agent (:composebridge-agent): Injected via ComposeLintAIAgent.Root. Renders non-intrusive hit-testing overlays, extracts semantic metadata, and transmits change requests over local WebSocket (ws://127.0.0.1:8711).

  2. 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.

  3. 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.bak rollback journal.

  4. 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 BridgeTextRegistry on first edit.

💾 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.txt

Step 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.json require 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:

  1. Open Android Studio / IntelliJ IDEA.

  2. Go to Settings (or Preferences on macOS) ➔ Tools ➔ AI ➔ MCP Servers.

  3. Click on the Installed tab.

  4. Click on the "Import JSON file" button (or "...Add via JSON" depending on your IDE version).

  5. Paste the JSON configuration provided above.

  6. Click OK or Apply.

  7. ⚠️ 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 Running in Studio or python server.py in terminal).

  • If using USB, verify ADB reverse is active by running:

    adb reverse tcp:8711 tcp:8711
  • If 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.aar is added under implementation(...) and composebridge-agent-release.aar is added under debugImplementation(...). 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.json or pass --project <path> when launching server.py.

  • Check the Changes tab in the ComposeLintAI tool window to review pending file diffs.


🤝 Contributing & Community

We welcome contributions! Please review our:


📄 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

2. Share Remote from Android Studio

  1. Open the ComposeLintAI tool window in Android Studio.

  2. Click ▶ Start Bridge to launch the local WebSocket hub with dynamic 64-character token authentication.

  3. 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.net endpoint and session auth token.

  4. (Optional) You can copy the URL or Token, or click Stop Sharing to turn off the funnel.

3. Connect from Android Device

  1. Open your debug app with ComposeLintAIAgent.

  2. Tap the floating 🎨 design button to open the toolbar, then tap the 🌐 remote button.

  3. Tap 📷 Scan QR (or paste connection JSON from clipboard).

  4. The agent immediately connects securely via TLS/WSS (wss://...), validates credentials, and begins live streaming UI edits.

  5. To return to USB/local development, tap Local (127.0.0.1) in the remote dialog.

Available Tools

36 tools
add_tokenC
Destructive

Convert a hardcoded value to a design token.

Inputs: file (required), line (required), value (required), token_name (required), +3 more. Returns: result

analyze_design_scatterA
Read-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_filesA
DestructiveIdempotent
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_changeA
DestructiveIdempotent
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_changesA
DestructiveIdempotent
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_cacheA
DestructiveIdempotent
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_variantsC
Read-onlyIdempotent

Detect repeated conditional patterns.

Inputs: token_name. Returns: result

find_token_by_colorA
Read-onlyIdempotent

Reverse lookup: Find token(s) matching an exact hex color.

Inputs: hex_color (required). Returns: result

get_all_token_groupsA
Read-onlyIdempotent

Read-only. Returns ALL semantic token groups in the project.

Inputs: no named parameters. Returns: result

get_design_file_mappingsA
Read-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_diffA
Read-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_statusA
Read-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_diagnosticsA
Read-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_conventionB
Read-onlyIdempotent

Read-only analysis. Detects if project uses camelCase, snake_case, or PascalCase for tokens.

Inputs: token_type. Returns: result

get_sync_statusA
Read-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_impactC
Read-onlyIdempotent

Get impact analysis for a specific token.

Inputs: token_name (required), project_path. Returns: result

get_token_siblingsC
Read-onlyIdempotent

Read-only. Returns semantically related tokens.

Inputs: token_name (required). Returns: result

list_allowed_gradle_tasksA
Read-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_patternsA
Read-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_filesA
Read-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_orphansB
Read-onlyIdempotent

List all orphan tokens (registered but never used).

Inputs: project_path. Returns: result

list_tokensB
Read-onlyIdempotent

List all design tokens in the project.

Inputs: project_path. Returns: result

reject_all_filesA
Destructive
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_forceA
Destructive
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_changeA
Destructive
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_changesA
Destructive
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_patternA
Destructive
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_lastA
Destructive

Reverts the LAST surgical edit made in the current session.

Inputs: no named parameters. Returns: result

rollback_patternA
Destructive
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_diagnosticsB
Read-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_mappingA
DestructiveIdempotent
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_textA
Destructive
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_tokenC
Destructive

DESTRUCTIVE: Modifies .kt files. Surgically edit a design token value in source code.

Inputs: value (required), token_name (required). Returns: result

suggest_token_splitC
Read-onlyIdempotent

Read-only analysis. Suggests splitting tokens used in multiple contexts.

Inputs: token_name, project_path. Returns: result

trigger_user_syncA
Destructive
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

    B3.2/5.0

    Scored across 36 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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).

    Completeness3/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Local-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.
      1
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      MCP 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
      -