replicant-mcp 1.0.0

package/dist/tools/gradle-list.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { CACHE_TTLS } from "../types/index.js";
+export const gradleListInputSchema = z.object({
+    operation: z.enum(["variants", "modules", "tasks"]),
+    module: z.string().optional(),
+});
+export async function handleGradleListTool(input, context) {
+    switch (input.operation) {
+        case "modules": {
+            const modules = await context.gradle.listModules();
+            return { modules };
+        }
+        case "variants": {
+            const variants = await context.gradle.listVariants(input.module);
+            return { variants, module: input.module || "all" };
+        }
+        case "tasks": {
+            const tasks = await context.gradle.listTasks(input.module);
+            // Cache full task list
+            const listId = context.cache.generateId("tasks");
+            context.cache.set(listId, { tasks }, "tasks", CACHE_TTLS.GRADLE_VARIANTS);
+            // Return categorized summary
+            const buildTasks = tasks.filter((t) => t.includes("assemble") || t.includes("bundle"));
+            const testTasks = tasks.filter((t) => t.includes("test") || t.includes("Test"));
+            const cleanTasks = tasks.filter((t) => t.includes("clean"));
+            return {
+                listId,
+                summary: {
+                    totalTasks: tasks.length,
+                    buildTasks: buildTasks.slice(0, 10),
+                    testTasks: testTasks.slice(0, 10),
+                    cleanTasks: cleanTasks.slice(0, 5),
+                },
+                module: input.module || "all",
+            };
+        }
+        default:
+            throw new Error(`Unknown operation: ${input.operation}`);
+    }
+}
+export const gradleListToolDefinition = {
+    name: "gradle-list",
+    description: "Introspect project structure. Operations: modules, variants, tasks.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            operation: {
+                type: "string",
+                enum: ["variants", "modules", "tasks"],
+            },
+            module: { type: "string", description: "Module path (for variants/tasks)" },
+        },
+        required: ["operation"],
+    },
+};

package/dist/tools/gradle-test.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { ServerContext } from "../server.js";
+export declare const gradleTestInputSchema: z.ZodObject<{
+    operation: z.ZodEnum<{
+        unitTest: "unitTest";
+        connectedTest: "connectedTest";
+    }>;
+    module: z.ZodOptional<z.ZodString>;
+    filter: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type GradleTestInput = z.infer<typeof gradleTestInputSchema>;
+export declare function handleGradleTestTool(input: GradleTestInput, context: ServerContext): Promise<Record<string, unknown>>;
+export declare const gradleTestToolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            operation: {
+                type: string;
+                enum: string[];
+            };
+            module: {
+                type: string;
+                description: string;
+            };
+            filter: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};

package/dist/tools/gradle-test.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { CACHE_TTLS } from "../types/index.js";
+export const gradleTestInputSchema = z.object({
+    operation: z.enum(["unitTest", "connectedTest"]),
+    module: z.string().optional(),
+    filter: z.string().optional(),
+});
+export async function handleGradleTestTool(input, context) {
+    const { result, fullOutput } = await context.gradle.test(input.operation, input.module, input.filter);
+    // Cache full output for later retrieval
+    const testId = context.cache.generateId("test");
+    context.cache.set(testId, { fullOutput, result, operation: input.operation }, "test", CACHE_TTLS.TEST_RESULTS);
+    return {
+        testId,
+        summary: {
+            passed: result.passed,
+            failed: result.failed,
+            skipped: result.skipped,
+            total: result.total,
+            duration: result.duration,
+        },
+        failures: result.failures,
+    };
+}
+export const gradleTestToolDefinition = {
+    name: "gradle-test",
+    description: "Run tests. Operations: unitTest, connectedTest. Returns summary with testId.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            operation: {
+                type: "string",
+                enum: ["unitTest", "connectedTest"],
+            },
+            module: { type: "string", description: "Module path" },
+            filter: { type: "string", description: "Test filter (e.g., '*LoginTest*')" },
+        },
+        required: ["operation"],
+    },
+};

