replicant-mcp 1.4.1 → 1.4.2

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.js

@@ -107,6 +107,10 @@ 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);
@@ -118,7 +122,17 @@ export async function handleUiTool(input, context, uiConfig) {
                     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 && elements.length === 0
+                    ? "Accessibility tree exists but no interactive elements found. Try 'ui find' with a text selector, or use screenshot for visual targeting."
+                    : undefined;
+                return {
+                    dumpId,
+                    elements,
+                    count: elements.length,
+                    deviceId,
+                    warning: emptyWarning || noInteractiveWarning,
+                };
             }
             // Full mode: hierarchical tree with all details
             const simplifyNode = (node, depth = 0) => ({
@@ -133,6 +147,7 @@ export async function handleUiTool(input, context, uiConfig) {
                 dumpId,
                 tree: tree.map((n) => simplifyNode(n)),
                 deviceId,
+                warning: emptyWarning,
             };
         }
         case "find": {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replicant-mcp",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "description": "Android MCP server for AI-assisted Android development",
   "type": "module",
   "main": "dist/index.js",