@slack/radar-mcp 1.19.0 → 1.21.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 +48 -8
- package/dist/mcp/api-paths.d.ts +11 -0
- package/dist/mcp/api-paths.js +67 -16
- package/dist/mcp/index.js +24 -7
- package/dist/mcp/network-detail.d.ts +5 -0
- package/dist/mcp/network-detail.js +86 -0
- package/dist/mcp/radar-response.d.ts +7 -0
- package/dist/mcp/radar-response.js +15 -0
- package/dist/mcp/session-backfill.d.ts +9 -3
- package/dist/mcp/session-backfill.js +77 -17
- package/dist/mcp/session-detail.js +54 -2
- package/dist/mcp/session-query.js +53 -11
- package/dist/mcp/sources-gate.js +4 -0
- package/dist/mcp/switchboard-tools.d.ts +9 -0
- package/dist/mcp/switchboard-tools.js +40 -0
- package/dist/mcp/tools.js +69 -18
- package/dist/shared/constants.d.ts +14 -3
- package/dist/shared/constants.js +14 -3
- package/dist/shared/event-spool.js +3 -2
- package/dist/shared/form-body.d.ts +18 -0
- package/dist/shared/form-body.js +251 -0
- package/dist/shared/stream.d.ts +1 -1
- package/dist/shared/switchboard.d.ts +9 -0
- package/dist/shared/switchboard.js +54 -0
- package/dist/shared/wire.d.ts +32 -0
- package/dist/web/install-app.d.ts +64 -1
- package/dist/web/install-app.js +174 -24
- package/dist/web/macapp/RadarApp.swift +1287 -71
- package/dist/web/public/index.html +216 -11
- package/dist/web/public/next/app.js +22 -12
- package/dist/web/public/next/db.js +180 -18
- package/dist/web/public/next/feed.js +571 -53
- package/dist/web/public/next/filters.js +160 -34
- package/dist/web/public/next/form-body.js +252 -0
- package/dist/web/public/next/inspector.js +103 -12
- package/dist/web/public/next/registry.js +33 -3
- package/dist/web/public/next/store.js +577 -53
- package/dist/web/public/next/voice-model.js +532 -0
- package/dist/web/public/next/voice.js +397 -0
- package/dist/web/server.d.ts +110 -6
- package/dist/web/server.js +436 -40
- package/dist/web/spec.d.ts +13 -6
- package/dist/web/spec.js +89 -6
- package/package.json +3 -3
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
|
-
* **Logs** — device logcat, filtered to the Slack app
|
|
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, and player diagnostics (re-arms, jitter trims, read stalls, pre-ready drops). 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 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, the handshake waterfall, model/you tracks with markers for re-arms, tts.stop and focus loss, and four stat cards, at a 60 s, 5 min or whole session zoom; the audio levels are not drawn.
|
|
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,7 +68,13 @@ 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
|
-
Clicking it starts the dashboard if it is not already running (the server auto-closes 5 minutes after the last tab closes, so this is the usual case), waits for the port, then shows it. 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.
|
|
71
|
+
Clicking it starts the dashboard if it is not already running (the server auto-closes 5 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.
|
|
72
|
+
|
|
73
|
+
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:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
npx -y @slack/radar-mcp@latest install-app
|
|
77
|
+
```
|
|
70
78
|
|
|
71
79
|
### Screen overlay
|
|
72
80
|
|
|
@@ -117,20 +125,23 @@ Radar starts **disabled** each session. All tools except `ping` return an error
|
|
|
117
125
|
|---|---|
|
|
118
126
|
| `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. |
|
|
119
127
|
| `get_recent_network_calls` | HTTP call summaries: method, URL, status code, duration. Filterable by URL substring and status code. |
|
|
120
|
-
| `get_network_call_detail` | Full request/response headers and bodies for a specific call (gzip/brotli decompressed). |
|
|
128
|
+
| `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). |
|
|
129
|
+
| `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. |
|
|
121
130
|
| `get_recent_rtm_events` | RTM event summaries: type, direction, channel, timestamp. Filterable by type, direction, channel. Uses subtypes (e.g. `message_changed`, not `message`). |
|
|
122
131
|
| `get_rtm_event_detail` | Full RTM event JSON payload for a specific event. |
|
|
123
132
|
| `get_recent_clogs` | Analytics event summaries: name and timestamp. Filterable by event name substring. Persists from app start. |
|
|
124
133
|
| `get_clog_detail` | Full clog JSON payload for a specific event. |
|
|
125
134
|
| `get_recent_traces` | Performance trace/span summaries: trace name, span name, duration. Filterable by name substring. |
|
|
126
135
|
| `get_trace_detail` | Full trace/span detail for a specific trace, including tags. |
|
|
136
|
+
| `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. Ids restart with the app process. |
|
|
137
|
+
| `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 and end. Narrow with `kind`; `limit` is how many of the newest records come back (default 50, max 2000), filtered by kind first, so a kind page is the newest `limit` records of that kind. |
|
|
127
138
|
| `wait_for_events` | Block until matching events arrive via SSE stream. Idle-timeout based, not polling. |
|
|
128
139
|
| `search` | Full-text search across network, RTM, clog, and trace buffers. |
|
|
129
140
|
| `get_app_state` | Current Activity/Fragment state via `dumpsys`. Shows visible screen, parameters, tab state. |
|
|
130
|
-
| `get_recent_logs` | Recent device logs, optionally filtered by tag (omit `tag` for all lines). Reads the app's own debug log buffer first, falling back to logcat; the result's `source` field (`app_buffer` / `logcat_capture` / `logcat_ring`) names which one served it. For Timber debug logs (`
|
|
141
|
+
| `get_recent_logs` | Recent device logs, optionally filtered by tag (omit `tag` for all lines). Reads the app's own debug log buffer first, falling back to logcat; the result's `source` field (`app_buffer` / `logcat_capture` / `logcat_ring`) names which one served it. For Timber debug logs (`SlackRadar`, `OkHttp`, etc.). |
|
|
131
142
|
| `list_profiles` | List the Android users and profiles on the device (personal, work, and so on). |
|
|
132
143
|
| `activate_for_user` | Activate radar for a specific Android user or profile. |
|
|
133
|
-
| `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. |
|
|
144
|
+
| `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. |
|
|
134
145
|
| `screenshot` | Capture device screen as PNG. 720px default, `full_res=true` for full resolution. |
|
|
135
146
|
| `record_screen` | Record short screen video (MP4). Default 5s, max 30s. |
|
|
136
147
|
| `list_databases` | List the app's on-device SQLite databases. Read-only. |
|
|
@@ -165,6 +176,8 @@ Mobile debug build (device)
|
|
|
165
176
|
|
|
166
177
|
All device-specific logic lives behind the `DeviceTransport` interface (`src/shared/transport.ts`). Buffers, SSE streaming, session management, and the HTTP wire protocol are platform-agnostic: the wire format is plain `GET /api/<resource>` with JSON, and adb appears only in the transport.
|
|
167
178
|
|
|
179
|
+
**Consuming the wire from your own tooling**: the dashboard's HTTP+SSE surface is documented as a read contract in [docs/wire-contract.md](docs/wire-contract.md) (Oracle Surface v1) — named routes, SSE frame grammar, backfill/dedupe recipe, the auto-close trap, and an executable preflight (`scripts/preflight.mjs`, which lives in this repo rather than the published package, and is meant to be copied into your own harness).
|
|
180
|
+
|
|
168
181
|
**Adding a new platform**: implement `DeviceTransport` in `src/shared/<platform>.ts` and add a case to `createTransport()` in `src/mcp/index.ts`. The device-shaped operations (screenshot, screen recording, app state, device logs) are optional members, so implement what the platform supports and leave the rest absent; callers report each absent capability as "not supported on platform X". Two things stay Android-only for now and are guarded rather than abstracted: the dashboard (its flow assumes a device to arm) and adb port forwarding.
|
|
169
182
|
|
|
170
183
|
## Security
|
|
@@ -257,3 +270,30 @@ Restart your Claude Code session. MCP servers are registered at session start.
|
|
|
257
270
|
|
|
258
271
|
**Port already in use (web dashboard)**
|
|
259
272
|
If a Radar dashboard is already running on the port, launching again just opens it. If the port is held by another program, run Radar on a different port with `SLACK_RADAR_WEB_PORT=8101 npx @slack/radar-mcp web`.
|
|
273
|
+
|
|
274
|
+
**The dashboard shows the version you just replaced**
|
|
275
|
+
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.
|
|
276
|
+
|
|
277
|
+
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, and never from a session; 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.
|
|
278
|
+
|
|
279
|
+
Ask the two surfaces separately. The installed dock app:
|
|
280
|
+
|
|
281
|
+
```bash
|
|
282
|
+
defaults read ~/Applications/Slack\ Radar.app/Contents/Info.plist CFBundleShortVersionString
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
And whatever is actually serving, with the dashboard open. A GET with the headers printed, not `curl -sI`: a HEAD only answers on the release that carries this change and later, and the dashboard you are diagnosing is an older one by definition.
|
|
286
|
+
|
|
287
|
+
```bash
|
|
288
|
+
curl -s -D - -o /dev/null http://127.0.0.1:8100/spec | grep -i x-radar-version
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
Use your own port if you set `SLACK_RADAR_WEB_PORT`. Against the wrong port both commands print nothing, which looks the same as a dashboard that is not there.
|
|
292
|
+
|
|
293
|
+
Two different versions is the answer. Stop the old dashboard, then quit the app and open it again:
|
|
294
|
+
|
|
295
|
+
```bash
|
|
296
|
+
curl -s -X POST -H 'X-Radar-Dashboard: 1' http://127.0.0.1:8100/shutdown
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
If it comes back older, the dashboard is being started by your Claude Code session, so restart that to reload its MCP server. Where npm enforces a minimum release age, `@latest` will not resolve to a release for its first week; pin the version in your MCP registration to get it sooner.
|
package/dist/mcp/api-paths.d.ts
CHANGED
|
@@ -1 +1,12 @@
|
|
|
1
|
+
import { SWITCHBOARD_KINDS, 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 declare function nonNegativeIntArg(v: unknown): number | null;
|
|
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,75 @@
|
|
|
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
|
-
|
|
9
|
+
import { switchboardListPath, switchboardSessionPath, SWITCHBOARD_KINDS } 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 holds at most 2000 records per session.
|
|
14
|
+
export const SWITCHBOARD_DEFAULT_LIMIT = 50;
|
|
15
|
+
export const SWITCHBOARD_MAX_LIMIT = 2000;
|
|
16
|
+
// One id rule for every detail-by-id tool, switchboard included: a non-negative safe integer, as
|
|
17
|
+
// a number or as a clean digit string (the SDK casts args without enforcing the schema, so "7"
|
|
18
|
+
// arrives as a string). Whitespace around the digits is trimmed like clampSwitchboardLimit does.
|
|
19
|
+
// Anything else (negative, fractional, 1e21, "7/../x", objects, arrays, booleans) is refused.
|
|
20
|
+
export function nonNegativeIntArg(v) {
|
|
16
21
|
let n;
|
|
17
|
-
if (typeof
|
|
18
|
-
n =
|
|
22
|
+
if (typeof v === "number") {
|
|
23
|
+
n = v;
|
|
19
24
|
}
|
|
20
|
-
else if (typeof
|
|
21
|
-
|
|
22
|
-
// but "1e3"/"0x10"/" 5 " would also coerce; the \d+ test rejects all of those outright.
|
|
23
|
-
n = Number(id.trim());
|
|
25
|
+
else if (typeof v === "string" && /^\d+$/.test(v.trim())) {
|
|
26
|
+
n = Number(v.trim());
|
|
24
27
|
}
|
|
25
28
|
else {
|
|
26
29
|
return null;
|
|
27
30
|
}
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
+
return Number.isSafeInteger(n) && n >= 0 ? n : null;
|
|
32
|
+
}
|
|
33
|
+
// What a refused argument looks like in an error: JSON, cut at 80 characters so a huge argument
|
|
34
|
+
// does not become a huge error.
|
|
35
|
+
const ECHO_MAX = 80;
|
|
36
|
+
function echoArg(v) {
|
|
37
|
+
const s = String(JSON.stringify(v));
|
|
38
|
+
return s.length > ECHO_MAX ? s.slice(0, ECHO_MAX) + "..." : s;
|
|
39
|
+
}
|
|
40
|
+
// The get_switchboard_session args as a device path, or the reason they cannot be one. The path
|
|
41
|
+
// builders live in shared/switchboard.ts so the MCP tool and the dashboard's replay hit the same
|
|
42
|
+
// strings. limit is clamped to what the ring can answer rather than rejected; a bad kind is an
|
|
43
|
+
// error, since a misspelling would silently page every kind, while an empty kind means every kind.
|
|
44
|
+
export function switchboardSessionQuery(args) {
|
|
45
|
+
const id = nonNegativeIntArg(args?.id);
|
|
46
|
+
if (id === null) {
|
|
47
|
+
return {
|
|
48
|
+
error: `id must be a non-negative integer session_id from get_switchboard_sessions; got ${echoArg(args?.id)}.`,
|
|
49
|
+
};
|
|
50
|
+
}
|
|
51
|
+
let kind;
|
|
52
|
+
if (args?.kind !== undefined && args.kind !== null) {
|
|
53
|
+
const k = String(args.kind).trim().toLowerCase();
|
|
54
|
+
if (k !== "") {
|
|
55
|
+
if (!SWITCHBOARD_KINDS.includes(k)) {
|
|
56
|
+
return { error: `kind must be one of ${SWITCHBOARD_KINDS.join("|")}; got ${echoArg(args.kind)}.` };
|
|
57
|
+
}
|
|
58
|
+
kind = k;
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
return { path: switchboardSessionPath(id, clampSwitchboardLimit(args?.limit), kind) };
|
|
62
|
+
}
|
|
63
|
+
// 1..2000, default 50. A digit string counts, the same rule as id; anything else that is not a
|
|
64
|
+
// finite number falls back to the default.
|
|
65
|
+
export function clampSwitchboardLimit(limit) {
|
|
66
|
+
const n = typeof limit === "number" ? limit : typeof limit === "string" && /^\d+$/.test(limit.trim()) ? Number(limit) : NaN;
|
|
67
|
+
if (!Number.isFinite(n))
|
|
68
|
+
return SWITCHBOARD_DEFAULT_LIMIT;
|
|
69
|
+
return Math.min(SWITCHBOARD_MAX_LIMIT, Math.max(1, Math.floor(n)));
|
|
70
|
+
}
|
|
71
|
+
// Build the device path for a detail-by-id tool. All four detail tools (network/rtm/clog/trace)
|
|
72
|
+
// read the device's OWN forwarded server with no shell/fs, so the blast radius is small, but an
|
|
73
|
+
// un-encoded id is still a path-traversal smell. nonNegativeIntArg is the rule; anything it refuses
|
|
74
|
+
// returns null (the caller reports "unknown tool"/no path rather than firing a malformed request).
|
|
75
|
+
function detailPath(resource, id) {
|
|
76
|
+
const n = nonNegativeIntArg(id);
|
|
77
|
+
return n === null ? null : `/api/${resource}/${n}`;
|
|
31
78
|
}
|
|
32
79
|
export function buildApiPath(name, args) {
|
|
33
80
|
switch (name) {
|
|
@@ -102,6 +149,10 @@ export function buildApiPath(name, args) {
|
|
|
102
149
|
params.set("limit", String(a.limit));
|
|
103
150
|
return `/api/search?${params.toString()}`;
|
|
104
151
|
}
|
|
152
|
+
case "get_switchboard_sessions":
|
|
153
|
+
return switchboardListPath();
|
|
154
|
+
// get_switchboard_session is not here: index.ts dispatches it to its own handler, which
|
|
155
|
+
// validates the args and answers a bad id with the reason (switchboardSessionQuery).
|
|
105
156
|
// list_feature_flags/search_feature_flags/get_feature_flag are NOT here -- see
|
|
106
157
|
// flags-tools.ts's file header for why they fetch and filter host-side instead.
|
|
107
158
|
default:
|
package/dist/mcp/index.js
CHANGED
|
@@ -21,6 +21,7 @@ import { buildBufferPath, createSnapshot } from "./snapshot.js";
|
|
|
21
21
|
import { clampLogLimit, shapeLogsResult } from "./logs-result.js";
|
|
22
22
|
import { querySession, clampByteCap, toNum } from "./session-query.js";
|
|
23
23
|
import { resolveDetailById } from "./session-detail.js";
|
|
24
|
+
import { decorateToolResult } from "./network-detail.js";
|
|
24
25
|
import { runSessionEnable } from "./session-enable.js";
|
|
25
26
|
import { applyEnableOutcome, clearSources, sourceGate } from "./sources-gate.js";
|
|
26
27
|
import { computeDispatch } from "./dispatch.js";
|
|
@@ -31,7 +32,8 @@ import { listFeatureFlags, searchFeatureFlags, getFeatureFlag, normalizeOverridd
|
|
|
31
32
|
import { cleanupPulledDatabases, initializeDatabasePath, resetDbState, } from "../shared/db.js";
|
|
32
33
|
import { TOOL_DEFINITIONS, serverInstructions, sessionGate } from "./tools.js";
|
|
33
34
|
import { buildApiPath } from "./api-paths.js";
|
|
34
|
-
import {
|
|
35
|
+
import { handleGetSwitchboardSession, handleGetSwitchboardSessions } from "./switchboard-tools.js";
|
|
36
|
+
import { interpretRadarResponse, responseBudgetError } from "./radar-response.js";
|
|
35
37
|
// --- Subcommand + bin-name dispatch ---
|
|
36
38
|
// See computeDispatch's own comment (dispatch.ts) for the full front-door table and rationale;
|
|
37
39
|
// pulled out to a pure function so the bin-name/subcommand rules are unit-testable.
|
|
@@ -333,6 +335,14 @@ async function runMcpServer() {
|
|
|
333
335
|
const arr = key ? res[key] : undefined;
|
|
334
336
|
return Array.isArray(arr) ? arr : [];
|
|
335
337
|
},
|
|
338
|
+
// The switchboard leg's raw GET: an error reply (a build without the plugin answers 404) is
|
|
339
|
+
// null, so the leg contributes nothing rather than failing the round.
|
|
340
|
+
fetchJson: async (apiPath) => {
|
|
341
|
+
const res = await callRadar(apiPath);
|
|
342
|
+
if (res.error)
|
|
343
|
+
return null;
|
|
344
|
+
return res;
|
|
345
|
+
},
|
|
336
346
|
readSpool,
|
|
337
347
|
write: writeFrame,
|
|
338
348
|
};
|
|
@@ -386,10 +396,7 @@ async function runMcpServer() {
|
|
|
386
396
|
if (bytes > MAX_RADAR_RESPONSE_BYTES) {
|
|
387
397
|
// Resolve the truncation NOW (not on "end" — req.destroy() aborts the response so
|
|
388
398
|
// "end" never fires; it surfaces as an "error" the settled-guard then swallows).
|
|
389
|
-
done(
|
|
390
|
-
error: `Device response exceeded the ${Math.round(MAX_RADAR_RESPONSE_BYTES / 1024)}KB response budget and was dropped to protect the model context. Narrow the query (lower limit, add a name/filter), or use capture_snapshot for a bulk export.`,
|
|
391
|
-
_truncated: true,
|
|
392
|
-
});
|
|
399
|
+
done(responseBudgetError());
|
|
393
400
|
req.destroy();
|
|
394
401
|
return;
|
|
395
402
|
}
|
|
@@ -810,7 +817,7 @@ async function runMcpServer() {
|
|
|
810
817
|
}
|
|
811
818
|
}
|
|
812
819
|
// --- MCP Server ---
|
|
813
|
-
const server = new Server({ name: "slack-radar", version: "1.
|
|
820
|
+
const server = new Server({ name: "slack-radar", version: "1.21.0" }, { capabilities: { tools: {} }, instructions: serverInstructions(device.platform) });
|
|
814
821
|
server.setRequestHandler(ListToolsRequestSchema, async () => ({
|
|
815
822
|
tools: TOOL_DEFINITIONS,
|
|
816
823
|
}));
|
|
@@ -929,12 +936,22 @@ async function runMcpServer() {
|
|
|
929
936
|
const { data, isError } = getFeatureFlag(response, key ?? "", scope, orgId);
|
|
930
937
|
return textResult(data, isError);
|
|
931
938
|
}
|
|
939
|
+
// The switchboard tools validate host-side and answer a bad id with a reason, where the generic
|
|
940
|
+
// buildApiPath fallthrough below would only say "unknown tool" for a null path.
|
|
941
|
+
if (name === "get_switchboard_sessions") {
|
|
942
|
+
const { data, isError } = await handleGetSwitchboardSessions(callRadar);
|
|
943
|
+
return textResult(data, isError);
|
|
944
|
+
}
|
|
945
|
+
if (name === "get_switchboard_session") {
|
|
946
|
+
const { data, isError } = await handleGetSwitchboardSession(toolArgs, callRadar);
|
|
947
|
+
return textResult(data, isError);
|
|
948
|
+
}
|
|
932
949
|
const apiPath = buildApiPath(name, toolArgs);
|
|
933
950
|
if (apiPath === null) {
|
|
934
951
|
return textResult(`Unknown tool: ${name}`, true);
|
|
935
952
|
}
|
|
936
953
|
const result = await callRadar(apiPath);
|
|
937
|
-
return textResult(result, !!result.error);
|
|
954
|
+
return textResult(decorateToolResult(name, result), !!result.error);
|
|
938
955
|
});
|
|
939
956
|
const transport = new StdioServerTransport();
|
|
940
957
|
await server.connect(transport);
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import type { RadarResponse } from "./radar-response.js";
|
|
2
|
+
export declare const DECODED_COPY_KEYS: readonly ["request_body_decoded", "request_body_decoded_unparsed"];
|
|
3
|
+
export declare function withDecodedRequestBody(input: RadarResponse): RadarResponse;
|
|
4
|
+
export declare function stripOwned(result: RadarResponse): RadarResponse;
|
|
5
|
+
export declare function decorateToolResult(name: string, result: RadarResponse): RadarResponse;
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
// Decorate a network-call detail with a decoded view of a form-encoded request body. Split out
|
|
2
|
+
// of index.ts so it is unit-testable (index connects stdio at load). The raw request_body is
|
|
3
|
+
// left untouched: it is the bytes a caller replays; the decoded object is a reading aid. Applied
|
|
4
|
+
// on the way out only, both by get_network_call_detail and by a query_session id read, so the
|
|
5
|
+
// spool keeps the raw record and a spool written before this existed reads the same.
|
|
6
|
+
import { FORM_DECODE_LIMIT_LABEL, MAX_FORM_DECODE_BYTES } from "../shared/constants.js";
|
|
7
|
+
import { decodeFormBody, formBodyLooksTruncated, formBodyToObject, formTextLooksTruncated, isFormBody, jsonTextLooksCut, } from "../shared/form-body.js";
|
|
8
|
+
const OMITTED_NOTE = `form body over ${FORM_DECODE_LIMIT_LABEL}; request_body holds the raw bytes`;
|
|
9
|
+
const DECODED_OMITTED_NOTE = `decoded form over ${FORM_DECODE_LIMIT_LABEL}; request_body holds the raw bytes`;
|
|
10
|
+
// The decoded-copy fields, the ones a byte-capped reader may drop while keeping the rest.
|
|
11
|
+
export const DECODED_COPY_KEYS = ["request_body_decoded", "request_body_decoded_unparsed"];
|
|
12
|
+
// Every field this decorator owns. The MCP is the only writer of these three (the device emits
|
|
13
|
+
// none of them), so a record that arrives already carrying one (a spool written by another
|
|
14
|
+
// version) has it recomputed here, never merged with a stale copy. request_body_truncated is not
|
|
15
|
+
// owned: the device knows whether its cap cut the body and a build that serializes that knowledge
|
|
16
|
+
// is authoritative; the shape read below only fills the flag in when the record carries none.
|
|
17
|
+
const OWNED_KEYS = [...DECODED_COPY_KEYS, "request_body_decoded_omitted"];
|
|
18
|
+
export function withDecodedRequestBody(input) {
|
|
19
|
+
const result = stripOwned(input);
|
|
20
|
+
const raw = result.request_body;
|
|
21
|
+
if (typeof raw !== "string")
|
|
22
|
+
return result;
|
|
23
|
+
// A record with request_content_type settles the form question; a record without it is read
|
|
24
|
+
// by shape. Same for the cut: a boolean request_body_truncated from the device stands, and the
|
|
25
|
+
// shape rules (bracket balance, a cut field name) decide only when it is absent. Shape cannot
|
|
26
|
+
// see a body clipped inside a plain value, which is the most ordinary cut there is.
|
|
27
|
+
const contentType = result.request_content_type;
|
|
28
|
+
const deviceFlag = typeof result.request_body_truncated === "boolean" ? result.request_body_truncated : undefined;
|
|
29
|
+
const cut = (byShape) => deviceFlag ?? byShape();
|
|
30
|
+
if (!isFormBody(raw, contentType)) {
|
|
31
|
+
// A JSON body the device cap cut deserves the same flag a cut form body gets, or its absence
|
|
32
|
+
// means nothing: a model reading a clipped body would take it for the whole request.
|
|
33
|
+
return cut(() => jsonTextLooksCut(raw, contentType)) ? { ...result, request_body_truncated: true } : result;
|
|
34
|
+
}
|
|
35
|
+
// Over the limit the decoded copy would be skipped anyway, so the saving is skipping
|
|
36
|
+
// formBodyToObject and the stringify below: the body still gets the truncation read of its
|
|
37
|
+
// last pair (for a single-pair body that pair is the whole body). Bytes, not string length:
|
|
38
|
+
// the payload leaves as UTF-8.
|
|
39
|
+
if (Buffer.byteLength(raw, "utf8") > MAX_FORM_DECODE_BYTES) {
|
|
40
|
+
const out = { ...result, request_body_decoded_omitted: OMITTED_NOTE };
|
|
41
|
+
if (cut(() => formTextLooksTruncated(raw)))
|
|
42
|
+
out.request_body_truncated = true;
|
|
43
|
+
return out;
|
|
44
|
+
}
|
|
45
|
+
const form = decodeFormBody(raw, contentType);
|
|
46
|
+
if (!form)
|
|
47
|
+
return result;
|
|
48
|
+
const out = { ...result };
|
|
49
|
+
const decoded = formBodyToObject(form);
|
|
50
|
+
// Measured as the pretty print textResult emits, in UTF-8 bytes, so the gate sees the same
|
|
51
|
+
// size the model does.
|
|
52
|
+
if (Buffer.byteLength(JSON.stringify(decoded, null, 2), "utf8") > MAX_FORM_DECODE_BYTES) {
|
|
53
|
+
out.request_body_decoded_omitted = DECODED_OMITTED_NOTE;
|
|
54
|
+
}
|
|
55
|
+
else {
|
|
56
|
+
out.request_body_decoded = decoded;
|
|
57
|
+
// A field whose JSON was deliberately left unparsed says so, by field name, the way the size
|
|
58
|
+
// gate explains itself above; otherwise the flat string reads as a value the app sent flat.
|
|
59
|
+
// Built without a prototype, like formBodyToObject, so a field named __proto__ survives.
|
|
60
|
+
const unparsed = Object.create(null);
|
|
61
|
+
for (const f of form.fields)
|
|
62
|
+
if (f.unparsedReason)
|
|
63
|
+
unparsed[f.key] = f.unparsedReason;
|
|
64
|
+
if (Object.keys(unparsed).length)
|
|
65
|
+
out.request_body_decoded_unparsed = Object.fromEntries(Object.entries(unparsed));
|
|
66
|
+
}
|
|
67
|
+
if (cut(() => formBodyLooksTruncated(form)))
|
|
68
|
+
out.request_body_truncated = true;
|
|
69
|
+
return out;
|
|
70
|
+
}
|
|
71
|
+
export function stripOwned(result) {
|
|
72
|
+
// A request_body_truncated that is not a boolean is nobody's verdict and goes too.
|
|
73
|
+
const junkFlag = "request_body_truncated" in result && typeof result.request_body_truncated !== "boolean";
|
|
74
|
+
if (!junkFlag && !OWNED_KEYS.some((k) => k in result))
|
|
75
|
+
return result;
|
|
76
|
+
const out = { ...result };
|
|
77
|
+
for (const k of OWNED_KEYS)
|
|
78
|
+
delete out[k];
|
|
79
|
+
if (junkFlag)
|
|
80
|
+
delete out.request_body_truncated;
|
|
81
|
+
return out;
|
|
82
|
+
}
|
|
83
|
+
// Only the detail tool carries a request body worth decoding; every other tool passes through.
|
|
84
|
+
export function decorateToolResult(name, result) {
|
|
85
|
+
return name === "get_network_call_detail" ? withDecodedRequestBody(result) : result;
|
|
86
|
+
}
|
|
@@ -19,3 +19,10 @@ export interface RadarResponse {
|
|
|
19
19
|
* body keeps the existing {raw} behavior, a real if unusual success payload.
|
|
20
20
|
*/
|
|
21
21
|
export declare function interpretRadarResponse(status: number, body: string): RadarResponse;
|
|
22
|
+
/**
|
|
23
|
+
* The error a proxied answer gets when it would not fit the response budget. radarRequest trips it
|
|
24
|
+
* on the wire as the bytes arrive; a handler that receives a parsed answer through an injected
|
|
25
|
+
* fetch trips it after the fact. One text for both so the model sees one note either way.
|
|
26
|
+
*/
|
|
27
|
+
export declare const RESPONSE_BUDGET_DEFAULT_HINT = "Narrow the query (lower limit, add a name/filter), or use capture_snapshot for a bulk export.";
|
|
28
|
+
export declare function responseBudgetError(hint?: string): RadarResponse;
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
// The shape a proxied device call resolves to, and how a raw (status, body) becomes one. Split
|
|
2
2
|
// out of index.ts so it is unit-testable: index.ts connects stdio at module load, so importing it
|
|
3
3
|
// from a test would hang.
|
|
4
|
+
import { MAX_RADAR_RESPONSE_BYTES } from "../shared/constants.js";
|
|
4
5
|
/**
|
|
5
6
|
* Turn a device HTTP (status, body) into the RadarResponse the tool layer returns. Parse JSON
|
|
6
7
|
* when the body is JSON: this preserves the device's own error bodies (e.g. an in-app 404 sends
|
|
@@ -36,3 +37,17 @@ export function interpretRadarResponse(status, body) {
|
|
|
36
37
|
}
|
|
37
38
|
return parsed;
|
|
38
39
|
}
|
|
40
|
+
/**
|
|
41
|
+
* The error a proxied answer gets when it would not fit the response budget. radarRequest trips it
|
|
42
|
+
* on the wire as the bytes arrive; a handler that receives a parsed answer through an injected
|
|
43
|
+
* fetch trips it after the fact. One text for both so the model sees one note either way.
|
|
44
|
+
*/
|
|
45
|
+
// The hint is what to do instead; the default suits the ring tools, a tool capture_snapshot does
|
|
46
|
+
// not bundle passes its own.
|
|
47
|
+
export const RESPONSE_BUDGET_DEFAULT_HINT = "Narrow the query (lower limit, add a name/filter), or use capture_snapshot for a bulk export.";
|
|
48
|
+
export function responseBudgetError(hint = RESPONSE_BUDGET_DEFAULT_HINT) {
|
|
49
|
+
return {
|
|
50
|
+
error: `Device response exceeded the ${Math.round(MAX_RADAR_RESPONSE_BYTES / 1024)}KB response budget and was dropped to protect the model context. ${hint}`,
|
|
51
|
+
_truncated: true,
|
|
52
|
+
};
|
|
53
|
+
}
|
|
@@ -1,7 +1,11 @@
|
|
|
1
1
|
import type { ParsedSSE, RadarEvent } from "../shared/stream.js";
|
|
2
2
|
export declare const BACKFILL_SOURCES: Map<string, string>;
|
|
3
|
+
export declare const SWITCHBOARD_BACKFILL_LIMIT = 2000;
|
|
3
4
|
export interface BackfillDeps {
|
|
4
5
|
fetchList: (source: string) => Promise<RadarEvent[]>;
|
|
6
|
+
fetchJson: (apiPath: string) => Promise<Record<string, unknown> | null>;
|
|
7
|
+
switchboardLimit?: number;
|
|
8
|
+
switchboardDeadlineMs?: number;
|
|
5
9
|
readSpool: () => ParsedSSE[];
|
|
6
10
|
write: (frame: ParsedSSE) => void;
|
|
7
11
|
}
|
|
@@ -12,9 +16,11 @@ export interface BackfillSummary {
|
|
|
12
16
|
* Backfill the device rings into the spool.
|
|
13
17
|
*
|
|
14
18
|
* For each backfillable source it fetches the device ring list, reads what the spool already holds,
|
|
15
|
-
* and writes only the rows whose
|
|
16
|
-
*
|
|
17
|
-
*
|
|
19
|
+
* and writes only the rows whose dedupKey is NOT already present (as a summary OR as a cached
|
|
20
|
+
* detail). Switchboard is fetched per session (see fetchSwitchboardRows) and keyed with its
|
|
21
|
+
* timestamp. Frames are written in the SAME shape the SSE push produces ({type: source,
|
|
22
|
+
* event: row}) and oldest-first (ascending id, or timestamp for switchboard) so the spool stays
|
|
23
|
+
* append-ordered like the live push.
|
|
18
24
|
*
|
|
19
25
|
* Never throws: a failed list fetch for one source is swallowed (that source is simply not
|
|
20
26
|
* backfilled this round) so a device blip cannot break enable or the stream. A row with no numeric
|