replicant-mcp 1.0.0

package/dist/server.js

@@ -0,0 +1,113 @@
+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 { CacheManager, DeviceStateManager, ProcessRunner } 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";
+export function createServerContext() {
+    const processRunner = new ProcessRunner();
+    const adb = new AdbAdapter(processRunner);
+    return {
+        cache: new CacheManager(),
+        deviceState: new DeviceStateManager(),
+        processRunner,
+        adb,
+        emulator: new EmulatorAdapter(processRunner),
+        gradle: new GradleAdapter(processRunner),
+        ui: new UiAutomatorAdapter(adb),
+    };
+}
+export async function createServer(context) {
+    const server = new Server({
+        name: "replicant-mcp",
+        version: "1.0.0",
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // Register tool list handler
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            cacheToolDefinition,
+            rtfmToolDefinition,
+            adbDeviceToolDefinition,
+            adbAppToolDefinition,
+            adbLogcatToolDefinition,
+            adbShellToolDefinition,
+            emulatorDeviceToolDefinition,
+            gradleBuildToolDefinition,
+            gradleTestToolDefinition,
+            gradleListToolDefinition,
+            gradleGetDetailsToolDefinition,
+            uiToolDefinition,
+        ],
+    }));
+    // Register tool call handler
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            let result;
+            switch (name) {
+                case "cache":
+                    result = await handleCacheTool(args, context.cache);
+                    break;
+                case "rtfm":
+                    result = await handleRtfmTool(args);
+                    break;
+                case "adb-device":
+                    result = await handleAdbDeviceTool(args, context);
+                    break;
+                case "adb-app":
+                    result = await handleAdbAppTool(args, context);
+                    break;
+                case "adb-logcat":
+                    result = await handleAdbLogcatTool(args, context);
+                    break;
+                case "adb-shell":
+                    result = await handleAdbShellTool(args, context);
+                    break;
+                case "emulator-device":
+                    result = await handleEmulatorDeviceTool(args, context);
+                    break;
+                case "gradle-build":
+                    result = await handleGradleBuildTool(args, context);
+                    break;
+                case "gradle-test":
+                    result = await handleGradleTestTool(args, context);
+                    break;
+                case "gradle-list":
+                    result = await handleGradleListTool(args, context);
+                    break;
+                case "gradle-get-details":
+                    result = await handleGradleGetDetailsTool(args, context);
+                    break;
+                case "ui":
+                    result = await handleUiTool(args, context);
+                    break;
+                default:
+                    throw new Error(`Unknown tool: ${name}`);
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            if (error instanceof ReplicantError) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify(error.toToolError(), null, 2) }],
+                    isError: true,
+                };
+            }
+            throw error;
+        }
+    });
+    return server;
+}
+export async function runServer() {
+    const context = createServerContext();
+    const server = await createServer(context);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/services/cache-manager.d.ts

@@ -0,0 +1,22 @@
+import { CacheEntry, CacheConfig } from "../types/index.js";
+export interface CacheStats {
+    entryCount: number;
+    totalSizeBytes: number;
+    typeBreakdown: Record<string, number>;
+    config: CacheConfig;
+}
+export declare class CacheManager {
+    private cache;
+    private accessOrder;
+    private config;
+    constructor(config?: Partial<CacheConfig>);
+    generateId(type: string): string;
+    set<T>(id: string, data: T, type: string, ttlMs?: number): void;
+    get<T>(id: string): CacheEntry<T> | undefined;
+    clear(id: string): void;
+    clearAll(): void;
+    invalidateByType(type: string): void;
+    getStats(): CacheStats;
+    getConfig(): CacheConfig;
+    setConfig(config: Partial<CacheConfig>): void;
+}

package/dist/services/cache-manager.js

@@ -0,0 +1,90 @@
+import { DEFAULT_CACHE_CONFIG } from "../types/index.js";
+import { randomBytes } from "crypto";
+export class CacheManager {
+    cache = new Map();
+    accessOrder = [];
+    config;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CACHE_CONFIG, ...config };
+    }
+    generateId(type) {
+        const hash = randomBytes(4).toString("hex");
+        const timestamp = Date.now();
+        return `${type}-${hash}-${timestamp}`;
+    }
+    set(id, data, type, ttlMs) {
+        const now = Date.now();
+        const sizeBytes = JSON.stringify(data).length;
+        // LRU eviction
+        while (this.cache.size >= this.config.maxEntries) {
+            const oldest = this.accessOrder.shift();
+            if (oldest) {
+                this.cache.delete(oldest);
+            }
+        }
+        const entry = {
+            data,
+            expiresAt: now + (ttlMs ?? this.config.defaultTtlMs),
+            metadata: {
+                createdAt: now,
+                type,
+                sizeBytes,
+            },
+        };
+        this.cache.set(id, entry);
+        this.accessOrder.push(id);
+    }
+    get(id) {
+        const entry = this.cache.get(id);
+        if (!entry) {
+            return undefined;
+        }
+        // Check expiration
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(id);
+            this.accessOrder = this.accessOrder.filter((k) => k !== id);
+            return undefined;
+        }
+        // Update access order for LRU
+        this.accessOrder = this.accessOrder.filter((k) => k !== id);
+        this.accessOrder.push(id);
+        return entry;
+    }
+    clear(id) {
+        this.cache.delete(id);
+        this.accessOrder = this.accessOrder.filter((k) => k !== id);
+    }
+    clearAll() {
+        this.cache.clear();
+        this.accessOrder = [];
+    }
+    invalidateByType(type) {
+        for (const [id, entry] of this.cache.entries()) {
+            if (entry.metadata.type === type) {
+                this.cache.delete(id);
+            }
+        }
+        this.accessOrder = this.accessOrder.filter((id) => this.cache.has(id));
+    }
+    getStats() {
+        const typeBreakdown = {};
+        let totalSizeBytes = 0;
+        for (const entry of this.cache.values()) {
+            const type = entry.metadata.type;
+            typeBreakdown[type] = (typeBreakdown[type] ?? 0) + 1;
+            totalSizeBytes += entry.metadata.sizeBytes ?? 0;
+        }
+        return {
+            entryCount: this.cache.size,
+            totalSizeBytes,
+            typeBreakdown,
+            config: this.config,
+        };
+    }
+    getConfig() {
+        return { ...this.config };
+    }
+    setConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+}

