replicant-mcp 1.0.0 → 1.0.4

package/README.md

@@ -10,6 +10,12 @@ replicant-mcp is a [Model Context Protocol](https://modelcontextprotocol.io/) se
 
 ---
 
+## Demo
+
+![replicant-mcp demo](demo.gif)
+
+---
+
 ## 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.
@@ -25,6 +31,44 @@ replicant-mcp wraps all of this into a clean interface that AI can understand an
 
 ---
 
+## Current Features
+
+| Category | Capabilities |
+|----------|-------------|
+| **Build & Test** | Build APKs/bundles, run unit and instrumented tests, list modules/variants/tasks, fetch detailed build logs |
+| **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; list installed packages |
+| **Log Analysis** | Filter logcat by package, tag, level, time; configurable line limits |
+| **UI Automation** | Accessibility-tree based element finding, tap, text input, screenshots |
+| **Utilities** | Response caching with progressive disclosure, on-demand documentation |
+
+---
+
+## Future Roadmap
+
+| Feature | Item | Status |
+|---------|------|--------|
+| **Visual Fallback** | Screenshot + metadata on accessibility failure | Planned |
+| | `visual-snapshot` operation for explicit visual mode | Planned |
+| | YAML config via `REPLICANT_CONFIG` | Planned |
+| | OCR fallback for text search (tesseract.js) | Planned |
+| | Icon recognition (template matching for common UI icons) | Planned |
+| | Semantic image search (LLM-assisted visual understanding) | Future |
+| **Custom Build Commands** | Skill override for project-specific builds | Planned |
+| | Auto-detect gradlew vs gradle | Planned |
+| | Configurable default variant | Planned |
+| | Extend skill override to test/lint operations | Future |
+| **Video Capture** | Start/stop recording | Planned |
+| | Duration-based capture | Planned |
+| | Configurable output directory and quality | Planned |
+| | WebM/GIF conversion (ffmpeg) | Future |
+| **Developer Experience** | Simplified tool authoring with `defineTool()` helper | Future |
+| | Auto-generate JSON schema from Zod via `zod-to-json-schema` | Future |
+| | Convention-based tool auto-discovery (no manual wiring) | Future |
+
+---
+
 ## Quick Start
 
 ### Prerequisites
@@ -43,18 +87,17 @@ emulator -version  # Should show Android emulator version
 
 ### Installation
 
+**Option 1: npm (recommended)**
+```bash
+npm install -g replicant-mcp
+```
+
+**Option 2: From source**
 ```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
 ```
 
@@ -75,31 +118,51 @@ Add this to your Claude Desktop config (`~/Library/Application Support/Claude/cl
 
 Restart Claude Desktop. You should see "replicant" in the MCP servers list.
 
-### Alternative: Claude Code Skill
+### Connect to Claude Code
 
-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.
+Add the MCP server with environment variables for Android SDK:
 
-**Option 1: Via Plugin Marketplace (Recommended)**
 ```bash
-/plugin marketplace add thecombatwombat/replicant-mcp
-/plugin install replicant-dev@replicant-mcp
+claude mcp add replicant \
+  -e ANDROID_HOME=$HOME/Library/Android/sdk \
+  -e PATH="$HOME/Library/Android/sdk/platform-tools:$HOME/Library/Android/sdk/emulator:$HOME/Library/Android/sdk/cmdline-tools/latest/bin:$PATH" \
+  -- node $(npm root -g)/replicant-mcp/dist/index.js
 ```
 
-**Option 2: Manual Installation**
-```bash
-# From the replicant-mcp directory
-npm run install-skill
+> **Note:** Adjust `ANDROID_HOME` if your Android SDK is in a different location. On Linux, it's typically `$HOME/Android/Sdk`.
+
+Restart Claude Code to load the MCP server.
+
+### Reducing Permission Prompts (Optional)
+
+By default, Claude Code asks for permission on each tool call. To auto-approve replicant-mcp tools, add this to your `.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "mcp__replicant__*"
+    ]
+  }
+}
 ```
 
-After installation, restart Claude Code to load the skill. The skill provides the same Android development capabilities through shell scripts rather than MCP tools.
+This is especially useful for agentic workflows where human intervention is limited.
 
-> **Note:** The Claude Code skill is currently compatible with macOS and Linux only. Windows support is planned for a future release.
+### PR Automation (Optional)
 
-**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
+This project includes a Claude Code skill for automated PR handling. When invoked, it:
+- Creates a branch and PR from your current changes
+- Polls for Greptile and human reviews every 2 minutes (max 5 cycles)
+- Automatically addresses Greptile feedback
+- Merges when a human approves
+
+To use:
+```
+/pr-with-review --branch feature/my-feature --title "My PR" --body "Description" --commit-message "feat: add feature"
+```
 
-Both approaches provide the same core functionality.
+Or let Claude invoke it automatically when creating PRs.
 
 ---
 

package/dist/adapters/adb.d.ts

@@ -11,6 +11,7 @@ export declare class AdbAdapter {
     stop(deviceId: string, packageName: string): Promise<void>;
     clearData(deviceId: string, packageName: string): Promise<void>;
     shell(deviceId: string, command: string, timeoutMs?: number): Promise<RunResult>;
+    pull(deviceId: string, remotePath: string, localPath: string): Promise<void>;
     logcat(deviceId: string, options: {
         lines?: number;
         filter?: string;

package/dist/adapters/adb.js

@@ -45,6 +45,12 @@ export class AdbAdapter {
     async shell(deviceId, command, timeoutMs) {
         return this.adb(["-s", deviceId, "shell", command], timeoutMs);
     }
+    async pull(deviceId, remotePath, localPath) {
+        const result = await this.adb(["-s", deviceId, "pull", remotePath, localPath]);
+        if (result.exitCode !== 0) {
+            throw new ReplicantError(ErrorCode.PULL_FAILED, `Failed to pull ${remotePath} to ${localPath}`, result.stderr || "Check device connection and file paths");
+        }
+    }
     async logcat(deviceId, options) {
         const args = ["-s", deviceId, "logcat", "-d"];
         if (options.lines) {
@@ -70,6 +76,6 @@ export class AdbAdapter {
         return props;
     }
     async adb(args, timeoutMs) {
-        return this.runner.run("adb", args, { timeoutMs });
+        return this.runner.runAdb(args, { timeoutMs });
     }
 }

package/dist/adapters/emulator.js

@@ -8,8 +8,8 @@ export class EmulatorAdapter {
     }
     async list() {
         const [avdResult, runningResult] = await Promise.all([
-            this.runner.run("avdmanager", ["list", "avd"]),
-            this.runner.run("emulator", ["-list-avds"]),
+            this.runner.runAvdManager(["list", "avd"]),
+            this.runner.runEmulator(["-list-avds"]),
         ]);
         return {
             available: parseAvdList(avdResult.stdout),
@@ -17,7 +17,7 @@ export class EmulatorAdapter {
         };
     }
     async create(name, device, systemImage) {
-        const result = await this.runner.run("avdmanager", [
+        const result = await this.runner.runAvdManager([
             "create", "avd",
             "-n", name,
             "-k", systemImage,
@@ -31,7 +31,7 @@ export class EmulatorAdapter {
     async start(avdName) {
         // Start emulator in background - don't wait for it
         // Returns immediately, emulator boots in background
-        this.runner.run("emulator", [
+        this.runner.runEmulator([
             "-avd", avdName,
             "-no-snapshot-load",
             "-no-boot-anim",
@@ -41,7 +41,7 @@ export class EmulatorAdapter {
         // 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 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");
@@ -49,24 +49,24 @@ export class EmulatorAdapter {
         return match[0];
     }
     async kill(emulatorId) {
-        await this.runner.run("adb", ["-s", emulatorId, "emu", "kill"]);
+        await this.runner.runAdb(["-s", emulatorId, "emu", "kill"]);
     }
     async wipe(avdName) {
-        await this.runner.run("emulator", ["-avd", avdName, "-wipe-data", "-no-window"], { timeoutMs: 5000 }).catch(() => {
+        await this.runner.runEmulator(["-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]);
+        await this.runner.runAdb(["-s", emulatorId, "emu", "avd", "snapshot", "save", name]);
     }
     async snapshotLoad(emulatorId, name) {
-        await this.runner.run("adb", ["-s", emulatorId, "emu", "avd", "snapshot", "load", name]);
+        await this.runner.runAdb(["-s", emulatorId, "emu", "avd", "snapshot", "load", name]);
     }
     async snapshotList(emulatorId) {
-        const result = await this.runner.run("adb", ["-s", emulatorId, "emu", "avd", "snapshot", "list"]);
+        const result = await this.runner.runAdb(["-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]);
+        await this.runner.runAdb(["-s", emulatorId, "emu", "avd", "snapshot", "delete", name]);
     }
 }

package/dist/adapters/ui-automator.d.ts

@@ -1,5 +1,24 @@
 import { AdbAdapter } from "./adb.js";
 import { AccessibilityNode } from "../parsers/ui-dump.js";
+import { OcrElement } from "../types/index.js";
+export interface ScreenshotOptions {
+    localPath?: string;
+    inline?: boolean;
+}
+export interface ScreenshotResult {
+    mode: "file" | "inline";
+    path?: string;
+    base64?: string;
+    sizeBytes?: number;
+}
+export interface FindWithOcrResult {
+    elements: (AccessibilityNode | OcrElement)[];
+    source: "accessibility" | "ocr";
+    fallbackReason?: string;
+}
+export interface FindOptions {
+    debug?: boolean;
+}
 export declare class UiAutomatorAdapter {
     private adb;
     constructor(adb?: AdbAdapter);
@@ -13,11 +32,17 @@ export declare class UiAutomatorAdapter {
     tap(deviceId: string, x: number, y: number): Promise<void>;
     tapElement(deviceId: string, element: AccessibilityNode): Promise<void>;
     input(deviceId: string, text: string): Promise<void>;
-    screenshot(deviceId: string, localPath: string): Promise<void>;
+    screenshot(deviceId: string, options?: ScreenshotOptions): Promise<ScreenshotResult>;
     accessibilityCheck(deviceId: string): Promise<{
         hasAccessibleElements: boolean;
         clickableCount: number;
         textCount: number;
         totalElements: number;
     }>;
+    findWithOcrFallback(deviceId: string, selector: {
+        resourceId?: string;
+        text?: string;
+        textContains?: string;
+        className?: string;
+    }, options?: FindOptions): Promise<FindWithOcrResult>;
 }

package/dist/adapters/ui-automator.js

@@ -1,5 +1,7 @@
 import { AdbAdapter } from "./adb.js";
 import { parseUiDump, findElements, flattenTree } from "../parsers/ui-dump.js";
+import { ReplicantError, ErrorCode } from "../types/index.js";
+import { extractText, searchText } from "../services/ocr.js";
 export class UiAutomatorAdapter {
     adb;
     constructor(adb = new AdbAdapter()) {
@@ -29,14 +31,35 @@ export class UiAutomatorAdapter {
         const escaped = text.replace(/(['"\\$`])/g, "\\$1").replace(/ /g, "%s");
         await this.adb.shell(deviceId, `input text "${escaped}"`);
     }
-    async screenshot(deviceId, localPath) {
-        const remotePath = "/sdcard/screenshot.png";
-        await this.adb.shell(deviceId, `screencap -p ${remotePath}`);
-        // Pull to local (using adb pull via shell workaround)
-        // In real implementation, would use adb pull directly
-        const result = await this.adb.shell(deviceId, `base64 ${remotePath}`);
-        // For now, just verify it worked
-        await this.adb.shell(deviceId, `rm ${remotePath}`);
+    async screenshot(deviceId, options = {}) {
+        const remotePath = "/sdcard/replicant-screenshot.png";
+        // Capture screenshot on device
+        const captureResult = await this.adb.shell(deviceId, `screencap -p ${remotePath}`);
+        if (captureResult.exitCode !== 0) {
+            throw new ReplicantError(ErrorCode.SCREENSHOT_FAILED, "Failed to capture screenshot", captureResult.stderr || "Ensure device screen is on and unlocked");
+        }
+        try {
+            if (options.inline) {
+                // Inline mode: return base64
+                const base64Result = await this.adb.shell(deviceId, `base64 ${remotePath}`);
+                const sizeResult = await this.adb.shell(deviceId, `stat -c%s ${remotePath}`);
+                return {
+                    mode: "inline",
+                    base64: base64Result.stdout.trim(),
+                    sizeBytes: parseInt(sizeResult.stdout.trim(), 10),
+                };
+            }
+            else {
+                // File mode (default): pull to local
+                const localPath = options.localPath || `/tmp/replicant-screenshot-${Date.now()}.png`;
+                await this.adb.pull(deviceId, remotePath, localPath);
+                return { mode: "file", path: localPath };
+            }
+        }
+        finally {
+            // Always clean up remote file
+            await this.adb.shell(deviceId, `rm -f ${remotePath}`);
+        }
     }
     async accessibilityCheck(deviceId) {
         const tree = await this.dump(deviceId);
@@ -50,4 +73,45 @@ export class UiAutomatorAdapter {
             totalElements: flat.length,
         };
     }
+    async findWithOcrFallback(deviceId, selector, options = {}) {
+        // First try accessibility tree
+        const accessibilityResults = await this.find(deviceId, selector);
+        if (accessibilityResults.length > 0) {
+            return {
+                elements: accessibilityResults,
+                source: "accessibility",
+            };
+        }
+        // Fall back to OCR if we have a text-based selector
+        if (selector.text || selector.textContains) {
+            const searchTerm = selector.text || selector.textContains;
+            // Take screenshot for OCR
+            const screenshotResult = await this.screenshot(deviceId, {});
+            try {
+                // Run OCR
+                const ocrResults = await extractText(screenshotResult.path);
+                const matches = searchText(ocrResults, searchTerm);
+                const result = {
+                    elements: matches,
+                    source: "ocr",
+                };
+                if (options.debug) {
+                    result.fallbackReason = "accessibility tree had no matching text";
+                }
+                return result;
+            }
+            finally {
+                // Clean up local screenshot file
+                if (screenshotResult.path) {
+                    const fs = await import("fs/promises");
+                    await fs.unlink(screenshotResult.path).catch(() => { });
+                }
+            }
+        }
+        // No text selector, can't use OCR
+        return {
+            elements: [],
+            source: "accessibility",
+        };
+    }
 }

package/dist/cli/gradle.js

@@ -37,10 +37,10 @@ export function createGradleCommand() {
         catch (error) {
             const duration = "0s";
             const cacheId = cache.generateId("build");
-            if (error instanceof ReplicantError && error.details?.buildResult) {
-                cache.set(cacheId, { result: error.details.buildResult, fullOutput: "" }, "build", CACHE_TTLS.BUILD_OUTPUT);
+            if (error instanceof ReplicantError && error.context?.buildResult) {
+                cache.set(cacheId, { result: error.context.buildResult, fullOutput: "" }, "build", CACHE_TTLS.BUILD_OUTPUT);
                 if (options.json) {
-                    console.log(JSON.stringify({ error: error.message, result: error.details.buildResult, cacheId }, null, 2));
+                    console.log(JSON.stringify({ error: error.message, result: error.context.buildResult, cacheId }, null, 2));
                 }
                 else {
                     console.log(formatBuildFailure({

package/dist/cli.js

@@ -4,7 +4,7 @@ import { createGradleCommand, createAdbCommand, createEmulatorCommand, createUiC
 const program = new Command();
 program
     .name("replicant")
-    .description("Android development CLI for Claude Code skills")
+    .description("Android development CLI")
     .version("1.0.0");
 program.addCommand(createGradleCommand());
 program.addCommand(createAdbCommand());

package/dist/server.d.ts

@@ -1,10 +1,11 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { CacheManager, DeviceStateManager, ProcessRunner } from "./services/index.js";
+import { CacheManager, DeviceStateManager, ProcessRunner, EnvironmentService } from "./services/index.js";
 import { AdbAdapter, EmulatorAdapter, GradleAdapter, UiAutomatorAdapter } from "./adapters/index.js";
 export interface ServerContext {
     cache: CacheManager;
     deviceState: DeviceStateManager;
     processRunner: ProcessRunner;
+    environment: EnvironmentService;
     adb: AdbAdapter;
     emulator: EmulatorAdapter;
     gradle: GradleAdapter;

package/dist/server.js

@@ -1,17 +1,19 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { CacheManager, DeviceStateManager, ProcessRunner } from "./services/index.js";
+import { CacheManager, DeviceStateManager, ProcessRunner, EnvironmentService } from "./services/index.js";
 import { AdbAdapter, EmulatorAdapter, GradleAdapter, UiAutomatorAdapter } from "./adapters/index.js";
 import { ReplicantError } from "./types/index.js";
 import { cacheToolDefinition, handleCacheTool, rtfmToolDefinition, handleRtfmTool, adbDeviceToolDefinition, handleAdbDeviceTool, adbAppToolDefinition, handleAdbAppTool, adbLogcatToolDefinition, handleAdbLogcatTool, adbShellToolDefinition, handleAdbShellTool, emulatorDeviceToolDefinition, handleEmulatorDeviceTool, gradleBuildToolDefinition, handleGradleBuildTool, gradleTestToolDefinition, handleGradleTestTool, gradleListToolDefinition, handleGradleListTool, gradleGetDetailsToolDefinition, handleGradleGetDetailsTool, uiToolDefinition, handleUiTool, } from "./tools/index.js";
 export function createServerContext() {
-    const processRunner = new ProcessRunner();
+    const environment = new EnvironmentService();
+    const processRunner = new ProcessRunner(environment);
     const adb = new AdbAdapter(processRunner);
     return {
         cache: new CacheManager(),
         deviceState: new DeviceStateManager(),
         processRunner,
+        environment,
         adb,
         emulator: new EmulatorAdapter(processRunner),
         gradle: new GradleAdapter(processRunner),

package/dist/services/device-state.d.ts

@@ -1,9 +1,11 @@
 import { Device } from "../types/index.js";
+import type { AdbAdapter } from "../adapters/adb.js";
 export declare class DeviceStateManager {
     private currentDevice;
     getCurrentDevice(): Device | null;
     setCurrentDevice(device: Device): void;
     clearCurrentDevice(): void;
     requireCurrentDevice(): Device;
+    ensureDevice(adb: AdbAdapter): Promise<Device>;
     autoSelectIfSingle(devices: Device[]): boolean;
 }

package/dist/services/device-state.js

@@ -16,6 +16,24 @@ export class DeviceStateManager {
         }
         return this.currentDevice;
     }
+    async ensureDevice(adb) {
+        // Already selected? Use it.
+        if (this.currentDevice) {
+            return this.currentDevice;
+        }
+        // Try to auto-select
+        const devices = await adb.getDevices();
+        if (devices.length === 0) {
+            throw new ReplicantError(ErrorCode.NO_DEVICES, "No devices connected", "Start an emulator with 'emulator-device start' or connect a USB device with debugging enabled");
+        }
+        if (devices.length === 1) {
+            this.currentDevice = devices[0];
+            return this.currentDevice;
+        }
+        // Multiple devices - user must choose
+        const deviceList = devices.map((d) => d.id).join(", ");
+        throw new ReplicantError(ErrorCode.MULTIPLE_DEVICES, `${devices.length} devices connected: ${deviceList}`, `Call adb-device({ operation: 'select', deviceId: '...' }) to choose one`);
+    }
     autoSelectIfSingle(devices) {
         if (devices.length === 1 && !this.currentDevice) {
             this.currentDevice = devices[0];

package/dist/services/environment.d.ts

@@ -0,0 +1,18 @@
+export interface Environment {
+    sdkPath: string | null;
+    adbPath: string | null;
+    emulatorPath: string | null;
+    platform: "darwin" | "linux" | "win32";
+    isValid: boolean;
+    issues: string[];
+}
+export declare class EnvironmentService {
+    private cached;
+    detect(): Promise<Environment>;
+    getAdbPath(): Promise<string>;
+    getEmulatorPath(): Promise<string>;
+    getAvdManagerPath(): Promise<string>;
+    private findSdkPath;
+    private getSearchPaths;
+    clearCache(): void;
+}

package/dist/services/environment.js

@@ -0,0 +1,130 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { ReplicantError, ErrorCode } from "../types/index.js";
+export class EnvironmentService {
+    cached = null;
+    async detect() {
+        if (this.cached) {
+            return this.cached;
+        }
+        const platform = os.platform();
+        const issues = [];
+        // Try to find SDK
+        const sdkPath = this.findSdkPath(platform);
+        if (!sdkPath) {
+            this.cached = {
+                sdkPath: null,
+                adbPath: null,
+                emulatorPath: null,
+                platform,
+                isValid: false,
+                issues: ["Android SDK not found. Install Android Studio or set ANDROID_HOME environment variable."],
+            };
+            return this.cached;
+        }
+        const adbPath = path.join(sdkPath, "platform-tools", "adb");
+        const emulatorPath = path.join(sdkPath, "emulator", "emulator");
+        // Verify adb exists
+        if (!fs.existsSync(adbPath)) {
+            issues.push(`adb not found at ${adbPath}`);
+        }
+        // Emulator is optional - just note if missing
+        if (!fs.existsSync(emulatorPath)) {
+            issues.push(`emulator not found at ${emulatorPath} (optional)`);
+        }
+        this.cached = {
+            sdkPath,
+            adbPath: fs.existsSync(adbPath) ? adbPath : null,
+            emulatorPath: fs.existsSync(emulatorPath) ? emulatorPath : null,
+            platform,
+            isValid: fs.existsSync(adbPath),
+            issues,
+        };
+        return this.cached;
+    }
+    async getAdbPath() {
+        const env = await this.detect();
+        if (!env.adbPath) {
+            throw new ReplicantError(ErrorCode.ADB_NOT_FOUND, "Android SDK not found", "Install Android Studio or set ANDROID_HOME environment variable", { checkedPaths: this.getSearchPaths(env.platform) });
+        }
+        return env.adbPath;
+    }
+    async getEmulatorPath() {
+        const env = await this.detect();
+        if (!env.emulatorPath) {
+            throw new ReplicantError(ErrorCode.EMULATOR_NOT_FOUND, "Android emulator not found", "Install Android Emulator via Android Studio SDK Manager");
+        }
+        return env.emulatorPath;
+    }
+    async getAvdManagerPath() {
+        const env = await this.detect();
+        if (!env.sdkPath) {
+            throw new ReplicantError(ErrorCode.SDK_NOT_FOUND, "Android SDK not found", "Install Android Studio or set ANDROID_HOME environment variable");
+        }
+        const avdManagerPath = path.join(env.sdkPath, "cmdline-tools", "latest", "bin", "avdmanager");
+        // Fallback to older location
+        const legacyPath = path.join(env.sdkPath, "tools", "bin", "avdmanager");
+        if (fs.existsSync(avdManagerPath)) {
+            return avdManagerPath;
+        }
+        if (fs.existsSync(legacyPath)) {
+            return legacyPath;
+        }
+        throw new ReplicantError(ErrorCode.SDK_NOT_FOUND, "avdmanager not found", "Install Android SDK Command-line Tools via Android Studio SDK Manager");
+    }
+    findSdkPath(platform) {
+        // 1. Check ANDROID_HOME
+        if (process.env.ANDROID_HOME) {
+            const adbPath = path.join(process.env.ANDROID_HOME, "platform-tools", "adb");
+            if (fs.existsSync(adbPath)) {
+                return process.env.ANDROID_HOME;
+            }
+        }
+        // 2. Check ANDROID_SDK_ROOT
+        if (process.env.ANDROID_SDK_ROOT) {
+            const adbPath = path.join(process.env.ANDROID_SDK_ROOT, "platform-tools", "adb");
+            if (fs.existsSync(adbPath)) {
+                return process.env.ANDROID_SDK_ROOT;
+            }
+        }
+        // 3. Probe common paths
+        const searchPaths = this.getSearchPaths(platform);
+        for (const sdkPath of searchPaths) {
+            const adbPath = path.join(sdkPath, "platform-tools", "adb");
+            if (fs.existsSync(adbPath)) {
+                return sdkPath;
+            }
+        }
+        return null;
+    }
+    getSearchPaths(platform) {
+        const home = os.homedir();
+        if (platform === "darwin") {
+            return [
+                path.join(home, "Library", "Android", "sdk"),
+                "/opt/homebrew/share/android-sdk",
+                "/usr/local/share/android-sdk",
+            ];
+        }
+        if (platform === "linux") {
+            return [
+                path.join(home, "Android", "Sdk"),
+                "/opt/android-sdk",
+                "/usr/lib/android-sdk",
+            ];
+        }
+        if (platform === "win32") {
+            const localAppData = process.env.LOCALAPPDATA || path.join(home, "AppData", "Local");
+            return [
+                path.join(localAppData, "Android", "Sdk"),
+                "C:\\Android\\sdk",
+            ];
+        }
+        return [];
+    }
+    // Clear cache (for testing)
+    clearCache() {
+        this.cached = null;
+    }
+}

package/dist/services/index.d.ts

@@ -1,3 +1,5 @@
 export { ProcessRunner, type RunOptions, type RunResult } from "./process-runner.js";
 export { CacheManager, type CacheStats } from "./cache-manager.js";
 export { DeviceStateManager } from "./device-state.js";
+export { EnvironmentService, type Environment } from "./environment.js";
+export * from "./ocr.js";

package/dist/services/index.js

@@ -1,3 +1,5 @@
 export { ProcessRunner } from "./process-runner.js";
 export { CacheManager } from "./cache-manager.js";
 export { DeviceStateManager } from "./device-state.js";
+export { EnvironmentService } from "./environment.js";
+export * from "./ocr.js";

package/dist/services/ocr.d.ts

@@ -0,0 +1,4 @@
+import { OcrResult, OcrElement } from "../types/ocr.js";
+export declare function extractText(imagePath: string): Promise<OcrResult[]>;
+export declare function terminateOcr(): Promise<void>;
+export declare function searchText(ocrResults: OcrResult[], searchTerm: string): OcrElement[];

package/dist/services/ocr.js

@@ -0,0 +1,59 @@
+import { createWorker } from "tesseract.js";
+let worker = null;
+async function getWorker() {
+    if (!worker) {
+        worker = await createWorker("eng");
+    }
+    return worker;
+}
+export async function extractText(imagePath) {
+    const w = await getWorker();
+    const { data } = await w.recognize(imagePath, {}, { blocks: true });
+    const results = [];
+    // Navigate through blocks -> paragraphs -> lines -> words
+    if (data.blocks) {
+        for (const block of data.blocks) {
+            for (const paragraph of block.paragraphs) {
+                for (const line of paragraph.lines) {
+                    for (const word of line.words) {
+                        if (word.text.trim()) {
+                            results.push({
+                                text: word.text,
+                                confidence: word.confidence / 100, // Normalize to 0-1
+                                bounds: {
+                                    x0: word.bbox.x0,
+                                    y0: word.bbox.y0,
+                                    x1: word.bbox.x1,
+                                    y1: word.bbox.y1,
+                                },
+                            });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return results;
+}
+export async function terminateOcr() {
+    if (worker) {
+        await worker.terminate();
+        worker = null;
+    }
+}
+export function searchText(ocrResults, searchTerm) {
+    const lowerSearch = searchTerm.toLowerCase();
+    const matches = ocrResults.filter((result) => result.text.toLowerCase().includes(lowerSearch));
+    // Index represents position in filtered matches (0, 1, 2...) for use with elementIndex tap
+    // This is intentional - users tap by match index, not original OCR result position
+    return matches.map((match, index) => ({
+        index,
+        text: match.text,
+        bounds: `[${match.bounds.x0},${match.bounds.y0}][${match.bounds.x1},${match.bounds.y1}]`,
+        center: {
+            x: Math.round((match.bounds.x0 + match.bounds.x1) / 2),
+            y: Math.round((match.bounds.y0 + match.bounds.y1) / 2),
+        },
+        confidence: match.confidence,
+    }));
+}

package/dist/services/process-runner.d.ts

@@ -1,3 +1,4 @@
+import type { EnvironmentService } from "./environment.js";
 export interface RunOptions {
     timeoutMs?: number;
     cwd?: string;
@@ -8,8 +9,13 @@ export interface RunResult {
     exitCode: number;
 }
 export declare class ProcessRunner {
+    private environment?;
     private readonly defaultTimeoutMs;
     private readonly maxTimeoutMs;
+    constructor(environment?: EnvironmentService | undefined);
     run(command: string, args: string[], options?: RunOptions): Promise<RunResult>;
+    runAdb(args: string[], options?: RunOptions): Promise<RunResult>;
+    runEmulator(args: string[], options?: RunOptions): Promise<RunResult>;
+    runAvdManager(args: string[], options?: RunOptions): Promise<RunResult>;
     private validateCommand;
 }

package/dist/services/process-runner.js

@@ -8,8 +8,12 @@ const BLOCKED_PATTERNS = [
     /\bformat\b/, // format commands
 ];
 export class ProcessRunner {
+    environment;
     defaultTimeoutMs = 30_000;
     maxTimeoutMs = 120_000;
+    constructor(environment) {
+        this.environment = environment;
+    }
     async run(command, args, options = {}) {
         this.validateCommand(command, args);
         const timeoutMs = Math.min(options.timeoutMs ?? this.defaultTimeoutMs, this.maxTimeoutMs);
@@ -48,6 +52,28 @@ export class ProcessRunner {
             throw error;
         }
     }
+    async runAdb(args, options = {}) {
+        if (!this.environment) {
+            // Fallback to bare "adb" if no environment service
+            return this.run("adb", args, options);
+        }
+        const adbPath = await this.environment.getAdbPath();
+        return this.run(adbPath, args, options);
+    }
+    async runEmulator(args, options = {}) {
+        if (!this.environment) {
+            return this.run("emulator", args, options);
+        }
+        const emulatorPath = await this.environment.getEmulatorPath();
+        return this.run(emulatorPath, args, options);
+    }
+    async runAvdManager(args, options = {}) {
+        if (!this.environment) {
+            return this.run("avdmanager", args, options);
+        }
+        const avdManagerPath = await this.environment.getAvdManagerPath();
+        return this.run(avdManagerPath, args, options);
+    }
     validateCommand(command, args) {
         if (BLOCKED_COMMANDS.has(command)) {
             throw new ReplicantError(ErrorCode.COMMAND_BLOCKED, `Command '${command}' is not allowed`, "Use safe commands only");

package/dist/tools/adb-app.js

@@ -5,7 +5,8 @@ export const adbAppInputSchema = z.object({
     packageName: z.string().optional(),
 });
 export async function handleAdbAppTool(input, context) {
-    const deviceId = context.deviceState.requireCurrentDevice().id;
+    const device = await context.deviceState.ensureDevice(context.adb);
+    const deviceId = device.id;
     switch (input.operation) {
         case "install": {
             if (!input.apkPath) {
@@ -52,7 +53,7 @@ export async function handleAdbAppTool(input, context) {
 }
 export const adbAppToolDefinition = {
     name: "adb-app",
-    description: "Manage applications. Operations: install, uninstall, launch, stop, clear-data, list.",
+    description: "Manage applications. Auto-selects device if only one connected. Operations: install, uninstall, launch, stop, clear-data, list.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/adb-device.d.ts

@@ -6,6 +6,7 @@ export declare const adbDeviceInputSchema: z.ZodObject<{
         select: "select";
         wait: "wait";
         properties: "properties";
+        "health-check": "health-check";
     }>;
     deviceId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;

package/dist/tools/adb-device.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 export const adbDeviceInputSchema = z.object({
-    operation: z.enum(["list", "select", "wait", "properties"]),
+    operation: z.enum(["list", "select", "wait", "properties", "health-check"]),
     deviceId: z.string().optional(),
 });
 export async function handleAdbDeviceTool(input, context) {
@@ -28,15 +28,18 @@ export async function handleAdbDeviceTool(input, context) {
             return { selected: device };
         }
         case "wait": {
-            const deviceId = input.deviceId || context.deviceState.getCurrentDevice()?.id;
-            if (!deviceId) {
-                throw new Error("No device selected. Call with deviceId or select a device first.");
-            }
+            const device = input.deviceId
+                ? { id: input.deviceId }
+                : await context.deviceState.ensureDevice(context.adb);
+            const deviceId = device.id;
             await context.adb.waitForDevice(deviceId);
             return { status: "device ready", deviceId };
         }
         case "properties": {
-            const deviceId = input.deviceId || context.deviceState.requireCurrentDevice().id;
+            const device = input.deviceId
+                ? { id: input.deviceId }
+                : await context.deviceState.ensureDevice(context.adb);
+            const deviceId = device.id;
             const props = await context.adb.getProperties(deviceId);
             return {
                 deviceId,
@@ -50,19 +53,55 @@ export async function handleAdbDeviceTool(input, context) {
                 allProperties: props,
             };
         }
+        case "health-check": {
+            const env = await context.environment.detect();
+            let adbServerRunning = false;
+            let connectedDevices = 0;
+            const warnings = [];
+            const errors = [];
+            if (!env.isValid) {
+                errors.push(...env.issues);
+            }
+            else {
+                // Test adb server
+                try {
+                    const devices = await context.adb.getDevices();
+                    adbServerRunning = true;
+                    connectedDevices = devices.length;
+                    if (devices.length === 0) {
+                        warnings.push("No devices connected. Start an emulator or connect a USB device.");
+                    }
+                }
+                catch (e) {
+                    errors.push("adb server not responding. Run 'adb kill-server && adb start-server'");
+                }
+            }
+            return {
+                healthy: errors.length === 0,
+                environment: {
+                    sdkPath: env.sdkPath,
+                    adbPath: env.adbPath,
+                    platform: env.platform,
+                },
+                adbServerRunning,
+                connectedDevices,
+                warnings,
+                errors,
+            };
+        }
         default:
             throw new Error(`Unknown operation: ${input.operation}`);
     }
 }
 export const adbDeviceToolDefinition = {
     name: "adb-device",
-    description: "Manage device connections. Operations: list, select, wait, properties.",
+    description: "Manage device connections. Operations: list, select, wait, properties, health-check.",
     inputSchema: {
         type: "object",
         properties: {
             operation: {
                 type: "string",
-                enum: ["list", "select", "wait", "properties"],
+                enum: ["list", "select", "wait", "properties", "health-check"],
             },
             deviceId: { type: "string", description: "Device ID for select/wait/properties" },
         },

package/dist/tools/adb-logcat.js

@@ -9,7 +9,8 @@ export const adbLogcatInputSchema = z.object({
     since: z.string().optional(),
 });
 export async function handleAdbLogcatTool(input, context) {
-    const deviceId = context.deviceState.requireCurrentDevice().id;
+    const device = await context.deviceState.ensureDevice(context.adb);
+    const deviceId = device.id;
     // Build filter string
     let filter = "";
     if (input.rawFilter) {
@@ -55,7 +56,7 @@ export async function handleAdbLogcatTool(input, context) {
 }
 export const adbLogcatToolDefinition = {
     name: "adb-logcat",
-    description: "Read device logs. Returns summary with logId for full output.",
+    description: "Read device logs. Auto-selects device if only one connected. Returns summary with logId for full output.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/adb-shell.js

@@ -4,7 +4,8 @@ export const adbShellInputSchema = z.object({
     timeout: z.number().optional(),
 });
 export async function handleAdbShellTool(input, context) {
-    const deviceId = context.deviceState.requireCurrentDevice().id;
+    const device = await context.deviceState.ensureDevice(context.adb);
+    const deviceId = device.id;
     const result = await context.adb.shell(deviceId, input.command, input.timeout);
     return {
         stdout: result.stdout,
@@ -15,7 +16,7 @@ export async function handleAdbShellTool(input, context) {
 }
 export const adbShellToolDefinition = {
     name: "adb-shell",
-    description: "Execute shell commands with safety guards. Dangerous commands are blocked.",
+    description: "Execute shell commands with safety guards. Auto-selects device if only one connected. Dangerous commands are blocked.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/gradle-get-details.d.ts

@@ -5,8 +5,8 @@ export declare const gradleGetDetailsInputSchema: z.ZodObject<{
     detailType: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
         all: "all";
         tasks: "tasks";
-        logs: "logs";
         errors: "errors";
+        logs: "logs";
     }>>>;
 }, z.core.$strip>;
 export type GradleGetDetailsInput = z.infer<typeof gradleGetDetailsInputSchema>;

package/dist/tools/ui.d.ts

@@ -20,6 +20,8 @@ export declare const uiInputSchema: z.ZodObject<{
     elementIndex: z.ZodOptional<z.ZodNumber>;
     text: z.ZodOptional<z.ZodString>;
     localPath: z.ZodOptional<z.ZodString>;
+    inline: z.ZodOptional<z.ZodBoolean>;
+    debug: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type UiInput = z.infer<typeof uiInputSchema>;
 export declare function handleUiTool(input: UiInput, context: ServerContext): Promise<Record<string, unknown>>;
@@ -71,6 +73,14 @@ export declare const uiToolDefinition: {
                 type: string;
                 description: string;
             };
+            inline: {
+                type: string;
+                description: string;
+            };
+            debug: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
     };

package/dist/tools/ui.js

@@ -13,11 +13,26 @@ export const uiInputSchema = z.object({
     elementIndex: z.number().optional(),
     text: z.string().optional(),
     localPath: z.string().optional(),
+    inline: z.boolean().optional(),
+    debug: z.boolean().optional(),
 });
 // Store last find results for elementIndex reference
+// Updated to support both accessibility and OCR elements
 let lastFindResults = [];
+// Helper to get center coordinates from either element type
+function getElementCenter(element) {
+    if ("centerX" in element) {
+        // AccessibilityNode
+        return { x: element.centerX, y: element.centerY };
+    }
+    else {
+        // OcrElement
+        return element.center;
+    }
+}
 export async function handleUiTool(input, context) {
-    const deviceId = context.deviceState.requireCurrentDevice().id;
+    const device = await context.deviceState.ensureDevice(context.adb);
+    const deviceId = device.id;
     switch (input.operation) {
         case "dump": {
             const tree = await context.ui.dump(deviceId);
@@ -43,6 +58,49 @@ export async function handleUiTool(input, context) {
             if (!input.selector) {
                 throw new Error("selector is required for find operation");
             }
+            const debug = input.debug ?? false;
+            // Use findWithOcrFallback for text-based selectors
+            if (input.selector.text || input.selector.textContains) {
+                const result = await context.ui.findWithOcrFallback(deviceId, input.selector, { debug });
+                lastFindResults = result.elements;
+                const response = {
+                    elements: result.elements.map((el, index) => {
+                        if ("centerX" in el) {
+                            // AccessibilityNode
+                            return {
+                                index,
+                                text: el.text,
+                                resourceId: el.resourceId,
+                                className: el.className,
+                                centerX: el.centerX,
+                                centerY: el.centerY,
+                                bounds: el.bounds,
+                                clickable: el.clickable,
+                            };
+                        }
+                        else {
+                            // OcrElement
+                            return {
+                                index,
+                                text: el.text,
+                                center: el.center,
+                                bounds: el.bounds,
+                                confidence: debug ? el.confidence : undefined,
+                            };
+                        }
+                    }),
+                    count: result.elements.length,
+                    deviceId,
+                };
+                if (debug) {
+                    response.source = result.source;
+                    if (result.fallbackReason) {
+                        response.fallbackReason = result.fallbackReason;
+                    }
+                }
+                return response;
+            }
+            // Non-text selectors use regular find (no OCR fallback)
             const elements = await context.ui.find(deviceId, input.selector);
             lastFindResults = elements;
             return {
@@ -67,8 +125,9 @@ export async function handleUiTool(input, context) {
                     throw new Error(`Element at index ${input.elementIndex} not found. Run 'find' first.`);
                 }
                 const element = lastFindResults[input.elementIndex];
-                x = element.centerX;
-                y = element.centerY;
+                const center = getElementCenter(element);
+                x = center.x;
+                y = center.y;
             }
             else if (input.x !== undefined && input.y !== undefined) {
                 x = input.x;
@@ -88,9 +147,11 @@ export async function handleUiTool(input, context) {
             return { input: input.text, deviceId };
         }
         case "screenshot": {
-            const localPath = input.localPath || `/tmp/screenshot-${Date.now()}.png`;
-            await context.ui.screenshot(deviceId, localPath);
-            return { path: localPath, deviceId };
+            const result = await context.ui.screenshot(deviceId, {
+                localPath: input.localPath,
+                inline: input.inline,
+            });
+            return { ...result, deviceId };
         }
         case "accessibility-check": {
             const result = await context.ui.accessibilityCheck(deviceId);
@@ -102,7 +163,7 @@ export async function handleUiTool(input, context) {
 }
 export const uiToolDefinition = {
     name: "ui",
-    description: "Interact with app UI via accessibility tree. Operations: dump, find, tap, input, screenshot, accessibility-check.",
+    description: "Interact with app UI via accessibility tree. Auto-selects device if only one connected. Operations: dump, find, tap, input, screenshot, accessibility-check.",
     inputSchema: {
         type: "object",
         properties: {
@@ -124,7 +185,9 @@ export const uiToolDefinition = {
             y: { type: "number", description: "Y coordinate (for tap)" },
             elementIndex: { type: "number", description: "Element index from last find (for tap)" },
             text: { type: "string", description: "Text to input" },
-            localPath: { type: "string", description: "Local path for screenshot" },
+            localPath: { type: "string", description: "Local path for screenshot (default: /tmp/replicant-screenshot-{timestamp}.png)" },
+            inline: { type: "boolean", description: "Return base64 instead of file path (token-heavy, use sparingly)" },
+            debug: { type: "boolean", description: "Include source (accessibility/ocr) and confidence in response" },
         },
         required: ["operation"],
     },

package/dist/types/errors.d.ts

@@ -9,13 +9,30 @@ export declare const ErrorCode: {
     readonly PACKAGE_NOT_FOUND: "PACKAGE_NOT_FOUND";
     readonly INSTALL_FAILED: "INSTALL_FAILED";
     readonly AVD_NOT_FOUND: "AVD_NOT_FOUND";
+    readonly EMULATOR_NOT_FOUND: "EMULATOR_NOT_FOUND";
     readonly EMULATOR_START_FAILED: "EMULATOR_START_FAILED";
     readonly SNAPSHOT_NOT_FOUND: "SNAPSHOT_NOT_FOUND";
     readonly COMMAND_BLOCKED: "COMMAND_BLOCKED";
     readonly TIMEOUT: "TIMEOUT";
     readonly CACHE_MISS: "CACHE_MISS";
+    readonly SDK_NOT_FOUND: "SDK_NOT_FOUND";
+    readonly ADB_NOT_FOUND: "ADB_NOT_FOUND";
+    readonly ADB_NOT_EXECUTABLE: "ADB_NOT_EXECUTABLE";
+    readonly ADB_SERVER_ERROR: "ADB_SERVER_ERROR";
+    readonly NO_DEVICES: "NO_DEVICES";
+    readonly MULTIPLE_DEVICES: "MULTIPLE_DEVICES";
+    readonly SCREENSHOT_FAILED: "SCREENSHOT_FAILED";
+    readonly PULL_FAILED: "PULL_FAILED";
+    readonly HEALTH_CHECK_FAILED: "HEALTH_CHECK_FAILED";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+export interface ErrorContext {
+    command?: string;
+    exitCode?: number;
+    stderr?: string;
+    checkedPaths?: string[];
+    [key: string]: unknown;
+}
 export interface ToolError {
     error: ErrorCode;
     message: string;
@@ -25,7 +42,13 @@ export interface ToolError {
 export declare class ReplicantError extends Error {
     readonly code: ErrorCode;
     readonly suggestion?: string | undefined;
-    readonly details?: Record<string, unknown> | undefined;
-    constructor(code: ErrorCode, message: string, suggestion?: string | undefined, details?: Record<string, unknown> | undefined);
+    readonly context?: ErrorContext | undefined;
+    constructor(code: ErrorCode, message: string, suggestion?: string | undefined, context?: ErrorContext | undefined);
+    toJSON(): {
+        error: ErrorCode;
+        message: string;
+        suggestion: string | undefined;
+        context: ErrorContext | undefined;
+    };
     toToolError(): ToolError;
 }

package/dist/types/errors.js

@@ -13,6 +13,7 @@ export const ErrorCode = {
     INSTALL_FAILED: "INSTALL_FAILED",
     // Emulator errors
     AVD_NOT_FOUND: "AVD_NOT_FOUND",
+    EMULATOR_NOT_FOUND: "EMULATOR_NOT_FOUND",
     EMULATOR_START_FAILED: "EMULATOR_START_FAILED",
     SNAPSHOT_NOT_FOUND: "SNAPSHOT_NOT_FOUND",
     // Safety errors
@@ -20,24 +21,42 @@ export const ErrorCode = {
     TIMEOUT: "TIMEOUT",
     // Cache errors
     CACHE_MISS: "CACHE_MISS",
+    // New "Just Works" UX error codes
+    SDK_NOT_FOUND: "SDK_NOT_FOUND",
+    ADB_NOT_FOUND: "ADB_NOT_FOUND",
+    ADB_NOT_EXECUTABLE: "ADB_NOT_EXECUTABLE",
+    ADB_SERVER_ERROR: "ADB_SERVER_ERROR",
+    NO_DEVICES: "NO_DEVICES",
+    MULTIPLE_DEVICES: "MULTIPLE_DEVICES",
+    SCREENSHOT_FAILED: "SCREENSHOT_FAILED",
+    PULL_FAILED: "PULL_FAILED",
+    HEALTH_CHECK_FAILED: "HEALTH_CHECK_FAILED",
 };
 export class ReplicantError extends Error {
     code;
     suggestion;
-    details;
-    constructor(code, message, suggestion, details) {
+    context;
+    constructor(code, message, suggestion, context) {
         super(message);
         this.code = code;
         this.suggestion = suggestion;
-        this.details = details;
+        this.context = context;
         this.name = "ReplicantError";
     }
+    toJSON() {
+        return {
+            error: this.code,
+            message: this.message,
+            suggestion: this.suggestion,
+            context: this.context,
+        };
+    }
     toToolError() {
         return {
             error: this.code,
             message: this.message,
             suggestion: this.suggestion,
-            details: this.details,
+            details: this.context,
         };
     }
 }

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./errors.js";
 export * from "./cache.js";
 export * from "./device.js";
+export * from "./ocr.js";

package/dist/types/index.js

@@ -1,3 +1,4 @@
 export * from "./errors.js";
 export * from "./cache.js";
 export * from "./device.js";
+export * from "./ocr.js";

package/dist/types/ocr.d.ts

@@ -0,0 +1,21 @@
+export interface OcrBounds {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+export interface OcrResult {
+    text: string;
+    confidence: number;
+    bounds: OcrBounds;
+}
+export interface OcrElement {
+    index: number;
+    text: string;
+    bounds: string;
+    center: {
+        x: number;
+        y: number;
+    };
+    confidence: number;
+}

package/dist/types/ocr.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replicant-mcp",
-  "version": "1.0.0",
+  "version": "1.0.4",
   "description": "Android MCP server for AI-assisted Android development",
   "type": "module",
   "main": "dist/index.js",
@@ -20,7 +20,6 @@
     "test:device": "tsx scripts/real-device-test.ts",
     "start": "node dist/index.js",
     "validate": "npm run build && npm run test -- --run",
-    "install-skill": "bash scripts/install-skill.sh",
     "prepublishOnly": "npm run build && npm test -- --run"
   },
   "keywords": [
@@ -52,6 +51,7 @@
     "@modelcontextprotocol/sdk": "^1.25.3",
     "commander": "^14.0.2",
     "execa": "^9.6.1",
+    "tesseract.js": "^7.0.0",
     "zod": "^4.3.5"
   },
   "devDependencies": {