package/dist/tools/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./cache.js";
+export * from "./rtfm.js";
+export * from "./adb-device.js";
+export * from "./adb-app.js";
+export * from "./adb-logcat.js";
+export * from "./adb-shell.js";
+export * from "./emulator-device.js";
+export * from "./gradle-build.js";
+export * from "./gradle-test.js";
+export * from "./gradle-list.js";
+export * from "./gradle-get-details.js";
+export * from "./ui.js";

package/dist/tools/index.js

@@ -0,0 +1,12 @@
+export * from "./cache.js";
+export * from "./rtfm.js";
+export * from "./adb-device.js";
+export * from "./adb-app.js";
+export * from "./adb-logcat.js";
+export * from "./adb-shell.js";
+export * from "./emulator-device.js";
+export * from "./gradle-build.js";
+export * from "./gradle-test.js";
+export * from "./gradle-list.js";
+export * from "./gradle-get-details.js";
+export * from "./ui.js";

package/dist/tools/rtfm.d.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+export declare const rtfmInputSchema: z.ZodObject<{
+    category: z.ZodOptional<z.ZodString>;
+    tool: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RtfmInput = z.infer<typeof rtfmInputSchema>;
+export declare function handleRtfmTool(input: RtfmInput): Promise<{
+    content: string;
+}>;
+export declare const rtfmToolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            category: {
+                type: string;
+                description: string;
+            };
+            tool: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+};

package/dist/tools/rtfm.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { readFile } from "fs/promises";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+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 async function handleRtfmTool(input) {
+    if (!input.category && !input.tool) {
+        // Return index
+        const content = await readFile(join(RTFM_DIR, "index.md"), "utf-8");
+        return { content };
+    }
+    if (input.category) {
+        try {
+            const content = await readFile(join(RTFM_DIR, `${input.category}.md`), "utf-8");
+            return { content };
+        }
+        catch {
+            return { content: `Category '${input.category}' not found. Available: build, adb, emulator, ui` };
+        }
+    }
+    if (input.tool) {
+        // Map tool to category
+        const toolToCategory = {
+            "gradle-build": "build",
+            "gradle-test": "build",
+            "gradle-list": "build",
+            "gradle-get-details": "build",
+            "adb-device": "adb",
+            "adb-app": "adb",
+            "adb-logcat": "adb",
+            "adb-shell": "adb",
+            "emulator-device": "emulator",
+            "ui": "ui",
+            "cache": "build",
+            "rtfm": "build",
+        };
+        const category = toolToCategory[input.tool] || "index";
+        try {
+            const content = await readFile(join(RTFM_DIR, `${category}.md`), "utf-8");
+            // Try to extract just the relevant section
+            const toolSection = extractToolSection(content, input.tool);
+            return { content: toolSection || content };
+        }
+        catch {
+            return { content: `Tool '${input.tool}' not found.` };
+        }
+    }
+    return { content: "No documentation found." };
+}
+function extractToolSection(content, toolName) {
+    const regex = new RegExp(`## ${toolName}[\\s\\S]*?(?=## |$)`, "i");
+    const match = content.match(regex);
+    return match ? match[0].trim() : null;
+}
+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" },
+            tool: { type: "string", description: "Tool name for specific docs" },
+        },
+    },
+};

