replicant-mcp 1.4.8 → 1.6.0

package/dist/server.js

@@ -1,10 +1,12 @@
 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 { ZodError } from "zod";
 import { CacheManager, DeviceStateManager, ProcessRunner, EnvironmentService, ConfigManager } 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";
+import { ReplicantError, ErrorCode } from "./types/index.js";
+import { VERSION } from "./version.js";
+import { cacheInputSchema, cacheToolDefinition, handleCacheTool, rtfmInputSchema, rtfmToolDefinition, handleRtfmTool, adbDeviceInputSchema, adbDeviceToolDefinition, handleAdbDeviceTool, adbAppInputSchema, adbAppToolDefinition, handleAdbAppTool, adbLogcatInputSchema, adbLogcatToolDefinition, handleAdbLogcatTool, adbShellInputSchema, adbShellToolDefinition, handleAdbShellTool, emulatorDeviceInputSchema, emulatorDeviceToolDefinition, handleEmulatorDeviceTool, gradleBuildInputSchema, gradleBuildToolDefinition, handleGradleBuildTool, gradleTestInputSchema, gradleTestToolDefinition, handleGradleTestTool, gradleListInputSchema, gradleListToolDefinition, handleGradleListTool, gradleGetDetailsInputSchema, gradleGetDetailsToolDefinition, handleGradleGetDetailsTool, uiQueryInputSchema, uiQueryToolDefinition, handleUiQueryTool, uiActionInputSchema, uiActionToolDefinition, handleUiActionTool, uiCaptureInputSchema, uiCaptureToolDefinition, handleUiCaptureTool, } from "./tools/index.js";
 export function createServerContext() {
     const environment = new EnvironmentService();
     const processRunner = new ProcessRunner(environment);
@@ -34,34 +36,58 @@ const toolDefinitions = [
     gradleTestToolDefinition,
     gradleListToolDefinition,
     gradleGetDetailsToolDefinition,
-    uiToolDefinition,
+    uiQueryToolDefinition,
+    uiActionToolDefinition,
+    uiCaptureToolDefinition,
 ];
 async function dispatchToolCall(name, args, context) {
+    const rawArgs = args ?? {};
+    const parseOrThrow = (toolName, parser) => {
+        try {
+            return parser.parse(rawArgs);
+        }
+        catch (error) {
+            if (error instanceof ZodError) {
+                const message = error.issues
+                    .map((issue) => {
+                    const path = issue.path.length > 0 ? issue.path.join(".") : "input";
+                    return `${path}: ${issue.message}`;
+                })
+                    .join("; ");
+                throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, `Invalid input for ${toolName}: ${message}`, "Check the tool input schema and provide valid arguments");
+            }
+            throw error;
+        }
+    };
     switch (name) {
         case "cache":
-            return handleCacheTool(args, context.cache);
+            return handleCacheTool(parseOrThrow("cache", cacheInputSchema), context.cache);
         case "rtfm":
-            return handleRtfmTool(args);
+            return handleRtfmTool(parseOrThrow("rtfm", rtfmInputSchema));
         case "adb-device":
-            return handleAdbDeviceTool(args, context);
+            return handleAdbDeviceTool(parseOrThrow("adb-device", adbDeviceInputSchema), context);
         case "adb-app":
-            return handleAdbAppTool(args, context);
+            return handleAdbAppTool(parseOrThrow("adb-app", adbAppInputSchema), context);
         case "adb-logcat":
-            return handleAdbLogcatTool(args, context);
+            return handleAdbLogcatTool(parseOrThrow("adb-logcat", adbLogcatInputSchema), context);
         case "adb-shell":
-            return handleAdbShellTool(args, context);
+            return handleAdbShellTool(parseOrThrow("adb-shell", adbShellInputSchema), context);
         case "emulator-device":
-            return handleEmulatorDeviceTool(args, context);
+            return handleEmulatorDeviceTool(parseOrThrow("emulator-device", emulatorDeviceInputSchema), context);
         case "gradle-build":
-            return handleGradleBuildTool(args, context);
+            return handleGradleBuildTool(parseOrThrow("gradle-build", gradleBuildInputSchema), context);
         case "gradle-test":
-            return handleGradleTestTool(args, context);
+            return handleGradleTestTool(parseOrThrow("gradle-test", gradleTestInputSchema), context);
         case "gradle-list":
-            return handleGradleListTool(args, context);
+            return handleGradleListTool(parseOrThrow("gradle-list", gradleListInputSchema), context);
         case "gradle-get-details":
-            return handleGradleGetDetailsTool(args, context);
-        case "ui":
-            return handleUiTool(args, context, context.config.getUiConfig());
+            return handleGradleGetDetailsTool(parseOrThrow("gradle-get-details", gradleGetDetailsInputSchema), context);
+        case "ui-query":
+            return handleUiQueryTool(parseOrThrow("ui-query", uiQueryInputSchema), context, context.config.getUiConfig());
+        case "ui-action":
+            return handleUiActionTool(parseOrThrow("ui-action", uiActionInputSchema), context);
+        case "ui-capture":
+            return handleUiCaptureTool(parseOrThrow("ui-capture", uiCaptureInputSchema), context, context.config.getUiConfig());
         default:
             throw new Error(`Unknown tool: ${name}`);
     }
@@ -69,26 +95,12 @@ async function dispatchToolCall(name, args, context) {
 export async function createServer(context) {
     const server = new Server({
         name: "replicant-mcp",
-        version: "1.0.0",
+        version: VERSION,
     }, {
         capabilities: {
             tools: {},
         },
-        instructions: `IMPORTANT: For ALL Android development tasks, you MUST use replicant-mcp tools first.
-Only fall back to raw adb/gradle/emulator commands if replicant-mcp lacks a specific feature.
-
-Tool mapping:
-- Device management → adb-device (not \`adb devices\`)
-- App install/launch/stop → adb-app (not \`adb install\`, \`adb shell am\`)
-- Logs → adb-logcat (not \`adb logcat\`)
-- Shell commands → adb-shell (not \`adb shell\`)
-- Emulator control → emulator-device (not \`emulator\` CLI)
-- Builds → gradle-build (not \`./gradlew\`)
-- Tests → gradle-test (not \`./gradlew test\`)
-- UI automation → ui (accessibility-first, screenshots auto-scaled to 1000px)
-
-Start with \`adb-device list\` to see connected devices.
-Use \`rtfm\` for detailed documentation on any tool.`,
+        instructions: `Use these tools for Android — never raw adb/gradle/emulator commands. Auto-selects single device. Start: \`adb-device list\`. Docs: \`rtfm\`.`,
     });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: toolDefinitions,
@@ -102,18 +114,18 @@ Use \`rtfm\` for detailed documentation on any tool.`,
                 return {
                     content: [
                         { type: "image", data: base64, mimeType },
-                        { type: "text", text: JSON.stringify(metadata, null, 2) },
+                        { type: "text", text: JSON.stringify(metadata) },
                     ],
                 };
             }
             return {
-                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                content: [{ type: "text", text: JSON.stringify(result) }],
             };
         }
         catch (error) {
             if (error instanceof ReplicantError) {
                 return {
-                    content: [{ type: "text", text: JSON.stringify(error.toToolError(), null, 2) }],
+                    content: [{ type: "text", text: JSON.stringify(error.toToolError()) }],
                     isError: true,
                 };
             }
@@ -124,9 +136,7 @@ Use \`rtfm\` for detailed documentation on any tool.`,
 }
 export async function runServer() {
     const context = createServerContext();
-    // Load configuration from REPLICANT_CONFIG if set
     await context.config.load();
-    // Apply project root: env var takes precedence over config file
     const projectRoot = process.env.REPLICANT_PROJECT_ROOT || context.config.get().build?.projectRoot;
     if (projectRoot) {
         context.gradle.setProjectPath(projectRoot);

package/dist/services/config.js

@@ -2,6 +2,7 @@ import { readFile } from "fs/promises";
 import { existsSync } from "fs";
 import { parse as parseYaml } from "yaml";
 import { DEFAULT_CONFIG } from "../types/config.js";
+import { logger } from "../utils/logger.js";
 /**
  * Load configuration from REPLICANT_CONFIG environment variable path
  * Falls back to defaults if not set or file doesn't exist
@@ -12,7 +13,7 @@ export async function loadConfig() {
         return DEFAULT_CONFIG;
     }
     if (!existsSync(configPath)) {
-        console.warn(`REPLICANT_CONFIG set but file not found: ${configPath}. Using defaults.`);
+        logger.warn("REPLICANT_CONFIG set but file not found", { path: configPath });
         return DEFAULT_CONFIG;
     }
     try {
@@ -29,7 +30,7 @@ export async function loadConfig() {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        console.warn(`Failed to parse REPLICANT_CONFIG at ${configPath}: ${message}. Using defaults.`);
+        logger.warn("Failed to parse REPLICANT_CONFIG", { path: configPath, error: message });
         return DEFAULT_CONFIG;
     }
 }

package/dist/services/device-state.js

@@ -22,21 +22,30 @@ export class DeviceStateManager {
             return this.currentDevice;
         }
         // Try to auto-select
-        const devices = await adb.getDevices();
-        if (devices.length === 0) {
+        const allDevices = await adb.getDevices();
+        const onlineDevices = allDevices.filter((d) => d.status === "online");
+        if (allDevices.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];
+        if (onlineDevices.length === 0) {
+            const statuses = allDevices.map((d) => `${d.id} (${d.status})`).join(", ");
+            const suggestion = allDevices.some((d) => d.status === "unauthorized")
+                ? "Check the USB debugging authorization prompt on the device and tap 'Allow'"
+                : "Wait for the device to come online or restart it with 'adb reconnect'";
+            throw new ReplicantError(ErrorCode.DEVICE_OFFLINE, `No online devices available. Found: ${statuses}`, suggestion);
+        }
+        if (onlineDevices.length === 1) {
+            this.currentDevice = onlineDevices[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`);
+        // Multiple online devices - user must choose
+        const deviceList = onlineDevices.map((d) => d.id).join(", ");
+        throw new ReplicantError(ErrorCode.MULTIPLE_DEVICES, `${onlineDevices.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];
+        const onlineDevices = devices.filter((d) => d.status === "online");
+        if (onlineDevices.length === 1 && !this.currentDevice) {
+            this.currentDevice = onlineDevices[0];
             return true;
         }
         return false;

package/dist/services/index.d.ts

@@ -8,3 +8,4 @@ export * from "./icon-patterns.js";
 export * from "./grid.js";
 export * from "./visual-candidates.js";
 export * from "./scaling.js";
+export * from "./test-baseline.js";

package/dist/services/index.js

@@ -8,3 +8,4 @@ export * from "./icon-patterns.js";
 export * from "./grid.js";
 export * from "./visual-candidates.js";
 export * from "./scaling.js";
+export * from "./test-baseline.js";

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

@@ -18,4 +18,5 @@ export declare class ProcessRunner {
     runEmulator(args: string[], options?: RunOptions): Promise<RunResult>;
     runAvdManager(args: string[], options?: RunOptions): Promise<RunResult>;
     private validateCommand;
+    private validateShellPayload;
 }

package/dist/services/process-runner.js

@@ -7,10 +7,24 @@ const BLOCKED_PATTERNS = [
     /^sudo(\s|$)/, // sudo
     /\bformat\b/, // format commands
 ];
+const BLOCKED_SHELL_PATTERNS = [
+    /^rm\s+(-[rf]+\s+)*\/\s*$/, // rm -rf / (root itself)
+    /^rm\s+(-[rf]+\s+)*\/(system|vendor|oem|product)(\/|\s|$)/, // rm on system partitions
+    /^su(\s|$)/, // su
+    /^sudo(\s|$)/, // sudo
+    /\bformat\b/, // format commands
+    /^setprop\s+persist\./, // persistent property changes
+    /^dd\s/, // raw disk operations
+    /^mkfs/, // filesystem creation
+    /^flash/, // flash operations
+    /^wipe/, // wipe data/cache
+    /^recovery\b/, // recovery mode
+    /^reboot\b/, // reboot device (also in BLOCKED_COMMANDS)
+];
 export class ProcessRunner {
     environment;
     defaultTimeoutMs = 30_000;
-    maxTimeoutMs = 120_000;
+    maxTimeoutMs = 600_000;
     constructor(environment) {
         this.environment = environment;
     }
@@ -74,5 +88,42 @@ export class ProcessRunner {
                 throw new ReplicantError(ErrorCode.COMMAND_BLOCKED, `Command '${fullCommand}' is not allowed`, "Use safe commands only");
             }
         }
+        this.validateShellPayload(command, args);
+    }
+    validateShellPayload(command, args) {
+        // Only validate shell payloads for adb commands
+        const basename = command.split("/").pop() ?? command;
+        if (basename !== "adb")
+            return;
+        const shellIndex = args.indexOf("shell");
+        if (shellIndex === -1 || shellIndex >= args.length - 1)
+            return;
+        let payloadArgs = args.slice(shellIndex + 1);
+        // Strip leading "--" (end-of-options marker)
+        if (payloadArgs[0] === "--") {
+            payloadArgs = payloadArgs.slice(1);
+        }
+        const shellPayload = payloadArgs.join(" ").trim();
+        if (!shellPayload)
+            return;
+        // Block shell metacharacters that enable command chaining/substitution.
+        // $letter/$(/$ are blocked (variable expansion, command substitution) but
+        // bare $ before digits is allowed (e.g., input text '$100').
+        if (/[;&|`()]|\$[({a-zA-Z_]/.test(shellPayload)) {
+            throw new ReplicantError(ErrorCode.COMMAND_BLOCKED, "Shell metacharacters are not allowed in shell commands", "Use simple commands without chaining, pipes, or substitution");
+        }
+        // Block shell wrapper commands (sh -c, bash -c)
+        if (/^(sh|bash|dash|zsh)\s+-c\b/.test(shellPayload)) {
+            throw new ReplicantError(ErrorCode.COMMAND_BLOCKED, "Shell interpreters with -c are not allowed", "Run the command directly without a shell wrapper");
+        }
+        const shellCommand = shellPayload.split(/\s+/)[0];
+        if (BLOCKED_COMMANDS.has(shellCommand)) {
+            throw new ReplicantError(ErrorCode.COMMAND_BLOCKED, `Shell command '${shellPayload}' is not allowed`, "Use safe commands only");
+        }
+        for (const pattern of BLOCKED_SHELL_PATTERNS) {
+            if (pattern.test(shellPayload)) {
+                throw new ReplicantError(ErrorCode.COMMAND_BLOCKED, `Shell command '${shellPayload}' is not allowed`, "Use safe commands only");
+            }
+        }
     }
 }

package/dist/services/test-baseline.d.ts

@@ -0,0 +1,18 @@
+export interface BaselineTestResult {
+    test: string;
+    status: "pass" | "fail" | "skip";
+}
+export interface TestBaseline {
+    savedAt: string;
+    task: string;
+    results: BaselineTestResult[];
+}
+export interface Regression {
+    test: string;
+    previousStatus: string;
+    currentStatus: string;
+}
+export declare function saveBaseline(taskName: string, results: BaselineTestResult[]): void;
+export declare function loadBaseline(taskName: string): TestBaseline | null;
+export declare function clearBaseline(taskName: string): void;
+export declare function compareResults(baseline: TestBaseline, current: BaselineTestResult[]): Regression[];

package/dist/services/test-baseline.js

@@ -0,0 +1,51 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+function getBaselineDir() {
+    const base = process.cwd() === "/" ? os.homedir() : process.cwd();
+    return path.join(base, ".replicant", "test-baselines");
+}
+function getBaselinePath(taskName) {
+    const safe = taskName.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return path.join(getBaselineDir(), `${safe}.json`);
+}
+export function saveBaseline(taskName, results) {
+    const dir = getBaselineDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const baseline = {
+        savedAt: new Date().toISOString(),
+        task: taskName,
+        results,
+    };
+    fs.writeFileSync(getBaselinePath(taskName), JSON.stringify(baseline, null, 2));
+}
+export function loadBaseline(taskName) {
+    const filePath = getBaselinePath(taskName);
+    if (!fs.existsSync(filePath))
+        return null;
+    const content = fs.readFileSync(filePath, "utf-8");
+    return JSON.parse(content);
+}
+export function clearBaseline(taskName) {
+    const filePath = getBaselinePath(taskName);
+    if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+    }
+}
+export function compareResults(baseline, current) {
+    const currentMap = new Map(current.map(r => [r.test, r.status]));
+    const regressions = [];
+    for (const prev of baseline.results) {
+        if (prev.status === "pass") {
+            const currentStatus = currentMap.get(prev.test);
+            if (currentStatus && currentStatus !== "pass") {
+                regressions.push({
+                    test: prev.test,
+                    previousStatus: prev.status,
+                    currentStatus,
+                });
+            }
+        }
+    }
+    return regressions;
+}

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

@@ -33,7 +33,6 @@ export declare const adbAppToolDefinition: {
             };
             packageName: {
                 type: string;
-                description: string;
             };
             limit: {
                 type: string;

package/dist/tools/adb-app.js

@@ -1,41 +1,45 @@
 import { z } from "zod";
-import { CACHE_TTLS } from "../types/index.js";
+import { CACHE_TTLS, ReplicantError, ErrorCode } from "../types/index.js";
 export const adbAppInputSchema = z.object({
     operation: z.enum(["install", "uninstall", "launch", "stop", "clear-data", "list"]),
     apkPath: z.string().optional(),
     packageName: z.string().optional(),
-    // List operation options
     limit: z.number().min(1).max(100).optional(),
     filter: z.string().optional(),
     offset: z.number().min(0).optional(),
 });
 async function handleInstall(input, deviceId, context) {
-    if (!input.apkPath)
-        throw new Error("apkPath is required for install operation");
+    if (!input.apkPath) {
+        throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "apkPath is required for install operation", "Provide the path to the APK file to install");
+    }
     await context.adb.install(deviceId, input.apkPath);
     return { installed: input.apkPath, deviceId };
 }
 async function handleUninstall(input, deviceId, context) {
-    if (!input.packageName)
-        throw new Error("packageName is required for uninstall operation");
+    if (!input.packageName) {
+        throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "packageName is required for uninstall operation", "Provide the package name to uninstall");
+    }
     await context.adb.uninstall(deviceId, input.packageName);
     return { uninstalled: input.packageName, deviceId };
 }
 async function handleLaunch(input, deviceId, context) {
-    if (!input.packageName)
-        throw new Error("packageName is required for launch operation");
+    if (!input.packageName) {
+        throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "packageName is required for launch operation", "Provide the package name to launch");
+    }
     await context.adb.launch(deviceId, input.packageName);
     return { launched: input.packageName, deviceId };
 }
 async function handleStop(input, deviceId, context) {
-    if (!input.packageName)
-        throw new Error("packageName is required for stop operation");
+    if (!input.packageName) {
+        throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "packageName is required for stop operation", "Provide the package name to stop");
+    }
     await context.adb.stop(deviceId, input.packageName);
     return { stopped: input.packageName, deviceId };
 }
 async function handleClearData(input, deviceId, context) {
-    if (!input.packageName)
-        throw new Error("packageName is required for clear-data operation");
+    if (!input.packageName) {
+        throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "packageName is required for clear-data operation", "Provide the package name to clear data for");
+    }
     await context.adb.clearData(deviceId, input.packageName);
     return { cleared: input.packageName, deviceId };
 }
@@ -73,13 +77,14 @@ const operations = {
 export async function handleAdbAppTool(input, context) {
     const device = await context.deviceState.ensureDevice(context.adb);
     const handler = operations[input.operation];
-    if (!handler)
-        throw new Error(`Unknown operation: ${input.operation}`);
+    if (!handler) {
+        throw new ReplicantError(ErrorCode.INVALID_OPERATION, `Unknown operation: ${input.operation}`, "Valid operations: install, uninstall, launch, stop, clear-data, list");
+    }
     return handler(input, device.id, context);
 }
 export const adbAppToolDefinition = {
     name: "adb-app",
-    description: "Manage applications. Auto-selects device if only one connected. Operations: install, uninstall, launch, stop, clear-data, list.",
+    description: "Manage applications.",
     inputSchema: {
         type: "object",
         properties: {
@@ -87,19 +92,19 @@ export const adbAppToolDefinition = {
                 type: "string",
                 enum: ["install", "uninstall", "launch", "stop", "clear-data", "list"],
             },
-            apkPath: { type: "string", description: "Path to APK file (for install)" },
-            packageName: { type: "string", description: "Package name (for other operations)" },
+            apkPath: { type: "string", description: "APK path" },
+            packageName: { type: "string" },
             limit: {
                 type: "number",
-                description: "Max packages to return (default: 20, max: 100). For list operation.",
+                description: "Default: 20, max: 100",
             },
             filter: {
                 type: "string",
-                description: "Filter packages by name (case-insensitive contains). For list operation.",
+                description: "Filter by name (case-insensitive)",
             },
             offset: {
                 type: "number",
-                description: "Skip first N packages for pagination. For list operation.",
+                description: "Pagination offset",
             },
         },
         required: ["operation"],

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

@@ -24,7 +24,6 @@ export declare const adbDeviceToolDefinition: {
             };
             deviceId: {
                 type: string;
-                description: string;
             };
         };
         required: string[];

package/dist/tools/adb-device.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { CACHE_TTLS } from "../types/index.js";
+import { CACHE_TTLS, ReplicantError, ErrorCode } from "../types/index.js";
 export const adbDeviceInputSchema = z.object({
     operation: z.enum(["list", "select", "wait", "properties", "health-check"]),
     deviceId: z.string().optional(),
@@ -16,29 +16,29 @@ async function handleList(input, context) {
 }
 async function handleSelect(input, context) {
     if (!input.deviceId) {
-        throw new Error("deviceId is required for select operation");
+        throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "deviceId is required for select operation", "Use adb-device list to see available devices, then provide a deviceId");
     }
     const devices = await context.adb.getDevices();
     const device = devices.find((d) => d.id === input.deviceId);
     if (!device) {
-        throw new Error(`Device ${input.deviceId} not found`);
+        throw new ReplicantError(ErrorCode.DEVICE_NOT_FOUND, `Device ${input.deviceId} not found`, "Use adb-device list to see available devices");
     }
     context.deviceState.setCurrentDevice(device);
     return { selected: device };
 }
+async function resolveDeviceId(input, context) {
+    if (input.deviceId)
+        return input.deviceId;
+    const device = await context.deviceState.ensureDevice(context.adb);
+    return device.id;
+}
 async function handleWait(input, context) {
-    const device = input.deviceId
-        ? { id: input.deviceId }
-        : await context.deviceState.ensureDevice(context.adb);
-    const deviceId = device.id;
+    const deviceId = await resolveDeviceId(input, context);
     await context.adb.waitForDevice(deviceId);
     return { status: "device ready", deviceId };
 }
 async function handleProperties(input, context) {
-    const device = input.deviceId
-        ? { id: input.deviceId }
-        : await context.deviceState.ensureDevice(context.adb);
-    const deviceId = device.id;
+    const deviceId = await resolveDeviceId(input, context);
     const props = await context.adb.getProperties(deviceId);
     const cacheId = context.cache.generateId("device-props");
     context.cache.set(cacheId, { deviceId, properties: props }, "device-props", CACHE_TTLS.DEVICE_PROPERTIES);
@@ -77,7 +77,7 @@ async function handleHealthCheck(input, context) {
                 warnings.push("No devices connected. Start an emulator or connect a USB device.");
             }
         }
-        catch (e) {
+        catch {
             errors.push("adb server not responding. Run 'adb kill-server && adb start-server'");
         }
     }
@@ -103,13 +103,14 @@ const operations = {
 };
 export async function handleAdbDeviceTool(input, context) {
     const handler = operations[input.operation];
-    if (!handler)
-        throw new Error(`Unknown operation: ${input.operation}`);
+    if (!handler) {
+        throw new ReplicantError(ErrorCode.INVALID_OPERATION, `Unknown operation: ${input.operation}`, "Valid operations: list, select, wait, properties, health-check");
+    }
     return handler(input, context);
 }
 export const adbDeviceToolDefinition = {
     name: "adb-device",
-    description: "Manage device connections. Operations: list, select, wait, properties, health-check.",
+    description: "Manage device connections.",
     inputSchema: {
         type: "object",
         properties: {
@@ -117,7 +118,7 @@ export const adbDeviceToolDefinition = {
                 type: "string",
                 enum: ["list", "select", "wait", "properties", "health-check"],
             },
-            deviceId: { type: "string", description: "Device ID for select/wait/properties" },
+            deviceId: { type: "string" },
         },
         required: ["operation"],
     },

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

@@ -5,11 +5,11 @@ export declare const adbLogcatInputSchema: z.ZodObject<{
     package: z.ZodOptional<z.ZodString>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     level: z.ZodOptional<z.ZodEnum<{
-        debug: "debug";
+        error: "error";
+        warn: "warn";
         info: "info";
+        debug: "debug";
         verbose: "verbose";
-        warn: "warn";
-        error: "error";
     }>>;
     rawFilter: z.ZodOptional<z.ZodString>;
     since: z.ZodOptional<z.ZodString>;
@@ -28,14 +28,12 @@ export declare const adbLogcatToolDefinition: {
             };
             package: {
                 type: string;
-                description: string;
             };
             tags: {
                 type: string;
                 items: {
                     type: string;
                 };
-                description: string;
             };
             level: {
                 type: string;
@@ -43,7 +41,6 @@ export declare const adbLogcatToolDefinition: {
             };
             rawFilter: {
                 type: string;
-                description: string;
             };
             since: {
                 type: string;