replicant-mcp 1.0.0 → 1.1.0

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/services/visual-candidates.d.ts

@@ -0,0 +1,24 @@
+import { AccessibilityNode, Bounds } from "../parsers/ui-dump.js";
+export declare const MIN_ICON_SIZE = 16;
+export declare const MAX_ICON_SIZE = 200;
+export declare const MIN_ASPECT_RATIO = 0.5;
+export declare const MAX_ASPECT_RATIO = 2;
+export declare const MAX_CANDIDATES = 6;
+/**
+ * Check if dimensions are within icon size constraints.
+ */
+export declare function isIconSized(width: number, height: number): boolean;
+/**
+ * Filter accessibility nodes to find unlabeled clickable elements that are icon-sized.
+ * Returns max 6 candidates sorted by position (top-to-bottom, left-to-right).
+ */
+export declare function filterIconCandidates(nodes: AccessibilityNode[]): AccessibilityNode[];
+/**
+ * Format candidate bounds as string "[x0,y0][x1,y1]"
+ */
+export declare function formatBounds(node: AccessibilityNode): string;
+/**
+ * Crop a region from an image and return as base64 JPEG.
+ * Scales down to max 128x128 if larger.
+ */
+export declare function cropCandidateImage(imagePath: string, bounds: Bounds): Promise<string>;

package/dist/services/visual-candidates.js

@@ -0,0 +1,78 @@
+import sharp from "sharp";
+export const MIN_ICON_SIZE = 16;
+export const MAX_ICON_SIZE = 200;
+export const MIN_ASPECT_RATIO = 0.5;
+export const MAX_ASPECT_RATIO = 2.0;
+export const MAX_CANDIDATES = 6;
+/**
+ * Check if dimensions are within icon size constraints.
+ */
+export function isIconSized(width, height) {
+    if (width < MIN_ICON_SIZE || width > MAX_ICON_SIZE)
+        return false;
+    if (height < MIN_ICON_SIZE || height > MAX_ICON_SIZE)
+        return false;
+    const aspectRatio = width / height;
+    if (aspectRatio < MIN_ASPECT_RATIO || aspectRatio > MAX_ASPECT_RATIO)
+        return false;
+    return true;
+}
+/**
+ * Filter accessibility nodes to find unlabeled clickable elements that are icon-sized.
+ * Returns max 6 candidates sorted by position (top-to-bottom, left-to-right).
+ */
+export function filterIconCandidates(nodes) {
+    const candidates = nodes.filter((node) => {
+        // Must be clickable
+        if (!node.clickable)
+            return false;
+        // Must not have text or contentDesc (we're looking for unlabeled icons)
+        if (node.text || node.contentDesc)
+            return false;
+        // Must be icon-sized
+        const width = node.bounds.right - node.bounds.left;
+        const height = node.bounds.bottom - node.bounds.top;
+        if (!isIconSized(width, height))
+            return false;
+        return true;
+    });
+    // Sort by Y first (top-to-bottom), then X (left-to-right)
+    candidates.sort((a, b) => {
+        if (a.centerY !== b.centerY)
+            return a.centerY - b.centerY;
+        return a.centerX - b.centerX;
+    });
+    // Limit to max candidates
+    return candidates.slice(0, MAX_CANDIDATES);
+}
+/**
+ * Format candidate bounds as string "[x0,y0][x1,y1]"
+ */
+export function formatBounds(node) {
+    return `[${node.bounds.left},${node.bounds.top}][${node.bounds.right},${node.bounds.bottom}]`;
+}
+const MAX_CROP_SIZE = 128;
+const JPEG_QUALITY = 70;
+/**
+ * Crop a region from an image and return as base64 JPEG.
+ * Scales down to max 128x128 if larger.
+ */
+export async function cropCandidateImage(imagePath, bounds) {
+    const width = bounds.right - bounds.left;
+    const height = bounds.bottom - bounds.top;
+    let pipeline = sharp(imagePath).extract({
+        left: bounds.left,
+        top: bounds.top,
+        width,
+        height,
+    });
+    // Scale down if larger than max size
+    if (width > MAX_CROP_SIZE || height > MAX_CROP_SIZE) {
+        pipeline = pipeline.resize(MAX_CROP_SIZE, MAX_CROP_SIZE, {
+            fit: "inside",
+            withoutEnlargement: true,
+        });
+    }
+    const buffer = await pipeline.jpeg({ quality: JPEG_QUALITY }).toBuffer();
+    return buffer.toString("base64");
+}

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/emulator-device.d.ts

@@ -3,8 +3,8 @@ import { ServerContext } from "../server.js";
 export declare const emulatorDeviceInputSchema: z.ZodObject<{
     operation: z.ZodEnum<{
         kill: "kill";
-        list: "list";
         create: "create";
+        list: "list";
         start: "start";
         wipe: "wipe";
         "snapshot-save": "snapshot-save";

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

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { ServerContext } from "../server.js";
+import { UiConfig } from "../types/index.js";
 export declare const uiInputSchema: z.ZodObject<{
     operation: z.ZodEnum<{
         find: "find";
@@ -8,21 +9,27 @@ export declare const uiInputSchema: z.ZodObject<{
         input: "input";
         screenshot: "screenshot";
         "accessibility-check": "accessibility-check";
+        "visual-snapshot": "visual-snapshot";
     }>;
     selector: z.ZodOptional<z.ZodObject<{
         resourceId: z.ZodOptional<z.ZodString>;
         text: z.ZodOptional<z.ZodString>;
         textContains: z.ZodOptional<z.ZodString>;
         className: z.ZodOptional<z.ZodString>;
+        nearestTo: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     x: z.ZodOptional<z.ZodNumber>;
     y: z.ZodOptional<z.ZodNumber>;
     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>;
+    gridCell: z.ZodOptional<z.ZodNumber>;
+    gridPosition: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type UiInput = z.infer<typeof uiInputSchema>;
-export declare function handleUiTool(input: UiInput, context: ServerContext): Promise<Record<string, unknown>>;
+export declare function handleUiTool(input: UiInput, context: ServerContext, uiConfig?: UiConfig): Promise<Record<string, unknown>>;
 export declare const uiToolDefinition: {
     name: string;
     description: string;
@@ -48,6 +55,10 @@ export declare const uiToolDefinition: {
                     className: {
                         type: string;
                     };
+                    nearestTo: {
+                        type: string;
+                        description: string;
+                    };
                 };
                 description: string;
             };
@@ -71,6 +82,26 @@ export declare const uiToolDefinition: {
                 type: string;
                 description: string;
             };
+            inline: {
+                type: string;
+                description: string;
+            };
+            debug: {
+                type: string;
+                description: string;
+            };
+            gridCell: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
+            gridPosition: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
         };
         required: string[];
     };