mobile-mcp-server 1.0.1

package/README.md

@@ -0,0 +1,43 @@
+# Mobile MCP Server
+
+A Model Context Protocol (MCP) server for controlling Android devices and emulators.
+
+## Quick Start (Local)
+1. `npm install`
+2. `npm run build`
+3. `node dist/server.http.js`
+
+## Connecting from another PC (e.g. Claude Desktop)
+If your Claude Desktop is on a different machine than the Android execution node:
+
+### 1. Networking (Tailscale 추천)
+Since devices on different subnets (e.g., `192.168.1.x` and `192.168.31.x`) cannot communicate directly:
+- Install **Tailscale** on both machines.
+- Use the Tailscale IP (e.g., `100.x.x.x`) of the server machine.
+
+### 2. Client Setup
+1. Copy `proxy_client.js` from this repo to your client machine.
+2. Update your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mobile-mcp-http": {
+      "command": "node",
+      "args": [
+        "C:\\path\\to\\your\\proxy_client.js"
+      ],
+      "env": {
+        "MCP_SERVER_URL": "http://<SERVER_IP>:7000/mcp",
+        "MCP_API_KEY": "hash2026"
+      }
+    }
+  }
+}
+```
+
+## Features
+- ADB Toolset (click, type, shell, devices)
+- App Management (install, launch, list)
+- Automated Prompts (smoke test, launch-only)
+- Hardware Control (start emulator)

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'url';
+import path from 'path';
+// Get current directory
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const args = process.argv.slice(2);
+/**
+ * Universal Entry Point for Mobile MCP
+ *
+ * Usage:
+ * npx mobile-mcp               -> Runs local Stdio server (for PC)
+ * npx mobile-mcp --remote      -> Runs Proxy client (for Laptop)
+ */
+async function start() {
+    if (args.includes('--remote')) {
+        console.error('[Mobile MCP] Starting in REMOTE mode (Proxy Client)...');
+        // Point to the compiled proxy logic
+        const proxyPath = path.resolve(__dirname, '../proxy_client.js');
+        import(proxyPath);
+    }
+    else {
+        // Standard Local Stdio mode
+        const serverPath = path.resolve(__dirname, '../server.js');
+        import(serverPath);
+    }
+}
+start().catch(err => {
+    console.error('[Mobile MCP] Fatal Error:', err);
+    process.exit(1);
+});

package/dist/config/env.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Environment and runtime configurations
+ */
+export declare const SERVER_NAME: string;
+export declare const SERVER_VERSION: string;
+export declare const DEFAULT_COMMAND_TIMEOUT: number;
+export declare const APK_INSTALL_TIMEOUT: number;
+export declare const SCREENSHOT_TIMEOUT: number;
+export declare const APPIUM_HOST: string;
+export declare const APPIUM_PORT: number;
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export declare const LOG_LEVEL: LogLevel;
+export declare const MCP_API_KEY: string;

package/dist/config/env.js

@@ -0,0 +1,15 @@
+/**
+ * Environment and runtime configurations
+ */
+export const SERVER_NAME = "mobile-automation-server";
+export const SERVER_VERSION = "1.0.0";
+// Timeouts (in milliseconds)
+export const DEFAULT_COMMAND_TIMEOUT = 30000;
+export const APK_INSTALL_TIMEOUT = 120000;
+export const SCREENSHOT_TIMEOUT = 10000;
+// Appium configuration (for future use)
+export const APPIUM_HOST = process.env.APPIUM_HOST || "127.0.0.1";
+export const APPIUM_PORT = parseInt(process.env.APPIUM_PORT || "4723", 10);
+export const LOG_LEVEL = process.env.LOG_LEVEL || "info";
+// Security
+export const MCP_API_KEY = process.env.MCP_API_KEY || "hash2026";

package/dist/config/paths.d.ts

@@ -0,0 +1,8 @@
+export declare const ANDROID_HOME: string;
+export declare const ADB_PATH: string;
+export declare const EMULATOR_PATH: string;
+export declare const ARTIFACTS_ROOT: string;
+export declare const LOG_DIR: string;
+export declare const SCREENSHOT_DIR: string;
+export declare const APK_DIR: string;
+export declare const DOWNLOADS_DIR: string;

package/dist/config/paths.js

@@ -0,0 +1,22 @@
+/**
+ * Centralized path configurations
+ */
+import { join } from "path";
+import { fileURLToPath } from "url";
+import { dirname } from "path";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Android SDK paths
+export const ANDROID_HOME = process.env.ANDROID_HOME || "E:\\Android\\Sdk";
+export const ADB_PATH = process.env.ADB_PATH || join(ANDROID_HOME, "platform-tools", "adb.exe");
+export const EMULATOR_PATH = process.env.EMULATOR_PATH || join(ANDROID_HOME, "emulator", "emulator.exe");
+// Strict Artifact Paths (LOCKED by User Constraints)
+export const ARTIFACTS_ROOT = "D:\\Automation\\artifacts";
+export const LOG_DIR = join(ARTIFACTS_ROOT, "logs");
+export const SCREENSHOT_DIR = join(ARTIFACTS_ROOT, "shots"); // Strictly "shots", not "screenshots"
+export const APK_DIR = join(ARTIFACTS_ROOT, "apks");
+// Map "downloads" to apks directory for now, or a temp dir if needed, 
+// but user only gave us 3 allowlisted buckets. Let's force downloads to be treated as APKs if they are APKs.
+// or just put them in a temp folder inside artifacts if generic.
+// For now, I will add a strict DOWNLOADS_DIR that maps to apks for consistency with user constraints on APKs.
+export const DOWNLOADS_DIR = APK_DIR;

package/dist/logs/2026-02-09.log

@@ -0,0 +1,8 @@
+{"timestamp":"2026-02-09T14:04:19.170Z","level":"info","message":"TOOL: adb_devices","data":{"input":{},"success":true,"error":null}}
+{"timestamp":"2026-02-09T14:10:39.712Z","level":"info","message":"TOOL: tap","data":{"input":{"x":200,"y":450},"success":true,"error":null}}
+{"timestamp":"2026-02-09T14:10:47.878Z","level":"info","message":"TOOL: type_text","data":{"input":{"text":"vigneshwaran@pxlbrain.com"},"success":true,"error":null}}
+{"timestamp":"2026-02-09T14:17:22.975Z","level":"info","message":"TOOL: uninstall_app","data":{"input":{"package_name":"com.hashhealth"},"success":true,"error":null}}
+{"timestamp":"2026-02-09T14:19:57.351Z","level":"info","message":"TOOL: install_apk","data":{"input":{"apk_path":"D:\\MCP\\mobile-mcp-server\\downloads\\downloaded_1770637108340.apk"},"success":false,"error":"Command failed: \"D:\\Android\\platform-tools\\adb.exe\"  install  \"D:\\MCP\\mobile-mcp-server\\downloads\\downloaded_1770637108340.apk\"\nadb.exe: failed to install D:\\MCP\\mobile-mcp-server\\downloads\\downloaded_1770637108340.apk: Failure [INSTALL_PARSE_FAILED_NOT_APK: Failed to parse /data/app/vmdl715720077.tmp/base.apk: Failed to load asset path /data/app/vmdl715720077.tmp/base.apk]\r\n\r\n"}}
+{"timestamp":"2026-02-09T14:29:15.278Z","level":"info","message":"TOOL: adb_devices","data":{"input":{},"success":true,"error":null}}
+{"timestamp":"2026-02-09T14:31:41.399Z","level":"info","message":"TOOL: adb_devices","data":{"input":{},"success":true,"error":null}}
+{"timestamp":"2026-02-09T14:32:41.069Z","level":"info","message":"TOOL: install_apk","data":{"input":{"apk_path":"C:\\Users\\Vigneshwaran G\\Downloads\\application-16cd461a-950b-4e50-9c7c-367848657e8a.apk","device_id":"emulator-5554"},"success":true,"error":null}}

package/dist/prompts/mobile.prompts.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Mobile Prompts Domain - Enhanced for Industry Level Standards
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Register all mobile prompts
+ */
+export declare function registerMobilePrompts(server: McpServer): void;

package/dist/prompts/mobile.prompts.js

@@ -0,0 +1,96 @@
+import { z } from "zod";
+/**
+ * Register all mobile prompts
+ */
+export function registerMobilePrompts(server) {
+    // Prompt: install_only
+    server.prompt("install_only", {
+        apk_name: z.string().optional().describe("Name of the APK file to install (must be in artifacts/apks)"),
+    }, ({ apk_name }) => ({
+        messages: [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `
+## SYSTEM ROLE
+You are the **Mobile Automation Engine**. Execute deterministic installation workflows.
+
+## TASK: INSTALL_ONLY_FLOW
+1.  **Check Device**: Call \`adb_devices\`. 
+    - IF empty -> Call \`list_avds\` -> Call \`start_emulator\` -> **Wait 30s** (\`wait\`).
+2.  **Install**: Call \`install_apk\` with "D:\\Automation\\artifacts\\apks\\${apk_name || "<latest_apk>.apk"}"
+3.  **Verify**: Call \`list_packages\` to confirm.
+`
+                }
+            }]
+    }));
+    // Prompt: mobile_smoke_test (CRITICAL)
+    server.prompt("mobile_smoke_test", {
+        apk_name: z.string().optional().describe("Name of the APK file to install"),
+    }, ({ apk_name }) => ({
+        messages: [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `
+## SYSTEM ROLE
+You are the **Mobile Automation Engine**. You orchestrate the full "Day 1" smoke test.
+
+## TASK: MOBILE_SMOKE_TEST
+Install -> Launch -> Verify.
+
+### PHASE 1: PREPARATION
+1.  **Check Device**: Call \`adb_devices\`.
+    - IF no device found:
+        - Call \`list_avds\`.
+        - Call \`start_emulator\` with the first available AVD (or "Medium_Phone_API_36.1").
+        - **Wait 30s** (\`wait\`) for boot, then call \`adb_devices\` again.
+
+### PHASE 2: INSTALLATION
+2.  **Install APK**: Call \`install_apk\` with "D:\\Automation\\artifacts\\apks\\${apk_name || "<latest>"}"
+
+### PHASE 3: EXECUTION
+3.  **Launch App**: Call \`launch_app\` using package "com.hashhealth".
+4.  **Stabilize (Smart)**: Call \`wait_for_text\` with "Hash Health" or "Login".
+
+### PHASE 4: EVIDENCE & ASSERTION
+5.  **Smart Click**: Call \`smart_click\` with action text like "Get Started".
+6.  **Evidence**: Call \`take_screenshot\`.
+`
+                }
+            }]
+    }));
+    // Prompt: launch_and_check (AUTO-LAUNCH EMULATOR)
+    server.prompt("launch_and_check", {}, () => ({
+        messages: [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `
+## SYSTEM ROLE
+You are the **Mobile Automation Engine**. 
+
+## TASK: LAUNCH_AND_CHECK
+This is an **Automated Action**. If the emulator is off, you MUST turn it on.
+
+### EXECUTION PLAN
+1.  **Environment Check**:
+    - Call \`adb_devices\`.
+    - IF empty:
+        - Call \`list_avds\`.
+        - Call \`start_emulator\` (using "Medium_Phone_API_36.1" as priority).
+        - **Wait 35s** (\`wait\`) for full Android boot.
+        - Call \`adb_devices\` again to confirm.
+
+2.  **Launch**:
+    - Call \`launch_app\` with package "com.hashhealth".
+    
+3.  **Verify (Smart)**:
+    - Call \`wait_for_text\` with key app text from "mobile://screens/home".
+    - Call \`take_screenshot\`.
+    - Assert focus on "com.hashhealth".
+`
+                }
+            }]
+    }));
+}

