@metamask/device-mcp 0.1.0

package/dist/utils/exec.mjs

@@ -0,0 +1,52 @@
+import { execFile } from "node:child_process";
+/**
+ * Execute a command and return stdout/stderr/exitCode.
+ * Rejects only on spawn failure — non-zero exit codes are returned, not thrown.
+ *
+ * @param command - The command to execute.
+ * @param args - Arguments to pass to the command.
+ * @param options - Execution options including timeoutMs.
+ * @returns The stdout, stderr, and exit code.
+ */
+export async function exec(command, args, options) {
+    const { timeoutMs = 30000, ...execOptions } = options ?? {};
+    return new Promise((resolve, reject) => {
+        const child = execFile(command, args, {
+            ...execOptions,
+            timeout: timeoutMs,
+            maxBuffer: 10 * 1024 * 1024, // 10MB — UI hierarchies can be large
+        }, (error, stdout, stderr) => {
+            if (error && !('code' in error)) {
+                // Spawn failure (command not found, ENOENT, etc.)
+                reject(new Error(error.message));
+                return;
+            }
+            resolve({
+                stdout: stdout?.toString() ?? '',
+                stderr: stderr?.toString() ?? '',
+                exitCode: error?.code
+                    ? 1
+                    : (child.exitCode ?? 0),
+            });
+        });
+    });
+}
+export async function execStrict(command, args, options) {
+    const result = await exec(command, args, options);
+    if (result.exitCode !== 0) {
+        throw new Error(`Command failed: ${command} ${args.join(' ')}\n` +
+            `Exit code: ${result.exitCode}\n` +
+            `stderr: ${result.stderr}`);
+    }
+    return result.stdout;
+}
+export async function isCommandAvailable(command) {
+    try {
+        await exec('which', [command], { timeoutMs: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=exec.mjs.map

package/dist/utils/exec.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.mjs","sourceRoot":"","sources":["../../src/utils/exec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAmB,2BAA2B;AAQ/D;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,OAAe,EACf,IAAc,EACd,OAAkD;IAElD,MAAM,EAAE,SAAS,GAAG,KAAM,EAAE,GAAG,WAAW,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;IAE7D,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,QAAQ,CACpB,OAAO,EACP,IAAI,EACJ;YACE,GAAG,WAAW;YACd,OAAO,EAAE,SAAS;YAClB,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,qCAAqC;SACnE,EACD,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;YACxB,IAAI,KAAK,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,EAAE,CAAC;gBAChC,kDAAkD;gBAClD,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;gBACjC,OAAO;YACT,CAAC;YACD,OAAO,CAAC;gBACN,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAChC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAChC,QAAQ,EAAG,KAA+B,EAAE,IAAI;oBAC9C,CAAC,CAAC,CAAC;oBACH,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAC;aAC1B,CAAC,CAAC;QACL,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,OAAe,EACf,IAAc,EACd,OAAkD;IAElD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAClD,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,mBAAmB,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI;YAC9C,cAAc,MAAM,CAAC,QAAQ,IAAI;YACjC,WAAW,MAAM,CAAC,MAAM,EAAE,CAC7B,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC;AACvB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,OAAe;IACtD,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAK,EAAE,CAAC,CAAC;QACrD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC","sourcesContent":["import { execFile, ExecFileOptions } from 'node:child_process';\n\nexport type ExecResult = {\n  stdout: string;\n  stderr: string;\n  exitCode: number;\n};\n\n/**\n * Execute a command and return stdout/stderr/exitCode.\n * Rejects only on spawn failure — non-zero exit codes are returned, not thrown.\n *\n * @param command - The command to execute.\n * @param args - Arguments to pass to the command.\n * @param options - Execution options including timeoutMs.\n * @returns The stdout, stderr, and exit code.\n */\nexport async function exec(\n  command: string,\n  args: string[],\n  options?: ExecFileOptions & { timeoutMs?: number },\n): Promise<ExecResult> {\n  const { timeoutMs = 30_000, ...execOptions } = options ?? {};\n\n  return new Promise((resolve, reject) => {\n    const child = execFile(\n      command,\n      args,\n      {\n        ...execOptions,\n        timeout: timeoutMs,\n        maxBuffer: 10 * 1024 * 1024, // 10MB — UI hierarchies can be large\n      },\n      (error, stdout, stderr) => {\n        if (error && !('code' in error)) {\n          // Spawn failure (command not found, ENOENT, etc.)\n          reject(new Error(error.message));\n          return;\n        }\n        resolve({\n          stdout: stdout?.toString() ?? '',\n          stderr: stderr?.toString() ?? '',\n          exitCode: (error as NodeJS.ErrnoException)?.code\n            ? 1\n            : (child.exitCode ?? 0),\n        });\n      },\n    );\n  });\n}\n\nexport async function execStrict(\n  command: string,\n  args: string[],\n  options?: ExecFileOptions & { timeoutMs?: number },\n): Promise<string> {\n  const result = await exec(command, args, options);\n  if (result.exitCode !== 0) {\n    throw new Error(\n      `Command failed: ${command} ${args.join(' ')}\\n` +\n        `Exit code: ${result.exitCode}\\n` +\n        `stderr: ${result.stderr}`,\n    );\n  }\n  return result.stdout;\n}\n\nexport async function isCommandAvailable(command: string): Promise<boolean> {\n  try {\n    await exec('which', [command], { timeoutMs: 5_000 });\n    return true;\n  } catch {\n    return false;\n  }\n}\n"]}

package/dist/utils/platform.cjs

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectPlatform = detectPlatform;
+const exec_js_1 = require("./exec.cjs");
+async function detectPlatform(explicitDeviceId) {
+    if (explicitDeviceId) {
+        return detectFromExplicitId(explicitDeviceId);
+    }
+    const [hasIdb, hasAdb] = await Promise.all([
+        (0, exec_js_1.isCommandAvailable)('idb'),
+        (0, exec_js_1.isCommandAvailable)('adb'),
+    ]);
+    if (hasIdb) {
+        const iosDevice = await findBootedIOSDevice();
+        if (iosDevice) {
+            return iosDevice;
+        }
+    }
+    if (hasAdb) {
+        const androidDevice = await findConnectedAndroidDevice();
+        if (androidDevice) {
+            return androidDevice;
+        }
+    }
+    throw new Error('No connected device found.\n' +
+        `  iOS (idb): ${hasIdb ? 'available, no booted simulator' : 'not installed'}\n` +
+        `  Android (adb): ${hasAdb ? 'available, no connected device' : 'not installed'}\n` +
+        'Boot a simulator/emulator or set DEVICE_ID explicitly.');
+}
+async function detectFromExplicitId(deviceId) {
+    // UUIDs with dashes are typically iOS simulator UDIDs
+    if (/^[0-9A-F]{8}-([0-9A-F]{4}-){3}[0-9A-F]{12}$/iu.test(deviceId)) {
+        return { platform: 'ios', deviceId };
+    }
+    // Android emulator or device serial patterns
+    if (deviceId.startsWith('emulator-') || /^[A-Za-z0-9]+$/u.test(deviceId)) {
+        return { platform: 'android', deviceId };
+    }
+    const [hasIdb, hasAdb] = await Promise.all([
+        (0, exec_js_1.isCommandAvailable)('idb'),
+        (0, exec_js_1.isCommandAvailable)('adb'),
+    ]);
+    if (hasIdb) {
+        const result = await (0, exec_js_1.exec)('idb', ['describe', '--udid', deviceId]);
+        if (result.exitCode === 0) {
+            return { platform: 'ios', deviceId };
+        }
+    }
+    if (hasAdb) {
+        const result = await (0, exec_js_1.exec)('adb', ['-s', deviceId, 'get-state']);
+        if (result.exitCode === 0) {
+            return { platform: 'android', deviceId };
+        }
+    }
+    throw new Error(`Cannot determine platform for device ID: ${deviceId}. ` +
+        'Ensure the device is connected and idb/adb is available.');
+}
+async function findBootedIOSDevice() {
+    const result = await (0, exec_js_1.exec)('idb', ['list-targets', '--json']);
+    if (result.exitCode !== 0) {
+        return null;
+    }
+    for (const line of result.stdout.trim().split('\n')) {
+        if (!line.trim()) {
+            continue;
+        }
+        try {
+            const target = JSON.parse(line);
+            if (target.state === 'Booted' && target.type === 'simulator') {
+                return { platform: 'ios', deviceId: target.udid };
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+async function findConnectedAndroidDevice() {
+    const result = await (0, exec_js_1.exec)('adb', ['devices']);
+    if (result.exitCode !== 0) {
+        return null;
+    }
+    const lines = result.stdout.trim().split('\n').slice(1);
+    for (const line of lines) {
+        const [serial, state] = line.trim().split(/\s+/u);
+        if (serial && state === 'device') {
+            return { platform: 'android', deviceId: serial };
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=platform.cjs.map

package/dist/utils/platform.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.cjs","sourceRoot":"","sources":["../../src/utils/platform.ts"],"names":[],"mappings":"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","sourcesContent":["import { exec, isCommandAvailable } from './exec.js';\nimport type { Platform } from '../backends/types.js';\n\ntype DetectedDevice = {\n  platform: Platform;\n  deviceId: string;\n};\n\nexport async function detectPlatform(\n  explicitDeviceId?: string,\n): Promise<DetectedDevice> {\n  if (explicitDeviceId) {\n    return detectFromExplicitId(explicitDeviceId);\n  }\n\n  const [hasIdb, hasAdb] = await Promise.all([\n    isCommandAvailable('idb'),\n    isCommandAvailable('adb'),\n  ]);\n\n  if (hasIdb) {\n    const iosDevice = await findBootedIOSDevice();\n    if (iosDevice) {\n      return iosDevice;\n    }\n  }\n\n  if (hasAdb) {\n    const androidDevice = await findConnectedAndroidDevice();\n    if (androidDevice) {\n      return androidDevice;\n    }\n  }\n\n  throw new Error(\n    'No connected device found.\\n' +\n      `  iOS (idb): ${hasIdb ? 'available, no booted simulator' : 'not installed'}\\n` +\n      `  Android (adb): ${hasAdb ? 'available, no connected device' : 'not installed'}\\n` +\n      'Boot a simulator/emulator or set DEVICE_ID explicitly.',\n  );\n}\n\nasync function detectFromExplicitId(deviceId: string): Promise<DetectedDevice> {\n  // UUIDs with dashes are typically iOS simulator UDIDs\n  if (/^[0-9A-F]{8}-([0-9A-F]{4}-){3}[0-9A-F]{12}$/iu.test(deviceId)) {\n    return { platform: 'ios', deviceId };\n  }\n\n  // Android emulator or device serial patterns\n  if (deviceId.startsWith('emulator-') || /^[A-Za-z0-9]+$/u.test(deviceId)) {\n    return { platform: 'android', deviceId };\n  }\n\n  const [hasIdb, hasAdb] = await Promise.all([\n    isCommandAvailable('idb'),\n    isCommandAvailable('adb'),\n  ]);\n\n  if (hasIdb) {\n    const result = await exec('idb', ['describe', '--udid', deviceId]);\n    if (result.exitCode === 0) {\n      return { platform: 'ios', deviceId };\n    }\n  }\n\n  if (hasAdb) {\n    const result = await exec('adb', ['-s', deviceId, 'get-state']);\n    if (result.exitCode === 0) {\n      return { platform: 'android', deviceId };\n    }\n  }\n\n  throw new Error(\n    `Cannot determine platform for device ID: ${deviceId}. ` +\n      'Ensure the device is connected and idb/adb is available.',\n  );\n}\n\nasync function findBootedIOSDevice(): Promise<DetectedDevice | null> {\n  const result = await exec('idb', ['list-targets', '--json']);\n  if (result.exitCode !== 0) {\n    return null;\n  }\n\n  for (const line of result.stdout.trim().split('\\n')) {\n    if (!line.trim()) {\n      continue;\n    }\n    try {\n      const target = JSON.parse(line);\n      if (target.state === 'Booted' && target.type === 'simulator') {\n        return { platform: 'ios', deviceId: target.udid };\n      }\n    } catch {\n      continue;\n    }\n  }\n  return null;\n}\n\nasync function findConnectedAndroidDevice(): Promise<DetectedDevice | null> {\n  const result = await exec('adb', ['devices']);\n  if (result.exitCode !== 0) {\n    return null;\n  }\n\n  const lines = result.stdout.trim().split('\\n').slice(1);\n  for (const line of lines) {\n    const [serial, state] = line.trim().split(/\\s+/u);\n    if (serial && state === 'device') {\n      return { platform: 'android', deviceId: serial };\n    }\n  }\n  return null;\n}\n"]}

package/dist/utils/platform.d.cts

@@ -0,0 +1,8 @@
+import type { Platform } from "../backends/types.cjs";
+type DetectedDevice = {
+    platform: Platform;
+    deviceId: string;
+};
+export declare function detectPlatform(explicitDeviceId?: string): Promise<DetectedDevice>;
+export {};
+//# sourceMappingURL=platform.d.cts.map

package/dist/utils/platform.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.cts","sourceRoot":"","sources":["../../src/utils/platform.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,8BAA6B;AAErD,KAAK,cAAc,GAAG;IACpB,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,wBAAsB,cAAc,CAClC,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,cAAc,CAAC,CA8BzB"}

package/dist/utils/platform.d.mts

@@ -0,0 +1,8 @@
+import type { Platform } from "../backends/types.mjs";
+type DetectedDevice = {
+    platform: Platform;
+    deviceId: string;
+};
+export declare function detectPlatform(explicitDeviceId?: string): Promise<DetectedDevice>;
+export {};
+//# sourceMappingURL=platform.d.mts.map

package/dist/utils/platform.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.mts","sourceRoot":"","sources":["../../src/utils/platform.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,8BAA6B;AAErD,KAAK,cAAc,GAAG;IACpB,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,wBAAsB,cAAc,CAClC,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,cAAc,CAAC,CA8BzB"}

package/dist/utils/platform.mjs

@@ -0,0 +1,90 @@
+import { exec, isCommandAvailable } from "./exec.mjs";
+export async function detectPlatform(explicitDeviceId) {
+    if (explicitDeviceId) {
+        return detectFromExplicitId(explicitDeviceId);
+    }
+    const [hasIdb, hasAdb] = await Promise.all([
+        isCommandAvailable('idb'),
+        isCommandAvailable('adb'),
+    ]);
+    if (hasIdb) {
+        const iosDevice = await findBootedIOSDevice();
+        if (iosDevice) {
+            return iosDevice;
+        }
+    }
+    if (hasAdb) {
+        const androidDevice = await findConnectedAndroidDevice();
+        if (androidDevice) {
+            return androidDevice;
+        }
+    }
+    throw new Error('No connected device found.\n' +
+        `  iOS (idb): ${hasIdb ? 'available, no booted simulator' : 'not installed'}\n` +
+        `  Android (adb): ${hasAdb ? 'available, no connected device' : 'not installed'}\n` +
+        'Boot a simulator/emulator or set DEVICE_ID explicitly.');
+}
+async function detectFromExplicitId(deviceId) {
+    // UUIDs with dashes are typically iOS simulator UDIDs
+    if (/^[0-9A-F]{8}-([0-9A-F]{4}-){3}[0-9A-F]{12}$/iu.test(deviceId)) {
+        return { platform: 'ios', deviceId };
+    }
+    // Android emulator or device serial patterns
+    if (deviceId.startsWith('emulator-') || /^[A-Za-z0-9]+$/u.test(deviceId)) {
+        return { platform: 'android', deviceId };
+    }
+    const [hasIdb, hasAdb] = await Promise.all([
+        isCommandAvailable('idb'),
+        isCommandAvailable('adb'),
+    ]);
+    if (hasIdb) {
+        const result = await exec('idb', ['describe', '--udid', deviceId]);
+        if (result.exitCode === 0) {
+            return { platform: 'ios', deviceId };
+        }
+    }
+    if (hasAdb) {
+        const result = await exec('adb', ['-s', deviceId, 'get-state']);
+        if (result.exitCode === 0) {
+            return { platform: 'android', deviceId };
+        }
+    }
+    throw new Error(`Cannot determine platform for device ID: ${deviceId}. ` +
+        'Ensure the device is connected and idb/adb is available.');
+}
+async function findBootedIOSDevice() {
+    const result = await exec('idb', ['list-targets', '--json']);
+    if (result.exitCode !== 0) {
+        return null;
+    }
+    for (const line of result.stdout.trim().split('\n')) {
+        if (!line.trim()) {
+            continue;
+        }
+        try {
+            const target = JSON.parse(line);
+            if (target.state === 'Booted' && target.type === 'simulator') {
+                return { platform: 'ios', deviceId: target.udid };
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+async function findConnectedAndroidDevice() {
+    const result = await exec('adb', ['devices']);
+    if (result.exitCode !== 0) {
+        return null;
+    }
+    const lines = result.stdout.trim().split('\n').slice(1);
+    for (const line of lines) {
+        const [serial, state] = line.trim().split(/\s+/u);
+        if (serial && state === 'device') {
+            return { platform: 'android', deviceId: serial };
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=platform.mjs.map

package/dist/utils/platform.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.mjs","sourceRoot":"","sources":["../../src/utils/platform.ts"],"names":[],"mappings":"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","sourcesContent":["import { exec, isCommandAvailable } from './exec.js';\nimport type { Platform } from '../backends/types.js';\n\ntype DetectedDevice = {\n  platform: Platform;\n  deviceId: string;\n};\n\nexport async function detectPlatform(\n  explicitDeviceId?: string,\n): Promise<DetectedDevice> {\n  if (explicitDeviceId) {\n    return detectFromExplicitId(explicitDeviceId);\n  }\n\n  const [hasIdb, hasAdb] = await Promise.all([\n    isCommandAvailable('idb'),\n    isCommandAvailable('adb'),\n  ]);\n\n  if (hasIdb) {\n    const iosDevice = await findBootedIOSDevice();\n    if (iosDevice) {\n      return iosDevice;\n    }\n  }\n\n  if (hasAdb) {\n    const androidDevice = await findConnectedAndroidDevice();\n    if (androidDevice) {\n      return androidDevice;\n    }\n  }\n\n  throw new Error(\n    'No connected device found.\\n' +\n      `  iOS (idb): ${hasIdb ? 'available, no booted simulator' : 'not installed'}\\n` +\n      `  Android (adb): ${hasAdb ? 'available, no connected device' : 'not installed'}\\n` +\n      'Boot a simulator/emulator or set DEVICE_ID explicitly.',\n  );\n}\n\nasync function detectFromExplicitId(deviceId: string): Promise<DetectedDevice> {\n  // UUIDs with dashes are typically iOS simulator UDIDs\n  if (/^[0-9A-F]{8}-([0-9A-F]{4}-){3}[0-9A-F]{12}$/iu.test(deviceId)) {\n    return { platform: 'ios', deviceId };\n  }\n\n  // Android emulator or device serial patterns\n  if (deviceId.startsWith('emulator-') || /^[A-Za-z0-9]+$/u.test(deviceId)) {\n    return { platform: 'android', deviceId };\n  }\n\n  const [hasIdb, hasAdb] = await Promise.all([\n    isCommandAvailable('idb'),\n    isCommandAvailable('adb'),\n  ]);\n\n  if (hasIdb) {\n    const result = await exec('idb', ['describe', '--udid', deviceId]);\n    if (result.exitCode === 0) {\n      return { platform: 'ios', deviceId };\n    }\n  }\n\n  if (hasAdb) {\n    const result = await exec('adb', ['-s', deviceId, 'get-state']);\n    if (result.exitCode === 0) {\n      return { platform: 'android', deviceId };\n    }\n  }\n\n  throw new Error(\n    `Cannot determine platform for device ID: ${deviceId}. ` +\n      'Ensure the device is connected and idb/adb is available.',\n  );\n}\n\nasync function findBootedIOSDevice(): Promise<DetectedDevice | null> {\n  const result = await exec('idb', ['list-targets', '--json']);\n  if (result.exitCode !== 0) {\n    return null;\n  }\n\n  for (const line of result.stdout.trim().split('\\n')) {\n    if (!line.trim()) {\n      continue;\n    }\n    try {\n      const target = JSON.parse(line);\n      if (target.state === 'Booted' && target.type === 'simulator') {\n        return { platform: 'ios', deviceId: target.udid };\n      }\n    } catch {\n      continue;\n    }\n  }\n  return null;\n}\n\nasync function findConnectedAndroidDevice(): Promise<DetectedDevice | null> {\n  const result = await exec('adb', ['devices']);\n  if (result.exitCode !== 0) {\n    return null;\n  }\n\n  const lines = result.stdout.trim().split('\\n').slice(1);\n  for (const line of lines) {\n    const [serial, state] = line.trim().split(/\\s+/u);\n    if (serial && state === 'device') {\n      return { platform: 'android', deviceId: serial };\n    }\n  }\n  return null;\n}\n"]}

package/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "@metamask/device-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for mobile device interaction — iOS (IDB), Android (ADB), and Appium/BrowserStack",
+  "homepage": "https://github.com/MetaMask/device-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/MetaMask/device-mcp/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MetaMask/device-mcp.git"
+  },
+  "license": "(MIT OR Apache-2.0)",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "bin": "./dist/cli/device-mcp.mjs",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "ts-bridge --project tsconfig.build.json --clean",
+    "build:docs": "typedoc",
+    "clean": "rm -rf dist",
+    "dev": "tsc --watch",
+    "lint": "yarn lint:eslint && yarn lint:constraints && yarn lint:misc --check && yarn lint:dependencies --check && yarn lint:changelog",
+    "lint:changelog": "auto-changelog validate --prettier",
+    "lint:constraints": "yarn constraints",
+    "lint:dependencies": "depcheck && yarn dedupe --check",
+    "lint:dependencies:fix": "depcheck && yarn dedupe",
+    "lint:eslint": "eslint .",
+    "lint:fix": "yarn lint:eslint --fix && yarn lint:constraints --fix && yarn lint:misc --write && yarn lint:dependencies:fix && yarn lint:changelog",
+    "lint:misc": "prettier '**/*.json' '**/*.md' '**/*.yml' '!.yarnrc.yml' --ignore-path .gitignore --no-error-on-unmatched-pattern",
+    "prepack": "./scripts/prepack.sh",
+    "start": "node dist/index.mjs",
+    "test": "vitest",
+    "test:watch": "vitest --watch"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@lavamoat/allow-scripts": "^3.0.4",
+    "@lavamoat/preinstall-always-fail": "^2.0.0",
+    "@metamask/auto-changelog": "^5.3.0",
+    "@metamask/eslint-config": "^15.0.0",
+    "@metamask/eslint-config-nodejs": "^15.0.0",
+    "@metamask/eslint-config-typescript": "^15.0.0",
+    "@metamask/eslint-config-vitest": "^15.0.0",
+    "@ts-bridge/cli": "^0.6.3",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/utils": "^8.6.0",
+    "@vitest/coverage-istanbul": "^3.0.7",
+    "@vitest/eslint-plugin": "^1.1.4",
+    "@yarnpkg/types": "^4.0.0-rc.52",
+    "depcheck": "^1.4.3",
+    "eslint": "^9.11.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-import-resolver-typescript": "^3.6.3",
+    "eslint-plugin-import-x": "^4.3.0",
+    "eslint-plugin-jsdoc": "^50.2.4",
+    "eslint-plugin-n": "^17.10.3",
+    "eslint-plugin-prettier": "^5.2.1",
+    "eslint-plugin-promise": "^7.1.0",
+    "prettier": "^3.3.3",
+    "prettier-plugin-packagejson": "^2.5.8",
+    "ts-node": "^10.7.0",
+    "typedoc": "^0.26.11",
+    "typescript": "~5.7.3",
+    "typescript-eslint": "^8.48.1",
+    "vite": "^6.4.1",
+    "vitest": "^3.2.1"
+  },
+  "packageManager": "yarn@4.11.0",
+  "engines": {
+    "node": "^20 || ^22 || >=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "lavamoat": {
+    "allowScripts": {
+      "@lavamoat/preinstall-always-fail": false,
+      "eslint-plugin-import-x>unrs-resolver": false,
+      "vite>esbuild": false,
+      "vitest>vite-node>vite>esbuild": false,
+      "vitest>vite>esbuild": false
+    }
+  }
+}