@0xhayd3n/fling 0.6.0

package/dist/tools/open-setting.js

@@ -0,0 +1,257 @@
+import { z } from "zod";
+import { runAdb } from "../adb.js";
+import { resolveDeviceArgs } from "../devices.js";
+import { FlingError } from "../errors.js";
+import { deviceIdInput } from "../schemas.js";
+import { toolErrorFrom } from "../toolResult.js";
+const PANEL_TO_SUFFIX = {
+    wifi: "WIFI_SETTINGS",
+    bluetooth: "BLUETOOTH_SETTINGS",
+    apps: "APPLICATION_SETTINGS",
+    display: "DISPLAY_SETTINGS",
+    sound: "SOUND_SETTINGS",
+    battery: "BATTERY_SAVER_SETTINGS",
+    storage: "INTERNAL_STORAGE_SETTINGS",
+    location: "LOCATION_SOURCE_SETTINGS",
+    security: "SECURITY_SETTINGS",
+    developer: "APPLICATION_DEVELOPMENT_SETTINGS",
+    about: "DEVICE_INFO_SETTINGS",
+    date: "DATE_SETTINGS",
+    language: "LOCALE_SETTINGS",
+    accessibility: "ACCESSIBILITY_SETTINGS",
+    notifications: "NOTIFICATION_SETTINGS",
+};
+const PANEL_NAMES = Object.keys(PANEL_TO_SUFFIX);
+const ACTION_PREFIX = "android.settings.";
+const SUFFIX_RE = /^[A-Z][A-Z0-9_]*$/;
+const DATA_URI_RE = /^package:[A-Za-z][\w]*(?:\.[A-Za-z][\w]*)+$/;
+// Standard android.provider.Settings.ACTION_* values that point at a built-in
+// Settings screen reachable via `am start -a android.settings.<X>`. Restricted
+// to a known set to avoid arbitrary intent dispatch through this tool.
+export const SETTINGS_ACTION_ALLOWLIST = new Set([
+    "ACCESSIBILITY_SETTINGS",
+    "AIRPLANE_MODE_SETTINGS",
+    "APN_SETTINGS",
+    "APPLICATION_DETAILS_SETTINGS",
+    "APPLICATION_DEVELOPMENT_SETTINGS",
+    "APPLICATION_SETTINGS",
+    "APP_NOTIFICATION_SETTINGS",
+    "BATTERY_SAVER_SETTINGS",
+    "BLUETOOTH_SETTINGS",
+    "CAPTIONING_SETTINGS",
+    "CAST_SETTINGS",
+    "DATA_ROAMING_SETTINGS",
+    "DATE_SETTINGS",
+    "DEVICE_INFO_SETTINGS",
+    "DISPLAY_SETTINGS",
+    "DREAM_SETTINGS",
+    "HARD_KEYBOARD_SETTINGS",
+    "HOME_SETTINGS",
+    "IGNORE_BATTERY_OPTIMIZATION_SETTINGS",
+    "INPUT_METHOD_SETTINGS",
+    "INPUT_METHOD_SUBTYPE_SETTINGS",
+    "INTERNAL_STORAGE_SETTINGS",
+    "LOCALE_SETTINGS",
+    "LOCATION_SOURCE_SETTINGS",
+    "MANAGE_ALL_APPLICATIONS_SETTINGS",
+    "MANAGE_APPLICATIONS_SETTINGS",
+    "MEMORY_CARD_SETTINGS",
+    "NETWORK_OPERATOR_SETTINGS",
+    "NFC_PAYMENT_SETTINGS",
+    "NFC_SETTINGS",
+    "NFCSHARING_SETTINGS",
+    "NOTIFICATION_SETTINGS",
+    "PRIVACY_SETTINGS",
+    "QUICK_LAUNCH_SETTINGS",
+    "SEARCH_SETTINGS",
+    "SECURITY_SETTINGS",
+    "SETTINGS",
+    "SOUND_SETTINGS",
+    "SYNC_SETTINGS",
+    "TETHER_SETTINGS",
+    "USAGE_ACCESS_SETTINGS",
+    "USER_DICTIONARY_SETTINGS",
+    "VOICE_INPUT_SETTINGS",
+    "VPN_SETTINGS",
+    "WIFI_IP_SETTINGS",
+    "WIFI_SETTINGS",
+    "WIRELESS_SETTINGS",
+]);
+export function panelToAction(panel) {
+    const suffix = PANEL_TO_SUFFIX[panel];
+    if (!suffix) {
+        throw new FlingError("INVALID_INPUT", `Unknown settings panel: ${panel}`);
+    }
+    return `android.settings.${suffix}`;
+}
+/**
+ * Accepts either the bare suffix (e.g. "WIFI_SETTINGS") or the fully qualified
+ * action (e.g. "android.settings.WIFI_SETTINGS") and returns the fully
+ * qualified form. Throws FlingError("INVALID_INPUT") on anything else — most
+ * importantly, on actions outside the allowlist, which is the guard against
+ * using this tool to fire arbitrary intents.
+ */
+export function normalizeSettingsAction(input) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        throw new FlingError("INVALID_INPUT", "Settings action is required.");
+    }
+    const suffix = trimmed.startsWith(ACTION_PREFIX)
+        ? trimmed.slice(ACTION_PREFIX.length)
+        : trimmed;
+    if (!SUFFIX_RE.test(suffix)) {
+        throw new FlingError("INVALID_INPUT", `Invalid settings action: "${input}". Expected an uppercase suffix like WIFI_SETTINGS, optionally prefixed with android.settings..`);
+    }
+    if (!SETTINGS_ACTION_ALLOWLIST.has(suffix)) {
+        throw new FlingError("INVALID_INPUT", `Settings action "${suffix}" is not in the allowlist. Known actions: ${[...SETTINGS_ACTION_ALLOWLIST].sort().join(", ")}.`);
+    }
+    return ACTION_PREFIX + suffix;
+}
+/**
+ * Strictly validates the `-d` payload. The only documented use for a data URI
+ * on a built-in settings intent is APPLICATION_DETAILS_SETTINGS, which expects
+ * `package:<dotted-android-id>`. Anything else is rejected to prevent arbitrary
+ * URI dispatch via this tool.
+ */
+export function validateSettingsDataUri(uri) {
+    if (!DATA_URI_RE.test(uri)) {
+        throw new FlingError("INVALID_INPUT", `Invalid data_uri: "${uri}". Only package:<dotted-android-id> is accepted (e.g. package:com.example.app).`);
+    }
+}
+export function buildSettingsAmArgs(params) {
+    // -W makes `am start` wait for the activity to come up and print Status: ok;
+    // without it the success line is suppressed and we can't tell whether the
+    // dispatch actually resolved an activity.
+    const argv = [
+        ...params.deviceArgs,
+        "shell",
+        "am",
+        "start",
+        "-W",
+        "-a",
+        params.action,
+    ];
+    if (params.dataUri) {
+        argv.push("-d", params.dataUri);
+    }
+    return argv;
+}
+/**
+ * Interpret `am start` output. The activity manager merges device-side stderr
+ * into adb stdout in some Android builds, so we concatenate both and look for
+ * known failure markers OR the absence of `Status: ok` (which `am start -W`
+ * always emits on success).
+ */
+export function interpretSettingsResult(stdout, stderr) {
+    const combined = `${stdout}\n${stderr}`;
+    const failureRe = /Error: (?:Activity (?:class|not started)|Intent does not match|.+ not found)|java\.lang\.SecurityException|No Activity found to handle/;
+    const successRe = /Status:\s*ok/i;
+    if (failureRe.test(combined) || !successRe.test(combined)) {
+        const reason = combined.trim().split(/\r?\n/).slice(0, 8).join("\n");
+        return {
+            success: false,
+            message: "Settings launch dispatch failed.",
+            raw: reason,
+        };
+    }
+    return {
+        success: true,
+        message: "Settings launch dispatched.",
+        raw: combined.trim(),
+    };
+}
+export async function performOpenSetting(params) {
+    const { stdout, stderr } = await runAdb(buildSettingsAmArgs(params));
+    return interpretSettingsResult(stdout, stderr);
+}
+/**
+ * Resolve the user's panel-or-action input into the fully qualified
+ * android.settings.* action string. Enforces XOR — exactly one of
+ * {panel, action} must be set. Delegates value validation to panelToAction
+ * (unknown panel) and normalizeSettingsAction (unknown / malformed /
+ * non-allowlisted action), each of which throws INVALID_INPUT on rejection.
+ */
+export function resolveOpenSettingAction(input) {
+    if (!input.panel && !input.action) {
+        throw new FlingError("INVALID_INPUT", "Provide either `panel` or `action`.");
+    }
+    if (input.panel && input.action) {
+        throw new FlingError("INVALID_INPUT", "Provide either `panel` or `action`, not both.");
+    }
+    return input.panel
+        ? panelToAction(input.panel)
+        : normalizeSettingsAction(input.action);
+}
+export function registerOpenSetting(server) {
+    server.registerTool("open_setting", {
+        title: "Open an Android Settings screen by intent",
+        description: "Open a built-in Android Settings screen via `am start -a android.settings.<ACTION>`. " +
+            "Pass either `panel` (friendly name: wifi, bluetooth, apps, display, sound, " +
+            "battery, storage, location, security, developer, about, date, language, " +
+            "accessibility, notifications) OR `action` (an allowlisted Settings action like " +
+            "WIFI_SETTINGS or the fully qualified android.settings.WIFI_SETTINGS). " +
+            "`data_uri` is for actions that need a target, currently restricted to " +
+            "package:<dotted-android-id> (the canonical form for APPLICATION_DETAILS_SETTINGS). " +
+            "Much faster than tap-walking the Settings UI — one adb call vs ~10 round-trips.",
+        inputSchema: {
+            device_id: deviceIdInput,
+            panel: z
+                .enum(PANEL_NAMES)
+                .optional()
+                .describe("Friendly panel name. Mutually exclusive with `action`."),
+            action: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Allowlisted Settings action. Bare suffix (WIFI_SETTINGS) or fully qualified (android.settings.WIFI_SETTINGS). Mutually exclusive with `panel`."),
+            data_uri: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Optional `-d` payload. Must be of the form package:<dotted-id>, e.g. package:com.example.app for APPLICATION_DETAILS_SETTINGS."),
+        },
+        outputSchema: {
+            device_id: z.string(),
+            action: z.string(),
+            data_uri: z.string().optional(),
+            success: z.boolean(),
+            message: z.string(),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ device_id, panel, action, data_uri }) => {
+        try {
+            const fullAction = resolveOpenSettingAction({ panel, action });
+            if (data_uri !== undefined)
+                validateSettingsDataUri(data_uri);
+            const { args: deviceArgs, serial } = await resolveDeviceArgs(device_id);
+            const result = await performOpenSetting({
+                action: fullAction,
+                dataUri: data_uri,
+                deviceArgs,
+            });
+            const text = result.success
+                ? `${result.message} (${fullAction}) on ${serial}.`
+                : `${result.message} (${fullAction} on ${serial})\n\n${result.raw}`;
+            return {
+                content: [{ type: "text", text }],
+                structuredContent: {
+                    device_id: serial,
+                    action: fullAction,
+                    data_uri,
+                    success: result.success,
+                    message: text,
+                },
+                isError: !result.success,
+            };
+        }
+        catch (err) {
+            return toolErrorFrom(err);
+        }
+    });
+}
+//# sourceMappingURL=open-setting.js.map

