replicant-mcp 1.6.2 → 1.6.4

package/dist/tools/index.d.ts

@@ -13,3 +13,200 @@ export * from "./ui-query.js";
 export * from "./ui-action.js";
 export * from "./ui-capture.js";
 export * from "./ui-find.js";
+export declare const ALL_TOOL_DEFINITIONS: readonly [{
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+}, {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+}, {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+}, {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+}, {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+}, {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+}, {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+}, {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+}, {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+}, {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+}, {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+}, {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+}, {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+}, {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+}];

package/dist/tools/index.js

@@ -13,3 +13,36 @@ export * from "./ui-query.js";
 export * from "./ui-action.js";
 export * from "./ui-capture.js";
 export * from "./ui-find.js";
+import { cacheToolDefinition } from "./cache.js";
+import { rtfmToolDefinition } from "./rtfm.js";
+import { adbDeviceToolDefinition } from "./adb-device.js";
+import { adbAppToolDefinition } from "./adb-app.js";
+import { adbLogcatToolDefinition } from "./adb-logcat.js";
+import { adbShellToolDefinition } from "./adb-shell.js";
+import { emulatorDeviceToolDefinition } from "./emulator-device.js";
+import { gradleBuildToolDefinition } from "./gradle-build.js";
+import { gradleTestToolDefinition } from "./gradle-test.js";
+import { gradleListToolDefinition } from "./gradle-list.js";
+import { gradleGetDetailsToolDefinition } from "./gradle-get-details.js";
+import { uiQueryToolDefinition } from "./ui-query.js";
+import { uiActionToolDefinition } from "./ui-action.js";
+import { uiCaptureToolDefinition } from "./ui-capture.js";
+// Single registry of all MCP tool definitions. Consumed by the server at
+// registration time, the contract generator, and the token-snapshot
+// generator — so adding a tool here is enough to keep all three in sync.
+export const ALL_TOOL_DEFINITIONS = [
+    cacheToolDefinition,
+    rtfmToolDefinition,
+    adbDeviceToolDefinition,
+    adbAppToolDefinition,
+    adbLogcatToolDefinition,
+    adbShellToolDefinition,
+    emulatorDeviceToolDefinition,
+    gradleBuildToolDefinition,
+    gradleTestToolDefinition,
+    gradleListToolDefinition,
+    gradleGetDetailsToolDefinition,
+    uiQueryToolDefinition,
+    uiActionToolDefinition,
+    uiCaptureToolDefinition,
+];

