@slack/radar-mcp 1.3.0 → 1.4.0

package/dist/mcp/tools.js

@@ -1,3 +1,4 @@
+import { SOURCES, VIZ, SERIES_METRICS } from "../web/spec.js";
 export const SERVER_INSTRUCTIONS = [
     "Slack Radar provides on-device debugging tools for the Slack Android app via ADB.",
     "",
@@ -31,24 +32,59 @@ export const SERVER_INSTRUCTIONS = [
     "- RTM event types use subtypes when available (e.g. message_changed, not message).",
     "- Use wait_for_events with idle_timeout_ms instead of polling loops.",
     "- Use ping(timeout_minutes=N) to extend sessions. Monitor remaining_minutes proactively.",
+    "- ping reports which app/profile is bound (android_user_id, profile, package). The debug",
+    "  build can run on more than one user (personal=0, plus a work profile or secondary user),",
+    "  and only the first to bind the socket wins. If events seem to come from the wrong app, tell",
+    "  the user which profile is bound and use list_profiles + activate_for_user to switch.",
     "- Screenshots default to 720px. Use full_res=true only when detail matters.",
     "- Setup: /slack-radar-setup",
     "- Manual enable (no skill): adb shell am broadcast -a slack.debug.ENABLE_RADAR --ei timeout_minutes 5 -p com.Slack.internal.debug",
     "  Then: adb forward tcp:8099 localabstract:slack-radar",
     "",
     "WEB DASHBOARD (/radar-ui):",
-    "A browser-based dashboard (http://localhost:8100) shows the same live device data in a",
-    "visual UI. Launched via the /radar-ui skill, which wraps `npx -p @slack/radar-mcp slack-radar-web`.",
+    "A browser-based dashboard (http://localhost:8100) shows the same live device data as",
+    "tabs: Live (everything), Network, RTM, Clogs, and Logs, each with counters, a graph, a",
+    "filterable feed, and a payload inspector. Launched via the /radar-ui skill, which runs",
+    "`npx @slack/radar-mcp web` (a global install also exposes it as `slack-radar`).",
     "",
-    "When to suggest /radar-ui (mention it ONCE per thread, do not auto-invoke):",
+    "PROACTIVELY offer the dashboard when it would help — do not wait to be asked. The moment a",
+    "device session turns visual or multi-step, say so and offer to open it, e.g.: \"This is",
+    "easier to watch live — want me to open the Radar dashboard?\" Offer (once per thread) when:",
     '- User says "watch", "monitor", "let me see", "show me live" about device traffic',
     "- User wants to share traffic with a colleague, pair, or teammate",
     "- User is doing a multi-minute investigation and the transcript is getting noisy",
     '- User explicitly asks about a GUI, UI, browser view, or dashboard',
     "",
-    "DO NOT invoke /radar-ui yourself. Opening a browser window is a user-visible action.",
-    "DO NOT suggest /radar-ui for single-query debugging or when the user is happy reading",
-    "results in the transcript. Suggest it when visual inspection adds real value.",
+    "OFFER, then open ONLY AFTER THE USER AGREES — opening a browser window is a user-visible",
+    "action; never pop one unbidden. On a yes, run the /radar-ui skill (or tell them to run",
+    "`npx @slack/radar-mcp web`) and hand over the URL. Nudge, do not auto-open.",
+    "DO NOT offer for single-query debugging or when the user is happy reading results in the",
+    "transcript. Offer when visual inspection adds real value.",
+    "",
+    "CUSTOM DASHBOARD (open_radar_dashboard):",
+    "The pre-built tabs (Live/Network/RTM/Clogs/Logs) cover the common cases. When the user",
+    "describes a live view the tabs do not show, SUGGEST building it; invoke open_radar_dashboard",
+    "only after they agree or explicitly ask for a custom view/dashboard (same discipline as",
+    "/radar-ui). To build, translate their words into a spec and call the tool; it renders your",
+    "spec as a 'Custom' tab on the dashboard (default http://localhost:8100) and returns the URL",
+    "for you to share. Cases worth suggesting it for:",
+    '- "graph calls per second vs average response time and flag the slow ones"',
+    '- "count every DM I receive and beep when one arrives"',
+    '- "show only RTM events on channel C... and let me click each for its payload"',
+    '- "watch network calls whose body contains <substring>"',
+    "Authoring rules:",
+    "- source is one of network/rtm/clog/log/all ('all' = one unified timeline).",
+    "- match filters on SUMMARY fields only, by source: network=url/method/status_code,",
+    "  rtm=event_type/direction/channel, clog=event_name, log=tag/level/message/pid/package.",
+    "  NEVER invent a field; a match on a field the stream does not carry silently matches",
+    "  nothing. To filter on body text use bodyContains (network/all only), which fetches detail.",
+    "- viz composes counter/rate/sparkline/feed/inspector/graph. graph needs a series array",
+    "  (1-2 entries; metric ratePerSec/count/avg/errorRate; avg needs a field like duration_ms).",
+    "- highlight {field, op, value} flags rows breaching a numeric threshold; alert {sound,flash,",
+    "  say, at} fires on each live match (or once at the Nth). Author an honest one-line `summary`.",
+    "Calling it again replaces/refines the live custom dashboard. The dashboard reads a connected",
+    "device, so Radar must be armed to show data (it has its own Reconnect button). Debug builds",
+    "only; local only. Does not open a browser window for you; surface the returned URL to the user.",
     "",
     "CAPTURE_SNAPSHOT OUTPUT:",
     "When capture_snapshot returns, tell the user:",
@@ -69,7 +105,7 @@ export const SERVER_INSTRUCTIONS = [
 export const TOOL_DEFINITIONS = [
     {
         name: "ping",
-        description: "Check if Slack Radar is running. Returns uptime, buffer sizes, remaining session time, and stream status.",
+        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.",
         inputSchema: {
             type: "object",
             properties: {
@@ -206,19 +242,19 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: "list_profiles",
-        description: "List Android user profiles that have the Slack debug build running. Use this before activate_for_user when the user asks to switch profiles (personal vs work) or when logs/app state seem to point at the wrong profile. Returns each profile's userId (e.g. '0' for personal, '10' for work) and a human label.",
+        description: "List Android user profiles that have the Slack debug build running. Use this before activate_for_user when the user asks to switch profiles (personal vs a secondary user such as a work profile) or when logs/app state seem to point at the wrong profile. Returns each profile's userId (e.g. '0' for personal, '10' for a secondary user) and a human label.",
         inputSchema: { type: "object", properties: {} },
         annotations: { readOnlyHint: true },
     },
     {
         name: "activate_for_user",
-        description: "Activate Slack Radar on a specific Android user profile. Use after list_profiles to switch between personal and work profile targets. Switching profiles restarts log capture with a new session-scoped file and reconnects the SSE event stream so events come from the newly activated profile; old captures remain on disk for up to 7 days. Call this when already connected and only the target profile needs to change.",
+        description: "Activate Slack Radar on a specific Android user profile. Use after list_profiles to switch between the personal user and a secondary user (such as a work profile). Switching profiles restarts log capture with a new session-scoped file and reconnects the SSE event stream so events come from the newly activated profile; old captures remain on disk for up to 7 days. Call this when already connected and only the target profile needs to change.",
         inputSchema: {
             type: "object",
             properties: {
                 user_id: {
                     type: "string",
-                    description: "Android user ID from list_profiles (e.g. '0' for personal, '10' for work).",
+                    description: "Android user ID from list_profiles (e.g. '0' for personal, '10' for a secondary user).",
                 },
                 timeout_minutes: {
                     type: "number",
@@ -298,6 +334,79 @@ export const TOOL_DEFINITIONS = [
         inputSchema: { type: "object", properties: {} },
         annotations: { readOnlyHint: false, idempotentHint: true },
     },
+    {
+        name: "open_radar_dashboard",
+        description: "Build or refine a custom live dashboard tab in the Slack Radar web UI from a spec YOU author. " +
+            "Suggest this when the user describes a live view the pre-built tabs (Live/Network/RTM/Clogs/Logs) do not cover " +
+            "(e.g. 'graph calls per second vs response time and flag slow ones', 'beep when I get a DM'); invoke it once they agree. " +
+            "Translate the request into the spec fields below and call this tool; it ensures the web dashboard is " +
+            "running (default http://localhost:8100) and renders your spec as a 'Custom' tab, then returns the URL to share. " +
+            "Calling again replaces/refines it. Does not open a browser window for the user. The dashboard reads a connected " +
+            "device, so Radar must be armed to show data (the dashboard has its own Reconnect button). Debug builds only, local only.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: { type: "string", description: "Short 1-3 word dashboard title; also the Custom tab label." },
+                summary: {
+                    type: "string",
+                    description: "ONE honest plain-English line describing what this shows, including any active filter.",
+                },
+                source: {
+                    type: "string",
+                    enum: [...SOURCES],
+                    description: "Which device stream to read. 'all' is a unified timeline mixing network, RTM, and clog.",
+                },
+                match: {
+                    type: "object",
+                    description: "Case-insensitive substring filter on SUMMARY fields, keyed by source. network: url/method/status_code; " +
+                        "rtm: event_type/direction/channel; clog: event_name; log: tag/level/package. NEVER invent a field " +
+                        "(a match on an absent field silently matches nothing). For body text use bodyContains instead.",
+                },
+                bodyContains: {
+                    type: "string",
+                    description: "network/all only: keep calls whose request/response BODY contains this substring (fetches each call's detail).",
+                },
+                viz: {
+                    type: "array",
+                    items: { type: "string", enum: [...VIZ] },
+                    description: "Widgets to compose. 'graph' requires a series array.",
+                },
+                rateWindowSec: {
+                    type: "number",
+                    description: "Sliding window in seconds for the rate widget (default 10).",
+                },
+                series: {
+                    type: "array",
+                    description: "Required when viz includes 'graph'. 1-2 entries.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            label: { type: "string" },
+                            metric: { type: "string", enum: [...SERIES_METRICS] },
+                            field: { type: "string", description: "Required for the 'avg' metric, e.g. duration_ms." },
+                            unit: { type: "string" },
+                        },
+                        required: ["metric"],
+                    },
+                },
+                extract: {
+                    type: "object",
+                    description: "Pull CONTENT from a record body into the feed: {parse:'response_body'|'request_body'|'data', field:'dot.path', label}.",
+                },
+                highlight: {
+                    type: "object",
+                    description: "Flag feed rows whose numeric field breaches a threshold: {field, op:'>'|'>='|'<'|'<='|'==', value, label}.",
+                },
+                alert: {
+                    type: "object",
+                    description: "Sentry mode: {sound, flash, say, at}. 'at':N fires once when the match count reaches N; omit to fire on every match.",
+                },
+            },
+            required: ["title", "summary", "source", "viz"],
+        },
+        // Not read-only: it starts a local web server and pushes a spec to it.
+        annotations: { readOnlyHint: false, idempotentHint: true },
+    },
 ];
 /**
  * Check whether a tool call should be blocked by the session gate.
@@ -312,6 +421,11 @@ export function sessionGate(toolName, sessionEnabled) {
     if (toolName === "ping") {
         return null;
     }
+    // open_radar_dashboard launches an independent local web process with its own
+    // device-enable (Reconnect) button, so it does not require the MCP session enabled.
+    if (toolName === "open_radar_dashboard") {
+        return null;
+    }
     if (!sessionEnabled) {
         return {
             content: [

package/dist/shared/android.d.ts

@@ -13,8 +13,9 @@ export declare function resolveAdbPath(): string | null;
 /**
  * Parse the output of `ps -A -o USER,NAME` to extract the Android user ID
  * for the debug build process. When multiple profiles are running, prefers
- * the work profile (user ID > 0) since that's the typical debugging target.
- * Returns "0" for primary user, "10" for work profile, etc.
+ * a secondary user (user ID > 0) since that's the typical debugging target.
+ * Returns "0" for the primary user, or the first secondary user id (commonly
+ * "10", which is often a work profile, but the id alone cannot prove that).
  */
 export declare function parseUserFromPsOutput(psOutput: string): string;
 export declare class AndroidTransport implements DeviceTransport {

package/dist/shared/android.js

@@ -61,8 +61,9 @@ const ADB = resolveAdbPath();
 /**
  * Parse the output of `ps -A -o USER,NAME` to extract the Android user ID
  * for the debug build process. When multiple profiles are running, prefers
- * the work profile (user ID > 0) since that's the typical debugging target.
- * Returns "0" for primary user, "10" for work profile, etc.
+ * a secondary user (user ID > 0) since that's the typical debugging target.
+ * Returns "0" for the primary user, or the first secondary user id (commonly
+ * "10", which is often a work profile, but the id alone cannot prove that).
  */
 export function parseUserFromPsOutput(psOutput) {
     if (!psOutput || !psOutput.trim())
@@ -77,9 +78,9 @@ export function parseUserFromPsOutput(psOutput) {
     }
     if (userIds.length === 0)
         return "0";
-    // Prefer work profile (non-zero user ID) when multiple profiles are running
-    const workProfile = userIds.find((id) => id !== "0");
-    return workProfile ?? userIds[0];
+    // Prefer a secondary user (non-zero user ID) when multiple profiles are running
+    const secondaryUser = userIds.find((id) => id !== "0");
+    return secondaryUser ?? userIds[0];
 }
 export class AndroidTransport {
     platform = "android";
@@ -228,7 +229,7 @@ export class AndroidTransport {
                     const id = match[1];
                     profiles.push({
                         userId: id,
-                        label: id === "0" ? "Personal (user 0)" : `Work profile (user ${id})`,
+                        label: id === "0" ? "Personal (user 0)" : `Secondary (user ${id}, e.g. a work profile)`,
                     });
                 }
             }

package/dist/shared/constants.d.ts

@@ -4,3 +4,9 @@ export declare const RADAR_PORT = 8099;
 export declare const RADAR_HOST = "127.0.0.1";
 /** Max events to retain in each local SSE buffer. */
 export declare const MAX_LOCAL_BUFFER = 500;
+/**
+ * Default port for the web dashboard. Shared so the MCP `open_radar_dashboard`
+ * tool POSTs its spec to the same port the web server listens on; both honor the
+ * `SLACK_RADAR_WEB_PORT` env override.
+ */
+export declare const WEB_PORT_DEFAULT = 8100;

package/dist/shared/constants.js

@@ -4,3 +4,9 @@ export const RADAR_PORT = 8099;
 export const RADAR_HOST = "127.0.0.1";
 /** Max events to retain in each local SSE buffer. */
 export const MAX_LOCAL_BUFFER = 500;
+/**
+ * Default port for the web dashboard. Shared so the MCP `open_radar_dashboard`
+ * tool POSTs its spec to the same port the web server listens on; both honor the
+ * `SLACK_RADAR_WEB_PORT` env override.
+ */
+export const WEB_PORT_DEFAULT = 8100;

package/dist/web/bin.js

@@ -1,35 +1,50 @@
 #!/usr/bin/env node
-import { createServer, WEB_PORT } from "./server.js";
 import { execSync } from "child_process";
-const server = createServer();
-server.on("error", (err) => {
-    if (err.code === "EADDRINUSE") {
-        console.error(`Port ${WEB_PORT} is already in use. Another instance may be running.\n` +
-            `Kill it with: lsof -ti :${WEB_PORT} | xargs kill\n` +
-            `Or set a different port: SLACK_RADAR_WEB_PORT=8101 slack-radar-web`);
-        process.exit(1);
-    }
-    throw err;
-});
-server.listen(WEB_PORT, () => {
-    const url = `http://localhost:${WEB_PORT}`;
-    console.log(`Slack Radar Web running at ${url}`);
-    try {
-        if (process.platform === "darwin") {
-            execSync(`open ${url}`, { stdio: "ignore" });
+import { createServer, WEB_PORT } from "./server.js";
+/**
+ * Start the web dashboard server, open the browser, and wire shutdown signals.
+ * Extracted so both the dedicated `slack-radar-web` bin and the default bin's
+ * `web` subcommand dispatcher launch the dashboard the same way.
+ */
+function startWebServer() {
+    const server = createServer();
+    server.on("error", (err) => {
+        if (err.code === "EADDRINUSE") {
+            console.error(`Port ${WEB_PORT} is already in use. Another instance may be running.\n` +
+                `Kill it with: lsof -ti :${WEB_PORT} | xargs kill\n` +
+                `Or set a different port: SLACK_RADAR_WEB_PORT=8101 slack-radar web`);
+            process.exit(1);
+        }
+        throw err;
+    });
+    server.listen(WEB_PORT, () => {
+        const url = `http://localhost:${WEB_PORT}`;
+        console.log(`Slack Radar Web running at ${url}`);
+        // Auto-open the browser for the HUMAN launcher (`slack-radar web` / `slack-radar-web`),
+        // but NOT when spawned as a bridge child by the open_radar_dashboard MCP tool
+        // (SLACK_RADAR_NO_OPEN=1). The Claude Code session must not pop a browser window the user
+        // did not ask for — the same no-auto-open-browser rule the SERVER_INSTRUCTIONS state for
+        // /radar-ui. The tool returns the URL instead, for the Claude Code session to surface.
+        if (process.env.SLACK_RADAR_NO_OPEN)
+            return;
+        try {
+            if (process.platform === "darwin") {
+                execSync(`open ${url}`, { stdio: "ignore" });
+            }
+            else if (process.platform === "linux") {
+                execSync(`xdg-open ${url}`, { stdio: "ignore" });
+            }
         }
-        else if (process.platform === "linux") {
-            execSync(`xdg-open ${url}`, { stdio: "ignore" });
+        catch {
+            // Browser open is best-effort
         }
-    }
-    catch {
-        // Browser open is best-effort
-    }
-});
-function shutdown() {
-    console.log("\nShutting down…");
-    server.close(() => process.exit(0));
-    setTimeout(() => process.exit(0), 2000);
+    });
+    const shutdown = () => {
+        console.log("\nShutting down…");
+        server.close(() => process.exit(0));
+        setTimeout(() => process.exit(0), 2000);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
 }
-process.on("SIGINT", shutdown);
-process.on("SIGTERM", shutdown);
+startWebServer();