package/dist/tools/ui.d.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { ServerContext } from "../server.js";
+export declare const uiInputSchema: z.ZodObject<{
+    operation: z.ZodEnum<{
+        find: "find";
+        dump: "dump";
+        tap: "tap";
+        input: "input";
+        screenshot: "screenshot";
+        "accessibility-check": "accessibility-check";
+    }>;
+    selector: z.ZodOptional<z.ZodObject<{
+        resourceId: z.ZodOptional<z.ZodString>;
+        text: z.ZodOptional<z.ZodString>;
+        textContains: z.ZodOptional<z.ZodString>;
+        className: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    x: z.ZodOptional<z.ZodNumber>;
+    y: z.ZodOptional<z.ZodNumber>;
+    elementIndex: z.ZodOptional<z.ZodNumber>;
+    text: z.ZodOptional<z.ZodString>;
+    localPath: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type UiInput = z.infer<typeof uiInputSchema>;
+export declare function handleUiTool(input: UiInput, context: ServerContext): Promise<Record<string, unknown>>;
+export declare const uiToolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            operation: {
+                type: string;
+                enum: string[];
+            };
+            selector: {
+                type: string;
+                properties: {
+                    resourceId: {
+                        type: string;
+                    };
+                    text: {
+                        type: string;
+                    };
+                    textContains: {
+                        type: string;
+                    };
+                    className: {
+                        type: string;
+                    };
+                };
+                description: string;
+            };
+            x: {
+                type: string;
+                description: string;
+            };
+            y: {
+                type: string;
+                description: string;
+            };
+            elementIndex: {
+                type: string;
+                description: string;
+            };
+            text: {
+                type: string;
+                description: string;
+            };
+            localPath: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};

package/dist/tools/ui.js

@@ -0,0 +1,131 @@
+import { z } from "zod";
+import { CACHE_TTLS } from "../types/index.js";
+export const uiInputSchema = z.object({
+    operation: z.enum(["dump", "find", "tap", "input", "screenshot", "accessibility-check"]),
+    selector: z.object({
+        resourceId: z.string().optional(),
+        text: z.string().optional(),
+        textContains: z.string().optional(),
+        className: z.string().optional(),
+    }).optional(),
+    x: z.number().optional(),
+    y: z.number().optional(),
+    elementIndex: z.number().optional(),
+    text: z.string().optional(),
+    localPath: z.string().optional(),
+});
+// Store last find results for elementIndex reference
+let lastFindResults = [];
+export async function handleUiTool(input, context) {
+    const deviceId = context.deviceState.requireCurrentDevice().id;
+    switch (input.operation) {
+        case "dump": {
+            const tree = await context.ui.dump(deviceId);
+            // Cache the tree
+            const dumpId = context.cache.generateId("ui-dump");
+            context.cache.set(dumpId, { tree, deviceId }, "ui-dump", CACHE_TTLS.UI_TREE);
+            // Create a simplified view
+            const simplifyNode = (node, depth = 0) => ({
+                className: node.className.split(".").pop(),
+                text: node.text || undefined,
+                resourceId: node.resourceId ? node.resourceId.split("/").pop() : undefined,
+                bounds: `[${node.bounds.left},${node.bounds.top}][${node.bounds.right},${node.bounds.bottom}]`,
+                clickable: node.clickable || undefined,
+                children: node.children?.map((c) => simplifyNode(c, depth + 1)),
+            });
+            return {
+                dumpId,
+                tree: tree.map((n) => simplifyNode(n)),
+                deviceId,
+            };
+        }
+        case "find": {
+            if (!input.selector) {
+                throw new Error("selector is required for find operation");
+            }
+            const elements = await context.ui.find(deviceId, input.selector);
+            lastFindResults = elements;
+            return {
+                elements: elements.map((el, index) => ({
+                    index,
+                    text: el.text,
+                    resourceId: el.resourceId,
+                    className: el.className,
+                    centerX: el.centerX,
+                    centerY: el.centerY,
+                    bounds: el.bounds,
+                    clickable: el.clickable,
+                })),
+                count: elements.length,
+                deviceId,
+            };
+        }
+        case "tap": {
+            let x, y;
+            if (input.elementIndex !== undefined) {
+                if (!lastFindResults[input.elementIndex]) {
+                    throw new Error(`Element at index ${input.elementIndex} not found. Run 'find' first.`);
+                }
+                const element = lastFindResults[input.elementIndex];
+                x = element.centerX;
+                y = element.centerY;
+            }
+            else if (input.x !== undefined && input.y !== undefined) {
+                x = input.x;
+                y = input.y;
+            }
+            else {
+                throw new Error("Either x/y coordinates or elementIndex is required for tap");
+            }
+            await context.ui.tap(deviceId, x, y);
+            return { tapped: { x, y }, deviceId };
+        }
+        case "input": {
+            if (!input.text) {
+                throw new Error("text is required for input operation");
+            }
+            await context.ui.input(deviceId, input.text);
+            return { input: input.text, deviceId };
+        }
+        case "screenshot": {
+            const localPath = input.localPath || `/tmp/screenshot-${Date.now()}.png`;
+            await context.ui.screenshot(deviceId, localPath);
+            return { path: localPath, deviceId };
+        }
+        case "accessibility-check": {
+            const result = await context.ui.accessibilityCheck(deviceId);
+            return { ...result, deviceId };
+        }
+        default:
+            throw new Error(`Unknown operation: ${input.operation}`);
+    }
+}
+export const uiToolDefinition = {
+    name: "ui",
+    description: "Interact with app UI via accessibility tree. Operations: dump, find, tap, input, screenshot, accessibility-check.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            operation: {
+                type: "string",
+                enum: ["dump", "find", "tap", "input", "screenshot", "accessibility-check"],
+            },
+            selector: {
+                type: "object",
+                properties: {
+                    resourceId: { type: "string" },
+                    text: { type: "string" },
+                    textContains: { type: "string" },
+                    className: { type: "string" },
+                },
+                description: "Element selector (for find)",
+            },
+            x: { type: "number", description: "X coordinate (for tap)" },
+            y: { type: "number", description: "Y coordinate (for tap)" },
+            elementIndex: { type: "number", description: "Element index from last find (for tap)" },
+            text: { type: "string", description: "Text to input" },
+            localPath: { type: "string", description: "Local path for screenshot" },
+        },
+        required: ["operation"],
+    },
+};