package/dist/tools/open-setting.js.map

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

package/dist/tools/read-logs.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerReadLogs(server: McpServer): void;

package/dist/tools/read-logs.js

@@ -0,0 +1,147 @@
+import { z } from "zod";
+import { runAdb } from "../adb.js";
+import { resolveDeviceArgs } from "../devices.js";
+import { FlingError } from "../errors.js";
+import { deviceIdInput } from "../schemas.js";
+import { toolErrorFrom } from "../toolResult.js";
+const LOGCAT_TIMEOUT_MS = 30_000;
+const LOGCAT_BUFFER_BYTES = 20 * 1024 * 1024;
+const PACKAGE_RE = /^[A-Za-z][\w]*(\.[A-Za-z][\w]*)+$/;
+const TAG_RE = /^[A-Za-z0-9_.+\-]+$/;
+function validatePackage(name) {
+    if (!PACKAGE_RE.test(name)) {
+        throw new FlingError("INVALID_INPUT", `Invalid Android package name: "${name}".`);
+    }
+}
+function validateTag(tag) {
+    if (!TAG_RE.test(tag)) {
+        throw new FlingError("INVALID_INPUT", `Invalid logcat tag: "${tag}". Allowed: letters, digits, underscore, dot, plus, hyphen.`);
+    }
+}
+/**
+ * Resolve PIDs for a package via the device shell.
+ *
+ * Uses `pidof` (toybox, Android 6+/API 23+). On older devices pidof is
+ * absent and this returns []; callers will treat that as "app not running"
+ * which can be a false negative on pre-API-23 hardware.
+ */
+async function resolvePids(deviceArgs, packageName) {
+    const { stdout } = await runAdb([...deviceArgs, "shell", `pidof ${packageName} 2>/dev/null || true`], { timeoutMs: 10_000 });
+    return stdout.trim().split(/\s+/).filter(Boolean);
+}
+export function registerReadLogs(server) {
+    server.registerTool("read_logs", {
+        title: "Read recent device logs",
+        description: "Dump the last N lines of `adb logcat`, optionally filtered by app package (via PID), " +
+            "by logcat tag, or by minimum priority. Returns a single snapshot — does not stream.",
+        inputSchema: {
+            package_name: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Filter to logs from this app's process(es). Resolved via `pidof` on the device. " +
+                "Returns an empty result with success=false if the app isn't currently running."),
+            tag: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Restrict to entries with this logcat tag."),
+            priority: z
+                .enum(["V", "D", "I", "W", "E", "F"])
+                .optional()
+                .describe("Minimum log priority (V=verbose, D=debug, I=info, W=warn, E=error, F=fatal). Default V."),
+            lines: z
+                .number()
+                .int()
+                .min(1)
+                .max(5000)
+                .optional()
+                .describe("Number of trailing lines to return. Default 200, max 5000."),
+            device_id: deviceIdInput,
+        },
+        outputSchema: {
+            device_id: z.string(),
+            package_name: z.string().optional(),
+            pids: z.array(z.string()).optional(),
+            lines_returned: z.number().int().nonnegative(),
+            logs: z.string(),
+        },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ package_name, tag, priority, lines, device_id }) => {
+        try {
+            if (package_name)
+                validatePackage(package_name);
+            if (tag)
+                validateTag(tag);
+            const { args: deviceArgs, serial } = await resolveDeviceArgs(device_id);
+            const lineCount = lines ?? 200;
+            let pids;
+            if (package_name) {
+                pids = await resolvePids(deviceArgs, package_name);
+                if (pids.length === 0) {
+                    const text = `${package_name} is not running on ${serial} — no logs to read.`;
+                    return {
+                        content: [{ type: "text", text }],
+                        structuredContent: {
+                            device_id: serial,
+                            package_name,
+                            pids: [],
+                            lines_returned: 0,
+                            logs: "",
+                        },
+                    };
+                }
+            }
+            // `-t N` implies a snapshot of the last N lines (it's a superset of `-d`).
+            // Passing both is redundant and adb already caps output at N, so
+            // truncation is not observable from this side.
+            // `--pid=` accepts a comma-separated list on API 28+. On older devices
+            // multi-PID filtering may be ignored; most apps run as a single process.
+            const logcatArgs = ["logcat", "-t", String(lineCount), "-v", "threadtime"];
+            if (pids && pids.length > 0) {
+                logcatArgs.push(`--pid=${pids.join(",")}`);
+            }
+            if (tag) {
+                logcatArgs.push(`${tag}:${priority ?? "V"}`, "*:S");
+            }
+            else if (priority) {
+                logcatArgs.push(`*:${priority}`);
+            }
+            const { stdout } = await runAdb([...deviceArgs, ...logcatArgs], {
+                timeoutMs: LOGCAT_TIMEOUT_MS,
+                maxBufferBytes: LOGCAT_BUFFER_BYTES,
+            });
+            const trimmed = stdout.replace(/\r?\n$/, "");
+            const linesReturned = trimmed.length === 0 ? 0 : trimmed.split(/\r?\n/).length;
+            const header = [
+                `Device: ${serial}`,
+                package_name ? `Package: ${package_name} (PIDs: ${pids.join(", ")})` : null,
+                tag ? `Tag: ${tag}` : null,
+                priority ? `Priority: ≥ ${priority}` : null,
+                `Lines: ${linesReturned}`,
+            ]
+                .filter(Boolean)
+                .join("  ·  ");
+            const text = linesReturned > 0
+                ? `${header}\n\n${trimmed}`
+                : `${header}\n\n(no matching log entries)`;
+            return {
+                content: [{ type: "text", text }],
+                structuredContent: {
+                    device_id: serial,
+                    package_name,
+                    pids,
+                    lines_returned: linesReturned,
+                    logs: trimmed,
+                },
+            };
+        }
+        catch (err) {
+            return toolErrorFrom(err);
+        }
+    });
+}
+//# sourceMappingURL=read-logs.js.map

