@slack/radar-mcp 1.11.0 → 1.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/README.md +12 -2
  2. package/dist/mcp/api-paths.js +2 -0
  3. package/dist/mcp/flags-tools.d.ts +71 -0
  4. package/dist/mcp/flags-tools.js +158 -0
  5. package/dist/mcp/index.js +103 -5
  6. package/dist/mcp/prefs-tools.d.ts +15 -0
  7. package/dist/mcp/prefs-tools.js +204 -0
  8. package/dist/mcp/session-enable.d.ts +2 -1
  9. package/dist/mcp/session-enable.js +29 -2
  10. package/dist/mcp/snapshot.js +6 -1
  11. package/dist/mcp/sources-gate.d.ts +23 -0
  12. package/dist/mcp/sources-gate.js +63 -0
  13. package/dist/mcp/tools.js +102 -2
  14. package/dist/shared/android.d.ts +33 -1
  15. package/dist/shared/android.js +203 -6
  16. package/dist/shared/constants.d.ts +8 -0
  17. package/dist/shared/constants.js +13 -1
  18. package/dist/shared/db.d.ts +21 -3
  19. package/dist/shared/db.js +89 -23
  20. package/dist/shared/feature-flags.d.ts +6 -0
  21. package/dist/shared/feature-flags.js +17 -0
  22. package/dist/shared/prefs.d.ts +78 -0
  23. package/dist/shared/prefs.js +416 -0
  24. package/dist/shared/transport.d.ts +68 -0
  25. package/dist/web/log-session.d.ts +13 -0
  26. package/dist/web/log-session.js +16 -0
  27. package/dist/web/public/index.html +129 -3
  28. package/dist/web/public/next/app.js +82 -4
  29. package/dist/web/public/next/feed.js +270 -14
  30. package/dist/web/public/next/filter.js +200 -0
  31. package/dist/web/public/next/flags.js +179 -0
  32. package/dist/web/public/next/prefs.js +399 -0
  33. package/dist/web/public/next/registry.js +16 -6
  34. package/dist/web/public/next/store.js +250 -11
  35. package/dist/web/server.js +267 -7
  36. package/dist/web/spec.d.ts +7 -7
  37. package/dist/web/spec.js +15 -9
  38. package/package.json +1 -1