package/dist/tools/rtfm.d.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 export declare const rtfmInputSchema: z.ZodObject<{
     category: z.ZodOptional<z.ZodString>;
     tool: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
+}, z.core.$strict>;
 export type RtfmInput = z.infer<typeof rtfmInputSchema>;
 export declare function handleRtfmTool(input: RtfmInput): Promise<{
     content: string;
@@ -11,17 +11,9 @@ export declare const rtfmToolDefinition: {
     name: string;
     description: string;
     inputSchema: {
-        type: string;
-        properties: {
-            category: {
-                type: string;
-                description: string;
-            };
-            tool: {
-                type: string;
-                description: string;
-            };
-        };
+        type: "object";
+        properties?: Record<string, unknown>;
+        required?: string[];
     };
     annotations: {
         readOnlyHint: boolean;

package/dist/tools/rtfm.js

@@ -2,11 +2,16 @@ import { z } from "zod";
 import { readFile } from "fs/promises";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
+import { toolSchema } from "../schemas/inputs.js";
+import { toMcpJsonSchema } from "../schemas/derive.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const RTFM_DIR = join(__dirname, "../../docs/rtfm");
-export const rtfmInputSchema = z.object({
-    category: z.string().optional(),
-    tool: z.string().optional(),
+export const rtfmInputSchema = toolSchema({
+    category: z
+        .string()
+        .optional()
+        .describe("Category: build, adb, emulator, ui, cache, index"),
+    tool: z.string().optional().describe("Tool name (e.g., 'ui-query') for tool-specific docs"),
 });
 const TOOL_TO_CATEGORY = {
     "gradle-build": "build",
@@ -55,14 +60,8 @@ function extractToolSection(content, toolName) {
 }
 export const rtfmToolDefinition = {
     name: "rtfm",
-    description: "Get documentation. Pass category or tool name.",
-    inputSchema: {
-        type: "object",
-        properties: {
-            category: { type: "string", description: "Category: build, adb, emulator, ui, cache" },
-            tool: { type: "string", description: "Tool name for specific docs" },
-        },
-    },
+    description: "Get documentation. Pass category ('build'|'adb'|'emulator'|'ui'|'cache'|'index') or tool (tool name like 'ui-query').",
+    inputSchema: toMcpJsonSchema(rtfmInputSchema),
     annotations: {
         readOnlyHint: true,
         destructiveHint: false,

package/dist/tools/ui-action.d.ts

@@ -1,14 +1,22 @@
 import { z } from "zod";
 import { ServerContext } from "../server.js";
+import { UiConfig } from "../types/index.js";
 export declare const uiActionInputSchema: z.ZodObject<{
     operation: z.ZodEnum<{
         tap: "tap";
         input: "input";
         scroll: "scroll";
     }>;
-    x: z.ZodOptional<z.ZodNumber>;
-    y: z.ZodOptional<z.ZodNumber>;
-    elementIndex: z.ZodOptional<z.ZodNumber>;
+    x: z.ZodOptional<z.ZodPipe<z.ZodTransform<string | number, unknown>, z.ZodCoercedNumber<unknown>>>;
+    y: z.ZodOptional<z.ZodPipe<z.ZodTransform<string | number, unknown>, z.ZodCoercedNumber<unknown>>>;
+    elementIndex: z.ZodOptional<z.ZodPipe<z.ZodTransform<string | number, unknown>, z.ZodCoercedNumber<unknown>>>;
+    selector: z.ZodOptional<z.ZodPipe<z.ZodTransform<any, unknown>, 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.$strict>>>;
     text: z.ZodOptional<z.ZodString>;
     direction: z.ZodOptional<z.ZodEnum<{
         up: "up";
@@ -16,49 +24,18 @@ export declare const uiActionInputSchema: z.ZodObject<{
         left: "left";
         right: "right";
     }>>;
-    amount: z.ZodOptional<z.ZodNumber>;
-    deviceSpace: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strip>;
+    amount: z.ZodOptional<z.ZodPipe<z.ZodTransform<string | number, unknown>, z.ZodCoercedNumber<unknown>>>;
+    deviceSpace: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodBoolean>>;
+}, z.core.$strict>;
 export type UiActionInput = z.infer<typeof uiActionInputSchema>;
-export declare function handleUiActionTool(input: UiActionInput, context: ServerContext): Promise<Record<string, unknown>>;
+export declare function handleUiActionTool(input: UiActionInput, context: ServerContext, uiConfig?: UiConfig): Promise<Record<string, unknown>>;
 export declare const uiActionToolDefinition: {
     name: string;
     description: string;
     inputSchema: {
-        type: string;
-        properties: {
-            operation: {
-                type: string;
-                enum: string[];
-            };
-            x: {
-                type: string;
-            };
-            y: {
-                type: string;
-            };
-            elementIndex: {
-                type: string;
-            };
-            text: {
-                type: string;
-            };
-            direction: {
-                type: string;
-                enum: string[];
-            };
-            amount: {
-                type: string;
-                minimum: number;
-                maximum: number;
-                description: string;
-            };
-            deviceSpace: {
-                type: string;
-                description: string;
-            };
-        };
-        required: string[];
+        type: "object";
+        properties?: Record<string, unknown>;
+        required?: string[];
     };
     annotations: {
         readOnlyHint: boolean;

package/dist/tools/ui-action.js

@@ -1,32 +1,145 @@
 import { z } from "zod";
 import { ReplicantError, ErrorCode } from "../types/index.js";
-import { getElementCenter } from "./ui-find.js";
-export const uiActionInputSchema = z.object({
+import { DEFAULT_CONFIG } from "../types/config.js";
+import { getElementCenter, handleFind, isAccessibilityNode } from "./ui-find.js";
+import { flattenTree } from "../parsers/ui-dump.js";
+import { booleanInput, jsonObjectInput, numberInput, toolSchema } from "../schemas/inputs.js";
+import { toMcpJsonSchema } from "../schemas/derive.js";
+export const uiActionInputSchema = toolSchema({
     operation: z.enum(["tap", "input", "scroll"]),
-    x: z.number().optional(),
-    y: z.number().optional(),
-    elementIndex: z.number().optional(),
+    x: numberInput().optional(),
+    y: numberInput().optional(),
+    elementIndex: numberInput().optional(),
+    selector: jsonObjectInput({
+        resourceId: z.string().optional(),
+        text: z.string().optional(),
+        textContains: z.string().optional(),
+        className: z.string().optional(),
+        nearestTo: z.string().optional(),
+    }).optional(),
     text: z.string().optional(),
     direction: z.enum(["up", "down", "left", "right"]).optional(),
-    amount: z.number().min(0).max(1).optional(),
-    deviceSpace: z.boolean().optional(),
+    amount: numberInput({ min: 0, max: 1 })
+        .optional()
+        .describe("Scroll fraction (0-1, default: 0.5)"),
+    deviceSpace: booleanInput()
+        .optional()
+        .describe("x/y in device-space (default true). Set false only for image-space coords."),
 });
 const operations = {
     tap: handleTap,
     input: handleInput,
     scroll: handleScroll,
 };
-export async function handleUiActionTool(input, context) {
+export async function handleUiActionTool(input, context, uiConfig) {
     const device = await context.deviceState.ensureDevice(context.adb);
+    const config = uiConfig ?? DEFAULT_CONFIG.ui;
     const handler = operations[input.operation];
     if (!handler) {
         throw new ReplicantError(ErrorCode.INVALID_OPERATION, `Unknown operation: ${input.operation}`, "Valid operations: tap, input, scroll");
     }
-    return handler(input, context, device.id);
+    return handler(input, context, config, device.id);
 }
-async function handleTap(input, context, deviceId) {
+function describeMatches(matches) {
+    return matches.map((el, index) => {
+        const base = { index };
+        if (isAccessibilityNode(el)) {
+            base.text = el.text || el.contentDesc || undefined;
+            base.resourceId = el.resourceId || undefined;
+            base.bounds = el.bounds;
+        }
+        else {
+            base.text = el.text;
+            base.center = el.center;
+            base.bounds = el.bounds;
+        }
+        return base;
+    });
+}
+async function resolveSelector(input, context, config, deviceId) {
+    if (!input.selector)
+        return { elements: [] };
+    const response = await handleFind({ selector: input.selector }, context, config, deviceId);
+    return {
+        elements: context.lastFindResults,
+        candidates: response.candidates,
+        visualFallback: response.visualFallback,
+    };
+}
+/**
+ * Resolves a selector match for an action operation.
+ * - 0   matches → ELEMENT_NOT_FOUND, preserving any fallback candidates the
+ *                 resolver already produced (so the caller doesn't pay the
+ *                 screenshot/dump/crop cost twice).
+ * - 1   match   → take it
+ * - 1+  matches with `nearestTo` set → take matches[0]; the find resolver
+ *                                     already proximity-sorted them.
+ * - 1+  matches without `nearestTo`  → AMBIGUOUS_MATCH with candidate list.
+ */
+function pickSelectorMatch(resolution, selector, operation) {
+    const { elements: matches, candidates, visualFallback } = resolution;
+    if (matches.length === 0) {
+        const hasFallbackPayload = candidates !== undefined || visualFallback !== undefined;
+        throw new ReplicantError(ErrorCode.ELEMENT_NOT_FOUND, `No element matched selector: ${JSON.stringify(selector)}`, hasFallbackPayload
+            ? "Inspect the candidates/visualFallback in error details, or refine the selector."
+            : operation === "scroll"
+                ? "Selector must resolve to an element inside a scrollable container."
+                : "Try a broader selector (textContains), or use ui-query find for fallback tiers.", hasFallbackPayload ? { buildResult: { candidates, visualFallback } } : undefined);
+    }
+    if (matches.length > 1 && !selector.nearestTo) {
+        throw new ReplicantError(ErrorCode.AMBIGUOUS_MATCH, `Selector matched ${matches.length} elements; cannot decide which to ${operation}.`, "Disambiguate via 'nearestTo', a tighter resourceId, or use ui-query find + elementIndex.", { buildResult: { matches: describeMatches(matches) } });
+    }
+    return matches[0];
+}
+function findScrollableAncestor(tree, target) {
+    const flat = flattenTree(tree);
+    let best = null;
+    let smallestArea = Infinity;
+    for (const node of flat) {
+        if (!isScrollableContainer(node))
+            continue;
+        const { bounds: b } = node;
+        if (target.centerX >= b.left &&
+            target.centerX <= b.right &&
+            target.centerY >= b.top &&
+            target.centerY <= b.bottom) {
+            const area = (b.right - b.left) * (b.bottom - b.top);
+            if (area < smallestArea) {
+                smallestArea = area;
+                best = node;
+            }
+        }
+    }
+    return best;
+}
+function isScrollableContainer(node) {
+    if (node.scrollable !== undefined)
+        return node.scrollable;
+    const scrollableClassFragments = [
+        "ScrollView",
+        "RecyclerView",
+        "ListView",
+        "ViewPager",
+        "AndroidComposeView",
+        "ComposeView",
+        "GridView",
+        "Gallery",
+        "NumberPicker",
+    ];
+    return scrollableClassFragments.some((fragment) => node.className.includes(fragment));
+}
+async function handleTap(input, context, config, deviceId) {
     let x, y;
-    if (input.elementIndex !== undefined) {
+    let usedSelector = false;
+    if (input.selector) {
+        const resolution = await resolveSelector(input, context, config, deviceId);
+        const match = pickSelectorMatch(resolution, input.selector, "tap");
+        const center = getElementCenter(match);
+        x = center.x;
+        y = center.y;
+        usedSelector = true;
+    }
+    else if (input.elementIndex !== undefined) {
         if (!context.lastFindResults[input.elementIndex]) {
             throw new ReplicantError(ErrorCode.ELEMENT_NOT_FOUND, `Element at index ${input.elementIndex} not found. Run 'find' first.`, "Use ui-query find to locate elements, then reference them by index");
         }
@@ -40,46 +153,77 @@ async function handleTap(input, context, deviceId) {
         y = input.y;
     }
     else {
-        throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "Either x/y coordinates or elementIndex is required for tap", "Provide x and y coordinates, or use elementIndex from a previous ui-query find result");
+        throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "tap requires x/y, elementIndex, or selector", "Provide one of: x+y coords, elementIndex from a prior find, or a selector.");
     }
-    await context.ui.tap(deviceId, x, y, input.deviceSpace);
-    return { tapped: { x, y, deviceSpace: input.deviceSpace ?? false }, deviceId };
+    // Selector and elementIndex paths always yield device-space coords (the find
+    // result is already in device space). Only the raw x/y path lets the caller
+    // override the space; default true matches the new ui-query dump contract.
+    const fromResolvedElement = usedSelector || input.elementIndex !== undefined;
+    const deviceSpace = fromResolvedElement ? true : (input.deviceSpace ?? true);
+    await context.ui.tap(deviceId, x, y, deviceSpace);
+    const response = { tapped: { x, y, deviceSpace }, deviceId };
+    if (usedSelector)
+        response.matchedSelector = input.selector;
+    return response;
 }
-async function handleInput(input, context, deviceId) {
+async function handleInput(input, context, config, deviceId) {
     if (!input.text) {
         throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "text is required for input operation", "Provide the text string to input");
     }
+    if (input.selector) {
+        const resolution = await resolveSelector(input, context, config, deviceId);
+        const match = pickSelectorMatch(resolution, input.selector, "input");
+        const center = getElementCenter(match);
+        await context.ui.tap(deviceId, center.x, center.y, true);
+    }
     await context.ui.input(deviceId, input.text);
-    return { input: input.text, deviceId };
+    return {
+        input: input.text,
+        deviceId,
+        ...(input.selector ? { matchedSelector: input.selector } : {}),
+    };
 }
-async function handleScroll(input, context, deviceId) {
+async function handleScroll(input, context, config, deviceId) {
     if (!input.direction) {
         throw new ReplicantError(ErrorCode.INPUT_VALIDATION_FAILED, "direction is required for scroll operation", "Provide a direction: up, down, left, or right");
     }
     const amount = input.amount ?? 0.5;
+    if (input.selector) {
+        const resolution = await resolveSelector(input, context, config, deviceId);
+        const target = pickSelectorMatch(resolution, input.selector, "scroll");
+        if (!isAccessibilityNode(target)) {
+            // OCR/grid match — fall back to screen-center scroll with a warning.
+            await context.ui.scroll(deviceId, input.direction, amount);
+            return {
+                scrolled: { direction: input.direction, amount },
+                deviceId,
+                warning: "selector resolved to a non-accessibility match; scrolled the screen center.",
+            };
+        }
+        const tree = await context.ui.dump(deviceId);
+        const scrollable = findScrollableAncestor(tree, target);
+        if (!scrollable) {
+            await context.ui.scroll(deviceId, input.direction, amount);
+            return {
+                scrolled: { direction: input.direction, amount },
+                deviceId,
+                warning: "no scrollable container found; scrolled the screen center.",
+            };
+        }
+        await context.ui.scroll(deviceId, input.direction, amount, scrollable.bounds);
+        return {
+            scrolled: { direction: input.direction, amount, container: scrollable.className },
+            deviceId,
+            matchedSelector: input.selector,
+        };
+    }
     await context.ui.scroll(deviceId, input.direction, amount);
     return { scrolled: { direction: input.direction, amount }, deviceId };
 }
 export const uiActionToolDefinition = {
     name: "ui-action",
-    description: "Interact with app UI: tap, input, scroll.",
-    inputSchema: {
-        type: "object",
-        properties: {
-            operation: {
-                type: "string",
-                enum: ["tap", "input", "scroll"],
-            },
-            x: { type: "number" },
-            y: { type: "number" },
-            elementIndex: { type: "number" },
-            text: { type: "string" },
-            direction: { type: "string", enum: ["up", "down", "left", "right"] },
-            amount: { type: "number", minimum: 0, maximum: 1, description: "Scroll fraction (0-1, default: 0.5)" },
-            deviceSpace: { type: "boolean", description: "Treat x/y as device coordinates (skip scaling)" },
-        },
-        required: ["operation"],
-    },
+    description: "Interact with app UI: tap, input, scroll. Use selector or coords.",
+    inputSchema: toMcpJsonSchema(uiActionInputSchema),
     annotations: {
         readOnlyHint: false,
         destructiveHint: true,