@metamask/device-mcp 0.2.0 → 0.3.0

package/dist/hermes/session.d.mts

@@ -0,0 +1,163 @@
+/**
+ * Standalone state module for Hermes CDP sessions.
+ *
+ * Holds the resolved Metro inspector proxy port, the expected app bundle ID,
+ * and the pinned Hermes `logicalDeviceId`. This module is intentionally
+ * INDEPENDENT of `DeviceBackend` — Hermes/Metro access is orthogonal to the
+ * idb/adb/Appium UI automation backends, and it stores no live connection
+ * (the MVP opens a fresh WebSocket per tool call).
+ *
+ * Resolution precedence for both port and appId is exactly:
+ *   per-call param > environment variable > default.
+ */
+/**
+ * Platform identifier used to pick the default app bundle ID.
+ *
+ * Kept structurally compatible with the backend's `Platform` type without
+ * importing it, so this module stays decoupled from `DeviceBackend`.
+ */
+export type HermesPlatform = 'ios' | 'android';
+/** Default MetaMask app bundle ID for iOS (`CFBundleIdentifier`). */
+export declare const DEFAULT_IOS_APP_ID = "io.metamask.MetaMask";
+/** Default MetaMask app bundle ID for Android (`applicationId`). */
+export declare const DEFAULT_ANDROID_APP_ID = "io.metamask";
+/** Default Metro inspector proxy port when none is configured. */
+export declare const DEFAULT_METRO_PORT = 8081;
+/**
+ * Resolve the platform default app bundle ID.
+ *
+ * Defaults to the iOS id when the platform is unknown. Agents running against
+ * Android should pass `appId` per call or set `HERMES_APP_ID` if they are not
+ * using the default Android bundle ID.
+ *
+ * @param platform - The active platform, if known.
+ * @returns The default app bundle ID for the platform.
+ */
+export declare function defaultAppIdForPlatform(platform?: HermesPlatform): string;
+/**
+ * Per-call overrides accepted by {@link HermesSession.resolve}.
+ *
+ * Any field left undefined falls back to the session default (which itself
+ * falls back to the relevant environment variable, then the hardcoded default).
+ */
+export type HermesSessionResolveInput = {
+    /** Override the Metro inspector proxy port for this call. */
+    metroPort?: number;
+    /** Override the expected app bundle ID for this call. */
+    appId?: string;
+    /**
+     * The active platform, used to compute the default app bundle ID AT CALL
+     * TIME when neither a per-call `appId` nor the `HERMES_APP_ID` env var is set.
+     * This lets a session created before a device connects (when the platform is
+     * not yet known) still resolve the correct Android default once the backend's
+     * live platform becomes `'android'`.
+     */
+    platform?: HermesPlatform;
+};
+/**
+ * The effective Hermes session parameters for a single tool call.
+ */
+export type HermesSessionResolved = {
+    /** The resolved Metro inspector proxy port. */
+    metroPort: number;
+    /** The resolved expected app bundle ID. */
+    appId: string;
+    /** The pinned Hermes `logicalDeviceId`, if one has been set. */
+    pinnedDeviceId: string | undefined;
+};
+/**
+ * Options for constructing a {@link HermesSession}.
+ */
+export type HermesSessionOptions = {
+    /** The active platform, used only to pick the default app bundle ID. */
+    platform?: HermesPlatform;
+    /**
+     * Environment source. Defaults to `process.env`. Injectable for tests so
+     * resolution precedence can be exercised without mutating the real env.
+     */
+    env?: NodeJS.ProcessEnv;
+};
+/**
+ * Holds the Metro port, expected appId, and pinned Hermes deviceId for a
+ * process-lifetime Hermes session.
+ *
+ * The stored port and appId are resolved once at construction time using
+ * `param ?? env ?? default` precedence (with `param` being undefined at
+ * construction — those are supplied per call to {@link resolve}). The pinned
+ * deviceId starts unset and is assigned on the first successful identity probe.
+ */
+export declare class HermesSession {
+    #private;
+    constructor(options?: HermesSessionOptions);
+    /**
+     * Returns the session-default Metro inspector proxy port.
+     *
+     * @returns The resolved Metro port (env `HERMES_METRO_PORT`, else 8081).
+     */
+    getMetroPort(): number;
+    /**
+     * Returns the session-default expected app bundle ID.
+     *
+     * @returns The resolved app bundle ID (env `HERMES_APP_ID`, else the
+     * platform default).
+     */
+    getAppId(): string;
+    /**
+     * Returns the pinned Hermes `logicalDeviceId` for this session, if any.
+     *
+     * Set on the first successful identity probe via
+     * {@link setPinnedHermesDeviceId}. Persists for the lifetime of this
+     * instance.
+     *
+     * @returns The pinned `logicalDeviceId`, or undefined when no pin is set.
+     */
+    getPinnedHermesDeviceId(): string | undefined;
+    /**
+     * Pin the Hermes `logicalDeviceId` for this session.
+     *
+     * Called after a successful identity probe on the first call. Subsequent
+     * calls then enforce this pin to prevent target switching mid-session.
+     *
+     * @param id - The `logicalDeviceId` from Metro's
+     * `reactNative.logicalDeviceId` field.
+     */
+    setPinnedHermesDeviceId(id: string): void;
+    /**
+     * Resolve the effective parameters for a single tool call by merging
+     * per-call overrides over the stored session defaults.
+     *
+     * This is PURE with respect to stored state: it never mutates the stored
+     * port, appId, or pin. Only {@link setPinnedHermesDeviceId} mutates the pin.
+     *
+     * Port precedence is `input.metroPort ?? this.getMetroPort()` (which itself
+     * already encodes `env ?? default`), mirroring the reference driver's
+     * `input.metroPort ?? driver.getMetroPort() ?? 8081`.
+     *
+     * AppId precedence is `input.appId ?? <HERMES_APP_ID env if set> ??
+     * defaultAppIdForPlatform(input.platform) ?? <stored default>`. An explicitly
+     * set `HERMES_APP_ID` always WINS over the per-call platform default (env is a
+     * deliberate override): in that case the stored appId is returned unchanged.
+     * Only when the stored appId is the construction-time platform fallback does
+     * a per-call `platform` recompute it — without mutating stored state. When no
+     * `platform` is passed this preserves the original iOS-default behavior.
+     *
+     * @param input - Optional per-call overrides for port, appId, and platform.
+     * @returns The effective `{ metroPort, appId, pinnedDeviceId }`.
+     */
+    resolve(input?: HermesSessionResolveInput): HermesSessionResolved;
+}
+/**
+ * Returns the process-singleton {@link HermesSession}, creating it on first
+ * access.
+ *
+ * @param options - Options applied only when the singleton is first created.
+ * @returns The shared `HermesSession` instance.
+ */
+export declare function getHermesSession(options?: HermesSessionOptions): HermesSession;
+/**
+ * Resets the process-singleton {@link HermesSession}.
+ *
+ * Intended for test isolation so each test can start from a clean session.
+ */
+export declare function resetHermesSession(): void;
+//# sourceMappingURL=session.d.mts.map

package/dist/hermes/session.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.mts","sourceRoot":"","sources":["../../src/hermes/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,SAAS,CAAC;AAE/C,qEAAqE;AACrE,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD,oEAAoE;AACpE,eAAO,MAAM,sBAAsB,gBAAgB,CAAC;AAEpD,kEAAkE;AAClE,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,CAAC,EAAE,cAAc,GAAG,MAAM,CAEzE;AAgBD;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB,CAAC;AAEF;;;;;;;;GAQG;AACH,qBAAa,aAAa;;gBAiBZ,OAAO,GAAE,oBAAyB;IAY9C;;;;OAIG;IACH,YAAY,IAAI,MAAM;IAItB;;;;;OAKG;IACH,QAAQ,IAAI,MAAM;IAIlB;;;;;;;;OAQG;IACH,uBAAuB,IAAI,MAAM,GAAG,SAAS;IAI7C;;;;;;;;OAQG;IACH,uBAAuB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAIzC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,KAAK,GAAE,yBAA8B,GAAG,qBAAqB;CAqBtE;AAOD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,CAAC,EAAE,oBAAoB,GAC7B,aAAa,CAKf;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/hermes/session.mjs

