mobile-device-mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// ============================================================
+// CLI entry point for mobile-device-mcp
+//
+// All user-facing output goes to stderr.
+// stdout is reserved for the MCP JSON-RPC protocol.
+// ============================================================
+import { createServer } from "./server.js";
+import { findAdbPath, getDefaultDevice } from "./utils/discovery.js";
+import { DEFAULT_CONFIG, DEFAULT_AI_CONFIG } from "./types.js";
+const PREFIX = "[mobile-device-mcp]";
+/** Write a message to stderr (never stdout). */
+function log(message) {
+    process.stderr.write(`${PREFIX} ${message}\n`);
+}
+/** Parse an env var as a positive integer, or return undefined. */
+function envInt(name) {
+    const raw = process.env[name];
+    if (raw === undefined || raw === "")
+        return undefined;
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+async function main() {
+    log("Starting...");
+    // 1. Discover ADB
+    let adbPath;
+    const envAdbPath = process.env["MCP_ADB_PATH"];
+    if (envAdbPath) {
+        adbPath = envAdbPath;
+        log(`Using ADB from MCP_ADB_PATH: ${adbPath}`);
+    }
+    else {
+        adbPath = await findAdbPath();
+        log(`Found ADB: ${adbPath}`);
+    }
+    // 2. Discover default device
+    let defaultDevice = process.env["MCP_DEFAULT_DEVICE"];
+    if (!defaultDevice) {
+        defaultDevice = await getDefaultDevice(adbPath);
+    }
+    if (defaultDevice) {
+        log(`Default device: ${defaultDevice}`);
+    }
+    // 3. Build config from defaults + env overrides
+    const screenshotFormat = process.env["MCP_SCREENSHOT_FORMAT"];
+    const config = {
+        adbPath,
+        defaultDevice,
+        screenshotFormat: screenshotFormat === "jpeg" || screenshotFormat === "png"
+            ? screenshotFormat
+            : DEFAULT_CONFIG.screenshotFormat,
+        screenshotQuality: envInt("MCP_SCREENSHOT_QUALITY") ?? DEFAULT_CONFIG.screenshotQuality,
+        screenshotMaxWidth: envInt("MCP_SCREENSHOT_MAX_WIDTH") ?? DEFAULT_CONFIG.screenshotMaxWidth,
+    };
+    // 3b. AI configuration — supports Anthropic and Google Gemini
+    const anthropicKey = process.env.ANTHROPIC_API_KEY || "";
+    const googleKey = process.env.GOOGLE_API_KEY || process.env.GEMINI_API_KEY || "";
+    const apiKey = anthropicKey || googleKey || process.env.MCP_AI_API_KEY || "";
+    if (apiKey) {
+        // Auto-detect provider from which key is set; env var can override.
+        const envProvider = process.env.MCP_AI_PROVIDER;
+        let provider;
+        if (envProvider === "anthropic" || envProvider === "google") {
+            provider = envProvider;
+        }
+        else if (googleKey && !anthropicKey) {
+            provider = "google";
+        }
+        else {
+            provider = "anthropic";
+        }
+        // Default model depends on provider.
+        const defaultModel = provider === "google" ? "gemini-2.5-flash" : "claude-sonnet-4-20250514";
+        config.ai = {
+            provider,
+            apiKey,
+            model: process.env.MCP_AI_MODEL || defaultModel,
+            maxTokens: parseInt(process.env.MCP_AI_MAX_TOKENS || String(DEFAULT_AI_CONFIG.maxTokens)),
+            analyzeWithScreenshot: process.env.MCP_AI_SCREENSHOT !== "false",
+            analyzeWithUITree: process.env.MCP_AI_UITREE !== "false",
+        };
+        log(`AI features enabled (provider: ${provider}, model: ${config.ai.model})`);
+    }
+    else {
+        log("AI features disabled (set ANTHROPIC_API_KEY or GOOGLE_API_KEY to enable)");
+    }
+    // 4. Create and start the server
+    const { start } = createServer(config);
+    await start();
+    log("Server running on stdio");
+}
+// ------------------------------------------------------------------
+// Graceful shutdown
+// ------------------------------------------------------------------
+function shutdown(signal) {
+    log(`Received ${signal}, shutting down...`);
+    process.exit(0);
+}
+process.on("SIGINT", () => shutdown("SIGINT"));
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+// ------------------------------------------------------------------
+// Error handling
+// ------------------------------------------------------------------
+process.on("uncaughtException", (error) => {
+    log(`Fatal error: ${error.message}`);
+    if (error.stack) {
+        process.stderr.write(`${error.stack}\n`);
+    }
+    process.exit(1);
+});
+process.on("unhandledRejection", (reason) => {
+    const message = reason instanceof Error ? reason.message : String(reason);
+    log(`Unhandled rejection: ${message}`);
+    if (reason instanceof Error && reason.stack) {
+        process.stderr.write(`${reason.stack}\n`);
+    }
+    process.exit(1);
+});
+// ------------------------------------------------------------------
+// Run
+// ------------------------------------------------------------------
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    log(`Failed to start: ${message}`);
+    if (error instanceof Error && error.stack) {
+        process.stderr.write(`${error.stack}\n`);
+    }
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -0,0 +1,13 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ServerConfig } from "./types.js";
+/**
+ * Create a configured MCP server ready to start.
+ *
+ * Returns the server instance and a `start()` function that connects
+ * a stdio transport (the MCP JSON-RPC channel).
+ */
+export declare function createServer(config: ServerConfig): {
+    server: McpServer;
+    start: () => Promise<void>;
+};
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAS/C;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG;IAClD,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B,CA2BA"}

