# Android Builder MCP Server

An advanced Model Context Protocol (MCP) server that empowers AI coding agents (like Claude or Antigravity) to act as fully capable local Android developers. 

By exposing compilation, emulator, asset management, and diagnostics capabilities directly to the agent, the MCP enables a **closed-loop build cycle** where the agent can build, run, visually inspect, debug, and sign release-ready Android applications.

---

## 🚀 Key Features

*   **Project Initialization**: Spin up templates (Empty Activity or Jetpack Compose) out-of-the-box.
*   **Safe Gradle Runner**: Execute build tasks (e.g. `assembleDebug`, `assembleRelease`) in a secure, non-hanging execution wrapper with automatic timeout safeguards and disabled background compilation daemons (preventing thread deadlocks).
*   **Live Visual Inspection**: Capture screenshots of the running emulator screen directly to your host's artifacts directory so vision-based AI models can inspect the UI layout.
*   **Logcat Diagnostics**: Stream filtered logs from active devices to diagnose app crashes.
*   **Android Resource Importer**: Automatically sanitizes asset names to comply with Android's strict naming rules (`[a-z0-9_]`) and places files in the correct module `res/` folders.
*   **Manifest & Build Editors**: Safely inject manifest permissions, set app names in XML resources, and update Gradle build versions without breaking formatting.
*   **Signing Pipeline**: Generate JKS keystores and run zip alignments (`zipalign`) followed by private key signing (`apksigner`) to produce Play Store-ready APKs.

---

## 🛠️ Prerequisites

To run this MCP server, the host machine must have the following tools installed and configured:

1.  **Python 3.10 to 3.12**
    *   Install Python and ensure it is added to your environment `PATH`.
2.  **Node.js**
    *   Required if you are running the server via the Javascript launcher bridge.
3.  **Android SDK**
    *   Ensure the Android SDK is installed (typically installed with Android Studio).
    *   Set the `ANDROID_HOME` or `ANDROID_SDK_ROOT` environment variable pointing to your SDK folder (e.g., `C:\Users\<YourUser>\AppData\Local\Android\Sdk`).
4.  **Java Development Kit (JDK 17 or 21)**
    *   Ensure a compatible JDK is installed (e.g. OpenLogic JDK or OpenJDK).
    *   Set the `JAVA_HOME` environment variable pointing to your JDK folder.

---

## 📦 Setup & Installation

1.  **Clone the repository** to your local machine (e.g. at `C:\Android-Builder-MCP`).
2.  **Install Python dependencies**:
    Open a terminal in the project directory and run:
    ```powershell
    pip install -r requirements.txt
    ```
    *Note: If you encounter a `TypeError: cannot specify both default and default_factory` when importing `fastmcp`, ensure Pydantic is downgraded to `2.11.x` by running:*
    ```powershell
    pip install "pydantic<2.12.0"
    ```

---

## ⚙️ Client Integration (Claude Desktop Configuration)

To connect this MCP server to Claude Desktop, open your configuration file (`%APPDATA%\Claude\claude_desktop_config.json`) and add the server inside the `mcpServers` object. 

Choose **one** of the following launcher options:

### Option 1: Direct CMD Execution (Recommended for Windows Store Python)
This bypasses Node.js entirely and executes Python 3.12 inside a command shell context, which is required to resolve Windows Store execution aliases:

```json
{
  "mcpServers": {
    "android-builder": {
      "command": "cmd.exe",
      "args": [
        "/c",
        "C:\\Users\\admin\\AppData\\Local\\Microsoft\\WindowsApps\\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\\python.exe",
        "-u",
        "C:/Android-Builder-MCP/server.py"
      ]
    }
  }
}
```
*(Make sure to adjust the path to your specific Python 3.12 executable if it differs).*

### Option 2: JS Launcher Bridge
Uses Node.js to launch the script wrapper, which routes commands through a shell context automatically:

```json
{
  "mcpServers": {
    "android-builder": {
      "command": "node",
      "args": [
        "C:/Android-Builder-MCP/mcp_launcher.js"
      ],
      "env": {
        "MCP_PYTHON_PATH": "C:\\Users\\admin\\AppData\\Local\\Microsoft\\WindowsApps\\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\\python.exe"
      }
    }
  }
}
```
*(You can omit the `MCP_PYTHON_PATH` environment variable if your default system `python` command already maps to the Python environment where `mcp` is installed).*

---

## 📖 MCP Tool Reference

| Tool Name | Type | Description |
| :--- | :--- | :--- |
| **`verify_sdk_setup`** | `Diagnostic` | Inspects and reports SDK, JDK, and build tool configurations. |
| **`list_projects`** | `Project` | Lists all Android projects created inside the workspace directory. |
| **`create_project`** | `Project` | Initializes a new project from templates (`empty_activity`, `compose`). |
| **`build_project`** | `Gradle` | Compiles your project using local Gradle configurations. |
| **`list_emulators`** | `Emulator` | Lists virtual device definitions (AVDs) and their current state. |
| **`start_emulator`** | `Emulator` | Launches an AVD and blocks until the Android boot cycle finishes. |
| **`list_devices`** | `ADB` | Lists all active device interfaces connected to ADB. |
| **`install_apk`** | `ADB` | Installs a built APK file onto a target running emulator or device. |
| **`import_image_resource`** | `Asset` | Sanity-checks image names and copies them to drawing/mipmap resource folders. |
| **`capture_screenshot`** | `Diagnostic` | Captures the emulator screen and saves it as a local PNG in the artifacts folder. |
| **`get_device_logs`** | `Diagnostic` | Streams filtered logcat outputs from active emulators to inspect app crashes. |
| **`add_manifest_permission`**| `Manifest` | Injects security permissions (e.g. Internet) safely into `AndroidManifest.xml`. |
| **`set_app_name`** | `Manifest` | Safely updates the app's user-facing display label in `strings.xml`. |
| **`update_gradle_versions`**| `Gradle` | Adjusts numeric version codes and semantic strings in build files. |
| **`generate_keystore`** | `Signing` | Generates JKS keystore files non-interactively using JDK's `keytool`. |
| **`sign_apk`** | `Signing` | Performs zip boundary alignment and signs the APK using a generated keystore. |

---

## 🤖 Closed-Loop Visual UI Development Workflow

With this MCP installed, you can upload screenshots of app screens or mockups directly into your chat with Claude and say:
> *"Build me an Android application that looks like this mockup image."*

Claude will proceed to:
1.  **Analyze** the mockup image using visual model reasoning.
2.  **Create** a Compose project using `create_project`.
3.  **Implement** the screens in Kotlin.
4.  **Compile** the APK using `build_project`.
5.  **Start** the emulator and install the APK (`start_emulator` -> `install_apk`).
6.  **Take a screenshot** of the running app using `capture_screenshot`.
7.  **Review the screenshot** visually, compare it to your design, and automatically patch the code to fix layout discrepancies, repeating the loop until it matches perfectly!