replicant-mcp 1.4.1 → 1.4.3

package/README.md

@@ -64,28 +64,30 @@ emulator -version   # Should show Android emulator version
 
 ### Installation
 
-**npm (recommended):**
 ```bash
 npm install -g replicant-mcp
 ```
 
-**From source:**
+### Updating
+
 ```bash
-git clone https://github.com/thecombatwombat/replicant-mcp.git
-cd replicant-mcp
-npm install && npm run build
+npm update -g replicant-mcp
 ```
 
+---
+
+## Setup
+
 ### Claude Desktop
 
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 
 ```json
 {
   "mcpServers": {
     "replicant": {
-      "command": "node",
-      "args": ["/absolute/path/to/replicant-mcp/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "replicant-mcp"]
     }
   }
 }
@@ -94,32 +96,78 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 ### Claude Code
 
 ```bash
-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
+claude mcp add replicant -- npx -y replicant-mcp
 ```
 
-> Adjust `ANDROID_HOME` if your SDK is elsewhere. On Linux, it's typically `$HOME/Android/Sdk`.
+### Cursor
 
----
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
 
-## Example
+```json
+{
+  "mcpServers": {
+    "replicant": {
+      "command": "npx",
+      "args": ["-y", "replicant-mcp"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "replicant": {
+      "command": "npx",
+      "args": ["-y", "replicant-mcp"]
+    }
+  }
+}
+```
+
+### OpenAI Codex CLI
 
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.replicant]
+command = "npx"
+args = ["-y", "replicant-mcp"]
+```
+
+Or via CLI:
+
+```bash
+codex mcp add replicant -- npx -y replicant-mcp
 ```
-You: "The app crashed after I tapped Login. What happened?"
 
-Claude: Let me check the error logs.
-        [Calls adb-logcat with level: "error", lines: 50]
+> **Note:** Ensure `adb` and `emulator` are in your PATH, or set `ANDROID_HOME` environment variable. On macOS: `~/Library/Android/sdk`, on Linux: `~/Android/Sdk`.
 
-        Found the crash:
+---
 
-        java.lang.NullPointerException: Attempt to invoke virtual method
-        'void com.example.User.getName()' on a null object reference
-            at com.example.ProfileActivity.onCreate(ProfileActivity.kt:47)
+## Example
 
-        Looks like `user` is null when ProfileActivity starts.
-        Want me to look at that file?
+```
+You: "I just changed the checkout flow. Build the app, go through checkout
+      with a test product, and make sure the confirmation screen shows up."
+
+Claude: [Builds debug APK, installs on emulator, launches app]
+        [Taps "Electronics" category → "Wireless Headphones" → "Add to Cart"]
+        [Navigates to cart, taps "Checkout"]
+        [Fills shipping form, taps "Place Order"]
+
+        Confirmation screen is showing:
+        - Order #38291
+        - "Wireless Headphones" × 1
+        - Total: $79.99
+        - Estimated delivery: Jan 30
+
+        The flow works. Want me to test the edge cases—empty cart,
+        invalid address, payment failure?
 ```
 
 ---

package/dist/services/grid.d.ts

@@ -23,6 +23,6 @@ export declare function calculatePositionCoordinates(position: 1 | 2 | 3 | 4 | 5
 export declare const POSITION_LABELS: string[];
 /**
  * Create a 4x6 numbered grid overlay on a screenshot.
- * Returns base64 PNG.
+ * Returns base64 JPEG (compressed for context efficiency).
  */
 export declare function createGridOverlay(imagePath: string): Promise<string>;

package/dist/services/grid.js

@@ -54,15 +54,21 @@ export const POSITION_LABELS = [
 ];
 const GRID_LINE_WIDTH = 3;
 const LABEL_FONT_SIZE = 36;
+const MAX_GRID_DIMENSION = 1000;
+const JPEG_QUALITY = 70;
 /**
  * Create a 4x6 numbered grid overlay on a screenshot.
- * Returns base64 PNG.
+ * Returns base64 JPEG (compressed for context efficiency).
  */
 export async function createGridOverlay(imagePath) {
     const image = sharp(imagePath);
     const metadata = await image.metadata();
     const width = metadata.width;
     const height = metadata.height;
+    // Calculate scaling to fit within MAX_GRID_DIMENSION
+    const scaleFactor = Math.min(1, MAX_GRID_DIMENSION / Math.max(width, height));
+    const scaledWidth = Math.round(width * scaleFactor);
+    const scaledHeight = Math.round(height * scaleFactor);
     const cellWidth = width / GRID_COLS;
     const cellHeight = height / GRID_ROWS;
     // Create SVG overlay with grid lines and numbers
@@ -90,9 +96,14 @@ export async function createGridOverlay(imagePath) {
         svgParts.push(`<text x="${centerX}" y="${centerY}" font-family="Arial, sans-serif" font-size="${LABEL_FONT_SIZE}" font-weight="bold" fill="white" text-anchor="middle" dominant-baseline="central">${cell}</text>`);
     }
     const svgOverlay = `<svg width="${width}" height="${height}">${svgParts.join("")}</svg>`;
-    const buffer = await image
+    // Composite at original size first, then resize
+    const composited = await image
         .composite([{ input: Buffer.from(svgOverlay), top: 0, left: 0 }])
-        .png()
+        .toBuffer();
+    // Resize and compress to JPEG
+    const buffer = await sharp(composited)
+        .resize(scaledWidth, scaledHeight)
+        .jpeg({ quality: JPEG_QUALITY })
         .toBuffer();
     return buffer.toString("base64");
 }

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

@@ -11,6 +11,9 @@ export declare const adbAppInputSchema: z.ZodObject<{
     }>;
     apkPath: z.ZodOptional<z.ZodString>;
     packageName: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    filter: z.ZodOptional<z.ZodString>;
+    offset: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type AdbAppInput = z.infer<typeof adbAppInputSchema>;
 export declare function handleAdbAppTool(input: AdbAppInput, context: ServerContext): Promise<Record<string, unknown>>;
@@ -32,6 +35,18 @@ export declare const adbAppToolDefinition: {
                 type: string;
                 description: string;
             };
+            limit: {
+                type: string;
+                description: string;
+            };
+            filter: {
+                type: string;
+                description: string;
+            };
+            offset: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
     };

package/dist/tools/adb-app.js

@@ -1,8 +1,13 @@
 import { z } from "zod";
+import { CACHE_TTLS } 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(),
 });
 export async function handleAdbAppTool(input, context) {
     const device = await context.deviceState.ensureDevice(context.adb);
@@ -44,8 +49,30 @@ export async function handleAdbAppTool(input, context) {
             return { cleared: input.packageName, deviceId };
         }
         case "list": {
-            const packages = await context.adb.getPackages(deviceId);
-            return { packages, count: packages.length, deviceId };
+            const allPackages = await context.adb.getPackages(deviceId);
+            const limit = input.limit ?? 20;
+            const offset = input.offset ?? 0;
+            const filter = input.filter?.toLowerCase();
+            // Apply filter if provided
+            const filtered = filter
+                ? allPackages.filter((pkg) => pkg.toLowerCase().includes(filter))
+                : allPackages;
+            // Paginate
+            const paginated = filtered.slice(offset, offset + limit);
+            const hasMore = offset + limit < filtered.length;
+            // Cache full list for subsequent requests
+            const cacheId = context.cache.generateId("app-list");
+            context.cache.set(cacheId, { packages: filtered, deviceId, filter: filter || null }, "app-list", CACHE_TTLS.APP_LIST);
+            return {
+                packages: paginated,
+                count: paginated.length,
+                totalCount: filtered.length,
+                hasMore,
+                offset,
+                limit,
+                cacheId,
+                deviceId,
+            };
         }
         default:
             throw new Error(`Unknown operation: ${input.operation}`);
@@ -63,6 +90,18 @@ export const adbAppToolDefinition = {
             },
             apkPath: { type: "string", description: "Path to APK file (for install)" },
             packageName: { type: "string", description: "Package name (for other operations)" },
+            limit: {
+                type: "number",
+                description: "Max packages to return (default: 20, max: 100). For list operation.",
+            },
+            filter: {
+                type: "string",
+                description: "Filter packages by name (case-insensitive contains). For list operation.",
+            },
+            offset: {
+                type: "number",
+                description: "Skip first N packages for pagination. For list operation.",
+            },
         },
         required: ["operation"],
     },

