mcp-android-emulator 1.4.0 → 2.0.0

package/package.json

@@ -1,48 +1,50 @@
-{
-  "name": "mcp-android-emulator",
-  "version": "1.4.0",
-  "description": "MCP Server for Android Emulator interaction via ADB - enables AI assistants to control Android devices",
-  "type": "module",
-  "main": "dist/index.js",
-  "bin": {
-    "mcp-android-emulator": "./dist/index.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "dev": "tsc --watch",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "android",
-    "emulator",
-    "adb",
-    "automation",
-    "testing",
-    "claude",
-    "ai"
-  ],
-  "author": "",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Anjos2/mcp-android-emulator.git"
-  },
-  "bugs": {
-    "url": "https://github.com/Anjos2/mcp-android-emulator/issues"
-  },
-  "homepage": "https://github.com/Anjos2/mcp-android-emulator#readme",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "zod": "^3.23.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
-  }
-}
+{
+  "name": "mcp-android-emulator",
+  "version": "2.0.0",
+  "description": "MCP Server for Android Emulator interaction via ADB - enables AI assistants to control Android devices",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-android-emulator": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "test": "node --test --import tsx test/validators.test.ts test/runner.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "android",
+    "emulator",
+    "adb",
+    "automation",
+    "testing",
+    "claude",
+    "ai"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Anjos2/mcp-android-emulator.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Anjos2/mcp-android-emulator/issues"
+  },
+  "homepage": "https://github.com/Anjos2/mcp-android-emulator#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "zod": "3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.17",
+    "tsx": "4.21.0",
+    "typescript": "5.9.3"
+  }
+}

package/src/adb/runner.ts

@@ -0,0 +1,107 @@
+/**
+ * Runner seguro para comandos adb.
+ *
+ * Finalidad:
+ *   Centraliza toda interacción con el binario adb usando execFile (NO exec),
+ *   lo que elimina la interpretación de metacaracteres shell en el HOST.
+ *   El host queda protegido aunque se pasen argumentos con ';', '|', '`', etc.
+ *
+ * Nota sobre adb shell:
+ *   Cuando se usa 'adb shell', adb concatena los argv con espacios y los
+ *   entrega al /system/bin/sh del device. El sh del device SÍ reinterpreta
+ *   metacaracteres. Por lo tanto, la defensa en profundidad exige que los
+ *   argumentos vengan validados (allowlist) por src/adb/validators.ts antes
+ *   de llegar aquí.
+ *
+ * Interrelación:
+ *   - Usado por src/index.ts (todas las tools migradas).
+ *   - Complementado por src/adb/validators.ts (allowlists zod).
+ *   - Config externa: variable de entorno ADB_PATH.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+const ADB_PATH = process.env.ADB_PATH || "adb";
+
+export interface RunOptions {
+  /** Timeout en ms; default 30s. 0 o negativo = sin timeout. */
+  timeoutMs?: number;
+  /** Buffer máximo de stdout/stderr en bytes; default 10 MB. */
+  maxBufferBytes?: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_BUFFER = 10 * 1024 * 1024;
+
+function normalizeOpts(opts: RunOptions): { timeout: number; maxBuffer: number } {
+  const t = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  return {
+    timeout: t > 0 ? t : 0,
+    maxBuffer: opts.maxBufferBytes ?? DEFAULT_MAX_BUFFER,
+  };
+}
+
+/**
+ * Ejecuta `adb <args...>` sin pasar por shell del host.
+ * Cada elemento de args llega como argumento separado al binario adb.
+ */
+export async function runAdb(args: string[], opts: RunOptions = {}): Promise<string> {
+  const { timeout, maxBuffer } = normalizeOpts(opts);
+  try {
+    const { stdout } = await execFileAsync(ADB_PATH, args, { timeout, maxBuffer });
+    return stdout.trim();
+  } catch (error: unknown) {
+    throw wrapAdbError(error);
+  }
+}
+
+/**
+ * Ejecuta `adb shell <argv...>`. Los tokens serán re-ensamblados por adb y
+ * pasados al sh del device. Los argumentos DEBEN estar validados contra
+ * shell metacharacters antes de invocar esta función (ver validators.ts).
+ */
+export async function runAdbShell(argv: string[], opts: RunOptions = {}): Promise<string> {
+  if (argv.length === 0) {
+    throw new Error("runAdbShell requires at least one argument");
+  }
+  return runAdb(["shell", ...argv], opts);
+}
+
+/**
+ * Ejecuta `adb exec-out <argv...>`. Útil para obtener bytes binarios sin
+ * transformación (screencap, pull de archivos). Los argumentos DEBEN estar
+ * validados. Devuelve un Buffer.
+ */
+export async function runAdbExecOutBinary(argv: string[], opts: RunOptions = {}): Promise<Buffer> {
+  if (argv.length === 0) {
+    throw new Error("runAdbExecOutBinary requires at least one argument");
+  }
+  const { timeout, maxBuffer } = normalizeOpts(opts);
+  return new Promise<Buffer>((resolve, reject) => {
+    execFile(
+      ADB_PATH,
+      ["exec-out", ...argv],
+      { timeout, maxBuffer, encoding: "buffer" },
+      (error, stdout) => {
+        if (error) {
+          reject(wrapAdbError(error));
+          return;
+        }
+        resolve(stdout as Buffer);
+      }
+    );
+  });
+}
+
+function wrapAdbError(error: unknown): Error {
+  if (error instanceof Error) {
+    // @ts-expect-error — stderr no es estándar pero lo añade child_process
+    const stderr: string | undefined = error.stderr;
+    const msg = stderr?.toString?.().trim() || error.message;
+    return new Error(`adb error: ${msg}`);
+  }
+  return new Error(`adb error: ${String(error)}`);
+}