package/dist/tools/read-logs.js.map

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

package/dist/tools/screenshot-with-ui.d.ts

@@ -0,0 +1,21 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { UiNode } from "../uiDump.js";
+export interface ScreenshotWithUiInput {
+    screenshotFn: () => Promise<Buffer>;
+    dumpFn: () => Promise<UiNode[]>;
+}
+export interface ScreenshotWithUiResult {
+    bytes: number;
+    nodes: UiNode[];
+    node_count: number;
+    png_base64: string;
+}
+/**
+ * Capture the screen PNG and the parsed UI hierarchy from the same moment,
+ * in parallel. Halves the round-trips when a caller needs both visual and
+ * semantic data. The two captures are issued concurrently but aren't truly
+ * atomic — they may be a few ms apart, which is much tighter than two
+ * separate MCP calls would produce.
+ */
+export declare function captureScreenshotWithUi(input: ScreenshotWithUiInput): Promise<ScreenshotWithUiResult>;
+export declare function registerScreenshotWithUi(server: McpServer): void;

package/dist/tools/screenshot-with-ui.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { fetchScreenshotPng } from "./screenshot.js";
+import { fetchUiDump } from "../uiDump.js";
+import { resolveDeviceArgs } from "../devices.js";
+import { deviceIdInput } from "../schemas.js";
+import { toolErrorFrom } from "../toolResult.js";
+/**
+ * Capture the screen PNG and the parsed UI hierarchy from the same moment,
+ * in parallel. Halves the round-trips when a caller needs both visual and
+ * semantic data. The two captures are issued concurrently but aren't truly
+ * atomic — they may be a few ms apart, which is much tighter than two
+ * separate MCP calls would produce.
+ */
+export async function captureScreenshotWithUi(input) {
+    const [png, nodes] = await Promise.all([input.screenshotFn(), input.dumpFn()]);
+    return {
+        bytes: png.length,
+        nodes,
+        node_count: nodes.length,
+        png_base64: png.toString("base64"),
+    };
+}
+export function registerScreenshotWithUi(server) {
+    server.registerTool("screenshot_with_ui", {
+        title: "Capture screenshot and UI hierarchy together",
+        description: "Returns the PNG and the parsed interactive UI nodes from the " +
+            "same moment, in a single MCP call. Prefer over separate " +
+            "screenshot + dump_ui when you need both visual and semantic data.",
+        inputSchema: {
+            device_id: deviceIdInput,
+        },
+        outputSchema: {
+            device_id: z.string(),
+            bytes: z.number().int().nonnegative(),
+            node_count: z.number().int().nonnegative(),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async ({ device_id }) => {
+        try {
+            const { args: deviceArgs, serial } = await resolveDeviceArgs(device_id);
+            const result = await captureScreenshotWithUi({
+                screenshotFn: () => fetchScreenshotPng(deviceArgs),
+                dumpFn: async () => (await fetchUiDump(deviceArgs)).nodes,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Captured ${result.bytes.toLocaleString()} bytes and ${result.node_count} UI node(s) from ${serial}.`,
+                    },
+                    {
+                        type: "image",
+                        data: result.png_base64,
+                        mimeType: "image/png",
+                    },
+                ],
+                structuredContent: {
+                    device_id: serial,
+                    bytes: result.bytes,
+                    node_count: result.node_count,
+                },
+            };
+        }
+        catch (err) {
+            return toolErrorFrom(err);
+        }
+    });
+}
+//# sourceMappingURL=screenshot-with-ui.js.map

package/dist/tools/screenshot-with-ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenshot-with-ui.js","sourceRoot":"","sources":["../../src/tools/screenshot-with-ui.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAejD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,KAA4B;IAE5B,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,YAAY,EAAE,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAC/E,OAAO;QACL,KAAK,EAAE,GAAG,CAAC,MAAM;QACjB,KAAK;QACL,UAAU,EAAE,KAAK,CAAC,MAAM;QACxB,UAAU,EAAE,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC;KACnC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,MAAiB;IACxD,MAAM,CAAC,YAAY,CACjB,oBAAoB,EACpB;QACE,KAAK,EAAE,8CAA8C;QACrD,WAAW,EACT,+DAA+D;YAC/D,0DAA0D;YAC1D,mEAAmE;QACrE,WAAW,EAAE;YACX,SAAS,EAAE,aAAa;SACzB;QACD,YAAY,EAAE;YACZ,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;YACrB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;YACrC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;SAC3C;QACD,WAAW,EAAE;YACX,YAAY,EAAE,IAAI;YAClB,eAAe,EAAE,KAAK;YACtB,cAAc,EAAE,KAAK;YACrB,aAAa,EAAE,KAAK;SACrB;KACF,EACD,KAAK,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE;QACtB,IAAI,CAAC;YACH,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,iBAAiB,CAAC,SAAS,CAAC,CAAC;YACxE,MAAM,MAAM,GAAG,MAAM,uBAAuB,CAAC;gBAC3C,YAAY,EAAE,GAAG,EAAE,CAAC,kBAAkB,CAAC,UAAU,CAAC;gBAClD,MAAM,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,WAAW,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK;aAC1D,CAAC,CAAC;YACH,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,YAAY,MAAM,CAAC,KAAK,CAAC,cAAc,EAAE,cAAc,MAAM,CAAC,UAAU,oBAAoB,MAAM,GAAG;qBAC5G;oBACD;wBACE,IAAI,EAAE,OAAgB;wBACtB,IAAI,EAAE,MAAM,CAAC,UAAU;wBACvB,QAAQ,EAAE,WAAW;qBACtB;iBACF;gBACD,iBAAiB,EAAE;oBACjB,SAAS,EAAE,MAAM;oBACjB,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,UAAU,EAAE,MAAM,CAAC,UAAU;iBAC9B;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,aAAa,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/screenshot.d.ts

@@ -0,0 +1,8 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Capture the device screen as a PNG buffer via `adb exec-out screencap -p`.
+ * Validates the result starts with a PNG signature. Used by both the
+ * standalone screenshot tool and the screenshot_with_ui composite.
+ */
+export declare function fetchScreenshotPng(deviceArgs: string[]): Promise<Buffer>;
+export declare function registerScreenshot(server: McpServer): void;

package/dist/tools/screenshot.js

@@ -0,0 +1,97 @@
+import { writeFile } from "node:fs/promises";
+import { resolve as resolvePath, sep } from "node:path";
+import { z } from "zod";
+import { runAdbBinary } from "../adb.js";
+import { resolveDeviceArgs } from "../devices.js";
+import { FlingError } from "../errors.js";
+import { deviceIdInput } from "../schemas.js";
+import { toolErrorFrom } from "../toolResult.js";
+const SCREENSHOT_TIMEOUT_MS = 30_000;
+const SCREENSHOT_MAX_BYTES = 30 * 1024 * 1024;
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+function looksLikePng(buf) {
+    return buf.length >= 8 && buf.subarray(0, 8).equals(PNG_SIGNATURE);
+}
+/**
+ * Capture the device screen as a PNG buffer via `adb exec-out screencap -p`.
+ * Validates the result starts with a PNG signature. Used by both the
+ * standalone screenshot tool and the screenshot_with_ui composite.
+ */
+export async function fetchScreenshotPng(deviceArgs) {
+    const { stdout } = await runAdbBinary([...deviceArgs, "exec-out", "screencap", "-p"], { timeoutMs: SCREENSHOT_TIMEOUT_MS, maxBufferBytes: SCREENSHOT_MAX_BYTES });
+    if (!looksLikePng(stdout)) {
+        throw new FlingError("ADB_FAILED", "screencap output did not start with a PNG signature. " +
+            "This usually means the device returned an error or the binary stream was corrupted.");
+    }
+    return stdout;
+}
+export function registerScreenshot(server) {
+    server.registerTool("screenshot", {
+        title: "Capture a screenshot",
+        description: "Grab the device's current screen as a PNG via `adb exec-out screencap -p`. " +
+            "Returns the image inline as MCP image content. Pass `save_to` to also write " +
+            "the PNG to disk on the host. When you also need parsed UI nodes from the same " +
+            "moment, prefer `screenshot_with_ui` (halves the round-trips).",
+        inputSchema: {
+            device_id: deviceIdInput,
+            save_to: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Optional host path to also save the PNG (relative to MCP server cwd)."),
+        },
+        outputSchema: {
+            device_id: z.string(),
+            bytes: z.number().int().positive(),
+            saved_to: z.string().optional(),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async ({ device_id, save_to }) => {
+        try {
+            const { args: deviceArgs, serial } = await resolveDeviceArgs(device_id);
+            const stdout = await fetchScreenshotPng(deviceArgs);
+            let savedTo;
+            if (save_to) {
+                // Constrain save_to to the server's cwd to prevent path-traversal
+                // primitives. A malicious or compromised assistant could otherwise
+                // pass `../../.ssh/authorized_keys` and overwrite arbitrary files.
+                // Users who genuinely want to write elsewhere can run the MCP server
+                // from that directory.
+                const cwd = process.cwd();
+                const resolved = resolvePath(cwd, save_to);
+                const cwdWithSep = cwd.endsWith(sep) ? cwd : cwd + sep;
+                if (resolved !== cwd && !resolved.startsWith(cwdWithSep)) {
+                    throw new FlingError("INVALID_INPUT", `save_to "${save_to}" resolves to ${resolved}, which is outside the server's cwd (${cwd}).`);
+                }
+                savedTo = resolved;
+                await writeFile(savedTo, stdout);
+            }
+            const base64 = stdout.toString("base64");
+            const summaryLines = [
+                `Captured ${stdout.length.toLocaleString()} bytes from ${serial}.`,
+            ];
+            if (savedTo)
+                summaryLines.push(`Saved to ${savedTo}.`);
+            return {
+                content: [
+                    { type: "text", text: summaryLines.join("\n") },
+                    { type: "image", data: base64, mimeType: "image/png" },
+                ],
+                structuredContent: {
+                    device_id: serial,
+                    bytes: stdout.length,
+                    saved_to: savedTo,
+                },
+            };
+        }
+        catch (err) {
+            return toolErrorFrom(err);
+        }
+    });
+}
+//# sourceMappingURL=screenshot.js.map

package/dist/tools/screenshot.js.map

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