package/dist/server.js

@@ -0,0 +1,41 @@
+// ============================================================
+// MCP Server factory — creates and wires up the server
+// ============================================================
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { AndroidDriver } from "./drivers/android/index.js";
+import { registerAllTools } from "./tools/index.js";
+import { AIClient } from "./ai/client.js";
+import { ScreenAnalyzer } from "./ai/analyzer.js";
+/** Server version — matches package.json */
+const SERVER_VERSION = "0.1.0";
+/**
+ * Create a configured MCP server ready to start.
+ *
+ * Returns the server instance and a `start()` function that connects
+ * a stdio transport (the MCP JSON-RPC channel).
+ */
+export function createServer(config) {
+    const server = new McpServer({
+        name: "mobile-device-mcp",
+        version: SERVER_VERSION,
+    });
+    const driver = new AndroidDriver(config.adbPath);
+    // Set up AI features if configured
+    let analyzer = null;
+    if (config.ai && config.ai.apiKey) {
+        const aiClient = new AIClient(config.ai);
+        analyzer = new ScreenAnalyzer(aiClient, driver, config.ai, {
+            format: config.screenshotFormat,
+            quality: config.screenshotQuality,
+            maxWidth: config.screenshotMaxWidth,
+        });
+    }
+    registerAllTools(server, () => driver, () => analyzer);
+    async function start() {
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+    }
+    return { server, start };
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,uDAAuD;AACvD,+DAA+D;AAE/D,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,4CAA4C;AAC5C,MAAM,cAAc,GAAG,OAAO,CAAC;AAE/B;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,MAAoB;IAI/C,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,mBAAmB;QACzB,OAAO,EAAE,cAAc;KACxB,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAEjD,mCAAmC;IACnC,IAAI,QAAQ,GAA0B,IAAI,CAAC;IAC3C,IAAI,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACzC,QAAQ,GAAG,IAAI,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE;YACzD,MAAM,EAAE,MAAM,CAAC,gBAAgB;YAC/B,OAAO,EAAE,MAAM,CAAC,iBAAiB;YACjC,QAAQ,EAAE,MAAM,CAAC,kBAAkB;SACpC,CAAC,CAAC;IACL,CAAC;IAED,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,CAAC;IAEvD,KAAK,UAAU,KAAK;QAClB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;QAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAClC,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAC3B,CAAC"}

package/dist/tools/ai-tools.d.ts

@@ -0,0 +1,11 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ScreenAnalyzer } from "../ai/analyzer.js";
+/**
+ * Register AI-powered MCP tools on the given server.
+ *
+ * @param server       — The McpServer instance to register tools on.
+ * @param getAnalyzer  — Returns the active ScreenAnalyzer, or null if AI
+ *                       features are not configured (missing API key).
+ */
+export declare function registerAITools(server: McpServer, getAnalyzer: () => ScreenAnalyzer | null): void;
+//# sourceMappingURL=ai-tools.d.ts.map

package/dist/tools/ai-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-tools.d.ts","sourceRoot":"","sources":["../../src/tools/ai-tools.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAyCxD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,MAAM,cAAc,GAAG,IAAI,GACvC,IAAI,CAsPN"}

package/dist/tools/ai-tools.js