package/dist/resources/mobile.resources.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Mobile Resources Domain
+ * Static configuration and ground-truth context
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Register all mobile resources
+ */
+export declare function registerMobileResources(server: McpServer): void;

package/dist/resources/mobile.resources.js

@@ -0,0 +1,66 @@
+/**
+ * Register all mobile resources
+ */
+export function registerMobileResources(server) {
+    // Resource: App Config
+    server.resource("app_config", "mobile://app/config", async (uri) => ({
+        contents: [{
+                uri: uri.href,
+                text: JSON.stringify({
+                    package: "com.hashhealth",
+                    launch_activity: ".MainActivity",
+                    timeouts: {
+                        install: 30000,
+                        launch: 5000
+                    }
+                }, null, 2)
+            }]
+    }));
+    // Resource: Device Config
+    server.resource("device_config", "mobile://device/config", async (uri) => ({
+        contents: [{
+                uri: uri.href,
+                text: JSON.stringify({
+                    default_emulator: "Medium_Phone_API_36.1",
+                    adb_serial: "emulator-5554"
+                }, null, 2)
+            }]
+    }));
+    // Resource: Home Screen Map (Refined for Orchestration)
+    server.resource("home_screen", "mobile://screens/home", async (uri) => ({
+        contents: [{
+                uri: uri.href,
+                text: JSON.stringify({
+                    screen: "home",
+                    description: "Main dashboard after login",
+                    selectors: {
+                        get_started: "Get Started",
+                        login_button: "Login",
+                        signup_link: "Sign Up",
+                        skip_intro: "Skip",
+                        main_nav: "com.hashhealth:id/nav_view"
+                    },
+                    anchors: {
+                        toolbar: { x: 540, y: 120 },
+                        primary_cta: { x: 540, y: 1750 }
+                    }
+                }, null, 2)
+            }]
+    }));
+    // Resource: App State Map
+    server.resource("app_states", "mobile://app/states", async (uri) => ({
+        contents: [{
+                uri: uri.href,
+                text: JSON.stringify({
+                    initial_load: {
+                        expected_text: "Welcome to Hash Health",
+                        next_action: "smart_click('Get Started')"
+                    },
+                    login_screen: {
+                        expected_text: "Sign In",
+                        fields: ["email", "password"]
+                    }
+                }, null, 2)
+            }]
+    }));
+}