@@ -0,0 +1,189 @@
+/**
+ * Standalone state module for Hermes CDP sessions.
+ *
+ * Holds the resolved Metro inspector proxy port, the expected app bundle ID,
+ * and the pinned Hermes `logicalDeviceId`. This module is intentionally
+ * INDEPENDENT of `DeviceBackend` — Hermes/Metro access is orthogonal to the
+ * idb/adb/Appium UI automation backends, and it stores no live connection
+ * (the MVP opens a fresh WebSocket per tool call).
+ *
+ * Resolution precedence for both port and appId is exactly:
+ *   per-call param > environment variable > default.
+ */
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _HermesSession_instances, _HermesSession_metroPort, _HermesSession_expectedAppId, _HermesSession_appIdFromEnv, _HermesSession_pinnedDeviceId, _HermesSession_resolveAppId;
+/** Default MetaMask app bundle ID for iOS (`CFBundleIdentifier`). */
+export const DEFAULT_IOS_APP_ID = 'io.metamask.MetaMask';
+/** Default MetaMask app bundle ID for Android (`applicationId`). */
+export const DEFAULT_ANDROID_APP_ID = 'io.metamask';
+/** Default Metro inspector proxy port when none is configured. */
+export const DEFAULT_METRO_PORT = 8081;
+/**
+ * Resolve the platform default app bundle ID.
+ *
+ * Defaults to the iOS id when the platform is unknown. Agents running against
+ * Android should pass `appId` per call or set `HERMES_APP_ID` if they are not
+ * using the default Android bundle ID.
+ *
+ * @param platform - The active platform, if known.
+ * @returns The default app bundle ID for the platform.
+ */
+export function defaultAppIdForPlatform(platform) {
+    return platform === 'android' ? DEFAULT_ANDROID_APP_ID : DEFAULT_IOS_APP_ID;
+}
+/**
+ * Parse a Metro port from an environment variable value.
+ *
+ * @param value - The raw environment variable value (or undefined).
+ * @returns The parsed integer port, or undefined when unset/invalid.
+ */
+function parseEnvPort(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return Number.isInteger(parsed) ? parsed : undefined;
+}
+/**
+ * Holds the Metro port, expected appId, and pinned Hermes deviceId for a
+ * process-lifetime Hermes session.
+ *
+ * The stored port and appId are resolved once at construction time using
+ * `param ?? env ?? default` precedence (with `param` being undefined at
+ * construction — those are supplied per call to {@link resolve}). The pinned
+ * deviceId starts unset and is assigned on the first successful identity probe.
+ */
+export class HermesSession {
+    constructor(options = {}) {
+        _HermesSession_instances.add(this);
+        _HermesSession_metroPort.set(this, void 0);
+        _HermesSession_expectedAppId.set(this, void 0);
+        /**
+         * Whether {@link #expectedAppId} came from an explicit source (the
+         * `HERMES_APP_ID` env var) rather than the platform fallback. When true, the
+         * stored appId is a deliberate override and {@link resolve} must not let a
+         * per-call `platform` recompute it; when false, the stored value is only the
+         * construction-time platform default and `resolve` may recompute it from the
+         * live platform.
+         */
+        _HermesSession_appIdFromEnv.set(this, void 0);
+        _HermesSession_pinnedDeviceId.set(this, void 0);
+        const env = options.env ?? process.env;
+        __classPrivateFieldSet(this, _HermesSession_metroPort, parseEnvPort(env.HERMES_METRO_PORT) ?? DEFAULT_METRO_PORT, "f");
+        __classPrivateFieldSet(this, _HermesSession_appIdFromEnv, env.HERMES_APP_ID !== undefined, "f");
+        __classPrivateFieldSet(this, _HermesSession_expectedAppId, env.HERMES_APP_ID ?? defaultAppIdForPlatform(options.platform), "f");
+        __classPrivateFieldSet(this, _HermesSession_pinnedDeviceId, undefined, "f");
+    }
+    /**
+     * Returns the session-default Metro inspector proxy port.
+     *
+     * @returns The resolved Metro port (env `HERMES_METRO_PORT`, else 8081).
+     */
+    getMetroPort() {
+        return __classPrivateFieldGet(this, _HermesSession_metroPort, "f");
+    }
+    /**
+     * Returns the session-default expected app bundle ID.
+     *
+     * @returns The resolved app bundle ID (env `HERMES_APP_ID`, else the
+     * platform default).
+     */
+    getAppId() {
+        return __classPrivateFieldGet(this, _HermesSession_expectedAppId, "f");
+    }
+    /**
+     * Returns the pinned Hermes `logicalDeviceId` for this session, if any.
+     *
+     * Set on the first successful identity probe via
+     * {@link setPinnedHermesDeviceId}. Persists for the lifetime of this
+     * instance.
+     *
+     * @returns The pinned `logicalDeviceId`, or undefined when no pin is set.
+     */
+    getPinnedHermesDeviceId() {
+        return __classPrivateFieldGet(this, _HermesSession_pinnedDeviceId, "f");
+    }
+    /**
+     * Pin the Hermes `logicalDeviceId` for this session.
+     *
+     * Called after a successful identity probe on the first call. Subsequent
+     * calls then enforce this pin to prevent target switching mid-session.
+     *
+     * @param id - The `logicalDeviceId` from Metro's
+     * `reactNative.logicalDeviceId` field.
+     */
+    setPinnedHermesDeviceId(id) {
+        __classPrivateFieldSet(this, _HermesSession_pinnedDeviceId, id, "f");
+    }
+    /**
+     * Resolve the effective parameters for a single tool call by merging
+     * per-call overrides over the stored session defaults.
+     *
+     * This is PURE with respect to stored state: it never mutates the stored
+     * port, appId, or pin. Only {@link setPinnedHermesDeviceId} mutates the pin.
+     *
+     * Port precedence is `input.metroPort ?? this.getMetroPort()` (which itself
+     * already encodes `env ?? default`), mirroring the reference driver's
+     * `input.metroPort ?? driver.getMetroPort() ?? 8081`.
+     *
+     * AppId precedence is `input.appId ?? <HERMES_APP_ID env if set> ??
+     * defaultAppIdForPlatform(input.platform) ?? <stored default>`. An explicitly
+     * set `HERMES_APP_ID` always WINS over the per-call platform default (env is a
+     * deliberate override): in that case the stored appId is returned unchanged.
+     * Only when the stored appId is the construction-time platform fallback does
+     * a per-call `platform` recompute it — without mutating stored state. When no
+     * `platform` is passed this preserves the original iOS-default behavior.
+     *
+     * @param input - Optional per-call overrides for port, appId, and platform.
+     * @returns The effective `{ metroPort, appId, pinnedDeviceId }`.
+     */
+    resolve(input = {}) {
+        return {
+            metroPort: input.metroPort ?? __classPrivateFieldGet(this, _HermesSession_metroPort, "f"),
+            appId: input.appId ?? __classPrivateFieldGet(this, _HermesSession_instances, "m", _HermesSession_resolveAppId).call(this, input.platform),
+            pinnedDeviceId: __classPrivateFieldGet(this, _HermesSession_pinnedDeviceId, "f"),
+        };
+    }
+}
+_HermesSession_metroPort = new WeakMap(), _HermesSession_expectedAppId = new WeakMap(), _HermesSession_appIdFromEnv = new WeakMap(), _HermesSession_pinnedDeviceId = new WeakMap(), _HermesSession_instances = new WeakSet(), _HermesSession_resolveAppId = function _HermesSession_resolveAppId(platform) {
+    if (__classPrivateFieldGet(this, _HermesSession_appIdFromEnv, "f") || platform === undefined) {
+        return __classPrivateFieldGet(this, _HermesSession_expectedAppId, "f");
+    }
+    return defaultAppIdForPlatform(platform);
+};
+/**
+ * Module-level lazily-created singleton instance.
+ */
+let sessionInstance;
+/**
+ * Returns the process-singleton {@link HermesSession}, creating it on first
+ * access.
+ *
+ * @param options - Options applied only when the singleton is first created.
+ * @returns The shared `HermesSession` instance.
+ */
+export function getHermesSession(options) {
+    if (sessionInstance === undefined) {
+        sessionInstance = new HermesSession(options);
+    }
+    return sessionInstance;
+}
+/**
+ * Resets the process-singleton {@link HermesSession}.
+ *
+ * Intended for test isolation so each test can start from a clean session.
+ */
+export function resetHermesSession() {
+    sessionInstance = undefined;
+}
+//# sourceMappingURL=session.mjs.map