@@ -0,0 +1,204 @@
1
+ /**
2
+ * Handler dispatch for the three prefs tools: list_prefs, get_prefs, search_prefs.
3
+ */
4
+ import { listPrefsFiles, readPrefsFile, parsePrefsXml, searchPrefs, } from "../shared/prefs.js";
5
+ import { resolveAdbPath } from "../shared/android.js";
6
+ import { availableUsers } from "../shared/db.js";
7
+ import { MAX_PREFS_RESPONSE_BYTES } from "../shared/constants.js";
8
+ /**
9
+ * Bound entries to the 64KB response budget with a single forward pass (the db-tools
10
+ * capQueryRows shape, see db-tools.ts:55-88, reimplemented here for the prefs entry type).
11
+ * Sizes against the WORST-CASE envelope (both truncation flags + the longest note text) so
12
+ * the fixed fields around `entries` never eat into a budget calculated for the untruncated
13
+ * case, which would either overrun MAX_PREFS_RESPONSE_BYTES or (the original bug) silently drop
14
+ * entries without setting response_truncated. Returns the entries to actually return, whether
15
+ * the cap tripped, and the keys of any entries dropped for being individually oversized (a
16
+ * single entry bigger than the WHOLE budget, e.g. one huge JSON-blob value) so the caller can
17
+ * name them rather than silently returning zero entries with no way to retrieve that key even
18
+ * via the `keys` filter, since `keys` filters BEFORE this cap runs.
19
+ */
20
+ function capPrefsEntries(entries, file, user) {
21
+ const overhead = JSON.stringify({
22
+ file,
23
+ user,
24
+ entries: [],
25
+ total_entries: entries.length,
26
+ returned_entries: 0,
27
+ device_read_truncated: true,
28
+ response_truncated: true,
29
+ note: "Device file exceeded 256KB and was truncated. Response truncated to 64KB. Use keys parameter to filter to specific entries or search_prefs to find what you need.",
30
+ dropped_keys: entries.map((e) => e.key),
31
+ privacy_note: "Preference values can include user, team, and org identifiers; review before sharing.",
32
+ }).length;
33
+ const entryBudget = MAX_PREFS_RESPONSE_BYTES - overhead;
34
+ const kept = [];
35
+ const droppedKeys = [];
36
+ let bytes = 0;
37
+ for (const entry of entries) {
38
+ // +1 for the joining comma between array elements.
39
+ const sz = Buffer.byteLength(JSON.stringify(entry), "utf8") + 1;
40
+ if (bytes + sz > entryBudget) {
41
+ // A single entry bigger than the WHOLE remaining budget can never fit by itself either
42
+ // (the budget only shrinks as more is kept, never grows), so record it as dropped and
43
+ // keep scanning for smaller entries that still fit, rather than stopping at the first
44
+ // oversized one. This is what makes an oversized key nameable instead of silently
45
+ // vanishing: `keys` filters before this cap runs, so without this the caller has no way
46
+ // to ever retrieve that key, even by asking for it directly.
47
+ if (sz > entryBudget)
48
+ droppedKeys.push(entry.key);
49
+ continue;
50
+ }
51
+ kept.push(entry);
52
+ bytes += sz;
53
+ }
54
+ return { entries: kept, truncated: kept.length < entries.length, droppedKeys };
55
+ }
56
+ export async function handleListPrefs(user) {
57
+ const adbPath = resolveAdbPath();
58
+ if (!adbPath) {
59
+ return {
60
+ data: {
61
+ error: "adb not found. Set ANDROID_HOME or install Android SDK platform-tools.",
62
+ },
63
+ isError: true,
64
+ };
65
+ }
66
+ try {
67
+ const result = listPrefsFiles(adbPath, user);
68
+ if (!result) {
69
+ const available = availableUsers();
70
+ return {
71
+ data: {
72
+ error: `Failed to list prefs files for user ${user ?? "(any)"}. Is the debug build installed and is a device connected? Available users: ${available.join(", ")}`,
73
+ },
74
+ isError: true,
75
+ };
76
+ }
77
+ return {
78
+ data: {
79
+ user: result.user,
80
+ available_users: availableUsers(),
81
+ files: result.files,
82
+ privacy_note: "Preference values can include user, team, and org identifiers; review before sharing.",
83
+ },
84
+ isError: false,
85
+ };
86
+ }
87
+ catch (e) {
88
+ return {
89
+ data: { error: e instanceof Error ? e.message : String(e) },
90
+ isError: true,
91
+ };
92
+ }
93
+ }
94
+ export async function handleGetPrefs(file, user, keys) {
95
+ if (!file) {
96
+ return {
97
+ data: { error: "file parameter is required" },
98
+ isError: true,
99
+ };
100
+ }
101
+ const adbPath = resolveAdbPath();
102
+ if (!adbPath) {
103
+ return {
104
+ data: {
105
+ error: "adb not found. Set ANDROID_HOME or install Android SDK platform-tools.",
106
+ },
107
+ isError: true,
108
+ };
109
+ }
110
+ try {
111
+ const readResult = await readPrefsFile(adbPath, file, user);
112
+ if ("error" in readResult) {
113
+ return {
114
+ data: { error: readResult.error },
115
+ isError: true,
116
+ };
117
+ }
118
+ const parseResult = parsePrefsXml(readResult.xml);
119
+ if ("parseError" in parseResult) {
120
+ return {
121
+ data: { error: parseResult.parseError },
122
+ isError: true,
123
+ };
124
+ }
125
+ let entries = parseResult.entries;
126
+ // Filter to specified keys if provided.
127
+ if (keys && keys.length > 0) {
128
+ const keySet = new Set(keys);
129
+ entries = entries.filter((e) => keySet.has(e.key));
130
+ }
131
+ // Total = entries after the keys filter (the set the user actually asked for);
132
+ // returned = what survived the 64KB byte cap below.
133
+ const totalEntries = entries.length;
134
+ const deviceTruncated = !!readResult.truncated;
135
+ const { entries: returnedEntries, truncated: responseTruncated, droppedKeys } = capPrefsEntries(entries, file, readResult.user);
136
+ return {
137
+ data: {
138
+ file,
139
+ user: readResult.user,
140
+ entries: returnedEntries,
141
+ total_entries: totalEntries,
142
+ returned_entries: returnedEntries.length,
143
+ ...(deviceTruncated ? { device_read_truncated: true } : {}),
144
+ ...(responseTruncated ? { response_truncated: true } : {}),
145
+ ...(droppedKeys.length > 0 ? { dropped_keys: droppedKeys } : {}),
146
+ ...(deviceTruncated || responseTruncated
147
+ ? {
148
+ note: `${deviceTruncated ? "Device file exceeded 256KB and was truncated. " : ""}${responseTruncated ? "Response truncated to 64KB. " : ""}${droppedKeys.length > 0 ? `${droppedKeys.length} entries were individually too large to include (see dropped_keys). ` : ""}Use keys parameter to filter to specific entries or search_prefs to find what you need.`,
149
+ }
150
+ : {}),
151
+ privacy_note: "Preference values can include user, team, and org identifiers; review before sharing.",
152
+ },
153
+ isError: false,
154
+ };
155
+ }
156
+ catch (e) {
157
+ return {
158
+ data: { error: e instanceof Error ? e.message : String(e) },
159
+ isError: true,
160
+ };
161
+ }
162
+ }
163
+ export async function handleSearchPrefs(query, user) {
164
+ if (!query) {
165
+ return {
166
+ data: { error: "query parameter is required" },
167
+ isError: true,
168
+ };
169
+ }
170
+ const adbPath = resolveAdbPath();
171
+ if (!adbPath) {
172
+ return {
173
+ data: {
174
+ error: "adb not found. Set ANDROID_HOME or install Android SDK platform-tools.",
175
+ },
176
+ isError: true,
177
+ };
178
+ }
179
+ try {
180
+ const { results, truncated, skipped, user: resolvedUser } = await searchPrefs(adbPath, query, user);
181
+ const response = {
182
+ query,
183
+ user: resolvedUser,
184
+ available_users: availableUsers(),
185
+ results,
186
+ };
187
+ if (truncated)
188
+ response.truncated = true;
189
+ if (skipped && skipped.length > 0)
190
+ response.skipped = skipped;
191
+ response.privacy_note =
192
+ "Preference values can include user, team, and org identifiers; review before sharing.";
193
+ return {
194
+ data: response,
195
+ isError: false,
196
+ };
197
+ }
198
+ catch (e) {
199
+ return {
200
+ data: { error: e instanceof Error ? e.message : String(e) },
201
+ isError: true,
202
+ };
203
+ }
204
+ }
@@ -9,9 +9,10 @@ export interface EnableDeps {
9
9
  runBackfill: () => Promise<unknown>;
10
10
  ping: () => Promise<Record<string, unknown>>;
11
11
  sleep: (ms: number) => Promise<void>;
12
+ onDeviceSwitch: () => void;
12
13
  }