package/dist/server.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Mobile Automation MCP Server
+ * Entry point for the MCP server that provides mobile automation tools
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Creates and configures the MCP Server instance
+ * Registers all tools, resources, and prompts
+ */
+export declare function createMcpServer(): McpServer;

package/dist/server.http.d.ts

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

package/dist/server.http.js

@@ -0,0 +1,94 @@
+/**
+ * Mobile Automation MCP Server — Dual HTTP Transport
+ * Using Vanilla Express for precise control over SSE and Stateless endpoints.
+ */
+import express from "express";
+import cors from "cors";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createMcpServer } from "./server.js";
+import { MCP_API_KEY } from "./config/env.js";
+import crypto from "crypto";
+const PORT = 7000;
+const app = express();
+app.use(cors());
+app.use(express.json());
+if (!MCP_API_KEY) {
+    console.warn("WARNING: MCP_API_KEY is not set. Authentication will fail.");
+}
+// ── 1. Stateful Setup (for /mcp/sse) ──────────────────────────────────────
+const statefulTransport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: () => crypto.randomUUID(),
+});
+const statefulServer = createMcpServer();
+statefulServer.connect(statefulTransport).catch(console.error);
+/**
+ * Authentication Helper
+ */
+function isAuthorized(req) {
+    const apiKey = req.headers["x-mcp-key"] || req.query.apiKey;
+    return !!(apiKey && apiKey === MCP_API_KEY);
+}
+/**
+ * JSON-RPC Error Formatter
+ */
+function sendJsonRpcError(res, code, message, id = null) {
+    res.status(200).json({
+        jsonrpc: "2.0",
+        error: { code, message },
+        id: id
+    });
+}
+// ── ENDPOINT: /mcp/sse (Stateful SSE for Remote Laptop) ───────────────────
+app.get("/mcp/sse", async (req, res) => {
+    if (!isAuthorized(req)) {
+        res.status(401).end("Unauthorized");
+        return;
+    }
+    await statefulTransport.handleRequest(req, res);
+});
+app.post("/mcp/sse", async (req, res) => {
+    if (!isAuthorized(req)) {
+        sendJsonRpcError(res, -32000, "Unauthorized", req.body?.id);
+        return;
+    }
+    await statefulTransport.handleRequest(req, res, req.body);
+});
+// ── ENDPOINT: /mcp (Stateless POST for Local Proxy Client) ────────────────
+app.post("/mcp", async (req, res) => {
+    const requestId = req.body?.id;
+    if (!isAuthorized(req)) {
+        sendJsonRpcError(res, -32000, "Unauthorized", requestId);
+        return;
+    }
+    try {
+        const statelessTransport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+        });
+        const statelessServer = createMcpServer();
+        await statelessServer.connect(statelessTransport);
+        // Handle the stateless JSON-RPC request
+        await statelessTransport.handleRequest(req, res, req.body);
+        res.on("close", () => {
+            statelessTransport.close();
+            statelessServer.close();
+        });
+    }
+    catch (error) {
+        console.error("Stateless Message Error:", error);
+        if (!res.headersSent) {
+            sendJsonRpcError(res, -32603, error.message || "Internal Server Error", requestId);
+        }
+    }
+});
+// ── Cleanup Helper ──
+app.delete("/mcp/sse", async (req, res) => {
+    await statefulTransport.handleRequest(req, res);
+});
+app.listen(PORT, "0.0.0.0", () => {
+    console.log(`HTTP MCP server running on http://0.0.0.0:${PORT}`);
+    console.log(`- Local PC Proxy: http://localhost:7000/mcp`);
+    console.log(`- Remote Laptop:  http://PC_IP:7000/mcp/sse`);
+});
+process.on("SIGINT", () => {
+    process.exit(0);
+});