package/dist/tools/adb-device.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { CACHE_TTLS } from "../types/index.js";
 export const adbDeviceInputSchema = z.object({
     operation: z.enum(["list", "select", "wait", "properties", "health-check"]),
     deviceId: z.string().optional(),
@@ -41,16 +42,25 @@ export async function handleAdbDeviceTool(input, context) {
                 : await context.deviceState.ensureDevice(context.adb);
             const deviceId = device.id;
             const props = await context.adb.getProperties(deviceId);
+            // Cache full properties for retrieval via cache tool
+            const cacheId = context.cache.generateId("device-props");
+            context.cache.set(cacheId, { deviceId, properties: props }, "device-props", CACHE_TTLS.DEVICE_PROPERTIES);
+            // Return summary only (key properties + cache ID for full details)
             return {
                 deviceId,
-                properties: {
+                summary: {
                     model: props["ro.product.model"],
                     manufacturer: props["ro.product.manufacturer"],
                     sdkVersion: props["ro.build.version.sdk"],
                     androidVersion: props["ro.build.version.release"],
                     buildId: props["ro.build.id"],
+                    device: props["ro.product.device"],
+                    product: props["ro.product.name"],
+                    hardware: props["ro.hardware"],
+                    abiList: props["ro.product.cpu.abilist"],
                 },
-                allProperties: props,
+                propertyCount: Object.keys(props).length,
+                cacheId,
             };
         }
         case "health-check": {

package/dist/tools/ui.d.ts

@@ -39,6 +39,8 @@ export declare const uiInputSchema: z.ZodObject<{
         right: "right";
     }>>;
     amount: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type UiInput = z.infer<typeof uiInputSchema>;
 export declare function handleUiTool(input: UiInput, context: ServerContext, uiConfig?: UiConfig): Promise<Record<string, unknown>>;
@@ -141,6 +143,17 @@ export declare const uiToolDefinition: {
                 maximum: number;
                 description: string;
             };
+            limit: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
+            offset: {
+                type: string;
+                minimum: number;
+                description: string;
+            };
         };
         required: string[];
     };

package/dist/tools/ui.js

@@ -25,6 +25,9 @@ export const uiInputSchema = z.object({
     compact: z.boolean().optional(),
     direction: z.enum(["up", "down", "left", "right"]).optional(),
     amount: z.number().min(0).max(1).optional(),
+    // Pagination for dump operation
+    limit: z.number().min(1).max(100).optional(),
+    offset: z.number().min(0).optional(),
 });
 // Store last find results for elementIndex reference
 // Updated to support accessibility, OCR, and grid elements
@@ -107,18 +110,47 @@ export async function handleUiTool(input, context, uiConfig) {
             // Cache the tree
             const dumpId = context.cache.generateId("ui-dump");
             context.cache.set(dumpId, { tree, deviceId }, "ui-dump", CACHE_TTLS.UI_TREE);
+            // Warning for empty dumps
+            const emptyWarning = tree.length === 0
+                ? "No accessibility nodes found. Possible causes: (1) UI still loading - wait and retry, (2) App uses custom rendering (Flutter, games, video players) - use screenshot instead, (3) App blocks accessibility services."
+                : undefined;
             if (input.compact) {
                 // Compact mode: flat list of interactive elements only
                 const flat = flattenTree(tree);
                 const interactive = flat.filter((n) => n.clickable || n.focusable);
-                const elements = interactive.map((n) => ({
+                // Pagination
+                const limit = input.limit ?? 20;
+                const offset = input.offset ?? 0;
+                const totalCount = interactive.length;
+                const paginated = interactive.slice(offset, offset + limit);
+                const hasMore = offset + limit < totalCount;
+                const elements = paginated.map((n) => ({
                     text: n.text || n.contentDesc || undefined,
                     type: n.className.split(".").pop(),
                     x: n.centerX,
                     y: n.centerY,
                     resourceId: n.resourceId ? n.resourceId.split("/").pop() : undefined,
                 }));
-                return { dumpId, elements, count: elements.length, deviceId };
+                // Also warn if tree has nodes but no interactive elements
+                const noInteractiveWarning = tree.length > 0 && totalCount === 0
+                    ? "Accessibility tree exists but no interactive elements found. Try 'ui find' with a text selector, or use screenshot for visual targeting."
+                    : undefined;
+                // Hint for pagination
+                const hint = hasMore
+                    ? `${elements.length} of ${totalCount} elements shown. Use 'ui find' for specific elements, or add offset: ${offset + limit} for more.`
+                    : undefined;
+                return {
+                    dumpId,
+                    elements,
+                    count: elements.length,
+                    totalCount,
+                    hasMore,
+                    offset,
+                    limit,
+                    deviceId,
+                    hint,
+                    warning: emptyWarning || noInteractiveWarning,
+                };
             }
             // Full mode: hierarchical tree with all details
             const simplifyNode = (node, depth = 0) => ({
@@ -133,6 +165,7 @@ export async function handleUiTool(input, context, uiConfig) {
                 dumpId,
                 tree: tree.map((n) => simplifyNode(n)),
                 deviceId,
+                warning: emptyWarning,
             };
         }
         case "find": {
@@ -410,7 +443,7 @@ export const uiToolDefinition = {
             },
             compact: {
                 type: "boolean",
-                description: "For dump: return flat list of interactive elements with {text, type, x, y, resourceId} instead of full tree.",
+                description: "For dump: return paginated flat list of interactive elements (default: 20, use limit/offset for more).",
             },
             direction: {
                 type: "string",
@@ -423,6 +456,17 @@ export const uiToolDefinition = {
                 maximum: 1,
                 description: "Scroll amount as fraction of screen (0-1, default: 0.5)",
             },
+            limit: {
+                type: "number",
+                minimum: 1,
+                maximum: 100,
+                description: "For dump with compact: max elements to return (default: 20).",
+            },
+            offset: {
+                type: "number",
+                minimum: 0,
+                description: "For dump with compact: skip first N elements for pagination.",
+            },
         },
         required: ["operation"],
     },

package/dist/types/cache.d.ts

@@ -21,4 +21,5 @@ export declare const CACHE_TTLS: {
     readonly UI_TREE: number;
     readonly GRADLE_VARIANTS: number;
     readonly LOGCAT: number;
+    readonly DEVICE_PROPERTIES: number;
 };

package/dist/types/cache.js

@@ -11,4 +11,5 @@ export const CACHE_TTLS = {
     UI_TREE: 30 * 1000, // 30 sec
     GRADLE_VARIANTS: 60 * 60 * 1000, // 1 hour
     LOGCAT: 5 * 60 * 1000, // 5 min
+    DEVICE_PROPERTIES: 5 * 60 * 1000, // 5 min
 };

package/docs/rtfm/adb.md

@@ -0,0 +1,48 @@
+# ADB Tools
+
+## adb-device
+
+Manage device connections.
+
+**Operations:**
+- `list` - List connected devices
+- `select` - Select active device
+- `wait` - Wait for device to connect
+- `properties` - Get device properties
+
+## adb-app
+
+Manage applications.
+
+**Operations:**
+- `install` - Install APK
+- `uninstall` - Uninstall package
+- `launch` - Launch app
+- `stop` - Force stop app
+- `clear-data` - Clear app data
+
+## adb-logcat
+
+Read device logs.
+
+**Structured mode:**
+- `package`: Filter to app's PID
+- `tags`: Array of log tags
+- `level`: "verbose" | "debug" | "info" | "warn" | "error"
+
+**Raw mode:**
+- `rawFilter`: Full logcat filter string (e.g., "ActivityManager:I MyApp:D *:S")
+
+**Common:**
+- `lines`: Number of lines (default: 100)
+- `since`: Time filter ("5m" or ISO timestamp)
+
+## adb-shell
+
+Execute shell commands with safety guards.
+
+**Parameters:**
+- `command` (required): Shell command
+- `timeout`: Max execution time (default: 30s, max: 120s)
+
+**Blocked commands:** rm -rf /, reboot, shutdown, su, sudo

package/docs/rtfm/build.md

@@ -0,0 +1,52 @@
+# Build Tools
+
+## gradle-build
+
+Build an Android application.
+
+**Operations:**
+- `assembleDebug` - Build debug APK
+- `assembleRelease` - Build release APK
+- `bundle` - Build Android App Bundle
+
+**Parameters:**
+- `operation` (required): Build operation
+- `module`: Module path (e.g., ":app", ":feature:login")
+- `flavor`: Product flavor name
+
+**Returns:** `{ buildId, summary: { success, duration, apkSize, warnings } }`
+
+**Example:**
+```json
+{ "operation": "assembleDebug", "module": ":app" }
+```
+
+## gradle-test
+
+Run tests.
+
+**Operations:**
+- `unitTest` - Run unit tests
+- `connectedTest` - Run instrumented tests on device
+
+**Parameters:**
+- `operation` (required): Test type
+- `module`: Module path
+- `filter`: Test filter (e.g., "com.example.MyTest", "*LoginTest*")
+
+## gradle-list
+
+Introspect project structure.
+
+**Operations:**
+- `variants` - List build variants
+- `modules` - List project modules
+- `tasks` - List Gradle tasks
+
+## gradle-get-details
+
+Fetch full output for a previous build/test.
+
+**Parameters:**
+- `id` (required): Build or test ID from previous operation
+- `detailType`: "logs" | "errors" | "tasks"

package/docs/rtfm/emulator.md

@@ -0,0 +1,23 @@
+# Emulator Tools
+
+## emulator-device
+
+Manage Android emulators.
+
+**Operations:**
+- `list` - List available and running emulators
+- `create` - Create new AVD
+- `start` - Start emulator
+- `kill` - Stop running emulator
+- `wipe` - Reset emulator data
+- `snapshot-save` - Save snapshot
+- `snapshot-load` - Load snapshot
+- `snapshot-list` - List snapshots
+- `snapshot-delete` - Delete snapshot
+
+**Parameters:**
+- `operation` (required): Operation to perform
+- `avdName`: AVD name (for create/start/wipe)
+- `device`: Device profile (for create, e.g., "pixel_7")
+- `systemImage`: System image (for create)
+- `snapshotName`: Snapshot name (for snapshot operations)

package/docs/rtfm/index.md

@@ -0,0 +1,9 @@
+# replicant-mcp Documentation
+
+## Categories
+
+- **build** - Gradle build and test tools
+- **adb** - Android Debug Bridge tools
+- **emulator** - Emulator management tools
+- **ui** - UI automation tools
+- **cache** - Cache management

package/docs/rtfm/ui.md

@@ -0,0 +1,107 @@
+# UI Automation Tools
+
+## ui
+
+Interact with app UI via accessibility tree with intelligent fallback.
+
+**Operations:**
+- `dump` - Get full accessibility tree
+- `find` - Find elements by selector (with OCR/visual fallback)
+- `tap` - Tap at coordinates, element index, or grid cell
+- `input` - Enter text
+- `screenshot` - Capture screen to file
+- `accessibility-check` - Quick accessibility assessment
+- `visual-snapshot` - Get screenshot + screen/app metadata
+
+**Selectors (for find):**
+- `resourceId`: Match resource ID (partial)
+- `text`: Match exact text
+- `textContains`: Match partial text
+- `className`: Match class name
+- `nearestTo`: Find elements nearest to this text (spatial proximity)
+
+**Tap options:**
+- `x`, `y`: Direct coordinates
+- `elementIndex`: Index from previous find result
+- `gridCell`: Grid cell 1-24 (6x4 grid overlay)
+- `gridPosition`: Position within cell (1=TL, 2=TR, 3=Center, 4=BL, 5=BR)
+
+**Optional parameters:**
+- `debug`: Include source (accessibility/ocr) and confidence scores
+- `inline`: Return base64 screenshot in response (for screenshot op)
+- `localPath`: Custom path for screenshot output
+
+**Fallback chain:**
+1. Accessibility tree (fast, reliable)
+2. OCR via Tesseract (when accessibility fails)
+3. Visual snapshot (screenshot + metadata for AI vision)
+
+**Example - Find and tap:**
+```json
+{ "operation": "find", "selector": { "text": "Login" } }
+// Returns: { elements: [{ index: 0, centerX: 540, centerY: 1200, ... }] }
+
+{ "operation": "tap", "elementIndex": 0 }
+```
+
+**Example - Spatial proximity:**
+```json
+{ "operation": "find", "selector": { "textContains": "edit", "nearestTo": "John" } }
+// Returns elements containing "edit", sorted by distance to "John"
+```
+
+**Example - Grid-based tap (for icons):**
+```json
+{ "operation": "tap", "gridCell": 12, "gridPosition": 3 }
+// Taps center of cell 12 in the 24-cell grid overlay
+```
+
+## Screenshot Scaling
+
+Screenshots are automatically scaled to fit within 1000px (longest side) by default.
+This prevents API context limits and reduces token usage.
+
+**All coordinates are in image space.** Tap coordinates are automatically converted
+to device coordinates. You don't need to do any math.
+
+### Scaling Modes
+
+| Mode | Parameter | Behavior |
+|------|-----------|----------|
+| Default | (none) | Scale to 1000px max |
+| Custom | `maxDimension: 1500` | Scale to specified size |
+| Raw | `raw: true` | No scaling (may exceed API limits) |
+
+### When to Use Raw Mode
+
+- Non-Anthropic models with different limits
+- External context management (compaction, agent respawning)
+- Debugging coordinate issues
+
+### Response Format
+
+Screenshot responses now include scaling metadata:
+
+```json
+{
+  "mode": "file",
+  "path": ".replicant/screenshots/screenshot-1234.png",
+  "device": { "width": 1080, "height": 2400 },
+  "image": { "width": 450, "height": 1000 },
+  "scaleFactor": 2.4
+}
+```
+
+## Context Management
+
+**Prefer accessibility tree (`dump`, `find`) because:**
+- No context cost (text, not images)
+- Coordinates are precise
+- Faster execution
+
+**Use screenshots when:**
+- Accessibility tree is empty/unhelpful
+- You need to see visual layout
+- Icons have no text labels
+
+**Ask yourself:** Do I need to SEE the screen, or just INTERACT with it?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replicant-mcp",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "description": "Android MCP server for AI-assisted Android development",
   "type": "module",
   "main": "dist/index.js",
@@ -44,6 +44,7 @@
   },
   "files": [
     "dist/",
+    "docs/rtfm/",
     "README.md",
     "LICENSE"
   ],