@slack/radar-mcp 1.20.0 → 1.22.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.
- package/README.md +75 -17
- package/dist/mcp/api-paths.d.ts +11 -0
- package/dist/mcp/api-paths.js +56 -20
- package/dist/mcp/dashboard-identity.d.ts +6 -0
- package/dist/mcp/dashboard-identity.js +11 -0
- package/dist/mcp/index.js +138 -36
- package/dist/mcp/logs-result.d.ts +1 -0
- package/dist/mcp/logs-result.js +1 -0
- package/dist/mcp/network-detail.d.ts +5 -0
- package/dist/mcp/network-detail.js +86 -0
- package/dist/mcp/radar-export-get.d.ts +30 -0
- package/dist/mcp/radar-export-get.js +49 -0
- package/dist/mcp/radar-response.d.ts +11 -1
- package/dist/mcp/radar-response.js +23 -3
- package/dist/mcp/session-backfill.d.ts +9 -3
- package/dist/mcp/session-backfill.js +76 -17
- package/dist/mcp/session-detail.js +54 -2
- package/dist/mcp/session-enable.d.ts +1 -0
- package/dist/mcp/session-enable.js +146 -15
- package/dist/mcp/session-query.js +53 -11
- package/dist/mcp/snapshot.js +42 -26
- package/dist/mcp/sources-gate.js +5 -0
- package/dist/mcp/stale-dashboard.d.ts +23 -0
- package/dist/mcp/stale-dashboard.js +122 -0
- package/dist/mcp/switchboard-spool.d.ts +12 -0
- package/dist/mcp/switchboard-spool.js +107 -0
- package/dist/mcp/switchboard-tools.d.ts +18 -0
- package/dist/mcp/switchboard-tools.js +178 -0
- package/dist/mcp/tools.d.ts +4 -1
- package/dist/mcp/tools.js +114 -23
- package/dist/mcp/web-child-env.d.ts +4 -1
- package/dist/mcp/web-child-env.js +4 -1
- package/dist/shared/android.d.ts +43 -0
- package/dist/shared/android.js +227 -19
- package/dist/shared/constants.d.ts +19 -4
- package/dist/shared/constants.js +19 -4
- package/dist/shared/event-spool.js +3 -2
- package/dist/shared/feature-flags.d.ts +1 -0
- package/dist/shared/feature-flags.js +1 -0
- package/dist/shared/form-body.d.ts +18 -0
- package/dist/shared/form-body.js +251 -0
- package/dist/shared/ios-logs.d.ts +10 -0
- package/dist/shared/ios-logs.js +91 -0
- package/dist/shared/ios.d.ts +25 -2
- package/dist/shared/ios.js +157 -3
- package/dist/{web → shared}/log-session.d.ts +45 -31
- package/dist/shared/log-session.js +300 -0
- package/dist/shared/radar-request-raw.d.ts +7 -0
- package/dist/shared/radar-request-raw.js +89 -0
- package/dist/shared/radar-token.d.ts +25 -0
- package/dist/shared/radar-token.js +164 -0
- package/dist/shared/stream.d.ts +4 -1
- package/dist/shared/stream.js +107 -15
- package/dist/shared/switchboard-host-store.d.ts +21 -0
- package/dist/shared/switchboard-host-store.js +166 -0
- package/dist/shared/switchboard-note.d.ts +15 -0
- package/dist/shared/switchboard-note.js +92 -0
- package/dist/shared/switchboard-report-file.d.ts +5 -0
- package/dist/shared/switchboard-report-file.js +26 -0
- package/dist/shared/switchboard-report.d.ts +20 -0
- package/dist/shared/switchboard-report.js +406 -0
- package/dist/shared/switchboard.d.ts +118 -0
- package/dist/shared/switchboard.js +487 -0
- package/dist/shared/transport.d.ts +43 -3
- package/dist/shared/version.d.ts +2 -0
- package/dist/shared/version.js +18 -0
- package/dist/shared/wire.d.ts +46 -1
- package/dist/web/install-app.d.ts +57 -8
- package/dist/web/install-app.js +270 -60
- package/dist/web/macapp/RadarApp.swift +340 -22
- package/dist/web/public/index.html +216 -12
- package/dist/web/public/next/app.js +43 -22
- package/dist/web/public/next/db.js +4 -1
- package/dist/web/public/next/feed.js +604 -59
- package/dist/web/public/next/filters.js +158 -40
- package/dist/web/public/next/flags.js +3 -0
- package/dist/web/public/next/form-body.js +252 -0
- package/dist/web/public/next/inspector.js +171 -14
- package/dist/web/public/next/prefs.js +5 -2
- package/dist/web/public/next/registry.js +35 -3
- package/dist/web/public/next/store.js +947 -69
- package/dist/web/public/next/switchboard-note.js +93 -0
- package/dist/web/public/next/toast.js +9 -5
- package/dist/web/public/next/voice-model.js +712 -0
- package/dist/web/public/next/voice.js +552 -0
- package/dist/web/server.d.ts +20 -9
- package/dist/web/server.js +834 -174
- package/dist/web/spec.d.ts +11 -6
- package/dist/web/spec.js +62 -6
- package/package.json +4 -4
- package/dist/web/log-session.js +0 -166
package/README.md
CHANGED
|
@@ -44,17 +44,19 @@ slack-radar
|
|
|
44
44
|
|
|
45
45
|
Opens `http://localhost:8100` automatically. Set `SLACK_RADAR_WEB_PORT` to use a different port. (`slack-radar-web` still works as a direct alias.) Tabs:
|
|
46
46
|
|
|
47
|
-
* **Live** — network, RTM, analytics clogs, traces,
|
|
47
|
+
* **Live** — network, RTM, analytics clogs, traces, Slack-app logcat and Switchboard voice records in one timeline (**level ≥** applies to the logcat lines). The rate and sparkline count every source together, so a voice session raises them the way RTM traffic does
|
|
48
48
|
* **Network** — calls per second vs response time, every call listed, slow ones flagged
|
|
49
49
|
* **RTM** — real-time websocket events
|
|
50
50
|
* **Clogs** — analytics events, click one to see its payload
|
|
51
51
|
* **Traces** — performance trace spans with durations, click one for its timing and tags
|
|
52
52
|
* **Logs** — device logcat, filtered to the Slack app. **app** switches app or shows all apps; **level ≥** sets the lowest level to show (VERBOSE shows everything; the choice follows you between Logs and Live and waits while you visit another tab)
|
|
53
|
+
* **Switchboard** — the Slackbot voice transport's own records: session begin and end, connection, mic and speaking state changes, every websocket frame (← in, → out) with type and size, phase timings, player diagnostics (re-arms, jitter trims, read stalls, pre-ready drops), mic/playback level meter batches, and timed voice turns (how long Slackbot took to start answering, e.g. `1840 ms, no card`), and whether each spoken turn got saved to the DM (`saved, thread`, `saved (line moved on), thread` for a late save whose line already moved on (a server resend counts again), or `dropped: missing field` with the reason; the session panel counts each of the four outcomes). Click a row for the rest of its fields; no level, so hide noise with the filter box or **exclude**, and the kinds chips on the toolbar (including **levels**) turn one kind of record off at a time. Records arrive once a Slackbot voice session starts. A debug build that declares its sources and lacks the plugin hides the tab; one too old to declare them shows it empty. Above the feed, a session panel draws the newest session: connection, mic and speaking pills, a pill naming the server's own id for the call (reading "pending" once a build known to report one has not sent it yet, and showing nothing at all on a build never known to), the handshake waterfall, model/you tracks with markers for re-arms, tts.stop and focus loss, mic and playback level sparklines once the device reports them, and four stat cards, at a 60 s, 5 min or whole session zoom. **Export** pages the device, then merges in the dashboard's own live stream copy (up to 50000 records per session); it can stop early (for example an old build, the size cap, the page limit, or the device going quiet), and the downloaded report's notes say why anything is missing. The tab's feed shows the same call as the panel, so a new call replaces both. Earlier calls still show on **Live** and in search.
|
|
53
54
|
* **Database** — read-only browser for the on-device SQLite stores (pick a database, then a table, or run a read-only query). See the data-handling note below.
|
|
54
55
|
* **Preferences** — read-only browser for the on-device SharedPreferences files (pick a file, browse its keys, or search across every file at once).
|
|
55
|
-
* **
|
|
56
|
+
* **Feature Flags** — live view of every feature flag and experiment the Slack app knows about, with its current effective value (ON/OFF for toggles, group name for experiments), its scope, and whether it is locally overridden; updates as they change on the device. Filter by name.
|
|
57
|
+
* **Custom** — a tab Claude builds on request. Ask a Claude Code session in your terminal for a view the pre-built tabs do not cover (e.g. "graph calls per second and flag the slow ones"); it authors the view via the `open_radar_dashboard` tool and it appears here. A Custom view can carry `exclude` terms to hide noisy rows; add more with the **exclude…** control on the feed toolbar or the Filters panel (comma-separated there), or have the agent set them in the spec (one phrase per term, no commas or line breaks). A log view narrowed to one tag is the same kind of ask: "show me only the `<Tag>` logs, DEBUG and up, without the noisy lines" becomes a spec with `source: log`, `match: {package, tag}`, `minLevel` and `exclude`, opened as a Custom tab. Persists until you refresh the page; exclude terms are remembered in the browser only on the pre-built tabs.
|
|
56
58
|
|
|
57
|
-
Each tab has a
|
|
59
|
+
Each tab has a filter / sort / pause / clear feed and a payload inspector, most a live rate, Network and Traces a graph. **Clear** empties the dashboard's own view only, so the device keeps its buffers and a reconnect or a source switch backfills recent records again (ask a Claude Code session for `clear_buffers` to wipe the device too). The filter box takes space-separated terms that must all match, `-term` to exclude, `/pattern/` for regex, and `"quoted phrases"` for spaces or a literal `-` or `/` (curly quotes count too, and pasting text with spaces quotes it for you, unless you are mid-word or the text starts in filter syntax). `-term` is page-wide and gone on reload; to keep an exclusion, use the **exclude…** control on the feed toolbar (one term, then Enter), the **exclude** row in the Filters panel (comma separated) or an agent's `exclude` on the spec: the terms show above the feed as removable chips, are saved with the tab, and on a pre-built tab are remembered in the browser when you come back; a spec an agent pushes lands as written and does not touch that memory. An exclude term written `field:value` (say `kind:frame`, the Switchboard record's own kind field; no space after the colon) hides rows whose field equals the value, case-insensitive, and a field no row carries hides nothing; plain terms match by substring, and the Switchboard tab's kind chips toggle those `kind:` terms for you. The `?` at the right edge of the box opens a short legend under it. A phrase that itself contains a quote character goes in `/regex/` form instead, where quotes are plain text. Committed terms turn into removable pills; a leading `-` is now the exclude operator (the old box matched it as plain text), and quoting restores the literal. Regex flags are optional and short (i/m/s/g, 1-2 letters only, so an ambiguous tail like `/api/im` reads as flags, noted in the tooltip); typos like `/error/x` become part of the pattern and match literally, and quoting any `/…/` term matches it literally. Invalid regexes and incomplete typing (e.g. `/foo(`) are ignored (the term turns amber) instead of blanking the feed. On the Live tab a row type name (`log`, `clog`, `trace`, `rtm`, `network`, `switchboard`) also matches rows of that type, and the `-log` form excludes by row type only, so it hides logcat lines without touching a `logout` clog (quote it, `-"log"`, to exclude by text instead). Switching tabs replays what you have already seen this session (the browser caches it, bounded by count and age) so the view does not reset to empty. ADB forwarding and device activation are handled for you; a reconnect control re-arms after a device sleep. The device-side session shuts down after its idle timeout, and an open dashboard tab now recovers that on its own: the header says there is no radar session on the device and re-enables it, once right away (or on the minute, if the session just came back and died again) and then at most once a minute, giving up after three failed attempts (a session that dies again within a minute of coming back counts as a failed attempt), or at once if the attached device changed, so the next press is yours. Only a tab you are looking at does this (a background tab never arms a device you let idle out), never a dashboard an agent opened, and **✋ stop auto re-enable** in the header turns it off for dashboards at this address if you would rather do it by hand (`SLACK_RADAR_NO_ARM=1` on the process turns it off for that process, along with the arm at launch). The dashboard follows your system light/dark setting by default; the theme toggle in the header overrides it and is remembered. A form-encoded request body is shown decoded, field by field, JSON fields expanded; Copy cURL still carries the raw bytes. A field whose JSON nests too deep stays as text with a note saying so, and a request body the device cap cut shows a truncation banner.
|
|
58
60
|
|
|
59
61
|
### Install it to your dock (macOS)
|
|
60
62
|
|
|
@@ -66,9 +68,19 @@ npx @slack/radar-mcp install-app
|
|
|
66
68
|
|
|
67
69
|
That writes `~/Applications/Slack Radar.app`. Open it once, then right-click its dock icon and choose **Options > Keep in Dock**.
|
|
68
70
|
|
|
69
|
-
|
|
71
|
+
The dashboard port is baked into the app at install time. To use a port other than `8100`, set it when you install, for example `SLACK_RADAR_WEB_PORT=8101 npx @slack/radar-mcp install-app`, and set the same `SLACK_RADAR_WEB_PORT` in your MCP server config so the tools and the app use the same dashboard. In Claude Code that is `-e` on the add command:
|
|
70
72
|
|
|
71
|
-
|
|
73
|
+
```bash
|
|
74
|
+
slack claude mcp add -s user slack-radar-mcp -e SLACK_RADAR_WEB_PORT=8101 -- npx -y @slack/radar-mcp@latest
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
If the server is already added, run `slack claude mcp remove -s user slack-radar-mcp` first, since `add` refuses a name that already exists. In a JSON config the port goes in the server entry's `"env"` object, as `"env": { "SLACK_RADAR_WEB_PORT": "8101" }`.
|
|
78
|
+
|
|
79
|
+
The native app also updates itself: when a newer version of the package is published, a launch rebuilds it in the background, and the update takes effect the next time you open it. That rebuild keeps the port the app was built with, or uses 8100 when that cannot be read. To change the port, run `install-app` again with the new `SLACK_RADAR_WEB_PORT`.
|
|
80
|
+
|
|
81
|
+
Clicking it starts the dashboard if it is not already running (the server auto-closes about 6 minutes after the last tab closes, so this is the usual case), waits for the port, then shows it. If an older dashboard is still holding the port and nobody is using it, the app asks that one to stop first, so an upgrade does not leave you looking at the version you replaced. Quitting the app stops the dashboard it started, unless a Claude Code session or another window is still using it; a dashboard that was already running when the app launched is never stopped. If Xcode's command line tools are installed (`xcode-select --install`), `install-app` compiles a small native window for this: its own dock icon, its own process, no browser tab, no tab bar. Without a Swift toolchain it falls back to opening your default browser instead.
|
|
82
|
+
|
|
83
|
+
If the window cannot start the dashboard after a node upgrade, the app is holding a node path that the upgrade moved. Run this, then quit and reopen the app. It keeps the port the app already has; to change it, put `SLACK_RADAR_WEB_PORT=<port>` in front, matching your MCP server config.
|
|
72
84
|
|
|
73
85
|
```bash
|
|
74
86
|
npx -y @slack/radar-mcp@latest install-app
|
|
@@ -94,7 +106,7 @@ All optional. Set them on the process that runs the MCP server or the dashboard.
|
|
|
94
106
|
|
|
95
107
|
| Variable | Effect |
|
|
96
108
|
|---|---|
|
|
97
|
-
| `SLACK_RADAR_WEB_PORT` | Port the dashboard listens on. Default `8100`. |
|
|
109
|
+
| `SLACK_RADAR_WEB_PORT` | Port the dashboard listens on. Default `8100`. The dock app bakes it in at install time, so set it when you run `install-app`. |
|
|
98
110
|
| `SLACK_RADAR_DEVICE_PORT` | Host port forwarded to the device-side server. Default `8099`. |
|
|
99
111
|
| `SLACK_RADAR_NO_AUTO_CLOSE=1` | Keep the dashboard running forever instead of closing it once every tab is gone. |
|
|
100
112
|
| `SLACK_RADAR_ALLOWED_HOSTS` | Extra `Host` values the dashboard will answer, comma-separated (`radar.local,myhost:8100`). Only needed when you reach it by a name other than localhost. See Security. |
|
|
@@ -106,7 +118,7 @@ All optional. Set them on the process that runs the MCP server or the dashboard.
|
|
|
106
118
|
|
|
107
119
|
## Session Management
|
|
108
120
|
|
|
109
|
-
Radar starts **disabled** each session. All tools except `ping` return an error until enabled.
|
|
121
|
+
Radar starts **disabled** each session. All tools except `ping` return an error until enabled. `export_switchboard_session` also works after an auto-disable if this process streamed the call live.
|
|
110
122
|
|
|
111
123
|
| Command | Effect |
|
|
112
124
|
|---|---|
|
|
@@ -115,7 +127,7 @@ Radar starts **disabled** each session. All tools except `ping` return an error
|
|
|
115
127
|
|
|
116
128
|
**Auto-enable**: When you ask Claude an obvious device question (clogs, network calls, screenshots, app state, RTM events, logs), Claude invokes `/radar-enable` automatically before calling the relevant tool.
|
|
117
129
|
|
|
118
|
-
**Auto-disable**: When the device-side radar shuts down after idle (default 5 min), the next tool call failure flips the session to disabled. Claude will tell you and offer to re-enable.
|
|
130
|
+
**Auto-disable**: When the device-side radar shuts down after idle (default 5 min), the next tool call failure flips the session to disabled. Claude will tell you and offer to re-enable. `export_switchboard_session` still works after this: it builds the report from the live stream copy alone, with no device call, as long as this process streamed the call live. An explicit `/radar-disable` or `clear_buffers` wipes that copy.
|
|
119
131
|
|
|
120
132
|
## Tools
|
|
121
133
|
|
|
@@ -123,20 +135,24 @@ Radar starts **disabled** each session. All tools except `ping` return an error
|
|
|
123
135
|
|---|---|
|
|
124
136
|
| `ping` | Health check. Returns uptime, buffer sizes, remaining session time, stream status, the Radar MCP version (`mcp_version`), and which app/profile is bound (`android_user_id`, `profile` personal/secondary, `package`). Use `timeout_minutes` to extend sessions. |
|
|
125
137
|
| `get_recent_network_calls` | HTTP call summaries: method, URL, status code, duration. Filterable by URL substring and status code. |
|
|
126
|
-
| `get_network_call_detail` | Full request/response headers and bodies for a specific call (gzip/brotli decompressed). |
|
|
138
|
+
| `get_network_call_detail` | Full request/response headers and bodies for a specific call (gzip/brotli decompressed). A form-encoded request body (by the record's `request_content_type`, or by shape on a build without it) also comes back decoded in `request_body_decoded`, JSON-valued fields parsed. A body, or its decoded copy, over 64 KB skips the decoded copy and `request_body_decoded_omitted` says so; a field left unparsed is named in `request_body_decoded_unparsed`. `request_body` stays the raw bytes; `request_body_truncated: true` means the device cap cut it (a build that reports the cut itself is believed, otherwise it is read from the body's shape). |
|
|
139
|
+
| `query_session` | The whole session from the host event spool (network, RTM, clogs, traces, switchboard), newest first, byte-capped, with a cursor to page older. An id read returns the full record, pulling the body from the device once and caching it; a network record gets the same decoded-form fields as `get_network_call_detail`; a body that cannot be pulled falls back to the summary with a note. |
|
|
127
140
|
| `get_recent_rtm_events` | RTM event summaries: type, direction, channel, timestamp. Filterable by type, direction, channel. Uses subtypes (e.g. `message_changed`, not `message`). |
|
|
128
141
|
| `get_rtm_event_detail` | Full RTM event JSON payload for a specific event. |
|
|
129
142
|
| `get_recent_clogs` | Analytics event summaries: name and timestamp. Filterable by event name substring. Persists from app start. |
|
|
130
143
|
| `get_clog_detail` | Full clog JSON payload for a specific event. |
|
|
131
144
|
| `get_recent_traces` | Performance trace/span summaries: trace name, span name, duration. Filterable by name substring. |
|
|
132
145
|
| `get_trace_detail` | Full trace/span detail for a specific trace, including tags. |
|
|
146
|
+
| `get_switchboard_sessions` | Slackbot voice (switchboard) sessions the device still holds, newest first: `session_id`, `team_id`, `began_at`, `ended_at`, record and frame counts, the newest state and audio levels, `server_session_id` (the server's own name for the session, null until it names one; absent on an older build), `turns` (turn count, the newest response time and its clock, null before the first turn; absent on an older build), and `saved_turn_counts` (saved turns per outcome; absent on an older build means not counted, not zero). Ids restart with the app process. |
|
|
147
|
+
| `get_switchboard_session` | One voice session's summary plus its records, oldest first: `state` transitions, control frames (`frame`) in and out, `player` stutter events, `phase` startup timings, `session` begin/end/ready (`ready` carries `server_session_id`), `levels` (batched mic/playback meter ticks), `turn` (one timed voice turn: `response_ms` and `clock`), and `saved_turn` (whether a spoken turn got saved to the DM: `outcome` (`applied`, `no_line`, `missing_field`, `other_session`) and `has_thread`; the summary's `saved_turn_counts` counts each outcome, and absent on an older device build means not counted, not zero). Narrow with `kind`; `limit` is how many of the newest records come back (default 50, max 2000 per request; the device may hold more, paged with before_id), filtered by kind first, so a kind page is the newest `limit` records of that kind. |
|
|
148
|
+
| `export_switchboard_session` | Write one voice session's summary and its records to a plain-text report under `~/.slack-radar/exports/`, permissions 0700/0600 like `capture_snapshot`. Pages the device, then merges in the live stream copy; the export can stop early (for example an old build, the 32 MB size cap, the page limit, or the device stopping answering), and the report notes say why anything is missing. An unknown id (404, unreachable, or too large to read) errors unless this process streamed the call live, then the report comes from the live stream copy alone, whichever process ran the export, since this MCP server and the web dashboard each keep their own. Defaults to newest when `id` is omitted; returns the file path and a summary. |
|
|
133
149
|
| `wait_for_events` | Block until matching events arrive via SSE stream. Idle-timeout based, not polling. |
|
|
134
150
|
| `search` | Full-text search across network, RTM, clog, and trace buffers. |
|
|
135
151
|
| `get_app_state` | Current Activity/Fragment state via `dumpsys`. Shows visible screen, parameters, tab state. |
|
|
136
|
-
| `get_recent_logs` | Recent device logs, optionally filtered by tag (omit `tag` for all lines).
|
|
152
|
+
| `get_recent_logs` | Recent device logs, optionally filtered by tag (omit `tag` for all lines). Android reads the app's own debug buffer first, falling back to logcat (`app_buffer` / `logcat_capture` / `logcat_ring`); iOS Simulator reads a bounded live unified-log capture. The result's `source` identifies which one served it. |
|
|
137
153
|
| `list_profiles` | List the Android users and profiles on the device (personal, work, and so on). |
|
|
138
154
|
| `activate_for_user` | Activate radar for a specific Android user or profile. |
|
|
139
|
-
| `capture_snapshot` | Bundle the current network, RTM, clog, and trace buffers, plus an optional screenshot, into one saved snapshot for a bug report or repro. |
|
|
155
|
+
| `capture_snapshot` | Bundle the current network, RTM, clog, and trace buffers, plus an optional screenshot, into one saved snapshot for a bug report or repro. Switchboard voice records are not included. |
|
|
140
156
|
| `screenshot` | Capture device screen as PNG. 720px default, `full_res=true` for full resolution. |
|
|
141
157
|
| `record_screen` | Record short screen video (MP4). Default 5s, max 30s. |
|
|
142
158
|
| `list_databases` | List the app's on-device SQLite databases. Read-only. |
|
|
@@ -148,7 +164,7 @@ Radar starts **disabled** each session. All tools except `ping` return an error
|
|
|
148
164
|
| `list_feature_flags` | List every feature flag with its live effective value and override status. Optionally filtered to just the overridden ones. Boolean toggles carry `enabled`; multi-variant experiments carry `type: "experiment"` and a `group_name` string (the effective variant, e.g. `"treatment_a"`) instead. |
|
|
149
165
|
| `search_feature_flags` | Case-insensitive substring search on feature flag names, against the same live list as `list_feature_flags`. Rows carry the same `type`/`group_name` fields for experiments. |
|
|
150
166
|
| `get_feature_flag` | Look up one feature flag by its exact key. Returns one row per scope (authenticated/unauthenticated) and per signed-in org, since each workspace resolves its own value; pass `org_id` to narrow to one workspace. An experiment row carries `type: "experiment"` and its `group_name` variant rather than a boolean `enabled`. |
|
|
151
|
-
| `clear_buffers` | Clear all captured buffers (network, RTM, clog, trace) on the device and locally. |
|
|
167
|
+
| `clear_buffers` | Clear all captured buffers (network, RTM, clog, trace) on the device and locally, and the switchboard copy `export_switchboard_session` falls back to. The session event spool `query_session` reads is kept. |
|
|
152
168
|
| `open_radar_dashboard` | Author or refine a custom live dashboard tab from a spec (source, filters, widgets, alerts). Suggested when a request is not covered by the pre-built tabs; not auto-invoked. Returns the dashboard URL; debug builds only, local only. |
|
|
153
169
|
| `_radar_session_enable` | Enable radar for the session. Called by `/radar-enable` skill. |
|
|
154
170
|
| `_radar_session_disable` | Disable radar for the session. Called by `/radar-disable` skill. |
|
|
@@ -178,10 +194,19 @@ All device-specific logic lives behind the `DeviceTransport` interface (`src/sha
|
|
|
178
194
|
## Security
|
|
179
195
|
|
|
180
196
|
* **No TCP port on device.** Uses platform-specific local sockets, only reachable via port forwarding. Requires physical USB or explicit debug pairing.
|
|
197
|
+
* **Per-user device token.** The first Radar process that needs the token (MCP or dashboard) mints it at `~/.slack-radar/radar-token`, mode 0600, one per OS user, and every enable hands it to the device in the enable broadcast. Every request then carries it as `X-Radar-Token`. A device build with the token check answers 401 to anything else; older device builds ignore the extra and stay in open mode without saying so.
|
|
198
|
+
* What it stops: a browser page that reaches the forwarded port (DNS rebinding, or any page you visit), and another app on the device connecting to the abstract socket. Neither can read your `~/.slack-radar`.
|
|
199
|
+
* What it does not stop: anything with adb access. The adb server on `127.0.0.1:5037` has no auth, so any local process can send a tokenless enable and put the device back in open mode, read the token from host or device `ps` while the broadcast runs, or read it off the debuggable app with `run-as`. Processes running as you can read the file. The token keeps honest sessions apart; it does not lock out adb.
|
|
200
|
+
* Open mode is deliberate: an enable with no `radar_token` extra (an older Radar MCP or dashboard, or a hand-typed `am broadcast`) turns the check off so older builds keep working. The MCP warns on every enable result and every `ping` that finds the device in open mode. The dashboard does not warn.
|
|
201
|
+
* The token is never logged and never appears in an error. A failed broadcast reports adb's exit code and the first line of its stderr, with any token-shaped text redacted.
|
|
202
|
+
* The file is never replaced on a 401. Delete it only when a message says the file itself is unusable; then re-enable every other Radar session so they pick up the new one.
|
|
203
|
+
* Known limit: the dashboard forwards every device route (`/api`, `/flags`, `/backfill`, `/detail`) to the device with the token attached. Reads need only a local Host header; writes need an `X-Radar-Dashboard: 1` header or a JSON Content-Type. Any local process can send all of these, so while a dashboard runs, any local process reaches the device through it, writes included. Stop the dashboard when you are not using it.
|
|
204
|
+
* After upgrading: restart Claude Code and any open dashboard so every process sends the token, then run `/radar-enable`.
|
|
205
|
+
|
|
181
206
|
* **Debug builds only.** Release builds bind a no-op implementation. Server code is eliminated at compile time.
|
|
182
207
|
* **Lazy activation.** Dormant until explicitly triggered.
|
|
183
208
|
* **Auto-shutdown.** Device-side server shuts down after idle timeout (default 5 minutes). Zero cost when unused.
|
|
184
|
-
* **Dashboard auto-close.** Once a dashboard has been opened in a browser, the process shuts itself down
|
|
209
|
+
* **Dashboard auto-close.** Once a dashboard has been opened in a browser, the process shuts itself down about 6 minutes after the last tab closes, so a dashboard you walked away from does not linger. Opening a dashboard again (`open_radar_dashboard`, which writes a spec) pushes that deadline out by another grace window, but nothing else does: the other MCP tools read the device directly and never touch the dashboard, so a long agent session with no tab open will still close on schedule. Reopen it, or use the opt-out below, if you want it to stay. Two more exceptions: a dashboard that no tab has **ever** opened (one an agent spawned and nobody visited) stays up until you visit it once or stop it, because there is no "last tab closed" moment to measure from; and when you first upgrade to a version that has auto-close, **reload any tab that was already open**, because page code from before this feature does not report itself as present, so it will not keep the process alive even while you are looking at it. Reloading once is enough; later upgrades do not need it. Click **⏻ Stop dashboard** in the header to stop it immediately instead (click twice to confirm, since it kills the process with no undo). Set `SLACK_RADAR_NO_AUTO_CLOSE=1` to turn auto-close off entirely.
|
|
185
210
|
* **Keep-alive is not forgeable from a web page.** Only the dashboard's own client and the MCP can postpone auto-close. A write to `/setspec` or `/enable` has to carry `X-Radar-Dashboard: 1`, or a content-type whose type is exactly `application/json`; the `/health` presence ping requires the header specifically, since a content-type says nothing about a request with no body. A cross-origin request cannot set either one without a CORS preflight it will fail. A request without either still works and still writes, it just does not extend the process lifetime, so `curl -X POST .../setspec -H 'Content-Type: text/plain'` sets the spec but will not stop the dashboard closing on schedule; use `-H 'Content-Type: application/json'` if you want it to count. This is a CSRF guard, not authentication: any local process can send either header, and the port is loopback-only by design.
|
|
186
211
|
* **Loopback `Host` only.** The dashboard answers a request only when its `Host` header names this machine (`localhost`, `127.0.0.1`, `[::1]`, `0.0.0.0`, with or without a port). Anything else gets a 403 whose body names the host it refused and how to allow it. Binding to 127.0.0.1 alone is not enough: a page that resolves its own domain to 127.0.0.1 connects locally, counts as same-origin in the browser, and could otherwise set the header above and stop your dashboard. If you reach the dashboard by some other name — a `/etc/hosts` alias, a container or Codespaces forwarded URL, your machine's LAN hostname — list it in `SLACK_RADAR_ALLOWED_HOSTS` (comma-separated, host or `host:port`). A plain SSH or VS Code port forward needs nothing, because the `Host` stays `localhost`.
|
|
187
212
|
|
|
@@ -242,9 +267,32 @@ SLACK_RADAR_PLATFORM=ios npm run start:web
|
|
|
242
267
|
```
|
|
243
268
|
|
|
244
269
|
Within the selected platform, Radar chooses the sole running device or shows the device picker
|
|
245
|
-
when several are available. It never probes the other platform. iOS
|
|
246
|
-
|
|
247
|
-
|
|
270
|
+
when several are available. It never probes the other platform. iOS supports live Simulator
|
|
271
|
+
logs through MCP and the dashboard, screenshots, screen mirroring, and recording via `simctl`.
|
|
272
|
+
After verifying that the shared host port belongs to the selected iOS app, Radar also enables
|
|
273
|
+
the HTTP tools for network calls, RTM events, clogs, traces, and feature flags.
|
|
274
|
+
|
|
275
|
+
### iOS Simulator logs
|
|
276
|
+
|
|
277
|
+
Enable the MCP session before you reproduce the issue, then call `get_recent_logs`. Capture
|
|
278
|
+
starts at enable and covers unified logs from subsystems under `com.tinyspeck`; nothing logged
|
|
279
|
+
before that point can be recovered. Results report `source: "ios_unified_capture"`.
|
|
280
|
+
|
|
281
|
+
* **`tag`** is a case-sensitive substring match on a line's category. Lines logged without a
|
|
282
|
+
category use their subsystem, or failing that the process name. `grep` searches every field
|
|
283
|
+
of the line (message, tag, subsystem, process, level, pid), ignoring case.
|
|
284
|
+
* **Levels** map Debug → DEBUG, Info and Default → INFO, Error → ERROR and Fault → FATAL.
|
|
285
|
+
Unified logging has no warning level, so a WARN filter matches nothing on iOS.
|
|
286
|
+
* **The dashboard** Live and Logs tabs run their own capture, separate from the MCP session's,
|
|
287
|
+
and replay what it has retained when you reconnect.
|
|
288
|
+
|
|
289
|
+
Physical iOS devices are not supported yet.
|
|
290
|
+
|
|
291
|
+
### Log retention
|
|
292
|
+
|
|
293
|
+
Android logcat and iOS unified-log capture share one host ring per process: up to 20,000
|
|
294
|
+
records or about 10 MiB, whichever comes first, with the oldest records dropped first. A single
|
|
295
|
+
record over 1 MiB is discarded.
|
|
248
296
|
|
|
249
297
|
## Troubleshooting
|
|
250
298
|
|
|
@@ -257,6 +305,12 @@ The device-side server may have auto-shut down. Use `/radar-enable` to restart i
|
|
|
257
305
|
**"Session disabled"**
|
|
258
306
|
Two consecutive connection failures disable the session. Use `/radar-enable` to reconnect.
|
|
259
307
|
|
|
308
|
+
**"The device is in open mode"**
|
|
309
|
+
An older Radar MCP or dashboard, or a manual `am broadcast`, enabled the device without a token. If an older Radar MCP or dashboard is still running, stop it, then run `/radar-enable`. After an enable, the warning names this enable's failed broadcast or the profile mismatch instead. The MCP warns on every enable result and every `ping` that finds the device open; the dashboard does not warn.
|
|
310
|
+
|
|
311
|
+
**"The device holds a different token than this session's"** (the dashboard says "This device answered to a different Radar token")
|
|
312
|
+
Another Radar session enabled the device after you did: another machine or OS user, a session using a token file you deleted, or Radar enabled in a different profile. Stop that session, or run `/radar-enable` in it so it picks up the new file, or make sure the Slack debug build runs in the profile you want (`list_profiles` shows which do), then run `/radar-enable` here (on the dashboard, press Reconnect). Deleting `~/.slack-radar/radar-token` never fixes this.
|
|
313
|
+
|
|
260
314
|
**Devices with more than one user (e.g. a work profile)**
|
|
261
315
|
The MCP server auto-detects the Android user ID via `ps` and targets the broadcast accordingly. No manual `--user` flag needed. In the dashboard's Logs tab, the package filter narrows logcat to the Slack app; clear the chip or pick another package to widen it.
|
|
262
316
|
|
|
@@ -269,7 +323,11 @@ If a Radar dashboard is already running on the port, launching again just opens
|
|
|
269
323
|
**The dashboard shows the version you just replaced**
|
|
270
324
|
That badge reports the version of the process serving the port, not the app or package you installed. Installing does not touch a server that is already running, so an older dashboard can keep serving after an upgrade.
|
|
271
325
|
|
|
272
|
-
The
|
|
326
|
+
The `open_radar_dashboard` tool checks this too. `stale_dashboard: true` means the dashboard server is older than this MCP server. A dashboard older than 1.6.0 reports no version, so it also gets `stale_dashboard: true`, just without `dashboard_version`. `stale_mcp: true` means the dashboard server is newer. Both come with `mcp_version`. When either version could not be read, `stale_dashboard` is `null`, `stale_mcp` is absent, and the null covers both directions.
|
|
327
|
+
|
|
328
|
+
The app also leaves an older dashboard alone on purpose when somebody else is using it, either a Claude Code session or another window with it open. A refresh (⌘R in the app window, or Retry on its failure page) tries to take it from a window, or from a dashboard too old to say who is using it, and never from a Claude Code session the dashboard names; taking it costs that window its page, and everyone the server's pulled databases, device pin and logcat ring. `~/Library/Logs/slack-radar-dashboard.log` names which one it found, and what a refresh will do about it.
|
|
329
|
+
|
|
330
|
+
The app window also says so in a strip at the top of the page when a launch or refresh keeps an older dashboard, or takes one from somebody. The strip has a short version of the log line and can be dismissed. If a refresh asked the older one to stop and the new dashboard then does not come up, the failure page says instead that the older one was asked to stop.
|
|
273
331
|
|
|
274
332
|
Ask the two surfaces separately. The installed dock app:
|
|
275
333
|
|
package/dist/mcp/api-paths.d.ts
CHANGED
|
@@ -1 +1,12 @@
|
|
|
1
|
+
import { SWITCHBOARD_KINDS, nonNegativeIntArg, type SwitchboardKind } from "../shared/switchboard.js";
|
|
2
|
+
export { SWITCHBOARD_KINDS, type SwitchboardKind };
|
|
3
|
+
export declare const SWITCHBOARD_DEFAULT_LIMIT = 50;
|
|
4
|
+
export declare const SWITCHBOARD_MAX_LIMIT = 2000;
|
|
5
|
+
export { nonNegativeIntArg };
|
|
6
|
+
export declare function switchboardSessionQuery(args: Record<string, unknown>): {
|
|
7
|
+
path: string;
|
|
8
|
+
} | {
|
|
9
|
+
error: string;
|
|
10
|
+
};
|
|
11
|
+
export declare function clampSwitchboardLimit(limit: unknown): number;
|
|
1
12
|
export declare function buildApiPath(name: string, args: Record<string, unknown>): string | null;
|
package/dist/mcp/api-paths.js
CHANGED
|
@@ -6,28 +6,60 @@
|
|
|
6
6
|
//
|
|
7
7
|
// The arg shapes here are the query-param subset each tool sends; they intentionally duplicate
|
|
8
8
|
// the (wider) handler arg interfaces in index.ts rather than couple this pure module to them.
|
|
9
|
-
|
|
10
|
-
//
|
|
11
|
-
//
|
|
12
|
-
|
|
13
|
-
//
|
|
14
|
-
//
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
9
|
+
import { switchboardListPath, switchboardSessionPath, SWITCHBOARD_KINDS, nonNegativeIntArg } from "../shared/switchboard.js";
|
|
10
|
+
// The record kinds the device's switchboard page filters on. Lower-case here; the device matches
|
|
11
|
+
// case-insensitively, so the query is sent normalized.
|
|
12
|
+
export { SWITCHBOARD_KINDS };
|
|
13
|
+
// The device pages at 50 without a limit and answers up to 2000 per request; it may hold more
|
|
14
|
+
// per session, reachable only by paging with before_id.
|
|
15
|
+
export const SWITCHBOARD_DEFAULT_LIMIT = 50;
|
|
16
|
+
export const SWITCHBOARD_MAX_LIMIT = 2000;
|
|
17
|
+
export { nonNegativeIntArg };
|
|
18
|
+
// What a refused argument looks like in an error: JSON, cut at 80 characters so a huge argument
|
|
19
|
+
// does not become a huge error.
|
|
20
|
+
const ECHO_MAX = 80;
|
|
21
|
+
function echoArg(v) {
|
|
22
|
+
const s = String(JSON.stringify(v));
|
|
23
|
+
return s.length > ECHO_MAX ? s.slice(0, ECHO_MAX) + "..." : s;
|
|
24
|
+
}
|
|
25
|
+
// The get_switchboard_session args as a device path, or the reason they cannot be one. The path
|
|
26
|
+
// builders live in shared/switchboard.ts so the MCP tool and the dashboard's replay hit the same
|
|
27
|
+
// strings. limit is clamped to what the ring can answer rather than rejected; a bad kind is an
|
|
28
|
+
// error, since a misspelling would silently page every kind, while an empty kind means every kind.
|
|
29
|
+
export function switchboardSessionQuery(args) {
|
|
30
|
+
const id = nonNegativeIntArg(args?.id);
|
|
31
|
+
if (id === null) {
|
|
32
|
+
return {
|
|
33
|
+
error: `id must be a non-negative integer session_id from get_switchboard_sessions; got ${echoArg(args?.id)}.`,
|
|
34
|
+
};
|
|
24
35
|
}
|
|
25
|
-
|
|
26
|
-
|
|
36
|
+
let kind;
|
|
37
|
+
if (args?.kind !== undefined && args.kind !== null) {
|
|
38
|
+
const k = String(args.kind).trim().toLowerCase();
|
|
39
|
+
if (k !== "") {
|
|
40
|
+
if (!SWITCHBOARD_KINDS.includes(k)) {
|
|
41
|
+
return { error: `kind must be one of ${SWITCHBOARD_KINDS.join("|")}; got ${echoArg(args.kind)}.` };
|
|
42
|
+
}
|
|
43
|
+
kind = k;
|
|
44
|
+
}
|
|
27
45
|
}
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
46
|
+
return { path: switchboardSessionPath(id, clampSwitchboardLimit(args?.limit), kind) };
|
|
47
|
+
}
|
|
48
|
+
// 1..2000, default 50. A digit string counts, the same rule as id; anything else that is not a
|
|
49
|
+
// finite number falls back to the default.
|
|
50
|
+
export function clampSwitchboardLimit(limit) {
|
|
51
|
+
const n = typeof limit === "number" ? limit : typeof limit === "string" && /^\d+$/.test(limit.trim()) ? Number(limit) : NaN;
|
|
52
|
+
if (!Number.isFinite(n))
|
|
53
|
+
return SWITCHBOARD_DEFAULT_LIMIT;
|
|
54
|
+
return Math.min(SWITCHBOARD_MAX_LIMIT, Math.max(1, Math.floor(n)));
|
|
55
|
+
}
|
|
56
|
+
// Build the device path for a detail-by-id tool. All four detail tools (network/rtm/clog/trace)
|
|
57
|
+
// read the device's OWN forwarded server with no shell/fs, so the blast radius is small, but an
|
|
58
|
+
// un-encoded id is still a path-traversal smell. nonNegativeIntArg is the rule; anything it refuses
|
|
59
|
+
// returns null (the caller reports "unknown tool"/no path rather than firing a malformed request).
|
|
60
|
+
function detailPath(resource, id) {
|
|
61
|
+
const n = nonNegativeIntArg(id);
|
|
62
|
+
return n === null ? null : `/api/${resource}/${n}`;
|
|
31
63
|
}
|
|
32
64
|
export function buildApiPath(name, args) {
|
|
33
65
|
switch (name) {
|
|
@@ -102,6 +134,10 @@ export function buildApiPath(name, args) {
|
|
|
102
134
|
params.set("limit", String(a.limit));
|
|
103
135
|
return `/api/search?${params.toString()}`;
|
|
104
136
|
}
|
|
137
|
+
case "get_switchboard_sessions":
|
|
138
|
+
return switchboardListPath();
|
|
139
|
+
// get_switchboard_session is not here: index.ts dispatches it to its own handler, which
|
|
140
|
+
// validates the args and answers a bad id with the reason (switchboardSessionQuery).
|
|
105
141
|
// list_feature_flags/search_feature_flags/get_feature_flag are NOT here -- see
|
|
106
142
|
// flags-tools.ts's file header for why they fetch and filter host-side instead.
|
|
107
143
|
default:
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
export interface DashboardHealthIdentity {
|
|
2
|
+
platform?: string;
|
|
3
|
+
device_serial?: string | null;
|
|
4
|
+
}
|
|
5
|
+
/** Whether an existing dashboard process belongs to this MCP transport and selected device. */
|
|
6
|
+
export declare function dashboardMatchesDevice(platform: string, selectedSerial: string | null | undefined, health: DashboardHealthIdentity): boolean;
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/** Whether an existing dashboard process belongs to this MCP transport and selected device. */
|
|
2
|
+
export function dashboardMatchesDevice(platform, selectedSerial, health) {
|
|
3
|
+
// A dashboard started before /health carried `platform` (1.21.0 and earlier) is Android-only,
|
|
4
|
+
// so a missing field reads as android rather than as a mismatch.
|
|
5
|
+
if ((health.platform ?? "android") !== platform)
|
|
6
|
+
return false;
|
|
7
|
+
if (selectedSerial && health.device_serial && selectedSerial !== health.device_serial) {
|
|
8
|
+
return false;
|
|
9
|
+
}
|
|
10
|
+
return true;
|
|
11
|
+
}
|