package/dist/hermes/session.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.mjs","sourceRoot":"","sources":["../../src/hermes/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;;;;;;;;;;;;;AAUH,qEAAqE;AACrE,MAAM,CAAC,MAAM,kBAAkB,GAAG,sBAAsB,CAAC;AAEzD,oEAAoE;AACpE,MAAM,CAAC,MAAM,sBAAsB,GAAG,aAAa,CAAC;AAEpD,kEAAkE;AAClE,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEvC;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAAyB;IAC/D,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,kBAAkB,CAAC;AAC9E,CAAC;AAED;;;;;GAKG;AACH,SAAS,YAAY,CAAC,KAAyB;IAC7C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC1C,OAAO,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAgDD;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAa;IAiBxB,YAAY,UAAgC,EAAE;;QAhBrC,2CAAmB;QAEnB,+CAAuB;QAEhC;;;;;;;WAOG;QACM,8CAAuB;QAEhC,gDAAoC;QAGlC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;QAEvC,uBAAA,IAAI,4BAAc,YAAY,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,kBAAkB,MAAA,CAAC;QAE5E,uBAAA,IAAI,+BAAiB,GAAG,CAAC,aAAa,KAAK,SAAS,MAAA,CAAC;QACrD,uBAAA,IAAI,gCACF,GAAG,CAAC,aAAa,IAAI,uBAAuB,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAA,CAAC;QAEjE,uBAAA,IAAI,iCAAmB,SAAS,MAAA,CAAC;IACnC,CAAC;IAED;;;;OAIG;IACH,YAAY;QACV,OAAO,uBAAA,IAAI,gCAAW,CAAC;IACzB,CAAC;IAED;;;;;OAKG;IACH,QAAQ;QACN,OAAO,uBAAA,IAAI,oCAAe,CAAC;IAC7B,CAAC;IAED;;;;;;;;OAQG;IACH,uBAAuB;QACrB,OAAO,uBAAA,IAAI,qCAAgB,CAAC;IAC9B,CAAC;IAED;;;;;;;;OAQG;IACH,uBAAuB,CAAC,EAAU;QAChC,uBAAA,IAAI,iCAAmB,EAAE,MAAA,CAAC;IAC5B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,QAAmC,EAAE;QAC3C,OAAO;YACL,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,uBAAA,IAAI,gCAAW;YAC7C,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,uBAAA,IAAI,6DAAc,MAAlB,IAAI,EAAe,KAAK,CAAC,QAAQ,CAAC;YACxD,cAAc,EAAE,uBAAA,IAAI,qCAAgB;SACrC,CAAC;IACJ,CAAC;CAeF;iSANe,QAAoC;IAChD,IAAI,uBAAA,IAAI,mCAAc,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QACjD,OAAO,uBAAA,IAAI,oCAAe,CAAC;IAC7B,CAAC;IACD,OAAO,uBAAuB,CAAC,QAAQ,CAAC,CAAC;AAC3C,CAAC;AAGH;;GAEG;AACH,IAAI,eAA0C,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAA8B;IAE9B,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;QAClC,eAAe,GAAG,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,eAAe,CAAC;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB;IAChC,eAAe,GAAG,SAAS,CAAC;AAC9B,CAAC","sourcesContent":["/**\n * Standalone state module for Hermes CDP sessions.\n *\n * Holds the resolved Metro inspector proxy port, the expected app bundle ID,\n * and the pinned Hermes `logicalDeviceId`. This module is intentionally\n * INDEPENDENT of `DeviceBackend` — Hermes/Metro access is orthogonal to the\n * idb/adb/Appium UI automation backends, and it stores no live connection\n * (the MVP opens a fresh WebSocket per tool call).\n *\n * Resolution precedence for both port and appId is exactly:\n *   per-call param > environment variable > default.\n */\n\n/**\n * Platform identifier used to pick the default app bundle ID.\n *\n * Kept structurally compatible with the backend's `Platform` type without\n * importing it, so this module stays decoupled from `DeviceBackend`.\n */\nexport type HermesPlatform = 'ios' | 'android';\n\n/** Default MetaMask app bundle ID for iOS (`CFBundleIdentifier`). */\nexport const DEFAULT_IOS_APP_ID = 'io.metamask.MetaMask';\n\n/** Default MetaMask app bundle ID for Android (`applicationId`). */\nexport const DEFAULT_ANDROID_APP_ID = 'io.metamask';\n\n/** Default Metro inspector proxy port when none is configured. */\nexport const DEFAULT_METRO_PORT = 8081;\n\n/**\n * Resolve the platform default app bundle ID.\n *\n * Defaults to the iOS id when the platform is unknown. Agents running against\n * Android should pass `appId` per call or set `HERMES_APP_ID` if they are not\n * using the default Android bundle ID.\n *\n * @param platform - The active platform, if known.\n * @returns The default app bundle ID for the platform.\n */\nexport function defaultAppIdForPlatform(platform?: HermesPlatform): string {\n  return platform === 'android' ? DEFAULT_ANDROID_APP_ID : DEFAULT_IOS_APP_ID;\n}\n\n/**\n * Parse a Metro port from an environment variable value.\n *\n * @param value - The raw environment variable value (or undefined).\n * @returns The parsed integer port, or undefined when unset/invalid.\n */\nfunction parseEnvPort(value: string | undefined): number | undefined {\n  if (value === undefined) {\n    return undefined;\n  }\n  const parsed = Number.parseInt(value, 10);\n  return Number.isInteger(parsed) ? parsed : undefined;\n}\n\n/**\n * Per-call overrides accepted by {@link HermesSession.resolve}.\n *\n * Any field left undefined falls back to the session default (which itself\n * falls back to the relevant environment variable, then the hardcoded default).\n */\nexport type HermesSessionResolveInput = {\n  /** Override the Metro inspector proxy port for this call. */\n  metroPort?: number;\n  /** Override the expected app bundle ID for this call. */\n  appId?: string;\n  /**\n   * The active platform, used to compute the default app bundle ID AT CALL\n   * TIME when neither a per-call `appId` nor the `HERMES_APP_ID` env var is set.\n   * This lets a session created before a device connects (when the platform is\n   * not yet known) still resolve the correct Android default once the backend's\n   * live platform becomes `'android'`.\n   */\n  platform?: HermesPlatform;\n};\n\n/**\n * The effective Hermes session parameters for a single tool call.\n */\nexport type HermesSessionResolved = {\n  /** The resolved Metro inspector proxy port. */\n  metroPort: number;\n  /** The resolved expected app bundle ID. */\n  appId: string;\n  /** The pinned Hermes `logicalDeviceId`, if one has been set. */\n  pinnedDeviceId: string | undefined;\n};\n\n/**\n * Options for constructing a {@link HermesSession}.\n */\nexport type HermesSessionOptions = {\n  /** The active platform, used only to pick the default app bundle ID. */\n  platform?: HermesPlatform;\n  /**\n   * Environment source. Defaults to `process.env`. Injectable for tests so\n   * resolution precedence can be exercised without mutating the real env.\n   */\n  env?: NodeJS.ProcessEnv;\n};\n\n/**\n * Holds the Metro port, expected appId, and pinned Hermes deviceId for a\n * process-lifetime Hermes session.\n *\n * The stored port and appId are resolved once at construction time using\n * `param ?? env ?? default` precedence (with `param` being undefined at\n * construction — those are supplied per call to {@link resolve}). The pinned\n * deviceId starts unset and is assigned on the first successful identity probe.\n */\nexport class HermesSession {\n  readonly #metroPort: number;\n\n  readonly #expectedAppId: string;\n\n  /**\n   * Whether {@link #expectedAppId} came from an explicit source (the\n   * `HERMES_APP_ID` env var) rather than the platform fallback. When true, the\n   * stored appId is a deliberate override and {@link resolve} must not let a\n   * per-call `platform` recompute it; when false, the stored value is only the\n   * construction-time platform default and `resolve` may recompute it from the\n   * live platform.\n   */\n  readonly #appIdFromEnv: boolean;\n\n  #pinnedDeviceId: string | undefined;\n\n  constructor(options: HermesSessionOptions = {}) {\n    const env = options.env ?? process.env;\n\n    this.#metroPort = parseEnvPort(env.HERMES_METRO_PORT) ?? DEFAULT_METRO_PORT;\n\n    this.#appIdFromEnv = env.HERMES_APP_ID !== undefined;\n    this.#expectedAppId =\n      env.HERMES_APP_ID ?? defaultAppIdForPlatform(options.platform);\n\n    this.#pinnedDeviceId = undefined;\n  }\n\n  /**\n   * Returns the session-default Metro inspector proxy port.\n   *\n   * @returns The resolved Metro port (env `HERMES_METRO_PORT`, else 8081).\n   */\n  getMetroPort(): number {\n    return this.#metroPort;\n  }\n\n  /**\n   * Returns the session-default expected app bundle ID.\n   *\n   * @returns The resolved app bundle ID (env `HERMES_APP_ID`, else the\n   * platform default).\n   */\n  getAppId(): string {\n    return this.#expectedAppId;\n  }\n\n  /**\n   * Returns the pinned Hermes `logicalDeviceId` for this session, if any.\n   *\n   * Set on the first successful identity probe via\n   * {@link setPinnedHermesDeviceId}. Persists for the lifetime of this\n   * instance.\n   *\n   * @returns The pinned `logicalDeviceId`, or undefined when no pin is set.\n   */\n  getPinnedHermesDeviceId(): string | undefined {\n    return this.#pinnedDeviceId;\n  }\n\n  /**\n   * Pin the Hermes `logicalDeviceId` for this session.\n   *\n   * Called after a successful identity probe on the first call. Subsequent\n   * calls then enforce this pin to prevent target switching mid-session.\n   *\n   * @param id - The `logicalDeviceId` from Metro's\n   * `reactNative.logicalDeviceId` field.\n   */\n  setPinnedHermesDeviceId(id: string): void {\n    this.#pinnedDeviceId = id;\n  }\n\n  /**\n   * Resolve the effective parameters for a single tool call by merging\n   * per-call overrides over the stored session defaults.\n   *\n   * This is PURE with respect to stored state: it never mutates the stored\n   * port, appId, or pin. Only {@link setPinnedHermesDeviceId} mutates the pin.\n   *\n   * Port precedence is `input.metroPort ?? this.getMetroPort()` (which itself\n   * already encodes `env ?? default`), mirroring the reference driver's\n   * `input.metroPort ?? driver.getMetroPort() ?? 8081`.\n   *\n   * AppId precedence is `input.appId ?? <HERMES_APP_ID env if set> ??\n   * defaultAppIdForPlatform(input.platform) ?? <stored default>`. An explicitly\n   * set `HERMES_APP_ID` always WINS over the per-call platform default (env is a\n   * deliberate override): in that case the stored appId is returned unchanged.\n   * Only when the stored appId is the construction-time platform fallback does\n   * a per-call `platform` recompute it — without mutating stored state. When no\n   * `platform` is passed this preserves the original iOS-default behavior.\n   *\n   * @param input - Optional per-call overrides for port, appId, and platform.\n   * @returns The effective `{ metroPort, appId, pinnedDeviceId }`.\n   */\n  resolve(input: HermesSessionResolveInput = {}): HermesSessionResolved {\n    return {\n      metroPort: input.metroPort ?? this.#metroPort,\n      appId: input.appId ?? this.#resolveAppId(input.platform),\n      pinnedDeviceId: this.#pinnedDeviceId,\n    };\n  }\n\n  /**\n   * Compute the effective default appId for a call, honouring the\n   * env-over-platform-default precedence documented on {@link resolve}.\n   *\n   * @param platform - The live platform passed for this call, if any.\n   * @returns The stored env/explicit appId, or the platform default.\n   */\n  #resolveAppId(platform: HermesPlatform | undefined): string {\n    if (this.#appIdFromEnv || platform === undefined) {\n      return this.#expectedAppId;\n    }\n    return defaultAppIdForPlatform(platform);\n  }\n}\n\n/**\n * Module-level lazily-created singleton instance.\n */\nlet sessionInstance: HermesSession | undefined;\n\n/**\n * Returns the process-singleton {@link HermesSession}, creating it on first\n * access.\n *\n * @param options - Options applied only when the singleton is first created.\n * @returns The shared `HermesSession` instance.\n */\nexport function getHermesSession(\n  options?: HermesSessionOptions,\n): HermesSession {\n  if (sessionInstance === undefined) {\n    sessionInstance = new HermesSession(options);\n  }\n  return sessionInstance;\n}\n\n/**\n * Resets the process-singleton {@link HermesSession}.\n *\n * Intended for test isolation so each test can start from a clean session.\n */\nexport function resetHermesSession(): void {\n  sessionInstance = undefined;\n}\n"]}

package/dist/index.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MultipleDevicesError = exports.detectAllDevices = exports.createMcpServer = exports.createLazyBackend = exports.createBackend = void 0;
+exports.DEFAULT_METRO_PORT = exports.DEFAULT_ANDROID_APP_ID = exports.DEFAULT_IOS_APP_ID = exports.defaultAppIdForPlatform = exports.resetHermesSession = exports.getHermesSession = exports.HermesSession = exports.LEGACY_SYNTHETIC_TITLE = exports.validateWebSocketUrl = exports.hasAmbiguousTarget = exports.selectHermesTarget = exports.fetchDiscoveryTargets = exports.runHermesCdp = exports.MultipleDevicesError = exports.detectAllDevices = exports.createMcpServer = exports.createLazyBackend = exports.createBackend = void 0;
 var index_js_1 = require("./backends/index.cjs");
 Object.defineProperty(exports, "createBackend", { enumerable: true, get: function () { return index_js_1.createBackend; } });
 Object.defineProperty(exports, "createLazyBackend", { enumerable: true, get: function () { return index_js_1.createLazyBackend; } });
@@ -9,4 +9,19 @@ Object.defineProperty(exports, "createMcpServer", { enumerable: true, get: funct
 var platform_js_1 = require("./utils/platform.cjs");
 Object.defineProperty(exports, "detectAllDevices", { enumerable: true, get: function () { return platform_js_1.detectAllDevices; } });
 Object.defineProperty(exports, "MultipleDevicesError", { enumerable: true, get: function () { return platform_js_1.MultipleDevicesError; } });
+var hermes_cdp_js_1 = require("./hermes/hermes-cdp.cjs");
+Object.defineProperty(exports, "runHermesCdp", { enumerable: true, get: function () { return hermes_cdp_js_1.runHermesCdp; } });
+Object.defineProperty(exports, "fetchDiscoveryTargets", { enumerable: true, get: function () { return hermes_cdp_js_1.fetchDiscoveryTargets; } });
+Object.defineProperty(exports, "selectHermesTarget", { enumerable: true, get: function () { return hermes_cdp_js_1.selectHermesTarget; } });
+Object.defineProperty(exports, "hasAmbiguousTarget", { enumerable: true, get: function () { return hermes_cdp_js_1.hasAmbiguousTarget; } });
+Object.defineProperty(exports, "validateWebSocketUrl", { enumerable: true, get: function () { return hermes_cdp_js_1.validateWebSocketUrl; } });
+Object.defineProperty(exports, "LEGACY_SYNTHETIC_TITLE", { enumerable: true, get: function () { return hermes_cdp_js_1.LEGACY_SYNTHETIC_TITLE; } });
+var session_js_1 = require("./hermes/session.cjs");
+Object.defineProperty(exports, "HermesSession", { enumerable: true, get: function () { return session_js_1.HermesSession; } });
+Object.defineProperty(exports, "getHermesSession", { enumerable: true, get: function () { return session_js_1.getHermesSession; } });
+Object.defineProperty(exports, "resetHermesSession", { enumerable: true, get: function () { return session_js_1.resetHermesSession; } });
+Object.defineProperty(exports, "defaultAppIdForPlatform", { enumerable: true, get: function () { return session_js_1.defaultAppIdForPlatform; } });
+Object.defineProperty(exports, "DEFAULT_IOS_APP_ID", { enumerable: true, get: function () { return session_js_1.DEFAULT_IOS_APP_ID; } });
+Object.defineProperty(exports, "DEFAULT_ANDROID_APP_ID", { enumerable: true, get: function () { return session_js_1.DEFAULT_ANDROID_APP_ID; } });
+Object.defineProperty(exports, "DEFAULT_METRO_PORT", { enumerable: true, get: function () { return session_js_1.DEFAULT_METRO_PORT; } });
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,iDAAuE;AAA9D,yGAAA,aAAa,OAAA;AAAE,6GAAA,iBAAiB,OAAA;AAEzC,0CAA8C;AAArC,4GAAA,eAAe,OAAA;AAExB,oDAA6E;AAApE,+GAAA,gBAAgB,OAAA;AAAE,mHAAA,oBAAoB,OAAA","sourcesContent":["export { createBackend, createLazyBackend } from './backends/index.js';\nexport type { LazyDeviceBackend } from './backends/index.js';\nexport { createMcpServer } from './server.js';\n\nexport { detectAllDevices, MultipleDevicesError } from './utils/platform.js';\nexport type { DetectedDevice } from './utils/platform.js';\n\nexport type {\n  DeviceBackend,\n  DeviceButton,\n  DeviceInfo,\n  UIElement,\n  ElementQuery,\n  SnapshotResult,\n  ScreenshotResult,\n  LogsResult,\n  TapResult,\n  AppStateResult,\n  Platform,\n  WindowSize,\n} from './backends/types.js';\n\nexport type { SessionConfig } from './backends/session-file.js';\n"]}
+{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,iDAAuE;AAA9D,yGAAA,aAAa,OAAA;AAAE,6GAAA,iBAAiB,OAAA;AAEzC,0CAA8C;AAArC,4GAAA,eAAe,OAAA;AAExB,oDAA6E;AAApE,+GAAA,gBAAgB,OAAA;AAAE,mHAAA,oBAAoB,OAAA;AAsB/C,yDAOgC;AAN9B,6GAAA,YAAY,OAAA;AACZ,sHAAA,qBAAqB,OAAA;AACrB,mHAAA,kBAAkB,OAAA;AAClB,mHAAA,kBAAkB,OAAA;AAClB,qHAAA,oBAAoB,OAAA;AACpB,uHAAA,sBAAsB,OAAA;AAQxB,mDAQ6B;AAP3B,2GAAA,aAAa,OAAA;AACb,8GAAA,gBAAgB,OAAA;AAChB,gHAAA,kBAAkB,OAAA;AAClB,qHAAA,uBAAuB,OAAA;AACvB,gHAAA,kBAAkB,OAAA;AAClB,oHAAA,sBAAsB,OAAA;AACtB,gHAAA,kBAAkB,OAAA","sourcesContent":["export { createBackend, createLazyBackend } from './backends/index.js';\nexport type { LazyDeviceBackend } from './backends/index.js';\nexport { createMcpServer } from './server.js';\n\nexport { detectAllDevices, MultipleDevicesError } from './utils/platform.js';\nexport type { DetectedDevice } from './utils/platform.js';\n\nexport type {\n  DeviceBackend,\n  DeviceButton,\n  DeviceInfo,\n  UIElement,\n  ElementQuery,\n  SnapshotResult,\n  ScreenshotResult,\n  ScreenshotFileResult,\n  ScreenshotOptions,\n  LogsResult,\n  TapResult,\n  AppStateResult,\n  Platform,\n  WindowSize,\n} from './backends/types.js';\n\nexport type { SessionConfig } from './backends/session-file.js';\n\nexport {\n  runHermesCdp,\n  fetchDiscoveryTargets,\n  selectHermesTarget,\n  hasAmbiguousTarget,\n  validateWebSocketUrl,\n  LEGACY_SYNTHETIC_TITLE,\n} from './hermes/hermes-cdp.js';\nexport type {\n  HermesTarget,\n  HermesCdpResult,\n  RunHermesCdpInput,\n} from './hermes/hermes-cdp.js';\n\nexport {\n  HermesSession,\n  getHermesSession,\n  resetHermesSession,\n  defaultAppIdForPlatform,\n  DEFAULT_IOS_APP_ID,\n  DEFAULT_ANDROID_APP_ID,\n  DEFAULT_METRO_PORT,\n} from './hermes/session.js';\nexport type {\n  HermesPlatform,\n  HermesSessionOptions,\n  HermesSessionResolved,\n  HermesSessionResolveInput,\n} from './hermes/session.js';\n"]}

package/dist/index.d.cts

@@ -3,6 +3,10 @@ export type { LazyDeviceBackend } from "./backends/index.cjs";
 export { createMcpServer } from "./server.cjs";
 export { detectAllDevices, MultipleDevicesError } from "./utils/platform.cjs";
 export type { DetectedDevice } from "./utils/platform.cjs";
-export type { DeviceBackend, DeviceButton, DeviceInfo, UIElement, ElementQuery, SnapshotResult, ScreenshotResult, LogsResult, TapResult, AppStateResult, Platform, WindowSize, } from "./backends/types.cjs";
+export type { DeviceBackend, DeviceButton, DeviceInfo, UIElement, ElementQuery, SnapshotResult, ScreenshotResult, ScreenshotFileResult, ScreenshotOptions, LogsResult, TapResult, AppStateResult, Platform, WindowSize, } from "./backends/types.cjs";
 export type { SessionConfig } from "./backends/session-file.cjs";
+export { runHermesCdp, fetchDiscoveryTargets, selectHermesTarget, hasAmbiguousTarget, validateWebSocketUrl, LEGACY_SYNTHETIC_TITLE, } from "./hermes/hermes-cdp.cjs";
+export type { HermesTarget, HermesCdpResult, RunHermesCdpInput, } from "./hermes/hermes-cdp.cjs";
+export { HermesSession, getHermesSession, resetHermesSession, defaultAppIdForPlatform, DEFAULT_IOS_APP_ID, DEFAULT_ANDROID_APP_ID, DEFAULT_METRO_PORT, } from "./hermes/session.cjs";
+export type { HermesPlatform, HermesSessionOptions, HermesSessionResolved, HermesSessionResolveInput, } from "./hermes/session.cjs";
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,6BAA4B;AACvE,YAAY,EAAE,iBAAiB,EAAE,6BAA4B;AAC7D,OAAO,EAAE,eAAe,EAAE,qBAAoB;AAE9C,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,6BAA4B;AAC7E,YAAY,EAAE,cAAc,EAAE,6BAA4B;AAE1D,YAAY,EACV,aAAa,EACb,YAAY,EACZ,UAAU,EACV,SAAS,EACT,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,SAAS,EACT,cAAc,EACd,QAAQ,EACR,UAAU,GACX,6BAA4B;AAE7B,YAAY,EAAE,aAAa,EAAE,oCAAmC"}
+{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,6BAA4B;AACvE,YAAY,EAAE,iBAAiB,EAAE,6BAA4B;AAC7D,OAAO,EAAE,eAAe,EAAE,qBAAoB;AAE9C,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,6BAA4B;AAC7E,YAAY,EAAE,cAAc,EAAE,6BAA4B;AAE1D,YAAY,EACV,aAAa,EACb,YAAY,EACZ,UAAU,EACV,SAAS,EACT,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,UAAU,EACV,SAAS,EACT,cAAc,EACd,QAAQ,EACR,UAAU,GACX,6BAA4B;AAE7B,YAAY,EAAE,aAAa,EAAE,oCAAmC;AAEhE,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,sBAAsB,GACvB,gCAA+B;AAChC,YAAY,EACV,YAAY,EACZ,eAAe,EACf,iBAAiB,GAClB,gCAA+B;AAEhC,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,uBAAuB,EACvB,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,GACnB,6BAA4B;AAC7B,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EACrB,yBAAyB,GAC1B,6BAA4B"}

package/dist/index.d.mts

@@ -3,6 +3,10 @@ export type { LazyDeviceBackend } from "./backends/index.mjs";
 export { createMcpServer } from "./server.mjs";
 export { detectAllDevices, MultipleDevicesError } from "./utils/platform.mjs";
 export type { DetectedDevice } from "./utils/platform.mjs";
-export type { DeviceBackend, DeviceButton, DeviceInfo, UIElement, ElementQuery, SnapshotResult, ScreenshotResult, LogsResult, TapResult, AppStateResult, Platform, WindowSize, } from "./backends/types.mjs";
+export type { DeviceBackend, DeviceButton, DeviceInfo, UIElement, ElementQuery, SnapshotResult, ScreenshotResult, ScreenshotFileResult, ScreenshotOptions, LogsResult, TapResult, AppStateResult, Platform, WindowSize, } from "./backends/types.mjs";
 export type { SessionConfig } from "./backends/session-file.mjs";
+export { runHermesCdp, fetchDiscoveryTargets, selectHermesTarget, hasAmbiguousTarget, validateWebSocketUrl, LEGACY_SYNTHETIC_TITLE, } from "./hermes/hermes-cdp.mjs";
+export type { HermesTarget, HermesCdpResult, RunHermesCdpInput, } from "./hermes/hermes-cdp.mjs";
+export { HermesSession, getHermesSession, resetHermesSession, defaultAppIdForPlatform, DEFAULT_IOS_APP_ID, DEFAULT_ANDROID_APP_ID, DEFAULT_METRO_PORT, } from "./hermes/session.mjs";
+export type { HermesPlatform, HermesSessionOptions, HermesSessionResolved, HermesSessionResolveInput, } from "./hermes/session.mjs";
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,6BAA4B;AACvE,YAAY,EAAE,iBAAiB,EAAE,6BAA4B;AAC7D,OAAO,EAAE,eAAe,EAAE,qBAAoB;AAE9C,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,6BAA4B;AAC7E,YAAY,EAAE,cAAc,EAAE,6BAA4B;AAE1D,YAAY,EACV,aAAa,EACb,YAAY,EACZ,UAAU,EACV,SAAS,EACT,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,SAAS,EACT,cAAc,EACd,QAAQ,EACR,UAAU,GACX,6BAA4B;AAE7B,YAAY,EAAE,aAAa,EAAE,oCAAmC"}
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,6BAA4B;AACvE,YAAY,EAAE,iBAAiB,EAAE,6BAA4B;AAC7D,OAAO,EAAE,eAAe,EAAE,qBAAoB;AAE9C,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,6BAA4B;AAC7E,YAAY,EAAE,cAAc,EAAE,6BAA4B;AAE1D,YAAY,EACV,aAAa,EACb,YAAY,EACZ,UAAU,EACV,SAAS,EACT,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,UAAU,EACV,SAAS,EACT,cAAc,EACd,QAAQ,EACR,UAAU,GACX,6BAA4B;AAE7B,YAAY,EAAE,aAAa,EAAE,oCAAmC;AAEhE,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,sBAAsB,GACvB,gCAA+B;AAChC,YAAY,EACV,YAAY,EACZ,eAAe,EACf,iBAAiB,GAClB,gCAA+B;AAEhC,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,uBAAuB,EACvB,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,GACnB,6BAA4B;AAC7B,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EACrB,yBAAyB,GAC1B,6BAA4B"}

package/dist/index.mjs

@@ -1,4 +1,6 @@
 export { createBackend, createLazyBackend } from "./backends/index.mjs";
 export { createMcpServer } from "./server.mjs";
 export { detectAllDevices, MultipleDevicesError } from "./utils/platform.mjs";
+export { runHermesCdp, fetchDiscoveryTargets, selectHermesTarget, hasAmbiguousTarget, validateWebSocketUrl, LEGACY_SYNTHETIC_TITLE } from "./hermes/hermes-cdp.mjs";
+export { HermesSession, getHermesSession, resetHermesSession, defaultAppIdForPlatform, DEFAULT_IOS_APP_ID, DEFAULT_ANDROID_APP_ID, DEFAULT_METRO_PORT } from "./hermes/session.mjs";
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,6BAA4B;AAEvE,OAAO,EAAE,eAAe,EAAE,qBAAoB;AAE9C,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,6BAA4B","sourcesContent":["export { createBackend, createLazyBackend } from './backends/index.js';\nexport type { LazyDeviceBackend } from './backends/index.js';\nexport { createMcpServer } from './server.js';\n\nexport { detectAllDevices, MultipleDevicesError } from './utils/platform.js';\nexport type { DetectedDevice } from './utils/platform.js';\n\nexport type {\n  DeviceBackend,\n  DeviceButton,\n  DeviceInfo,\n  UIElement,\n  ElementQuery,\n  SnapshotResult,\n  ScreenshotResult,\n  LogsResult,\n  TapResult,\n  AppStateResult,\n  Platform,\n  WindowSize,\n} from './backends/types.js';\n\nexport type { SessionConfig } from './backends/session-file.js';\n"]}
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,6BAA4B;AAEvE,OAAO,EAAE,eAAe,EAAE,qBAAoB;AAE9C,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,6BAA4B;AAsB7E,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,sBAAsB,EACvB,gCAA+B;AAOhC,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,uBAAuB,EACvB,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EACnB,6BAA4B","sourcesContent":["export { createBackend, createLazyBackend } from './backends/index.js';\nexport type { LazyDeviceBackend } from './backends/index.js';\nexport { createMcpServer } from './server.js';\n\nexport { detectAllDevices, MultipleDevicesError } from './utils/platform.js';\nexport type { DetectedDevice } from './utils/platform.js';\n\nexport type {\n  DeviceBackend,\n  DeviceButton,\n  DeviceInfo,\n  UIElement,\n  ElementQuery,\n  SnapshotResult,\n  ScreenshotResult,\n  ScreenshotFileResult,\n  ScreenshotOptions,\n  LogsResult,\n  TapResult,\n  AppStateResult,\n  Platform,\n  WindowSize,\n} from './backends/types.js';\n\nexport type { SessionConfig } from './backends/session-file.js';\n\nexport {\n  runHermesCdp,\n  fetchDiscoveryTargets,\n  selectHermesTarget,\n  hasAmbiguousTarget,\n  validateWebSocketUrl,\n  LEGACY_SYNTHETIC_TITLE,\n} from './hermes/hermes-cdp.js';\nexport type {\n  HermesTarget,\n  HermesCdpResult,\n  RunHermesCdpInput,\n} from './hermes/hermes-cdp.js';\n\nexport {\n  HermesSession,\n  getHermesSession,\n  resetHermesSession,\n  defaultAppIdForPlatform,\n  DEFAULT_IOS_APP_ID,\n  DEFAULT_ANDROID_APP_ID,\n  DEFAULT_METRO_PORT,\n} from './hermes/session.js';\nexport type {\n  HermesPlatform,\n  HermesSessionOptions,\n  HermesSessionResolved,\n  HermesSessionResolveInput,\n} from './hermes/session.js';\n"]}

package/dist/server.cjs

@@ -15,6 +15,7 @@ function createMcpServer(backend) {
             'Check for system alerts with device_snapshot before interacting with app elements.',
             'If multiple devices are connected and no device is selected, tools will return the device list.',
             'Call device_list_devices to see available devices, then device_select_device to choose one.',
+            'The Hermes tools (hermes_cdp, hermes_targets) talk to the React Native Hermes JS runtime via Metro and require a DEBUG build with Metro running (Node 20 needs NODE_OPTIONS="--experimental-websocket").',
         ].join('\n'),
     });
     (0, index_js_1.registerSnapshotTool)(server, backend);
@@ -43,6 +44,8 @@ function createMcpServer(backend) {
     (0, index_js_1.registerGetElementTextTool)(server, backend);
     (0, index_js_1.registerListDevicesTool)(server, backend);
     (0, index_js_1.registerSelectDeviceTool)(server, backend);
+    (0, index_js_1.registerHermesCdpTool)(server, backend);
+    (0, index_js_1.registerHermesTargetsTool)(server, backend);
     return server;
 }
 //# sourceMappingURL=server.cjs.map

package/dist/server.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"server.cjs","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";;AAgCA,0CA8CC;AA9ED,oEAAoE;AAGpE,gDA2B0B;AAE1B,SAAgB,eAAe,CAAC,OAA0B;IACxD,MAAM,MAAM,GAAG,IAAI,kBAAS,CAC1B,EAAE,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,OAAO,EAAE,EAClD;QACE,YAAY,EAAE;YACZ,kEAAkE;YAClE,kFAAkF;YAClF,6DAA6D;YAC7D,4FAA4F;YAC5F,4EAA4E;YAC5E,yFAAyF;YACzF,oFAAoF;YACpF,iGAAiG;YACjG,6FAA6F;SAC9F,CAAC,IAAI,CAAC,IAAI,CAAC;KACb,CACF,CAAC;IAEF,IAAA,+BAAoB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,IAAA,iCAAsB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,IAAA,iCAAsB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,IAAA,iCAAsB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,IAAA,qCAA0B,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,IAAA,2BAAgB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,IAAA,4BAAiB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,IAAA,gCAAqB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,IAAA,8BAAmB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,IAAA,+BAAoB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,IAAA,8BAAmB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,IAAA,+BAAoB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,IAAA,kCAAuB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,IAAA,sCAA2B,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,IAAA,mCAAwB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,IAAA,2BAAgB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,IAAA,sCAA2B,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,IAAA,gCAAqB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,IAAA,iCAAsB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,IAAA,8BAAmB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,IAAA,gCAAqB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,IAAA,sCAA2B,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,IAAA,uCAA4B,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,IAAA,qCAA0B,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,IAAA,kCAAuB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,IAAA,mCAAwB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE1C,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\n\nimport type { LazyDeviceBackend } from './backends/index.js';\nimport {\n  registerSnapshotTool,\n  registerScreenshotTool,\n  registerTapElementTool,\n  registerTapCoordinatesTool,\n  registerTypeTool,\n  registerSwipeTool,\n  registerLongPressTool,\n  registerWaitForTool,\n  registerAppStateTool,\n  registerDeviceInfoTool,\n  registerOpenAppTool,\n  registerCloseAppTool,\n  registerPressButtonTool,\n  registerDismissKeyboardTool,\n  registerDismissAlertTool,\n  registerLogsTool,\n  registerScrollToElementTool,\n  registerAlertTextTool,\n  registerWindowSizeTool,\n  registerContextTool,\n  registerClipboardTool,\n  registerScreenRecordingTool,\n  registerGenerateLocatorsTool,\n  registerGetElementTextTool,\n  registerListDevicesTool,\n  registerSelectDeviceTool,\n} from './tools/index.js';\n\nexport function createMcpServer(backend: LazyDeviceBackend): McpServer {\n  const server = new McpServer(\n    { name: '@metamask/device-mcp', version: '0.0.0' },\n    {\n      instructions: [\n        'Mobile device interaction tools for iOS (IDB) and Android (ADB).',\n        'ALWAYS call device_snapshot before device_tap_element to see the current screen.',\n        'Never call device_snapshot twice without acting in between.',\n        'Elements are identified by accessibility label, resource-id, content-description, or text.',\n        'Element matching is fuzzy: partial text and case-insensitive matches work.',\n        'After typing, call device_dismiss_keyboard to reveal elements obscured by the keyboard.',\n        'Check for system alerts with device_snapshot before interacting with app elements.',\n        'If multiple devices are connected and no device is selected, tools will return the device list.',\n        'Call device_list_devices to see available devices, then device_select_device to choose one.',\n      ].join('\\n'),\n    },\n  );\n\n  registerSnapshotTool(server, backend);\n  registerScreenshotTool(server, backend);\n  registerDeviceInfoTool(server, backend);\n  registerTapElementTool(server, backend);\n  registerTapCoordinatesTool(server, backend);\n  registerTypeTool(server, backend);\n  registerSwipeTool(server, backend);\n  registerLongPressTool(server, backend);\n  registerWaitForTool(server, backend);\n  registerAppStateTool(server, backend);\n  registerOpenAppTool(server, backend);\n  registerCloseAppTool(server, backend);\n  registerPressButtonTool(server, backend);\n  registerDismissKeyboardTool(server, backend);\n  registerDismissAlertTool(server, backend);\n  registerLogsTool(server, backend);\n  registerScrollToElementTool(server, backend);\n  registerAlertTextTool(server, backend);\n  registerWindowSizeTool(server, backend);\n  registerContextTool(server, backend);\n  registerClipboardTool(server, backend);\n  registerScreenRecordingTool(server, backend);\n  registerGenerateLocatorsTool(server, backend);\n  registerGetElementTextTool(server, backend);\n  registerListDevicesTool(server, backend);\n  registerSelectDeviceTool(server, backend);\n\n  return server;\n}\n"]}
+{"version":3,"file":"server.cjs","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";;AAkCA,0CAiDC;AAnFD,oEAAoE;AAGpE,gDA6B0B;AAE1B,SAAgB,eAAe,CAAC,OAA0B;IACxD,MAAM,MAAM,GAAG,IAAI,kBAAS,CAC1B,EAAE,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,OAAO,EAAE,EAClD;QACE,YAAY,EAAE;YACZ,kEAAkE;YAClE,kFAAkF;YAClF,6DAA6D;YAC7D,4FAA4F;YAC5F,4EAA4E;YAC5E,yFAAyF;YACzF,oFAAoF;YACpF,iGAAiG;YACjG,6FAA6F;YAC7F,0MAA0M;SAC3M,CAAC,IAAI,CAAC,IAAI,CAAC;KACb,CACF,CAAC;IAEF,IAAA,+BAAoB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,IAAA,iCAAsB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,IAAA,iCAAsB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,IAAA,iCAAsB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,IAAA,qCAA0B,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,IAAA,2BAAgB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,IAAA,4BAAiB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,IAAA,gCAAqB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,IAAA,8BAAmB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,IAAA,+BAAoB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,IAAA,8BAAmB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,IAAA,+BAAoB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,IAAA,kCAAuB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,IAAA,sCAA2B,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,IAAA,mCAAwB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,IAAA,2BAAgB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,IAAA,sCAA2B,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,IAAA,gCAAqB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,IAAA,iCAAsB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,IAAA,8BAAmB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,IAAA,gCAAqB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,IAAA,sCAA2B,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,IAAA,uCAA4B,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,IAAA,qCAA0B,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,IAAA,kCAAuB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,IAAA,mCAAwB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,IAAA,gCAAqB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,IAAA,oCAAyB,EAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE3C,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\n\nimport type { LazyDeviceBackend } from './backends/index.js';\nimport {\n  registerSnapshotTool,\n  registerScreenshotTool,\n  registerTapElementTool,\n  registerTapCoordinatesTool,\n  registerTypeTool,\n  registerSwipeTool,\n  registerLongPressTool,\n  registerWaitForTool,\n  registerAppStateTool,\n  registerDeviceInfoTool,\n  registerOpenAppTool,\n  registerCloseAppTool,\n  registerPressButtonTool,\n  registerDismissKeyboardTool,\n  registerDismissAlertTool,\n  registerLogsTool,\n  registerScrollToElementTool,\n  registerAlertTextTool,\n  registerWindowSizeTool,\n  registerContextTool,\n  registerClipboardTool,\n  registerScreenRecordingTool,\n  registerGenerateLocatorsTool,\n  registerGetElementTextTool,\n  registerListDevicesTool,\n  registerSelectDeviceTool,\n  registerHermesCdpTool,\n  registerHermesTargetsTool,\n} from './tools/index.js';\n\nexport function createMcpServer(backend: LazyDeviceBackend): McpServer {\n  const server = new McpServer(\n    { name: '@metamask/device-mcp', version: '0.0.0' },\n    {\n      instructions: [\n        'Mobile device interaction tools for iOS (IDB) and Android (ADB).',\n        'ALWAYS call device_snapshot before device_tap_element to see the current screen.',\n        'Never call device_snapshot twice without acting in between.',\n        'Elements are identified by accessibility label, resource-id, content-description, or text.',\n        'Element matching is fuzzy: partial text and case-insensitive matches work.',\n        'After typing, call device_dismiss_keyboard to reveal elements obscured by the keyboard.',\n        'Check for system alerts with device_snapshot before interacting with app elements.',\n        'If multiple devices are connected and no device is selected, tools will return the device list.',\n        'Call device_list_devices to see available devices, then device_select_device to choose one.',\n        'The Hermes tools (hermes_cdp, hermes_targets) talk to the React Native Hermes JS runtime via Metro and require a DEBUG build with Metro running (Node 20 needs NODE_OPTIONS=\"--experimental-websocket\").',\n      ].join('\\n'),\n    },\n  );\n\n  registerSnapshotTool(server, backend);\n  registerScreenshotTool(server, backend);\n  registerDeviceInfoTool(server, backend);\n  registerTapElementTool(server, backend);\n  registerTapCoordinatesTool(server, backend);\n  registerTypeTool(server, backend);\n  registerSwipeTool(server, backend);\n  registerLongPressTool(server, backend);\n  registerWaitForTool(server, backend);\n  registerAppStateTool(server, backend);\n  registerOpenAppTool(server, backend);\n  registerCloseAppTool(server, backend);\n  registerPressButtonTool(server, backend);\n  registerDismissKeyboardTool(server, backend);\n  registerDismissAlertTool(server, backend);\n  registerLogsTool(server, backend);\n  registerScrollToElementTool(server, backend);\n  registerAlertTextTool(server, backend);\n  registerWindowSizeTool(server, backend);\n  registerContextTool(server, backend);\n  registerClipboardTool(server, backend);\n  registerScreenRecordingTool(server, backend);\n  registerGenerateLocatorsTool(server, backend);\n  registerGetElementTextTool(server, backend);\n  registerListDevicesTool(server, backend);\n  registerSelectDeviceTool(server, backend);\n  registerHermesCdpTool(server, backend);\n  registerHermesTargetsTool(server, backend);\n\n  return server;\n}\n"]}

package/dist/server.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.cts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,gDAAgD;AAEpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,6BAA4B;AA8B7D,wBAAgB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,CA8CrE"}
+{"version":3,"file":"server.d.cts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,gDAAgD;AAEpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,6BAA4B;AAgC7D,wBAAgB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,CAiDrE"}

package/dist/server.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.mts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,gDAAgD;AAEpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,6BAA4B;AA8B7D,wBAAgB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,CA8CrE"}
+{"version":3,"file":"server.d.mts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,gDAAgD;AAEpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,6BAA4B;AAgC7D,wBAAgB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,CAiDrE"}

package/dist/server.mjs

@@ -1,5 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { registerSnapshotTool, registerScreenshotTool, registerTapElementTool, registerTapCoordinatesTool, registerTypeTool, registerSwipeTool, registerLongPressTool, registerWaitForTool, registerAppStateTool, registerDeviceInfoTool, registerOpenAppTool, registerCloseAppTool, registerPressButtonTool, registerDismissKeyboardTool, registerDismissAlertTool, registerLogsTool, registerScrollToElementTool, registerAlertTextTool, registerWindowSizeTool, registerContextTool, registerClipboardTool, registerScreenRecordingTool, registerGenerateLocatorsTool, registerGetElementTextTool, registerListDevicesTool, registerSelectDeviceTool } from "./tools/index.mjs";
+import { registerSnapshotTool, registerScreenshotTool, registerTapElementTool, registerTapCoordinatesTool, registerTypeTool, registerSwipeTool, registerLongPressTool, registerWaitForTool, registerAppStateTool, registerDeviceInfoTool, registerOpenAppTool, registerCloseAppTool, registerPressButtonTool, registerDismissKeyboardTool, registerDismissAlertTool, registerLogsTool, registerScrollToElementTool, registerAlertTextTool, registerWindowSizeTool, registerContextTool, registerClipboardTool, registerScreenRecordingTool, registerGenerateLocatorsTool, registerGetElementTextTool, registerListDevicesTool, registerSelectDeviceTool, registerHermesCdpTool, registerHermesTargetsTool } from "./tools/index.mjs";
 export function createMcpServer(backend) {
     const server = new McpServer({ name: '@metamask/device-mcp', version: '0.0.0' }, {
         instructions: [
@@ -12,6 +12,7 @@ export function createMcpServer(backend) {
             'Check for system alerts with device_snapshot before interacting with app elements.',
             'If multiple devices are connected and no device is selected, tools will return the device list.',
             'Call device_list_devices to see available devices, then device_select_device to choose one.',
+            'The Hermes tools (hermes_cdp, hermes_targets) talk to the React Native Hermes JS runtime via Metro and require a DEBUG build with Metro running (Node 20 needs NODE_OPTIONS="--experimental-websocket").',
         ].join('\n'),
     });
     registerSnapshotTool(server, backend);
@@ -40,6 +41,8 @@ export function createMcpServer(backend) {
     registerGetElementTextTool(server, backend);
     registerListDevicesTool(server, backend);
     registerSelectDeviceTool(server, backend);
+    registerHermesCdpTool(server, backend);
+    registerHermesTargetsTool(server, backend);
     return server;
 }
 //# sourceMappingURL=server.mjs.map

package/dist/server.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"server.mjs","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,gDAAgD;AAGpE,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,EACtB,0BAA0B,EAC1B,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,2BAA2B,EAC3B,wBAAwB,EACxB,gBAAgB,EAChB,2BAA2B,EAC3B,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,qBAAqB,EACrB,2BAA2B,EAC3B,4BAA4B,EAC5B,0BAA0B,EAC1B,uBAAuB,EACvB,wBAAwB,EACzB,0BAAyB;AAE1B,MAAM,UAAU,eAAe,CAAC,OAA0B;IACxD,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,OAAO,EAAE,EAClD;QACE,YAAY,EAAE;YACZ,kEAAkE;YAClE,kFAAkF;YAClF,6DAA6D;YAC7D,4FAA4F;YAC5F,4EAA4E;YAC5E,yFAAyF;YACzF,oFAAoF;YACpF,iGAAiG;YACjG,6FAA6F;SAC9F,CAAC,IAAI,CAAC,IAAI,CAAC;KACb,CACF,CAAC;IAEF,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,sBAAsB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,sBAAsB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,sBAAsB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,0BAA0B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,mBAAmB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,mBAAmB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,uBAAuB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,2BAA2B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,wBAAwB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,2BAA2B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,sBAAsB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,mBAAmB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,2BAA2B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,4BAA4B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,0BAA0B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,uBAAuB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,wBAAwB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE1C,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\n\nimport type { LazyDeviceBackend } from './backends/index.js';\nimport {\n  registerSnapshotTool,\n  registerScreenshotTool,\n  registerTapElementTool,\n  registerTapCoordinatesTool,\n  registerTypeTool,\n  registerSwipeTool,\n  registerLongPressTool,\n  registerWaitForTool,\n  registerAppStateTool,\n  registerDeviceInfoTool,\n  registerOpenAppTool,\n  registerCloseAppTool,\n  registerPressButtonTool,\n  registerDismissKeyboardTool,\n  registerDismissAlertTool,\n  registerLogsTool,\n  registerScrollToElementTool,\n  registerAlertTextTool,\n  registerWindowSizeTool,\n  registerContextTool,\n  registerClipboardTool,\n  registerScreenRecordingTool,\n  registerGenerateLocatorsTool,\n  registerGetElementTextTool,\n  registerListDevicesTool,\n  registerSelectDeviceTool,\n} from './tools/index.js';\n\nexport function createMcpServer(backend: LazyDeviceBackend): McpServer {\n  const server = new McpServer(\n    { name: '@metamask/device-mcp', version: '0.0.0' },\n    {\n      instructions: [\n        'Mobile device interaction tools for iOS (IDB) and Android (ADB).',\n        'ALWAYS call device_snapshot before device_tap_element to see the current screen.',\n        'Never call device_snapshot twice without acting in between.',\n        'Elements are identified by accessibility label, resource-id, content-description, or text.',\n        'Element matching is fuzzy: partial text and case-insensitive matches work.',\n        'After typing, call device_dismiss_keyboard to reveal elements obscured by the keyboard.',\n        'Check for system alerts with device_snapshot before interacting with app elements.',\n        'If multiple devices are connected and no device is selected, tools will return the device list.',\n        'Call device_list_devices to see available devices, then device_select_device to choose one.',\n      ].join('\\n'),\n    },\n  );\n\n  registerSnapshotTool(server, backend);\n  registerScreenshotTool(server, backend);\n  registerDeviceInfoTool(server, backend);\n  registerTapElementTool(server, backend);\n  registerTapCoordinatesTool(server, backend);\n  registerTypeTool(server, backend);\n  registerSwipeTool(server, backend);\n  registerLongPressTool(server, backend);\n  registerWaitForTool(server, backend);\n  registerAppStateTool(server, backend);\n  registerOpenAppTool(server, backend);\n  registerCloseAppTool(server, backend);\n  registerPressButtonTool(server, backend);\n  registerDismissKeyboardTool(server, backend);\n  registerDismissAlertTool(server, backend);\n  registerLogsTool(server, backend);\n  registerScrollToElementTool(server, backend);\n  registerAlertTextTool(server, backend);\n  registerWindowSizeTool(server, backend);\n  registerContextTool(server, backend);\n  registerClipboardTool(server, backend);\n  registerScreenRecordingTool(server, backend);\n  registerGenerateLocatorsTool(server, backend);\n  registerGetElementTextTool(server, backend);\n  registerListDevicesTool(server, backend);\n  registerSelectDeviceTool(server, backend);\n\n  return server;\n}\n"]}
+{"version":3,"file":"server.mjs","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,gDAAgD;AAGpE,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,EACtB,0BAA0B,EAC1B,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,2BAA2B,EAC3B,wBAAwB,EACxB,gBAAgB,EAChB,2BAA2B,EAC3B,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,qBAAqB,EACrB,2BAA2B,EAC3B,4BAA4B,EAC5B,0BAA0B,EAC1B,uBAAuB,EACvB,wBAAwB,EACxB,qBAAqB,EACrB,yBAAyB,EAC1B,0BAAyB;AAE1B,MAAM,UAAU,eAAe,CAAC,OAA0B;IACxD,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,OAAO,EAAE,EAClD;QACE,YAAY,EAAE;YACZ,kEAAkE;YAClE,kFAAkF;YAClF,6DAA6D;YAC7D,4FAA4F;YAC5F,4EAA4E;YAC5E,yFAAyF;YACzF,oFAAoF;YACpF,iGAAiG;YACjG,6FAA6F;YAC7F,0MAA0M;SAC3M,CAAC,IAAI,CAAC,IAAI,CAAC;KACb,CACF,CAAC;IAEF,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,sBAAsB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,sBAAsB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,sBAAsB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,0BAA0B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,mBAAmB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,mBAAmB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,uBAAuB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,2BAA2B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,wBAAwB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,2BAA2B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,sBAAsB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,mBAAmB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,2BAA2B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,4BAA4B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,0BAA0B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,uBAAuB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,wBAAwB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,yBAAyB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE3C,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\n\nimport type { LazyDeviceBackend } from './backends/index.js';\nimport {\n  registerSnapshotTool,\n  registerScreenshotTool,\n  registerTapElementTool,\n  registerTapCoordinatesTool,\n  registerTypeTool,\n  registerSwipeTool,\n  registerLongPressTool,\n  registerWaitForTool,\n  registerAppStateTool,\n  registerDeviceInfoTool,\n  registerOpenAppTool,\n  registerCloseAppTool,\n  registerPressButtonTool,\n  registerDismissKeyboardTool,\n  registerDismissAlertTool,\n  registerLogsTool,\n  registerScrollToElementTool,\n  registerAlertTextTool,\n  registerWindowSizeTool,\n  registerContextTool,\n  registerClipboardTool,\n  registerScreenRecordingTool,\n  registerGenerateLocatorsTool,\n  registerGetElementTextTool,\n  registerListDevicesTool,\n  registerSelectDeviceTool,\n  registerHermesCdpTool,\n  registerHermesTargetsTool,\n} from './tools/index.js';\n\nexport function createMcpServer(backend: LazyDeviceBackend): McpServer {\n  const server = new McpServer(\n    { name: '@metamask/device-mcp', version: '0.0.0' },\n    {\n      instructions: [\n        'Mobile device interaction tools for iOS (IDB) and Android (ADB).',\n        'ALWAYS call device_snapshot before device_tap_element to see the current screen.',\n        'Never call device_snapshot twice without acting in between.',\n        'Elements are identified by accessibility label, resource-id, content-description, or text.',\n        'Element matching is fuzzy: partial text and case-insensitive matches work.',\n        'After typing, call device_dismiss_keyboard to reveal elements obscured by the keyboard.',\n        'Check for system alerts with device_snapshot before interacting with app elements.',\n        'If multiple devices are connected and no device is selected, tools will return the device list.',\n        'Call device_list_devices to see available devices, then device_select_device to choose one.',\n        'The Hermes tools (hermes_cdp, hermes_targets) talk to the React Native Hermes JS runtime via Metro and require a DEBUG build with Metro running (Node 20 needs NODE_OPTIONS=\"--experimental-websocket\").',\n      ].join('\\n'),\n    },\n  );\n\n  registerSnapshotTool(server, backend);\n  registerScreenshotTool(server, backend);\n  registerDeviceInfoTool(server, backend);\n  registerTapElementTool(server, backend);\n  registerTapCoordinatesTool(server, backend);\n  registerTypeTool(server, backend);\n  registerSwipeTool(server, backend);\n  registerLongPressTool(server, backend);\n  registerWaitForTool(server, backend);\n  registerAppStateTool(server, backend);\n  registerOpenAppTool(server, backend);\n  registerCloseAppTool(server, backend);\n  registerPressButtonTool(server, backend);\n  registerDismissKeyboardTool(server, backend);\n  registerDismissAlertTool(server, backend);\n  registerLogsTool(server, backend);\n  registerScrollToElementTool(server, backend);\n  registerAlertTextTool(server, backend);\n  registerWindowSizeTool(server, backend);\n  registerContextTool(server, backend);\n  registerClipboardTool(server, backend);\n  registerScreenRecordingTool(server, backend);\n  registerGenerateLocatorsTool(server, backend);\n  registerGetElementTextTool(server, backend);\n  registerListDevicesTool(server, backend);\n  registerSelectDeviceTool(server, backend);\n  registerHermesCdpTool(server, backend);\n  registerHermesTargetsTool(server, backend);\n\n  return server;\n}\n"]}