replicant-mcp 1.4.8 → 1.6.0

package/README.md

@@ -31,12 +31,13 @@ replicant-mcp is a [Model Context Protocol](https://modelcontextprotocol.io/) se
 
 | Category | Capabilities |
 |----------|-------------|
-| **Build & Test** | Build APKs/bundles, run unit and instrumented tests, list modules/variants/tasks |
+| **Build & Test** | Build APKs/bundles, run unit and instrumented tests, list modules/variants/tasks, test regression detection with baseline comparison |
 | **Emulator** | Create, start, stop, wipe emulators; save/load/delete snapshots |
 | **Device Control** | List connected devices, select active device, query device properties |
 | **App Management** | Install, uninstall, launch, stop apps; clear app data |
 | **Log Analysis** | Filter logcat by package, tag, level, time |
 | **UI Automation** | Accessibility-first element finding, spatial proximity search, tap, text input, screenshots |
+| **Diagnostics** | Environment health checks via `replicant doctor`; structured logging with configurable level and format |
 
 ---
 
@@ -44,7 +45,6 @@ replicant-mcp is a [Model Context Protocol](https://modelcontextprotocol.io/) se
 
 - Custom build commands (project-specific overrides, auto-detect gradlew)
 - Video capture (start/stop recording, duration-based capture)
-- Raw screenshot mode for external context management
 
 ---
 
@@ -68,6 +68,12 @@ emulator -version   # Should show Android emulator version
 npm install -g replicant-mcp
 ```
 
+After installation, run the built-in diagnostics to verify your environment:
+
+```bash
+replicant doctor
+```
+
 ### Updating
 
 ```bash
@@ -181,11 +187,31 @@ replicant-mcp uses progressive disclosure (summaries first, details on demand) t
 ## More Info
 
 - **Configuration:** Set `REPLICANT_CONFIG` for advanced options. See [docs/configuration.md](docs/configuration.md).
+- **Logging:** Set `REPLICANT_LOG_LEVEL` (`error`, `warn`, `info`, `debug`) and `REPLICANT_LOG_FORMAT` (`json` for structured output) to control server logging. Logs are written to stderr.
 - **Troubleshooting:** Common issues and solutions in [docs/troubleshooting.md](docs/troubleshooting.md).
 - **Tool documentation:** Ask Claude to call `rtfm` with a category like "build", "adb", "emulator", or "ui".
 
 ---
 
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Architecture](docs/architecture.md) | Design overview and progressive disclosure pattern |
+| [Configuration](docs/configuration.md) | Config file reference, environment variables, Gradle setup |
+| [API Stability](docs/api-stability.md) | Tool API versioning policy and deprecation process |
+| [Security Model](docs/security.md) | adb-shell safety model, command denylist, threat boundaries |
+| [Support Matrix](docs/support-matrix.md) | Tested OS, Node.js, Android SDK, and emulator versions |
+| [Known Limitations](docs/known-limitations.md) | Accessibility gaps, timeouts, single-device focus, and more |
+| [Artifacts](docs/artifacts.md) | `.replicant/` directory contents and privacy considerations |
+| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
+| [Changelog](CHANGELOG.md) | Version history |
+| [Security Policy](SECURITY.md) | Vulnerability reporting process |
+| [Support / Getting Help](SUPPORT.md) | How to report bugs and ask questions |
+| [Contributing](CONTRIBUTING.md) | Development setup and guidelines |
+
+---
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

package/dist/adapters/adb.d.ts

@@ -15,6 +15,8 @@ export declare class AdbAdapter {
     logcat(deviceId: string, options: {
         lines?: number;
         filter?: string;
+        since?: string;
+        package?: string;
     }): Promise<string>;
     waitForDevice(deviceId: string, timeoutMs?: number): Promise<void>;
     getProperties(deviceId: string): Promise<Record<string, string>>;

package/dist/adapters/adb.js

@@ -53,6 +53,9 @@ export class AdbAdapter {
     }
     async logcat(deviceId, options) {
         const args = ["-s", deviceId, "logcat", "-d"];
+        if (options.since) {
+            args.push("-T", options.since);
+        }
         if (options.lines) {
             args.push("-t", options.lines.toString());
         }
@@ -60,7 +63,15 @@ export class AdbAdapter {
             args.push(...options.filter.split(" "));
         }
         const result = await this.adb(args);
-        return result.stdout;
+        let output = result.stdout;
+        // Package filtering: filter output lines containing the package name
+        // We use string matching on output lines rather than --pid (requires pidof)
+        // or -e regex (varies across adb versions)
+        if (options.package) {
+            const lines = output.split("\n");
+            output = lines.filter((line) => line.includes(options.package)).join("\n");
+        }
+        return output;
     }
     async waitForDevice(deviceId, timeoutMs = 30000) {
         await this.adb(["-s", deviceId, "wait-for-device"], timeoutMs);

package/dist/adapters/emulator.d.ts

@@ -10,6 +10,8 @@ export declare class EmulatorAdapter {
     list(): Promise<EmulatorListResult>;
     create(name: string, device: string, systemImage: string): Promise<void>;
     start(avdName: string): Promise<string>;
+    private getRunningEmulatorIds;
+    private getAvdName;
     kill(emulatorId: string): Promise<void>;
     wipe(avdName: string): Promise<void>;
     snapshotSave(emulatorId: string, name: string): Promise<void>;

package/dist/adapters/emulator.js

@@ -29,6 +29,8 @@ export class EmulatorAdapter {
         }
     }
     async start(avdName) {
+        // Snapshot existing emulators before starting a new one
+        const existingIds = await this.getRunningEmulatorIds();
         // Start emulator in background - don't wait for it
         // Returns immediately, emulator boots in background
         this.runner.runEmulator([
@@ -40,13 +42,41 @@ export class EmulatorAdapter {
         });
         // Give it a moment to register
         await new Promise((r) => setTimeout(r, 2000));
-        // Find the new emulator ID
+        // Find the NEW emulator by diffing against pre-existing ones
+        const currentIds = await this.getRunningEmulatorIds();
+        const newIds = currentIds.filter((id) => !existingIds.includes(id));
+        if (newIds.length === 1) {
+            return newIds[0];
+        }
+        // Ambiguous or no new emulator — fall back to matching by AVD name
+        for (const id of currentIds) {
+            if (existingIds.includes(id))
+                continue;
+            const name = await this.getAvdName(id);
+            if (name === avdName)
+                return id;
+        }
+        // Last resort: check all current emulators by AVD name
+        for (const id of currentIds) {
+            const name = await this.getAvdName(id);
+            if (name === avdName)
+                return id;
+        }
+        throw new ReplicantError(ErrorCode.EMULATOR_START_FAILED, `Emulator ${avdName} failed to start`, "Check the AVD name and try again");
+    }
+    async getRunningEmulatorIds() {
         const result = await this.runner.runAdb(["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");
+        const matches = result.stdout.match(/emulator-\d+/g);
+        return matches ?? [];
+    }
+    async getAvdName(emulatorId) {
+        try {
+            const result = await this.runner.runAdb(["-s", emulatorId, "emu", "avd", "name"]);
+            return result.stdout.trim().split("\n")[0].trim();
+        }
+        catch {
+            return "";
         }
-        return match[0];
     }
     async kill(emulatorId) {
         await this.runner.runAdb(["-s", emulatorId, "emu", "kill"]);

package/dist/adapters/ui-fallback-find.js

@@ -3,7 +3,20 @@ import { extractText, searchText } from "../services/ocr.js";
 import { matchIconPattern, matchesResourceId } from "../services/icon-patterns.js";
 import { filterIconCandidates, formatBounds, cropCandidateImage } from "../services/visual-candidates.js";
 import { calculateGridCellBounds, calculatePositionCoordinates, createGridOverlay, POSITION_LABELS, } from "../services/grid.js";
+function createEarlyStopResult(tier, source) {
+    return {
+        elements: [],
+        source,
+        tier,
+        confidence: "low",
+        stoppedEarly: true,
+        stoppedAtTier: tier,
+        nextTierAvailable: tier < 5 ? (tier + 1) : undefined,
+        stopReason: "maxTier limit reached",
+    };
+}
 export async function findWithFallbacks(deps, deviceId, selector, options = {}) {
+    const maxTier = options.maxTier ?? 5;
     // Handle Tier 5 grid refinement FIRST (when gridCell and gridPosition are provided)
     if (options.gridCell !== undefined && options.gridPosition !== undefined) {
         let width, height;
@@ -42,6 +55,9 @@ export async function findWithFallbacks(deps, deviceId, selector, options = {})
             confidence: "high",
         };
     }
+    if (maxTier === 1) {
+        return createEarlyStopResult(1, "accessibility");
+    }
     // Tier 2: ResourceId pattern match (for text-based queries)
     if (selector.text || selector.textContains) {
         const query = selector.text || selector.textContains;
@@ -62,9 +78,12 @@ export async function findWithFallbacks(deps, deviceId, selector, options = {})
                 };
             }
         }
+        if (maxTier === 2) {
+            return createEarlyStopResult(2, "accessibility");
+        }
     }
     // Tier 3: OCR
-    if (selector.text || selector.textContains) {
+    if ((selector.text || selector.textContains) && maxTier >= 3) {
         const searchTerm = selector.text || selector.textContains;
         const screenshotResult = await deps.screenshot(deviceId, {});
         try {
@@ -81,6 +100,9 @@ export async function findWithFallbacks(deps, deviceId, selector, options = {})
                         : undefined,
                 };
             }
+            if (maxTier === 3) {
+                return createEarlyStopResult(3, "ocr");
+            }
             // Tier 4: Visual candidates (unlabeled clickables)
             const tree = await deps.dump(deviceId);
             const flat = flattenTree(tree);
@@ -106,6 +128,9 @@ export async function findWithFallbacks(deps, deviceId, selector, options = {})
                         : undefined,
                 };
             }
+            if (maxTier === 4) {
+                return createEarlyStopResult(4, "visual");
+            }
             // Tier 5: Grid fallback
             const gridImage = await createGridOverlay(screenshotResult.path);
             return {

package/dist/cli/doctor.d.ts

@@ -0,0 +1,10 @@
+import { Command } from "commander";
+export interface CheckResult {
+    name: string;
+    status: "ok" | "warn" | "fail";
+    detail: string;
+    suggestion?: string;
+}
+export declare function runChecks(): CheckResult[];
+export declare function formatJson(checks: CheckResult[]): string;
+export declare function createDoctorCommand(): Command;

package/dist/cli/doctor.js

@@ -0,0 +1,154 @@
+import { Command } from "commander";
+import { execSync } from "child_process";
+import { existsSync } from "fs";
+// All commands below are hardcoded literals (no user input), so execSync is safe here.
+function exec(cmd) {
+    return execSync(cmd, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).toString().trim();
+}
+function checkNode() {
+    const version = process.version;
+    const major = parseInt(version.slice(1).split(".")[0], 10);
+    if (major >= 18) {
+        return { name: "Node.js", status: "ok", detail: version };
+    }
+    return { name: "Node.js", status: "fail", detail: version, suggestion: "Upgrade to Node.js >= 18" };
+}
+function checkNpm() {
+    try {
+        return { name: "npm", status: "ok", detail: exec("npm --version") };
+    }
+    catch {
+        return { name: "npm", status: "fail", detail: "not found", suggestion: "Install npm (comes with Node.js)" };
+    }
+}
+function checkAndroidHome() {
+    const home = process.env.ANDROID_HOME;
+    if (!home) {
+        return { name: "ANDROID_HOME", status: "fail", detail: "not set", suggestion: "Set ANDROID_HOME to your Android SDK path" };
+    }
+    if (!existsSync(home)) {
+        return { name: "ANDROID_HOME", status: "fail", detail: `${home} (not found)`, suggestion: "Path does not exist. Check ANDROID_HOME value" };
+    }
+    return { name: "ANDROID_HOME", status: "ok", detail: home };
+}
+function checkAdb() {
+    try {
+        const out = exec("adb version");
+        const match = out.match(/Android Debug Bridge version ([\d.]+)/);
+        return { name: "adb", status: "ok", detail: match ? match[1] : "installed" };
+    }
+    catch {
+        return { name: "adb", status: "fail", detail: "not found", suggestion: "Install Android SDK platform-tools and add to PATH" };
+    }
+}
+function checkEmulator() {
+    try {
+        const out = exec("emulator -version");
+        const match = out.match(/version ([\d.]+)/);
+        return { name: "emulator", status: "ok", detail: match ? match[1] : "installed" };
+    }
+    catch {
+        return { name: "emulator", status: "fail", detail: "not found", suggestion: "Install Android SDK emulator and add to PATH" };
+    }
+}
+function checkAvdmanager() {
+    try {
+        exec("avdmanager list avd");
+        return { name: "avdmanager", status: "ok", detail: "installed" };
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : "";
+        const detail = msg.includes("ENOENT") || msg.includes("not found") ? "not found" : "command failed";
+        return { name: "avdmanager", status: "fail", detail, suggestion: "Install Android SDK cmdline-tools and add to PATH" };
+    }
+}
+function checkAvds(avdmanagerResult) {
+    if (avdmanagerResult.status === "fail") {
+        return { name: "AVDs", status: "fail", detail: "skipped (avdmanager unavailable)", suggestion: "Install avdmanager first" };
+    }
+    try {
+        const out = exec("avdmanager list avd");
+        const matches = out.match(/Name:/g);
+        const count = matches ? matches.length : 0;
+        if (count === 0) {
+            return { name: "AVDs", status: "warn", detail: "none found", suggestion: "Create an AVD: avdmanager create avd ..." };
+        }
+        return { name: "AVDs", status: "ok", detail: `${count} available` };
+    }
+    catch {
+        return { name: "AVDs", status: "fail", detail: "could not list", suggestion: "avdmanager command failed" };
+    }
+}
+function checkDevices(adbResult) {
+    if (adbResult.status === "fail") {
+        return { name: "Connected devices", status: "fail", detail: "skipped (adb unavailable)", suggestion: "Install adb first" };
+    }
+    try {
+        const out = exec("adb devices");
+        const lines = out.split("\n").filter((l) => l.includes("\tdevice"));
+        return { name: "Connected devices", status: lines.length > 0 ? "ok" : "warn", detail: `${lines.length} connected` };
+    }
+    catch {
+        return { name: "Connected devices", status: "fail", detail: "could not query", suggestion: "adb command failed" };
+    }
+}
+function checkGradle() {
+    try {
+        const out = exec("gradle --version");
+        const match = out.match(/Gradle ([\d.]+)/);
+        return { name: "System gradle", status: "ok", detail: match ? match[1] : "installed" };
+    }
+    catch {
+        return { name: "System gradle", status: "warn", detail: "not found (optional)", suggestion: "Most projects use the Gradle wrapper (gradlew) instead" };
+    }
+}
+export function runChecks() {
+    const adbResult = checkAdb();
+    const avdmanagerResult = checkAvdmanager();
+    return [
+        checkNode(), checkNpm(), checkAndroidHome(), adbResult,
+        checkEmulator(), avdmanagerResult, checkAvds(avdmanagerResult), checkDevices(adbResult), checkGradle(),
+    ];
+}
+function formatTty(checks) {
+    const symbols = { ok: "\u2713 OK", warn: "\u26A0 WARN", fail: "\u2717 FAIL" };
+    const colors = { ok: "\x1b[32m", warn: "\x1b[33m", fail: "\x1b[31m" };
+    const reset = "\x1b[0m";
+    const lines = ["\nReplicant Doctor\n================\n"];
+    for (const c of checks) {
+        const sym = `${colors[c.status]}${symbols[c.status]}${reset}`;
+        lines.push(`  ${sym}  ${c.name}: ${c.detail}`);
+        if (c.suggestion)
+            lines.push(`       ${c.suggestion}`);
+    }
+    const summary = { ok: 0, warn: 0, fail: 0 };
+    for (const c of checks)
+        summary[c.status]++;
+    lines.push(`\n${summary.ok} passed, ${summary.warn} warnings, ${summary.fail} failures\n`);
+    return lines.join("\n");
+}
+export function formatJson(checks) {
+    const summary = { ok: 0, warn: 0, fail: 0 };
+    for (const c of checks)
+        summary[c.status]++;
+    const status = summary.fail > 0 ? "fail" : summary.warn > 0 ? "warn" : "ok";
+    return JSON.stringify({ status, checks, summary }, null, 2);
+}
+export function createDoctorCommand() {
+    return new Command("doctor")
+        .description("Check environment for Android development readiness")
+        .option("--json", "Output as JSON")
+        .action((options) => {
+        const checks = runChecks();
+        const useJson = options.json || !process.stdout.isTTY;
+        if (useJson) {
+            console.log(formatJson(checks));
+        }
+        else {
+            console.log(formatTty(checks));
+        }
+        const hasFail = checks.some((c) => c.status === "fail");
+        if (hasFail)
+            process.exit(1);
+    });
+}

package/dist/cli/emulator.js

@@ -135,7 +135,7 @@ export function createEmulatorCommand() {
                         console.log(`Snapshot loaded: ${snapshotName}`);
                     }
                     break;
-                case "list":
+                case "list": {
                     const snapshots = await adapter.snapshotList(deviceId);
                     if (options.json) {
                         console.log(JSON.stringify({ deviceId, snapshots }, null, 2));
@@ -152,6 +152,7 @@ export function createEmulatorCommand() {
                         }
                     }
                     break;
+                }
                 case "delete":
                     if (!snapshotName) {
                         console.error("Error: --name is required for delete action");

package/dist/cli/index.d.ts

@@ -3,4 +3,5 @@ export { createAdbCommand } from "./adb.js";
 export { createEmulatorCommand } from "./emulator.js";
 export { createUiCommand } from "./ui.js";
 export { createCacheCommand } from "./cache.js";
+export { createDoctorCommand } from "./doctor.js";
 export * from "./formatter.js";

package/dist/cli/index.js

@@ -3,4 +3,5 @@ export { createAdbCommand } from "./adb.js";
 export { createEmulatorCommand } from "./emulator.js";
 export { createUiCommand } from "./ui.js";
 export { createCacheCommand } from "./cache.js";
+export { createDoctorCommand } from "./doctor.js";
 export * from "./formatter.js";

package/dist/cli.js

@@ -1,14 +1,16 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import { createGradleCommand, createAdbCommand, createEmulatorCommand, createUiCommand, createCacheCommand, } from "./cli/index.js";
+import { createGradleCommand, createAdbCommand, createEmulatorCommand, createUiCommand, createCacheCommand, createDoctorCommand, } from "./cli/index.js";
+import { VERSION } from "./version.js";
 const program = new Command();
 program
-    .name("replicant")
+    .name("replicant-mcp")
     .description("Android development CLI")
-    .version("1.0.0");
+    .version(VERSION);
 program.addCommand(createGradleCommand());
 program.addCommand(createAdbCommand());
 program.addCommand(createEmulatorCommand());
 program.addCommand(createUiCommand());
 program.addCommand(createCacheCommand());
+program.addCommand(createDoctorCommand());
 program.parse();

package/dist/index.js

@@ -1,6 +1,23 @@
 #!/usr/bin/env node
-import { runServer } from "./server.js";
-runServer().catch((error) => {
-    console.error("Server error:", error);
-    process.exit(1);
-});
+if (process.argv.length > 2) {
+    // CLI mode: has arguments (e.g., --version, doctor, adb, etc.)
+    import("./cli.js").catch((error) => {
+        console.error("Failed to load CLI:", error);
+        process.exit(1);
+    });
+}
+else {
+    // MCP server mode: no arguments, start the server
+    Promise.all([import("./server.js"), import("./utils/logger.js")])
+        .then(([{ runServer }, { logger }]) => {
+        runServer().catch((error) => {
+            logger.error("Server error", { error: String(error) });
+            process.exit(1);
+        });
+    })
+        .catch((error) => {
+        console.error("Failed to start server:", error);
+        process.exit(1);
+    });
+}
+export {};

package/dist/parsers/adb-output.js

@@ -9,7 +9,11 @@ export function parseDeviceList(output) {
         if (!id)
             continue;
         const type = id.startsWith("emulator") ? "emulator" : "physical";
-        const status = statusStr === "device" ? "online" : "offline";
+        const status = statusStr === "device"
+            ? "online"
+            : statusStr === "unauthorized"
+                ? "unauthorized"
+                : "offline";
         devices.push({
             id,
             type,

package/dist/parsers/gradle-output.d.ts

@@ -17,6 +17,7 @@ export interface TestResult {
         test: string;
         message: string;
     }>;
+    passedTests: string[];
 }
 export declare function parseBuildOutput(output: string): BuildResult;
 export declare function parseTestOutput(output: string): TestResult;

package/dist/parsers/gradle-output.js

@@ -31,6 +31,12 @@ export function parseTestOutput(output) {
     while ((match = failureRegex.exec(output)) !== null) {
         failures.push({ test: `${match[1]}.${match[2]}`, message: "" });
     }
+    // Extract passed test names
+    const passedTests = [];
+    const passedRegex = /(\S+) > (\S+) PASSED/g;
+    while ((match = passedRegex.exec(output)) !== null) {
+        passedTests.push(`${match[1]}.${match[2]}`);
+    }
     return {
         passed,
         failed,
@@ -38,6 +44,7 @@ export function parseTestOutput(output) {
         total,
         duration: durationMatch?.[1],
         failures,
+        passedTests,
     };
 }
 export function parseModuleList(output) {