package/dist/services/device-state.d.ts

@@ -0,0 +1,9 @@
+import { Device } from "../types/index.js";
+export declare class DeviceStateManager {
+    private currentDevice;
+    getCurrentDevice(): Device | null;
+    setCurrentDevice(device: Device): void;
+    clearCurrentDevice(): void;
+    requireCurrentDevice(): Device;
+    autoSelectIfSingle(devices: Device[]): boolean;
+}

package/dist/services/device-state.js

@@ -0,0 +1,26 @@
+import { ReplicantError, ErrorCode } from "../types/index.js";
+export class DeviceStateManager {
+    currentDevice = null;
+    getCurrentDevice() {
+        return this.currentDevice;
+    }
+    setCurrentDevice(device) {
+        this.currentDevice = device;
+    }
+    clearCurrentDevice() {
+        this.currentDevice = null;
+    }
+    requireCurrentDevice() {
+        if (!this.currentDevice) {
+            throw new ReplicantError(ErrorCode.NO_DEVICE_SELECTED, "No device selected", "Call adb-device({ operation: 'list' }) to see available devices");
+        }
+        return this.currentDevice;
+    }
+    autoSelectIfSingle(devices) {
+        if (devices.length === 1 && !this.currentDevice) {
+            this.currentDevice = devices[0];
+            return true;
+        }
+        return false;
+    }
+}

package/dist/services/index.d.ts

@@ -0,0 +1,3 @@
+export { ProcessRunner, type RunOptions, type RunResult } from "./process-runner.js";
+export { CacheManager, type CacheStats } from "./cache-manager.js";
+export { DeviceStateManager } from "./device-state.js";

package/dist/services/index.js

@@ -0,0 +1,3 @@
+export { ProcessRunner } from "./process-runner.js";
+export { CacheManager } from "./cache-manager.js";
+export { DeviceStateManager } from "./device-state.js";

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

@@ -0,0 +1,15 @@
+export interface RunOptions {
+    timeoutMs?: number;
+    cwd?: string;
+}
+export interface RunResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export declare class ProcessRunner {
+    private readonly defaultTimeoutMs;
+    private readonly maxTimeoutMs;
+    run(command: string, args: string[], options?: RunOptions): Promise<RunResult>;
+    private validateCommand;
+}

package/dist/services/process-runner.js