package/dist/types/cache.d.ts

@@ -0,0 +1,24 @@
+export interface CacheEntry<T = unknown> {
+    data: T;
+    expiresAt: number;
+    metadata: {
+        createdAt: number;
+        type: string;
+        sizeBytes?: number;
+    };
+}
+export interface CacheConfig {
+    maxEntries: number;
+    maxEntrySizeBytes: number;
+    defaultTtlMs: number;
+}
+export declare const DEFAULT_CACHE_CONFIG: CacheConfig;
+export declare const CACHE_TTLS: {
+    readonly BUILD_OUTPUT: number;
+    readonly TEST_RESULTS: number;
+    readonly EMULATOR_LIST: number;
+    readonly APP_LIST: number;
+    readonly UI_TREE: number;
+    readonly GRADLE_VARIANTS: number;
+    readonly LOGCAT: number;
+};

package/dist/types/cache.js

@@ -0,0 +1,14 @@
+export const DEFAULT_CACHE_CONFIG = {
+    maxEntries: 100,
+    maxEntrySizeBytes: 1024 * 1024, // 1MB
+    defaultTtlMs: 5 * 60 * 1000, // 5 minutes
+};
+export const CACHE_TTLS = {
+    BUILD_OUTPUT: 30 * 60 * 1000, // 30 min
+    TEST_RESULTS: 30 * 60 * 1000, // 30 min
+    EMULATOR_LIST: 5 * 60 * 1000, // 5 min
+    APP_LIST: 2 * 60 * 1000, // 2 min
+    UI_TREE: 30 * 1000, // 30 sec
+    GRADLE_VARIANTS: 60 * 60 * 1000, // 1 hour
+    LOGCAT: 5 * 60 * 1000, // 5 min
+};

package/dist/types/device.d.ts

@@ -0,0 +1,11 @@
+export type DeviceType = "emulator" | "physical";
+export type DeviceStatus = "online" | "offline" | "booting";
+export interface Device {
+    id: string;
+    type: DeviceType;
+    name: string;
+    status: DeviceStatus;
+}
+export interface DeviceState {
+    currentDevice: Device | null;
+}

package/dist/types/device.js

@@ -0,0 +1 @@
+export {};

package/dist/types/errors.d.ts