13
14
  export interface EnableOutcome {
14
15
  body: Record<string, unknown>;
15
16
  enabled: boolean;
16
17
  }
17
- export declare function runSessionEnable(timeoutMinutes: number, deps: EnableDeps): Promise<EnableOutcome>;
18
+ export declare function runSessionEnable(timeoutMinutes: number, deviceSerial: string | null, deps: EnableDeps): Promise<EnableOutcome>;
@@ -2,8 +2,8 @@
2
2
  // this is the whole latency of a normal enable), then two patient retries to
3
3
  // absorb real server startup.
4
4
  const PING_WAITS_MS = [500, 1000, 1000];
5
- export async function runSessionEnable(timeoutMinutes, deps) {
6
- const { device, destroyStream, connectStream, isStreamConnected, resetDbState, startSpool, runBackfill, ping, sleep, } = deps;
5
+ export async function runSessionEnable(timeoutMinutes, deviceSerial, deps) {
6
+ const { device, destroyStream, connectStream, isStreamConnected, resetDbState, startSpool, runBackfill, ping, sleep, onDeviceSwitch, } = deps;
7
7
  // Tear down the old stream (and its reconnect loop) FIRST, then drop all cached
8
8
  // transport state so this enable starts clean. Without the reset, a stale adb
9
9
  // forward (device end dead after an idle timeout or a replug) makes ensureForward()
@@ -15,6 +15,29 @@ export async function runSessionEnable(timeoutMinutes, deps) {
15
15
  // A re-enable may be a different device or a re-armed profile, so drop the cached DB
16
16
  // user set + sqlite path; the next DB tool call re-detects the profiles fresh.
17
17
  resetDbState();
18
+ // Pin which device this session targets BEFORE any adb call. selectDevice sets
19
+ // process.env.ANDROID_SERIAL once; every later adb call site inherits it. An ambiguous
20
+ // choice (multiple devices, no serial) or an unattached explicit serial short-circuits
21
+ // here with the device list, before ensureForward touches the wrong device.
22
+ const selection = device.selectDevice?.(deviceSerial);
23
+ if (selection && !selection.ok) {
24
+ return {
25
+ enabled: false,
26
+ body: {
27
+ // The transport error is a neutral core; the MCP body appends agent-facing retry guidance.
28
+ error: `${selection.error} Retry _radar_session_enable with device_serial set to one of them. If you cannot tell which device the user wants, ask them before retrying.`,
29
+ devices: selection.devices,
30
+ enabled: false,
31
+ platform: device.platform,
32
+ },
33
+ };
34
+ }
35
+ // A switch to a different device makes the prior session's device-scoped state
36
+ // (buffers, spool, capture, pulled DBs) belong to the wrong hardware, so reset it
37
+ // before forwarding. A same-device re-enable skips this: spool continuity is intended.
38
+ if (selection && selection.ok && selection.switched) {
39
+ onDeviceSwitch();
40
+ }
18
41
  if (!device.ensureForward()) {
19
42
  const reason = device.getLastForwardError?.() ?? null;
20
43
  return {
@@ -83,12 +106,16 @@ export async function runSessionEnable(timeoutMinutes, deps) {
83
106
  },
84
107
  };
85
108
  }
109
+ const selected = device.getSelectedDevice?.() ?? null;
86
110
  return {
87
111
  enabled: true,
88
112
  body: {
89
113
  enabled: true,
90
114
  platform: device.platform,
91
115
  stream_connected: isStreamConnected(),
116
+ ...(selected
117
+ ? { device_serial: selected.serial, device_label: selected.label }
118
+ : {}),
92
119
  // The broadcast failed but the server answered (armed by a prior session).
93
120
  // activate()'s success branch never ran, so the logcat capture is not
94
121
  // armed: get_recent_logs degrades to the device ring for this session.
@@ -2,6 +2,7 @@ import { spawnSync } from "child_process";
2
2
  import fs from "fs";
3
3
  import os from "os";
4
4
  import path from "path";
5
+ import { RADAR_VERSION } from "../shared/constants.js";
5
6
  import { getCaptureFilePath, readTailBytes } from "../shared/logcat-capture.js";
6
7
  /**
7
8
  * `capture_snapshot` composer: bundles everything Radar has seen into a
@@ -34,6 +35,7 @@ This directory is a point-in-time bundle of Radar state.
34
35
 
35
36
  Files:
36
37
  - bundle.json: device-side network/RTM/clog/trace buffers, counts, and metadata.
38
+ Its mcp_version field records which @slack/radar-mcp produced this bundle.
37
39
  - logcat.tail.log (optional): last N lines of the on-device logcat capture.
38
40
  - screenshot.png (optional): current screen.
39
41
 
@@ -241,7 +243,10 @@ export async function createSnapshot(device, fetchBuffer, opts = {}, now = Date.
241
243
  screenshot: screenshotCaptured,
242
244
  };
243
245
  const bundle = {
244
- version: 2,
246
+ // Format version of this bundle's schema — not the Radar version, which
247
+ // is mcp_version below. Named to keep the two unmistakable in a shared file.
248
+ bundle_format_version: 2,
249
+ mcp_version: RADAR_VERSION,
245
250
  timestamp: now,
246
251
  platform: device.platform,
247
252
  active_user_id: device.getActiveUserId(),
@@ -0,0 +1,23 @@
1
+ export interface DeviceSource {
2
+ name: string;
3
+ kind: string;
4
+ revision: number;
5
+ }
6
+ export declare const TOOL_SOURCE: Record<string, string>;
7
+ /** Cache the `sources` array from an enable ping body. Ignores bodies without one. */
8
+ export declare function recordSources(pingBody: Record<string, unknown>): void;
9
+ /** Drop the cached list (session disable or device switch). */
10
+ export declare function clearSources(): void;
11
+ /** Apply an enable outcome: a successful enable's body carries the ping fields (and on seam
12
+ * builds the sources); a failed enable leaves the gate off. */
13
+ export declare function applyEnableOutcome(outcome: {
14
+ enabled: boolean;
15
+ body: Record<string, unknown>;
16
+ }): void;
17
+ /** The cached device sources, or null when the build reported none. */
18
+ export declare function getSources(): DeviceSource[] | null;
19
+ /**
20
+ * Blocks a tool whose source the device declared absent. Returns the error body, or null when
21
+ * the tool is allowed (unmapped tool, source present, or no discovery info to gate on).
22
+ */
23
+ export declare function sourceGate(toolName: string): Record<string, unknown> | null;
@@ -0,0 +1,63 @@
1
+ // Source discovery gate. Devices with the plugin seam (slack-android-ng #123402) report a
2
+ // `sources` array on ping: [{name, kind, revision}] for every capture source the build serves.
3
+ // This module caches that list per session and blocks tools whose source the device declared
4
+ // absent, turning a raw route 404 into one uniform, actionable error.
5
+ //
6
+ // Only sources that ship as plugins on the device are gateable. Sources still hardcoded in the
7
+ // device core (network/rtm/clog) are absent from `sources` on every build today, so their tools
8
+ // must pass through; each entry joins GATEABLE_SOURCES when its device-side migration lands.
9
+ // A build that predates the seam sends no `sources` at all, which disables gating entirely.
10
+ // Tool name -> the ping `sources` name that must be present for the tool to work. Every key
11
+ // must name a real tool in TOOL_DEFINITIONS (pinned by test).
12
+ export const TOOL_SOURCE = {
13
+ get_recent_traces: "traces",
14
+ get_trace_detail: "traces",
15
+ list_feature_flags: "feature_flags",
16
+ search_feature_flags: "feature_flags",
17
+ get_feature_flag: "feature_flags",
18
+ };
19
+ // null = no discovery info (old build or no session); gating is off.
20
+ let sessionSources = null;
21
+ /** Cache the `sources` array from an enable ping body. Ignores bodies without one. */
22
+ export function recordSources(pingBody) {
23
+ const raw = pingBody["sources"];
24
+ if (!Array.isArray(raw)) {
25
+ sessionSources = null;
26
+ return;
27
+ }
28
+ sessionSources = raw.filter((s) => !!s && typeof s === "object" && typeof s.name === "string");
29
+ }
30
+ /** Drop the cached list (session disable or device switch). */
31
+ export function clearSources() {
32
+ sessionSources = null;
33
+ }
34
+ /** Apply an enable outcome: a successful enable's body carries the ping fields (and on seam
35
+ * builds the sources); a failed enable leaves the gate off. */
36
+ export function applyEnableOutcome(outcome) {
37
+ if (outcome.enabled)
38
+ recordSources(outcome.body);
39
+ else
40
+ clearSources();
41
+ }
42
+ /** The cached device sources, or null when the build reported none. */
43
+ export function getSources() {
44
+ return sessionSources;
45
+ }
46
+ /**
47
+ * Blocks a tool whose source the device declared absent. Returns the error body, or null when
48
+ * the tool is allowed (unmapped tool, source present, or no discovery info to gate on).
49
+ */
50
+ export function sourceGate(toolName) {
51
+ if (sessionSources === null)
52
+ return null;
53
+ const required = TOOL_SOURCE[toolName];
54
+ if (!required)
55
+ return null;
56
+ if (sessionSources.some((s) => s.name === required))
57
+ return null;
58
+ return {
59
+ error: `This debug build does not serve ${required}. Update the app to a build with the ${required} Radar plugin, or re-run _radar_session_enable if the device or build changed since the session started.`,
60
+ missing_source: required,
61
+ available_sources: sessionSources.map((s) => s.name),
62
+ };
63
+ }
package/dist/mcp/tools.js CHANGED
@@ -25,6 +25,9 @@ export const SERVER_INSTRUCTIONS = [
25
25
  '- "did I get X" / "did X happen" -> search(query="X") across ALL buffers, not just one',
26
26
  '- "everything since I enabled" / "the whole session" / "what did I miss" -> query_session',
27
27
  '- "check the debug logs" -> get_recent_logs (tag is OPTIONAL: pass tag="FKDebug" to filter, or omit it for all recent lines)',
28
+ '- "is flag X on?" / "what is the effective value of X" / "what feature flags does the app have" -> get_feature_flag(key="X") / search_feature_flags(query="X") / list_feature_flags. This is the LIVE effective state (override if set, else server value), requires a debug build with the feature-flag Radar plugin.',
29
+ '- "what feature-flag overrides are set?" / "check debug_features" -> search_prefs(query="X") or get_prefs(file="debug_features_...xml"). This shows MANUAL OVERRIDES only, not effective flag state: debug_features_*.xml holds only flags the debug menu overrode, and an override is deleted once it matches the server value. A flag missing from this file can still be ON server-side -- absence means "no override," never "disabled." Prefer get_feature_flag/list_feature_flags/search_feature_flags for the actual live value; use this route only when the manual-override history itself is what is being asked about.',
30
+ '- "what did the app remember" / "what is cached in prefs" / "what team_prefs are set" -> list_prefs then get_prefs',
28
31
  '- "save this" / "file this as a bug" / "share this" / "bundle this" / "attach to ticket" / "give me a repro" / "snapshot this" / "preserve this" / "hold this state" / "save what you just saw" -> capture_snapshot',
29
32
  "",
30
33
  "Key behaviors:",
@@ -38,10 +41,17 @@ export const SERVER_INSTRUCTIONS = [
38
41
  " build can run on more than one user (personal=0, plus a work profile or secondary user),",
39
42
  " and only the first to bind the socket wins. If events seem to come from the wrong app, tell",
40
43
  " the user which profile is bound and use list_profiles + activate_for_user to switch.",
44
+ "- MULTIPLE DEVICES: with more than one device attached, enable fails and returns the list of",
45
+ " attached serials. Retry _radar_session_enable with device_serial set to one of them. When the",
46
+ " intent is unclear (you cannot tell which device the user means), ask which device before retrying;",
47
+ " do not guess. The enable success response names the bound device via device_label, so confirm it",
48
+ " matches what the user expected. The picked device applies to every tool for the whole session. Do",
49
+ " not confuse this with profiles: profiles are separate users on ONE device (personal vs work), while",
50
+ " devices are separate hardware.",
41
51
  "- Screenshots default to 720px. Use full_res=true only when detail matters.",
42
52
  "- Setup: /slack-radar-setup",
43
53
  "- Manual enable (no skill): adb shell am broadcast -a slack.debug.ENABLE_RADAR --ei timeout_minutes 5 -p com.Slack.internal.debug",
44
- " Then: adb forward tcp:8099 localabstract:slack-radar",
54
+ " Then: adb forward tcp:8099 localabstract:slack-radar (prefix adb -s <serial> when multiple devices are attached)",
45
55
  "",
46
56
  "WEB DASHBOARD (/radar-ui):",
47
57
  "A browser-based dashboard (http://localhost:8100) shows the same live device data as",
@@ -119,7 +129,7 @@ export const SERVER_INSTRUCTIONS = [
119
129
  export const TOOL_DEFINITIONS = [
120
130
  {
121
131
  name: "ping",
122
- description: "Check if Slack Radar is running. Returns uptime, buffer sizes, remaining session time, stream status, and which app/profile is bound: android_user_id (0 = personal, non-zero = a secondary user such as a work profile), profile ('personal'/'secondary'), and package.",
132
+ description: "Check if Slack Radar is running. Returns uptime, buffer sizes, remaining session time, stream status, the Radar MCP tool version (mcp_version), and which app/profile is bound: android_user_id (0 = personal, non-zero = a secondary user such as a work profile), profile ('personal'/'secondary'), and package.",
123
133
  inputSchema: {
124
134
  type: "object",
125
135
  properties: {
@@ -361,6 +371,10 @@ export const TOOL_DEFINITIONS = [
361
371
  type: "object",
362
372
  properties: {
363
373
  timeout_minutes: { type: "number", description: "Device-side auto-shutdown timeout in minutes (default: 5)" },
374
+ device_serial: {
375
+ type: "string",
376
+ description: "Target device serial from adb devices. Optional; auto-selected when exactly one device is attached. When multiple devices are attached the enable fails with the list; retry with one of the listed serials.",
377
+ },
364
378
  },
365
379
  },
366
380
  annotations: { readOnlyHint: false, idempotentHint: true },
@@ -504,6 +518,92 @@ export const TOOL_DEFINITIONS = [
504
518
  },
505
519
  annotations: { readOnlyHint: true },
506
520
  },
521
+ {
522
+ name: "list_prefs",
523
+ description: "List the app's SharedPreferences XML files (including feature-flag files like debug_features_*.xml, which holds manual overrides, and easy_features_*.xml, the persisted server snapshot), with file sizes and the Android user they were read from.",
524
+ inputSchema: {
525
+ type: "object",
526
+ properties: {
527
+ user: {
528
+ type: "string",
529
+ pattern: "^[0-9]*$",
530
+ description: "Android user ID to read (0=personal, 10+=work profile). If omitted, uses the first available user.",
531
+ },
532
+ },
533
+ },
534
+ annotations: { readOnlyHint: true },
535
+ },
536
+ {
537
+ name: "get_prefs",
538
+ description: "Read a SharedPreferences file, parse it, and return its entries (key, type, value). When keys are provided, filter to those keys only (exact match). Reads the on-disk XML, which can lag the app's live in-memory state by the async-write window, so a value may be slightly stale. debug_features_* holds manual overrides only -- a flag absent there means no override was set, not that the flag is off. easy_features_*/feature_flags_* is the persisted server snapshot, not an override list -- a hit there is the server's value, still subject to the same write-lag caveat.",
539
+ inputSchema: {
540
+ type: "object",
541
+ properties: {
542
+ file: { type: "string", description: "Filename from list_prefs, e.g. 'default_preferences.xml'" },
543
+ user: {
544
+ type: "string",
545
+ pattern: "^[0-9]*$",
546
+ description: "Android user ID (0=personal, 10+=work profile). If omitted, uses the first available user.",
547
+ },
548
+ keys: { type: "array", items: { type: "string" }, description: "If provided, filter results to only these keys (exact match). Omit to return all entries." },
549
+ },
550
+ required: ["file"],
551
+ },
552
+ annotations: { readOnlyHint: true },
553
+ },
554
+ {
555
+ name: "search_prefs",
556
+ description: "Search SharedPreferences across all files for a user. Performs case-insensitive substring search on key names and stringified values. Returns per-file match results. Reads the on-disk XML, which can lag the app's live in-memory state by the async-write window, so a value may be slightly stale. A hit in debug_features_* is a manual override -- no hit means no override, not that the flag is off. A hit in easy_features_*/feature_flags_* is the server's persisted value, not an override.",
557
+ inputSchema: {
558
+ type: "object",
559
+ properties: {
560
+ query: { type: "string", description: "Search substring (case-insensitive)" },
561
+ user: {
562
+ type: "string",
563
+ pattern: "^[0-9]*$",
564
+ description: "Android user ID (0=personal, 10+=work profile). If omitted, uses the first available user.",
565
+ },
566
+ },
567
+ required: ["query"],
568
+ },
569
+ annotations: { readOnlyHint: true },
570
+ },
571
+ {
572
+ name: "list_feature_flags",
573
+ description: "List every feature flag the app knows about right now, with its EFFECTIVE value (local override if set, else the server value) and whether that value is a local override. This is the actual live state the app is using, unlike get_prefs/search_prefs on debug_features_*.xml, which shows only manual overrides. Requires a debug build with the feature-flag Radar plugin; older builds report a clear error instead of the list.",
574
+ inputSchema: {
575
+ type: "object",
576
+ properties: {
577
+ overridden: { type: "boolean", description: "If true, return only flags with a local override active. If false, return only flags with no override (server value in effect). Omit for the complete list." },
578
+ },
579
+ },
580
+ annotations: { readOnlyHint: true },
581
+ },
582
+ {
583
+ name: "search_feature_flags",
584
+ description: "Case-insensitive substring search on feature flag names, against the same live effective-value list as list_feature_flags. Use this instead of search_prefs when you need to know whether a flag is actually ON right now, not just whether it has a manual override.",
585
+ inputSchema: {
586
+ type: "object",
587
+ properties: {
588
+ query: { type: "string", description: "Search substring, matched against the flag key (case-insensitive)." },
589
+ },
590
+ required: ["query"],
591
+ },
592
+ annotations: { readOnlyHint: true },
593
+ },
594
+ {
595
+ name: "get_feature_flag",
596
+ description: "Look up one feature flag by its exact key (case-sensitive) and return its effective value and override status. Always returns rows: an array, since every flag exists in TWO scopes (authenticated = the value for a signed-in user, unauthenticated = the value for a visitor who has not signed in yet) with potentially different values -- rows has one entry when scope is given or when the key has only one scope, two when both scopes exist and no scope was given. Use list_feature_flags or search_feature_flags first if you are not sure of the exact key.",
597
+ inputSchema: {
598
+ type: "object",
599
+ properties: {
600
+ key: { type: "string", description: "Exact flag key, e.g. 'android_some_flag'." },
601
+ scope: { type: "string", description: "Optional. 'authenticated' (signed-in user) or 'unauthenticated' (visitor). Omit to get rows for every scope that exists." },
602
+ },
603
+ required: ["key"],
604
+ },
605
+ annotations: { readOnlyHint: true },
606
+ },
507
607
  ];
508
608
  /**
509
609
  * Check whether a tool call should be blocked by the session gate.
@@ -1,4 +1,4 @@
1
- import type { DeviceTransport, LogResult } from "./transport.js";
1
+ import type { DeviceInfo, DeviceTransport, LogResult } from "./transport.js";
2
2
  /**
3
3
  * Resolve the adb binary. MCP servers spawned from GUI launchers (Spotlight,
4
4
  * Raycast, Dock) do not inherit the user's shell PATH, so a bare `adb` call
@@ -18,6 +18,19 @@ export declare function resolveAdbPath(): string | null;
18
18
  * "10", which is often a work profile, but the id alone cannot prove that).
19
19
  */
20
20
  export declare function parseUserFromPsOutput(psOutput: string): string;
21
+ /**
22
+ * Parse `adb devices -l` output into a list of attached devices. Skips the
23
+ * "List of devices attached" header and the daemon-restart preamble adb sometimes
24
+ * prints ("* daemon not running; starting now at tcp:5037", "* daemon started
25
+ * successfully"). Each real entry is "<serial> <state> [key:value ...]"; the label
26
+ * comes from the model: field with underscores turned to spaces (adb renders spaces
27
+ * in model names as underscores), falling back to the serial when no model is present.
28
+ */
29
+ export declare function parseAdbDevicesOutput(raw: string): {
30
+ serial: string;
31
+ label: string;
32
+ state: string;
33
+ }[];
21
34
  export declare class AndroidTransport implements DeviceTransport {
22
35
  readonly platform = "android";
23
36
  private portForwarded;
@@ -26,7 +39,10 @@ export declare class AndroidTransport implements DeviceTransport {
26
39
  private radarEnabled;
27
40
  private lastForwardError;
28
41
  private lastActivateError;
42
+ private selectedDevice;
29
43
  ensureForward(): boolean;
44
+ private rebuildForward;
45
+ reassertForward(): boolean;
30
46
  getLastForwardError(): string | null;
31
47
  activate(timeoutMinutes: number): void;
32
48
  getLastActivateError(): string | null;
@@ -53,5 +69,21 @@ export declare class AndroidTransport implements DeviceTransport {
53
69
  label: string;
54
70
  }[];
55
71
  activateForUser(userId: string, timeoutMinutes: number): void;
72
+ listDevices(): DeviceInfo[] | null;
73
+ private reconcileSelectedDevice;
74
+ selectDevice(serial: string | null): {
75
+ ok: true;
76
+ serial: string | null;
77
+ switched?: boolean;
78
+ } | {
79
+ ok: false;
80
+ error: string;
81
+ devices: DeviceInfo[];
82
+ };
83
+ getSelectedDevice(): {
84
+ serial: string;
85
+ label: string;
86
+ } | null;
87
+ private pin;
56
88
  private detectDebugBuildUser;
57
89
  }