@@ -0,0 +1,62 @@
+import { execa } from "execa";
+import { ReplicantError, ErrorCode } from "../types/index.js";
+const BLOCKED_COMMANDS = new Set(["reboot", "shutdown", "halt", "poweroff"]);
+const BLOCKED_PATTERNS = [
+    /^rm\s+(-[rf]+\s+)*\//, // rm -rf /
+    /^su(\s|$)/, // su
+    /^sudo(\s|$)/, // sudo
+    /\bformat\b/, // format commands
+];
+export class ProcessRunner {
+    defaultTimeoutMs = 30_000;
+    maxTimeoutMs = 120_000;
+    async run(command, args, options = {}) {
+        this.validateCommand(command, args);
+        const timeoutMs = Math.min(options.timeoutMs ?? this.defaultTimeoutMs, this.maxTimeoutMs);
+        try {
+            const result = await execa(command, args, {
+                timeout: timeoutMs,
+                cwd: options.cwd,
+            });
+            return {
+                stdout: result.stdout,
+                stderr: result.stderr,
+                exitCode: result.exitCode ?? 0,
+            };
+        }
+        catch (error) {
+            // Check for timeout (execa v9 uses timedOut property)
+            if (typeof error === "object" &&
+                error !== null &&
+                "timedOut" in error &&
+                error.timedOut) {
+                throw new ReplicantError(ErrorCode.TIMEOUT, `Command timed out after ${timeoutMs}ms`, "Try increasing the timeout or simplifying the command");
+            }
+            // For non-zero exit code, return the result instead of throwing
+            if (typeof error === "object" &&
+                error !== null &&
+                "exitCode" in error &&
+                "stdout" in error &&
+                "stderr" in error) {
+                const execaError = error;
+                return {
+                    stdout: execaError.stdout,
+                    stderr: execaError.stderr,
+                    exitCode: execaError.exitCode,
+                };
+            }
+            throw error;
+        }
+    }
+    validateCommand(command, args) {
+        if (BLOCKED_COMMANDS.has(command)) {
+            throw new ReplicantError(ErrorCode.COMMAND_BLOCKED, `Command '${command}' is not allowed`, "Use safe commands only");
+        }
+        const fullCommand = `${command} ${args.join(" ")}`;
+        for (const pattern of BLOCKED_PATTERNS) {
+            if (pattern.test(fullCommand)) {
+                throw new ReplicantError(ErrorCode.COMMAND_BLOCKED, `Command '${fullCommand}' is not allowed`, "Use safe commands only");
+            }
+        }
+    }
+}

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

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { ServerContext } from "../server.js";
+export declare const adbAppInputSchema: z.ZodObject<{
+    operation: z.ZodEnum<{
+        list: "list";
+        install: "install";
+        uninstall: "uninstall";
+        launch: "launch";
+        stop: "stop";
+        "clear-data": "clear-data";
+    }>;
+    apkPath: z.ZodOptional<z.ZodString>;
+    packageName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AdbAppInput = z.infer<typeof adbAppInputSchema>;
+export declare function handleAdbAppTool(input: AdbAppInput, context: ServerContext): Promise<Record<string, unknown>>;
+export declare const adbAppToolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            operation: {
+                type: string;
+                enum: string[];
+            };
+            apkPath: {
+                type: string;
+                description: string;
+            };
+            packageName: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};