@@ -0,0 +1,238 @@
+// ============================================================
+// AI-powered tools — visual analysis, smart interactions,
+// element finding, and screen verification via Claude vision.
+// ============================================================
+import { z } from "zod";
+/** Standard error payload when AI features are unavailable. */
+const AI_UNAVAILABLE = {
+    content: [
+        {
+            type: "text",
+            text: "AI features are not available. Set ANTHROPIC_API_KEY environment variable to enable AI-powered tools.",
+        },
+    ],
+    isError: true,
+};
+/**
+ * Format a value as a JSON text MCP response with 2-space indentation.
+ */
+function jsonResponse(value) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(value, null, 2),
+            },
+        ],
+    };
+}
+/**
+ * Format an error as a text MCP response.
+ */
+function errorResponse(label, error) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Error in ${label}: ${error instanceof Error ? error.message : String(error)}`,
+            },
+        ],
+    };
+}
+/**
+ * Register AI-powered MCP tools on the given server.
+ *
+ * @param server       — The McpServer instance to register tools on.
+ * @param getAnalyzer  — Returns the active ScreenAnalyzer, or null if AI
+ *                       features are not configured (missing API key).
+ */
+export function registerAITools(server, getAnalyzer) {
+    // ----------------------------------------------------------
+    // analyze_screen
+    // ----------------------------------------------------------
+    server.registerTool("analyze_screen", {
+        title: "Analyze Screen (AI)",
+        description: "Uses AI vision to analyze the current screen of a mobile device. Returns a structured analysis including app name, screen type, interactive elements with coordinates, visible text, and suggested next actions. This is the primary tool for understanding what is currently displayed on the device.",
+        inputSchema: z.object({
+            device_id: z.string().describe("Device serial ID"),
+        }),
+    }, async ({ device_id }) => {
+        try {
+            const analyzer = getAnalyzer();
+            if (!analyzer)
+                return AI_UNAVAILABLE;
+            const analysis = await analyzer.analyzeScreen(device_id);
+            return jsonResponse(analysis);
+        }
+        catch (error) {
+            return errorResponse("analyze_screen", error);
+        }
+    });
+    // ----------------------------------------------------------
+    // find_element
+    // ----------------------------------------------------------
+    server.registerTool("find_element", {
+        title: "Find Element by Description (AI)",
+        description: "Uses AI vision to find a specific UI element by natural language description. Returns the element's coordinates, type, and confidence score. Use this when you need to locate a specific button, field, or other UI element. Example queries: 'the login button', 'email input field', 'the red error message'.",
+        inputSchema: z.object({
+            device_id: z.string().describe("Device serial ID"),
+            query: z
+                .string()
+                .describe("Natural language description of the element to find, e.g. 'the blue Submit button' or 'email input field'"),
+        }),
+    }, async ({ device_id, query }) => {
+        try {
+            const analyzer = getAnalyzer();
+            if (!analyzer)
+                return AI_UNAVAILABLE;
+            const match = await analyzer.findElement(device_id, query);
+            return jsonResponse(match);
+        }
+        catch (error) {
+            return errorResponse("find_element", error);
+        }
+    });
+    // ----------------------------------------------------------
+    // suggest_actions
+    // ----------------------------------------------------------
+    server.registerTool("suggest_actions", {
+        title: "Suggest Actions for Goal (AI)",
+        description: "Uses AI to analyze the current screen and suggest a sequence of actions to achieve a specified goal. Returns step-by-step instructions with exact coordinates for each action. Example goals: 'log into the app', 'navigate to settings', 'add an item to cart'.",
+        inputSchema: z.object({
+            device_id: z.string().describe("Device serial ID"),
+            goal: z
+                .string()
+                .describe("What you want to accomplish, e.g. 'log into the app' or 'navigate to settings'"),
+        }),
+    }, async ({ device_id, goal }) => {
+        try {
+            const analyzer = getAnalyzer();
+            if (!analyzer)
+                return AI_UNAVAILABLE;
+            const plan = await analyzer.suggestActions(device_id, goal);
+            return jsonResponse(plan);
+        }
+        catch (error) {
+            return errorResponse("suggest_actions", error);
+        }
+    });
+    // ----------------------------------------------------------
+    // visual_diff
+    // ----------------------------------------------------------
+    server.registerTool("visual_diff", {
+        title: "Visual Diff (AI)",
+        description: "Compares the current screen with a previous screenshot to identify what changed. Provide a base64 PNG screenshot as the 'before' image — the tool captures the current screen as the 'after' image. Returns a list of changes with descriptions and regions. Useful for verifying that an action had the expected effect.",
+        inputSchema: z.object({
+            device_id: z.string().describe("Device serial ID"),
+            before_screenshot: z
+                .string()
+                .describe("Base64-encoded PNG of the previous screen state to compare against"),
+        }),
+    }, async ({ device_id, before_screenshot }) => {
+        try {
+            const analyzer = getAnalyzer();
+            if (!analyzer)
+                return AI_UNAVAILABLE;
+            const diff = await analyzer.compareScreenshots(device_id, before_screenshot);
+            return jsonResponse(diff);
+        }
+        catch (error) {
+            return errorResponse("visual_diff", error);
+        }
+    });
+    // ----------------------------------------------------------
+    // smart_tap
+    // ----------------------------------------------------------
+    server.registerTool("smart_tap", {
+        title: "Smart Tap (AI)",
+        description: "Finds a UI element by natural language description and taps it. Combines element finding and tapping into a single action. Example: smart_tap('the Sign In button') will locate the button and tap its center coordinates. Returns whether the tap succeeded and which element was tapped.",
+        inputSchema: z.object({
+            device_id: z.string().describe("Device serial ID"),
+            element_description: z
+                .string()
+                .describe("Description of the element to tap, e.g. 'the Submit button' or 'the settings icon'"),
+        }),
+    }, async ({ device_id, element_description }) => {
+        try {
+            const analyzer = getAnalyzer();
+            if (!analyzer)
+                return AI_UNAVAILABLE;
+            const result = await analyzer.smartTap(device_id, element_description);
+            return jsonResponse(result);
+        }
+        catch (error) {
+            return errorResponse("smart_tap", error);
+        }
+    });
+    // ----------------------------------------------------------
+    // smart_type
+    // ----------------------------------------------------------
+    server.registerTool("smart_type", {
+        title: "Smart Type (AI)",
+        description: "Finds an input field by natural language description, taps it to focus, and types the specified text. Example: smart_type('email field', 'user@example.com') will find the email input, tap it, and type the email address.",
+        inputSchema: z.object({
+            device_id: z.string().describe("Device serial ID"),
+            field_description: z
+                .string()
+                .describe("Description of the input field, e.g. 'email field' or 'search bar'"),
+            text: z.string().describe("Text to type into the field"),
+        }),
+    }, async ({ device_id, field_description, text }) => {
+        try {
+            const analyzer = getAnalyzer();
+            if (!analyzer)
+                return AI_UNAVAILABLE;
+            const result = await analyzer.smartType(device_id, field_description, text);
+            return jsonResponse(result);
+        }
+        catch (error) {
+            return errorResponse("smart_type", error);
+        }
+    });
+    // ----------------------------------------------------------
+    // extract_text
+    // ----------------------------------------------------------
+    server.registerTool("extract_text", {
+        title: "Extract Text from Screen (AI)",
+        description: "Uses AI vision to extract all visible text from the current screen. Returns text in reading order (top to bottom, left to right). Useful for reading content, checking labels, or getting text that isn't in the accessibility tree.",
+        inputSchema: z.object({
+            device_id: z.string().describe("Device serial ID"),
+        }),
+    }, async ({ device_id }) => {
+        try {
+            const analyzer = getAnalyzer();
+            if (!analyzer)
+                return AI_UNAVAILABLE;
+            const texts = await analyzer.extractText(device_id);
+            return jsonResponse({ texts });
+        }
+        catch (error) {
+            return errorResponse("extract_text", error);
+        }
+    });
+    // ----------------------------------------------------------
+    // verify_screen
+    // ----------------------------------------------------------
+    server.registerTool("verify_screen", {
+        title: "Verify Screen State (AI)",
+        description: "Uses AI to verify whether a specific assertion about the current screen is true. Returns a boolean result with confidence score and evidence. Example assertions: 'the login was successful', 'an error message is displayed', 'the cart has 3 items'.",
+        inputSchema: z.object({
+            device_id: z.string().describe("Device serial ID"),
+            assertion: z
+                .string()
+                .describe("What to verify about the current screen state, e.g. 'the login was successful' or 'an error message is showing'"),
+        }),
+    }, async ({ device_id, assertion }) => {
+        try {
+            const analyzer = getAnalyzer();
+            if (!analyzer)
+                return AI_UNAVAILABLE;
+            const verification = await analyzer.verifyScreen(device_id, assertion);
+            return jsonResponse(verification);
+        }
+        catch (error) {
+            return errorResponse("verify_screen", error);
+        }
+    });
+}
+//# sourceMappingURL=ai-tools.js.map

package/dist/tools/ai-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-tools.js","sourceRoot":"","sources":["../../src/tools/ai-tools.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { DeviceDriver } from "../types.js";
+export declare function registerAppTools(server: McpServer, getDriver: () => DeviceDriver): void;
+//# sourceMappingURL=app-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"app-tools.d.ts","sourceRoot":"","sources":["../../src/tools/app-tools.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,EACjB,SAAS,EAAE,MAAM,YAAY,GAC5B,IAAI,CAqQN"}