package/src/adb/validators.ts

@@ -0,0 +1,125 @@
+/**
+ * Validators zod — allowlists estrictas para todo input que eventualmente
+ * llegará a `adb shell` (donde el sh del device reinterpreta metacaracteres).
+ *
+ * Finalidad:
+ *   Actuar como segunda línea de defensa sobre src/adb/runner.ts. El runner
+ *   protege el host (no invoca sh local); estos validators protegen el device
+ *   (bloquean metacaracteres antes de llegar al sh del device).
+ *
+ * Interrelación:
+ *   - Usado por los schemas de tool en src/index.ts.
+ *   - Combinable con z.object() normal de la librería zod.
+ */
+
+import { z } from "zod";
+
+/**
+ * Regex para metacaracteres shell peligrosos.
+ * Usado para rechazo en allowlists que admiten ciertos caracteres
+ * pero quieren excluir los más peligrosos explícitamente.
+ */
+export const SHELL_METACHARS = /[;&|`$()<>\\"'\n\r\t\x00-\x1f]/;
+
+// ---------------------------------------------------------------------------
+// Android package name
+// Formato Java-compatible: segmentos separados por puntos, cada segmento
+// empieza con letra o underscore, continúa con alfanumérico/underscore.
+// Mínimo dos segmentos (no hay package top-level sin punto en Android real).
+// ---------------------------------------------------------------------------
+const PACKAGE_NAME_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)+$/;
+
+export const packageNameSchema = z
+  .string()
+  .min(3)
+  .max(255)
+  .regex(PACKAGE_NAME_REGEX, "Invalid Android package name");
+
+// ---------------------------------------------------------------------------
+// APK path
+// Rechaza metacaracteres shell y exige extensión .apk.
+// La existencia del archivo se valida en el handler (no aquí, para que
+// los tests puedan usar paths simulados).
+// ---------------------------------------------------------------------------
+export const apkPathSchema = z
+  .string()
+  .min(5)
+  .max(4096)
+  .refine((p) => p.toLowerCase().endsWith(".apk"), {
+    message: "Must be a .apk file",
+  })
+  .refine((p) => !SHELL_METACHARS.test(p), {
+    message: "Path contains disallowed characters",
+  });
+
+// ---------------------------------------------------------------------------
+// Android resource-id (e.g. com.app:id/button_login)
+// ---------------------------------------------------------------------------
+const RESOURCE_ID_REGEX = /^[a-zA-Z_][a-zA-Z0-9_.]*:[a-zA-Z]+\/[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+export const resourceIdSchema = z
+  .string()
+  .min(3)
+  .max(512)
+  .regex(RESOURCE_ID_REGEX, "Invalid Android resource-id");
+
+// ---------------------------------------------------------------------------
+// Texto libre del usuario (filter, search, assert)
+// Este texto NO llega al shell: se usa en JavaScript (String.includes,
+// RegExp.source con escape). Aceptamos caracteres amplios pero limitamos
+// longitud y prohibimos control characters para evitar sorpresas.
+// ---------------------------------------------------------------------------
+const CONTROL_CHARS = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/;
+
+export const freeTextSchema = z
+  .string()
+  .max(1024)
+  .refine((s) => !CONTROL_CHARS.test(s), {
+    message: "Text contains control characters",
+  });
+
+// ---------------------------------------------------------------------------
+// Texto que se va a tipear en un input Android (type_text, set_text).
+// Este texto PASA por el shell del device (`input text ...`). Usamos DENY-list
+// (rechazar solo metacaracteres shell y caracteres de control), NO allow-list,
+// para no romper i18n: acentos, ñ, CJK y emoji son válidos en inputs reales
+// de aplicaciones. Mismo nivel de seguridad que una allow-list ASCII porque
+// los shell metachars son el único vector de inyección.
+// ---------------------------------------------------------------------------
+export const typeableTextSchema = z
+  .string()
+  .min(0)
+  .max(2048)
+  .refine((s) => !SHELL_METACHARS.test(s), {
+    message:
+      "Text contains shell metacharacters (; & | ` $ ( ) < > \\ \" ' or control chars). Use key events for these.",
+  });
+
+// ---------------------------------------------------------------------------
+// Filter para list_packages / get_logs — usado en JS, no en shell.
+// ---------------------------------------------------------------------------
+export const searchFilterSchema = z
+  .string()
+  .max(256)
+  .refine((s) => !CONTROL_CHARS.test(s), {
+    message: "Filter contains control characters",
+  });
+
+// ---------------------------------------------------------------------------
+// Conteo numérico sanitizado (lines en get_logs, etc).
+// ---------------------------------------------------------------------------
+export const positiveCountSchema = z
+  .number()
+  .int()
+  .positive()
+  .max(100_000);
+
+// ---------------------------------------------------------------------------
+// Coordenadas (seguras por tipo, pero clamp a límites razonables).
+// ---------------------------------------------------------------------------
+export const coordinateSchema = z.number().int().min(0).max(100_000);
+
+// ---------------------------------------------------------------------------
+// Duración en ms.
+// ---------------------------------------------------------------------------
+export const durationMsSchema = z.number().int().nonnegative().max(600_000);