package/dist/tools/adb-app.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+export const adbAppInputSchema = z.object({
+    operation: z.enum(["install", "uninstall", "launch", "stop", "clear-data", "list"]),
+    apkPath: z.string().optional(),
+    packageName: z.string().optional(),
+});
+export async function handleAdbAppTool(input, context) {
+    const deviceId = context.deviceState.requireCurrentDevice().id;
+    switch (input.operation) {
+        case "install": {
+            if (!input.apkPath) {
+                throw new Error("apkPath is required for install operation");
+            }
+            await context.adb.install(deviceId, input.apkPath);
+            return { installed: input.apkPath, deviceId };
+        }
+        case "uninstall": {
+            if (!input.packageName) {
+                throw new Error("packageName is required for uninstall operation");
+            }
+            await context.adb.uninstall(deviceId, input.packageName);
+            return { uninstalled: input.packageName, deviceId };
+        }
+        case "launch": {
+            if (!input.packageName) {
+                throw new Error("packageName is required for launch operation");
+            }
+            await context.adb.launch(deviceId, input.packageName);
+            return { launched: input.packageName, deviceId };
+        }
+        case "stop": {
+            if (!input.packageName) {
+                throw new Error("packageName is required for stop operation");
+            }
+            await context.adb.stop(deviceId, input.packageName);
+            return { stopped: input.packageName, deviceId };
+        }
+        case "clear-data": {
+            if (!input.packageName) {
+                throw new Error("packageName is required for clear-data operation");
+            }
+            await context.adb.clearData(deviceId, input.packageName);
+            return { cleared: input.packageName, deviceId };
+        }
+        case "list": {
+            const packages = await context.adb.getPackages(deviceId);
+            return { packages, count: packages.length, deviceId };
+        }
+        default:
+            throw new Error(`Unknown operation: ${input.operation}`);
+    }
+}
+export const adbAppToolDefinition = {
+    name: "adb-app",
+    description: "Manage applications. Operations: install, uninstall, launch, stop, clear-data, list.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            operation: {
+                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)" },
+        },
+        required: ["operation"],
+    },
+};

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

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { ServerContext } from "../server.js";
+export declare const adbDeviceInputSchema: z.ZodObject<{
+    operation: z.ZodEnum<{
+        list: "list";
+        select: "select";
+        wait: "wait";
+        properties: "properties";
+    }>;
+    deviceId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AdbDeviceInput = z.infer<typeof adbDeviceInputSchema>;
+export declare function handleAdbDeviceTool(input: AdbDeviceInput, context: ServerContext): Promise<Record<string, unknown>>;
+export declare const adbDeviceToolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            operation: {
+                type: string;
+                enum: string[];
+            };
+            deviceId: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};

package/dist/tools/adb-device.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+export const adbDeviceInputSchema = z.object({
+    operation: z.enum(["list", "select", "wait", "properties"]),
+    deviceId: z.string().optional(),
+});
+export async function handleAdbDeviceTool(input, context) {
+    switch (input.operation) {
+        case "list": {
+            const devices = await context.adb.getDevices();
+            context.deviceState.autoSelectIfSingle(devices);
+            const current = context.deviceState.getCurrentDevice();
+            return {
+                devices,
+                currentDevice: current?.id || null,
+                autoSelected: devices.length === 1,
+            };
+        }
+        case "select": {
+            if (!input.deviceId) {
+                throw new Error("deviceId is required for select operation");
+            }
+            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`);
+            }
+            context.deviceState.setCurrentDevice(device);
+            return { selected: device };
+        }
+        case "wait": {
+            const deviceId = input.deviceId || context.deviceState.getCurrentDevice()?.id;
+            if (!deviceId) {
+                throw new Error("No device selected. Call with deviceId or select a device first.");
+            }
+            await context.adb.waitForDevice(deviceId);
+            return { status: "device ready", deviceId };
+        }
+        case "properties": {
+            const deviceId = input.deviceId || context.deviceState.requireCurrentDevice().id;
+            const props = await context.adb.getProperties(deviceId);
+            return {
+                deviceId,
+                properties: {
+                    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"],
+                },
+                allProperties: props,
+            };
+        }
+        default:
+            throw new Error(`Unknown operation: ${input.operation}`);
+    }
+}
+export const adbDeviceToolDefinition = {
+    name: "adb-device",
+    description: "Manage device connections. Operations: list, select, wait, properties.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            operation: {
+                type: "string",
+                enum: ["list", "select", "wait", "properties"],
+            },
+            deviceId: { type: "string", description: "Device ID for select/wait/properties" },
+        },
+        required: ["operation"],
+    },
+};

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

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { ServerContext } from "../server.js";
+export declare const adbLogcatInputSchema: z.ZodObject<{
+    lines: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    package: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    level: z.ZodOptional<z.ZodEnum<{
+        debug: "debug";
+        info: "info";
+        verbose: "verbose";
+        warn: "warn";
+        error: "error";
+    }>>;
+    rawFilter: z.ZodOptional<z.ZodString>;
+    since: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AdbLogcatInput = z.infer<typeof adbLogcatInputSchema>;
+export declare function handleAdbLogcatTool(input: AdbLogcatInput, context: ServerContext): Promise<Record<string, unknown>>;
+export declare const adbLogcatToolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            lines: {
+                type: string;
+                description: string;
+            };
+            package: {
+                type: string;
+                description: string;
+            };
+            tags: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            level: {
+                type: string;
+                enum: string[];
+            };
+            rawFilter: {
+                type: string;
+                description: string;
+            };
+            since: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+};