@@ -0,0 +1,31 @@
+export declare const ErrorCode: {
+    readonly NO_DEVICE_SELECTED: "NO_DEVICE_SELECTED";
+    readonly DEVICE_NOT_FOUND: "DEVICE_NOT_FOUND";
+    readonly DEVICE_OFFLINE: "DEVICE_OFFLINE";
+    readonly BUILD_FAILED: "BUILD_FAILED";
+    readonly GRADLE_NOT_FOUND: "GRADLE_NOT_FOUND";
+    readonly MODULE_NOT_FOUND: "MODULE_NOT_FOUND";
+    readonly APK_NOT_FOUND: "APK_NOT_FOUND";
+    readonly PACKAGE_NOT_FOUND: "PACKAGE_NOT_FOUND";
+    readonly INSTALL_FAILED: "INSTALL_FAILED";
+    readonly AVD_NOT_FOUND: "AVD_NOT_FOUND";
+    readonly EMULATOR_START_FAILED: "EMULATOR_START_FAILED";
+    readonly SNAPSHOT_NOT_FOUND: "SNAPSHOT_NOT_FOUND";
+    readonly COMMAND_BLOCKED: "COMMAND_BLOCKED";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly CACHE_MISS: "CACHE_MISS";
+};
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+export interface ToolError {
+    error: ErrorCode;
+    message: string;
+    suggestion?: string;
+    details?: Record<string, unknown>;
+}
+export declare class ReplicantError extends Error {
+    readonly code: ErrorCode;
+    readonly suggestion?: string | undefined;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: ErrorCode, message: string, suggestion?: string | undefined, details?: Record<string, unknown> | undefined);
+    toToolError(): ToolError;
+}

package/dist/types/errors.js

@@ -0,0 +1,43 @@
+export const ErrorCode = {
+    // Device errors
+    NO_DEVICE_SELECTED: "NO_DEVICE_SELECTED",
+    DEVICE_NOT_FOUND: "DEVICE_NOT_FOUND",
+    DEVICE_OFFLINE: "DEVICE_OFFLINE",
+    // Build errors
+    BUILD_FAILED: "BUILD_FAILED",
+    GRADLE_NOT_FOUND: "GRADLE_NOT_FOUND",
+    MODULE_NOT_FOUND: "MODULE_NOT_FOUND",
+    // App errors
+    APK_NOT_FOUND: "APK_NOT_FOUND",
+    PACKAGE_NOT_FOUND: "PACKAGE_NOT_FOUND",
+    INSTALL_FAILED: "INSTALL_FAILED",
+    // Emulator errors
+    AVD_NOT_FOUND: "AVD_NOT_FOUND",
+    EMULATOR_START_FAILED: "EMULATOR_START_FAILED",
+    SNAPSHOT_NOT_FOUND: "SNAPSHOT_NOT_FOUND",
+    // Safety errors
+    COMMAND_BLOCKED: "COMMAND_BLOCKED",
+    TIMEOUT: "TIMEOUT",
+    // Cache errors
+    CACHE_MISS: "CACHE_MISS",
+};
+export class ReplicantError extends Error {
+    code;
+    suggestion;
+    details;
+    constructor(code, message, suggestion, details) {
+        super(message);
+        this.code = code;
+        this.suggestion = suggestion;
+        this.details = details;
+        this.name = "ReplicantError";
+    }
+    toToolError() {
+        return {
+            error: this.code,
+            message: this.message,
+            suggestion: this.suggestion,
+            details: this.details,
+        };
+    }
+}

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./errors.js";
+export * from "./cache.js";
+export * from "./device.js";

package/dist/types/index.js

@@ -0,0 +1,3 @@
+export * from "./errors.js";
+export * from "./cache.js";
+export * from "./device.js";

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "replicant-mcp",
+  "version": "1.0.0",
+  "description": "Android MCP server for AI-assisted Android development",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "replicant-mcp": "dist/index.js",
+    "replicant": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest",
+    "test:unit": "vitest --run tests/services tests/adapters tests/tools",
+    "test:integration": "vitest --run tests/integration",
+    "test:coverage": "vitest --run --coverage",
+    "check-prereqs": "bash scripts/check-prerequisites.sh",
+    "smoke-test": "bash scripts/smoke-test.sh",
+    "test:device": "tsx scripts/real-device-test.ts",
+    "start": "node dist/index.js",
+    "validate": "npm run build && npm run test -- --run",
+    "install-skill": "bash scripts/install-skill.sh",
+    "prepublishOnly": "npm run build && npm test -- --run"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "android",
+    "adb",
+    "gradle",
+    "emulator",
+    "ui-automation",
+    "ai",
+    "llm"
+  ],
+  "author": "Archit Joshi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thecombatwombat/replicant-mcp.git"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "commander": "^14.0.2",
+    "execa": "^9.6.1",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.9",
+    "@vitest/coverage-v8": "^4.0.17",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  }
+}