replicant-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Archit Joshi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,386 @@
+# replicant-mcp
+
+**Let AI build, test, and debug your Android apps.**
+
+[![CI](https://github.com/thecombatwombat/replicant-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/thecombatwombat/replicant-mcp/actions/workflows/ci.yml)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+replicant-mcp is a [Model Context Protocol](https://modelcontextprotocol.io/) server that gives AI assistants like Claude the ability to interact with your Android development environment. Build APKs, launch emulators, install apps, navigate UIs, and debug crashes—all through natural conversation.
+
+---
+
+## Why replicant-mcp?
+
+Android development involves juggling a lot: Gradle builds, emulator management, ADB commands, logcat filtering, UI testing. Each has its own CLI, flags, and quirks.
+
+replicant-mcp wraps all of this into a clean interface that AI can understand and use effectively:
+
+| Without replicant-mcp | With replicant-mcp |
+|-----------------------|-------------------|
+| "Run `./gradlew assembleDebug`, then `adb install`, then `adb shell am start`..." | "Build and run the app" |
+| Copy-paste logcat output, lose context | AI reads filtered logs directly |
+| Screenshot → describe UI → guess coordinates | AI sees accessibility tree, taps elements by text |
+| 5,000 tokens of raw Gradle output | 50-token summary + details on demand |
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+You'll need:
+- **Node.js 18+**
+- **Android SDK** with `adb` and `emulator` in your PATH
+- An Android project with `gradlew` (for build tools)
+
+Verify your setup:
+```bash
+node --version  # Should be 18+
+adb --version   # Should show Android Debug Bridge version
+emulator -version  # Should show Android emulator version
+```
+
+### Installation
+
+```bash
+# Clone the repo
+git clone https://github.com/thecombatwombat/replicant-mcp.git
+cd replicant-mcp
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Verify everything works
+npm test
+```
+
+### Connect to Claude Desktop
+
+Add this to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "replicant": {
+      "command": "node",
+      "args": ["/absolute/path/to/replicant-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You should see "replicant" in the MCP servers list.
+
+### Alternative: Claude Code Skill
+
+If you use [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (Anthropic's CLI), you can install replicant as a skill instead of an MCP server. This provides shell script wrappers optimized for Claude Code's workflow.
+
+**Option 1: Via Plugin Marketplace (Recommended)**
+```bash
+/plugin marketplace add thecombatwombat/replicant-mcp
+/plugin install replicant-dev@replicant-mcp
+```
+
+**Option 2: Manual Installation**
+```bash
+# From the replicant-mcp directory
+npm run install-skill
+```
+
+After installation, restart Claude Code to load the skill. The skill provides the same Android development capabilities through shell scripts rather than MCP tools.
+
+> **Note:** The Claude Code skill is currently compatible with macOS and Linux only. Windows support is planned for a future release.
+
+**Which should you choose?**
+- **MCP Server** — Use with Claude Desktop or any MCP-compatible client
+- **Claude Code Skill** — Use with Claude Code CLI for a shell-native experience
+
+Both approaches provide the same core functionality.
+
+---
+
+## What Can It Do?
+
+### Build & Test
+
+```
+You: "Build the debug variant of the app"
+
+Claude: I'll build the debug APK.
+        [Calls gradle-build with operation: "assembleDebug"]
+
+        Build successful in 34s
+        APK: app/build/outputs/apk/debug/app-debug.apk (12.4 MB)
+        2 warnings (use gradle-get-details for full output)
+```
+
+```
+You: "Run the unit tests for the login module"
+
+Claude: Running unit tests for :feature:login...
+        [Calls gradle-test with operation: "unitTest", module: ":feature:login"]
+
+        47 tests passed, 2 failed, 0 skipped
+
+        Failed:
+        - LoginViewModelTest.testInvalidEmail
+        - LoginRepositoryTest.testNetworkError
+
+        Want me to show the failure details?
+```
+
+### Emulator Management
+
+```
+You: "Start up a Pixel 7 emulator"
+
+Claude: I'll start the Pixel_7_API_34 emulator.
+        [Calls emulator-device with operation: "start", avdName: "Pixel_7_API_34"]
+
+        Emulator started: emulator-5554
+        Waiting for boot... ready!
+```
+
+### Install & Launch Apps
+
+```
+You: "Install the APK we just built and open the app"
+
+Claude: Installing and launching...
+        [Calls adb-app with operation: "install"]
+        [Calls adb-app with operation: "launch"]
+
+        App installed and running on emulator-5554
+```
+
+### Debug with Logcat
+
+```
+You: "The app crashed. What happened?"
+
+Claude: Let me check the error logs.
+        [Calls adb-logcat with level: "error", lines: 50]
+
+        Found the crash:
+
+        java.lang.NullPointerException: Attempt to invoke virtual method
+        'void com.example.User.getName()' on a null object reference
+            at com.example.ProfileActivity.onCreate(ProfileActivity.kt:47)
+
+        Looks like `user` is null when ProfileActivity starts.
+        Want me to look at that file?
+```
+
+### UI Automation (No Screenshots Needed!)
+
+```
+You: "Tap the Login button"
+
+Claude: I'll find and tap the Login button.
+        [Calls ui with operation: "find", selector: { text: "Login" }]
+        [Calls ui with operation: "tap", elementIndex: 0]
+
+        Tapped "Login" at coordinates (540, 1847)
+```
+
+This works by reading the **accessibility tree**—the same data screen readers use. It's faster, cheaper, and more reliable than screenshot-based approaches.
+
+---
+
+## Tool Reference
+
+replicant-mcp provides 12 tools organized into categories:
+
+### Build & Test
+| Tool | Description |
+|------|-------------|
+| `gradle-build` | Build APKs and bundles (`assembleDebug`, `assembleRelease`, `bundle`) |
+| `gradle-test` | Run unit and instrumented tests with filtering |
+| `gradle-list` | List modules, build variants, and tasks |
+| `gradle-get-details` | Fetch full logs/errors from cached build results |
+
+### Emulator
+| Tool | Description |
+|------|-------------|
+| `emulator-device` | Create, start, stop emulators; manage snapshots |
+
+### ADB
+| Tool | Description |
+|------|-------------|
+| `adb-device` | List devices, select active device, get properties |
+| `adb-app` | Install, uninstall, launch, stop apps; clear data |
+| `adb-logcat` | Read filtered device logs by package/tag/level |
+| `adb-shell` | Run shell commands (with safety guards) |
+
+### UI Automation
+| Tool | Description |
+|------|-------------|
+| `ui` | Dump accessibility tree, find elements, tap, input text, screenshot |
+
+### Utilities
+| Tool | Description |
+|------|-------------|
+| `cache` | Manage cached outputs (stats, clear, config) |
+| `rtfm` | On-demand documentation for tools |
+
+**Want details?** Ask Claude to call `rtfm` with a category like "build", "adb", "emulator", or "ui".
+
+---
+
+## Design Philosophy
+
+### Progressive Disclosure
+
+Gradle builds can produce thousands of lines of output. Dumping all of that into an AI context is wasteful and confusing.
+
+Instead, replicant-mcp returns **summaries with cache IDs**:
+
+```json
+{
+  "buildId": "build-a1b2c3-1705789200",
+  "summary": {
+    "success": true,
+    "duration": "34s",
+    "apkSize": "12.4 MB",
+    "warnings": 2
+  }
+}
+```
+
+If the AI needs the full output (e.g., to debug a failure), it can request it:
+
+```json
+{ "tool": "gradle-get-details", "id": "build-a1b2c3-1705789200", "detailType": "errors" }
+```
+
+This typically reduces token usage by **90-99%**.
+
+### Accessibility-First UI
+
+Most AI-driven UI automation uses screenshots: capture the screen, send it to a vision model, get coordinates, click.
+
+replicant-mcp takes a different approach: it reads the **accessibility tree**—the same structured data that powers screen readers. This is:
+
+- **Faster** — No image processing
+- **Cheaper** — Text is smaller than images
+- **More reliable** — Elements are identified by text/ID, not pixel coordinates
+- **Better for apps** — Encourages accessible app development
+
+### Single Device Focus
+
+Instead of passing `deviceId` to every command, you select a device once:
+
+```json
+{ "tool": "adb-device", "operation": "select", "deviceId": "emulator-5554" }
+```
+
+All subsequent commands target that device automatically. Simple.
+
+### Safety Guards
+
+The `adb-shell` tool blocks dangerous commands like `rm -rf /`, `reboot`, and `su`. You can run shell commands, but not brick your device.
+
+---
+
+## Development
+
+### Project Structure
+
+```
+src/
+  index.ts           # Entry point
+  server.ts          # MCP server setup
+  tools/             # Tool implementations (one file per tool)
+  adapters/          # CLI wrappers (adb, emulator, gradle)
+  services/          # Core services (cache, device state, process runner)
+  parsers/           # Output parsers
+  types/             # TypeScript types
+docs/rtfm/           # On-demand documentation
+tests/               # Unit and integration tests
+scripts/             # Utility scripts
+```
+
+### Running Tests
+
+```bash
+# All tests
+npm test
+
+# Unit tests only
+npm run test:unit
+
+# Integration tests (MCP protocol compliance)
+npm run test:integration
+
+# With coverage
+npm run test:coverage
+
+# Full validation (build + all tests)
+npm run validate
+```
+
+### Checking Prerequisites
+
+```bash
+npm run check-prereqs
+```
+
+This verifies your Android SDK setup and reports what's available.
+
+---
+
+## Troubleshooting
+
+### "No device selected"
+
+Run `adb-device` with `operation: "list"` to see available devices, then `operation: "select"` to choose one. If only one device is connected, it's auto-selected.
+
+### "Gradle wrapper not found"
+
+Make sure you're in an Android project directory that contains `gradlew`. The Gradle tools won't work from other locations.
+
+### "Command timed out"
+
+Long-running operations (builds, tests) have a 5-minute default timeout. If your builds are slower, you may need to adjust the timeout in the adapter.
+
+### Emulator won't start
+
+Check that:
+1. You have an AVD created (`avdmanager list avd`)
+2. Virtualization is enabled (KVM on Linux, HAXM on Mac/Windows)
+3. Enough disk space for the emulator
+
+---
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repo
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run `npm run validate` to ensure tests pass
+5. Commit with a descriptive message
+6. Push and open a PR
+
+---
+
+## Acknowledgments
+
+- Inspired by [xc-mcp](https://github.com/conorluddy/xc-mcp) for iOS
+- Built on the [Model Context Protocol](https://modelcontextprotocol.io/)
+- Thanks to the Android team for `adb` and the emulator
+
+---
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+**Questions? Issues? Ideas?** [Open an issue](https://github.com/thecombatwombat/replicant-mcp/issues) — we'd love to hear from you.

package/dist/adapters/adb.d.ts

@@ -0,0 +1,21 @@
+import { ProcessRunner, RunResult } from "../services/index.js";
+import { Device } from "../types/index.js";
+export declare class AdbAdapter {
+    private runner;
+    constructor(runner?: ProcessRunner);
+    getDevices(): Promise<Device[]>;
+    getPackages(deviceId: string): Promise<string[]>;
+    install(deviceId: string, apkPath: string): Promise<void>;
+    uninstall(deviceId: string, packageName: string): Promise<void>;
+    launch(deviceId: string, packageName: string): Promise<void>;
+    stop(deviceId: string, packageName: string): Promise<void>;
+    clearData(deviceId: string, packageName: string): Promise<void>;
+    shell(deviceId: string, command: string, timeoutMs?: number): Promise<RunResult>;
+    logcat(deviceId: string, options: {
+        lines?: number;
+        filter?: string;
+    }): Promise<string>;
+    waitForDevice(deviceId: string, timeoutMs?: number): Promise<void>;
+    getProperties(deviceId: string): Promise<Record<string, string>>;
+    private adb;
+}

package/dist/adapters/adb.js

@@ -0,0 +1,75 @@
+import { ProcessRunner } from "../services/index.js";
+import { ReplicantError, ErrorCode } from "../types/index.js";
+import { parseDeviceList, parsePackageList } from "../parsers/adb-output.js";
+export class AdbAdapter {
+    runner;
+    constructor(runner = new ProcessRunner()) {
+        this.runner = runner;
+    }
+    async getDevices() {
+        const result = await this.adb(["devices"]);
+        return parseDeviceList(result.stdout);
+    }
+    async getPackages(deviceId) {
+        const result = await this.adb(["-s", deviceId, "shell", "pm", "list", "packages"]);
+        return parsePackageList(result.stdout);
+    }
+    async install(deviceId, apkPath) {
+        const result = await this.adb(["-s", deviceId, "install", "-r", apkPath]);
+        if (result.exitCode !== 0 || result.stdout.includes("Failure")) {
+            throw new ReplicantError(ErrorCode.INSTALL_FAILED, `Failed to install APK: ${result.stdout}`, "Check the APK path and device state");
+        }
+    }
+    async uninstall(deviceId, packageName) {
+        const result = await this.adb(["-s", deviceId, "uninstall", packageName]);
+        if (result.exitCode !== 0) {
+            throw new ReplicantError(ErrorCode.PACKAGE_NOT_FOUND, `Failed to uninstall ${packageName}`, "Check the package name");
+        }
+    }
+    async launch(deviceId, packageName) {
+        // Get the main activity using dumpsys
+        const result = await this.adb([
+            "-s", deviceId, "shell", "monkey",
+            "-p", packageName, "-c", "android.intent.category.LAUNCHER", "1"
+        ]);
+        if (result.exitCode !== 0) {
+            throw new ReplicantError(ErrorCode.PACKAGE_NOT_FOUND, `Failed to launch ${packageName}`, "Check the package name and ensure the app is installed");
+        }
+    }
+    async stop(deviceId, packageName) {
+        await this.adb(["-s", deviceId, "shell", "am", "force-stop", packageName]);
+    }
+    async clearData(deviceId, packageName) {
+        await this.adb(["-s", deviceId, "shell", "pm", "clear", packageName]);
+    }
+    async shell(deviceId, command, timeoutMs) {
+        return this.adb(["-s", deviceId, "shell", command], timeoutMs);
+    }
+    async logcat(deviceId, options) {
+        const args = ["-s", deviceId, "logcat", "-d"];
+        if (options.lines) {
+            args.push("-t", options.lines.toString());
+        }
+        if (options.filter) {
+            args.push(...options.filter.split(" "));
+        }
+        const result = await this.adb(args);
+        return result.stdout;
+    }
+    async waitForDevice(deviceId, timeoutMs = 30000) {
+        await this.adb(["-s", deviceId, "wait-for-device"], timeoutMs);
+    }
+    async getProperties(deviceId) {
+        const result = await this.adb(["-s", deviceId, "shell", "getprop"]);
+        const props = {};
+        const regex = /\[([^\]]+)\]:\s*\[([^\]]*)\]/g;
+        let match;
+        while ((match = regex.exec(result.stdout)) !== null) {
+            props[match[1]] = match[2];
+        }
+        return props;
+    }
+    async adb(args, timeoutMs) {
+        return this.runner.run("adb", args, { timeoutMs });
+    }
+}

package/dist/adapters/emulator.d.ts

@@ -0,0 +1,19 @@
+import { ProcessRunner } from "../services/index.js";
+import { AvdInfo } from "../parsers/emulator-output.js";
+export interface EmulatorListResult {
+    available: AvdInfo[];
+    running: string[];
+}
+export declare class EmulatorAdapter {
+    private runner;
+    constructor(runner?: ProcessRunner);
+    list(): Promise<EmulatorListResult>;
+    create(name: string, device: string, systemImage: string): Promise<void>;
+    start(avdName: string): Promise<string>;
+    kill(emulatorId: string): Promise<void>;
+    wipe(avdName: string): Promise<void>;
+    snapshotSave(emulatorId: string, name: string): Promise<void>;
+    snapshotLoad(emulatorId: string, name: string): Promise<void>;
+    snapshotList(emulatorId: string): Promise<string[]>;
+    snapshotDelete(emulatorId: string, name: string): Promise<void>;
+}

package/dist/adapters/emulator.js

@@ -0,0 +1,72 @@
+import { ProcessRunner } from "../services/index.js";
+import { ReplicantError, ErrorCode } from "../types/index.js";
+import { parseAvdList, parseEmulatorList, parseSnapshotList } from "../parsers/emulator-output.js";
+export class EmulatorAdapter {
+    runner;
+    constructor(runner = new ProcessRunner()) {
+        this.runner = runner;
+    }
+    async list() {
+        const [avdResult, runningResult] = await Promise.all([
+            this.runner.run("avdmanager", ["list", "avd"]),
+            this.runner.run("emulator", ["-list-avds"]),
+        ]);
+        return {
+            available: parseAvdList(avdResult.stdout),
+            running: parseEmulatorList(runningResult.stdout),
+        };
+    }
+    async create(name, device, systemImage) {
+        const result = await this.runner.run("avdmanager", [
+            "create", "avd",
+            "-n", name,
+            "-k", systemImage,
+            "-d", device,
+            "--force",
+        ], { timeoutMs: 60000 });
+        if (result.exitCode !== 0) {
+            throw new ReplicantError(ErrorCode.EMULATOR_START_FAILED, `Failed to create AVD: ${result.stderr}`, "Check device and system image names");
+        }
+    }
+    async start(avdName) {
+        // Start emulator in background - don't wait for it
+        // Returns immediately, emulator boots in background
+        this.runner.run("emulator", [
+            "-avd", avdName,
+            "-no-snapshot-load",
+            "-no-boot-anim",
+        ], { timeoutMs: 5000 }).catch(() => {
+            // Expected to "timeout" as emulator runs forever
+        });
+        // Give it a moment to register
+        await new Promise((r) => setTimeout(r, 2000));
+        // Find the new emulator ID
+        const result = await this.runner.run("adb", ["devices"]);
+        const match = result.stdout.match(/emulator-\d+/);
+        if (!match) {
+            throw new ReplicantError(ErrorCode.EMULATOR_START_FAILED, `Emulator ${avdName} failed to start`, "Check the AVD name and try again");
+        }
+        return match[0];
+    }
+    async kill(emulatorId) {
+        await this.runner.run("adb", ["-s", emulatorId, "emu", "kill"]);
+    }
+    async wipe(avdName) {
+        await this.runner.run("emulator", ["-avd", avdName, "-wipe-data", "-no-window"], { timeoutMs: 5000 }).catch(() => {
+            // Expected behavior
+        });
+    }
+    async snapshotSave(emulatorId, name) {
+        await this.runner.run("adb", ["-s", emulatorId, "emu", "avd", "snapshot", "save", name]);
+    }
+    async snapshotLoad(emulatorId, name) {
+        await this.runner.run("adb", ["-s", emulatorId, "emu", "avd", "snapshot", "load", name]);
+    }
+    async snapshotList(emulatorId) {
+        const result = await this.runner.run("adb", ["-s", emulatorId, "emu", "avd", "snapshot", "list"]);
+        return parseSnapshotList(result.stdout);
+    }
+    async snapshotDelete(emulatorId, name) {
+        await this.runner.run("adb", ["-s", emulatorId, "emu", "avd", "snapshot", "delete", name]);
+    }
+}

package/dist/adapters/gradle.d.ts

@@ -0,0 +1,20 @@
+import { ProcessRunner } from "../services/index.js";
+import { BuildResult, TestResult, VariantInfo } from "../parsers/gradle-output.js";
+export declare class GradleAdapter {
+    private runner;
+    private projectPath?;
+    constructor(runner?: ProcessRunner, projectPath?: string | undefined);
+    build(operation: "assembleDebug" | "assembleRelease" | "bundle", module?: string, flavor?: string): Promise<{
+        result: BuildResult;
+        fullOutput: string;
+    }>;
+    test(operation: "unitTest" | "connectedTest", module?: string, filter?: string): Promise<{
+        result: TestResult;
+        fullOutput: string;
+    }>;
+    listModules(): Promise<string[]>;
+    listVariants(module?: string): Promise<VariantInfo[]>;
+    listTasks(module?: string): Promise<string[]>;
+    clean(stopDaemons?: boolean): Promise<void>;
+    private gradle;
+}