package/dist/server.js

@@ -0,0 +1,60 @@
+/**
+ * Mobile Automation MCP Server
+ * Entry point for the MCP server that provides mobile automation tools
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+// Import tool domain registration functions
+import { registerDeviceTools } from "./tools/device.tools.js";
+import { registerApkTools } from "./tools/apk.tools.js";
+import { registerAppTools } from "./tools/app.tools.js";
+import { registerEvidenceTools } from "./tools/evidence.tools.js";
+import { registerAppiumTools } from "./tools/appium.tools.js";
+import { registerSmartTools } from "./tools/smart.tools.js";
+import { registerUtilityTools } from "./tools/utility.tools.js";
+// Import control plane registration functions
+import { registerMobileResources } from "./resources/mobile.resources.js";
+import { registerMobilePrompts } from "./prompts/mobile.prompts.js";
+import { SERVER_NAME, SERVER_VERSION } from "./config/env.js";
+/**
+ * Creates and configures the MCP Server instance
+ * Registers all tools, resources, and prompts
+ */
+export function createMcpServer() {
+    // Create server instance
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    });
+    // Register all tool domains
+    // Device Tools: adb_devices, check_device_online, get_device_info
+    registerDeviceTools(server);
+    // APK Tools: install_apk, uninstall_app, clear_app_data, list_packages, download_apk
+    registerApkTools(server);
+    // App Tools: launch_app, launch_activity, force_stop_app, open_deep_link, open_url_in_browser
+    registerAppTools(server);
+    // Evidence Tools: take_screenshot, get_logcat, get_page_source
+    registerEvidenceTools(server);
+    // Appium Tools: tap, type_text, swipe, press_key, long_press
+    registerAppiumTools(server);
+    // Smart Tools: smart_click, wait_for_text, get_ui_inventory
+    registerSmartTools(server);
+    // Utility Tools: wait
+    registerUtilityTools(server);
+    // Register Control Plane (Resources & Prompts)
+    registerMobileResources(server);
+    registerMobilePrompts(server);
+    return server;
+}
+// Start the server with stdio transport if running directly
+// This maintains the original behavior for local stdio usage
+async function main() {
+    const server = createMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+// Only run main if called directly (not imported)
+import { fileURLToPath } from "url";
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    main().catch(console.error);
+}

package/dist/tools/apk.tools.d.ts

@@ -0,0 +1,5 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Register all APK management tools
+ */
+export declare function registerApkTools(server: McpServer): void;