@slack/radar-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Slack Technologies, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# slack-radar-mcp
+
+Platform-agnostic MCP server for on-device debugging of mobile apps.
+
+Gives Claude Code direct access to network calls, RTM events, analytics (clogs), screenshots, logs, and more from a running debug build. Ships with Android support (ADB); the `DeviceTransport` interface makes adding iOS or other platforms straightforward.
+
+> **For Slack engineers.** The npm package is published publicly as a distribution convenience, but the source repository, issue tracker, and support live on Slack's internal GitHub Enterprise. External users can install the package but should not expect support or source access. The tool only functions against a Slack debug build, which is not distributed externally.
+
+## Installation
+
+```bash
+git clone slack-github.com/slack/slack-radar-mcp
+cd slack-radar-mcp
+npm install
+npm run build
+```
+
+Register the server with Claude Code:
+
+```bash
+slack claude mcp add -s user slack-radar-mcp -- node /path/to/slack-radar-mcp/dist/index.js
+```
+
+Restart your Claude Code session for the tools to appear.
+
+## Prerequisites
+
+* Node.js 18+
+* ADB with a single connected device (USB or wireless debug)
+* A debug build of Slack installed on the device (must include the `slack-radar` modules)
+
+## Session Management
+
+Radar starts **disabled** each session. All tools except `ping` return an error until enabled.
+
+| Command | Effect |
+|---|---|
+| `/radar-enable` | Activates ADB forwarding, device broadcast, SSE stream. Tools become available. |
+| `/radar-disable` | Tears down stream, clears local buffers. Tools return "not active" error. |
+
+**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.
+
+**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.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `ping` | Health check. Returns uptime, buffer sizes, remaining session time, stream status. Use `timeout_minutes` to extend sessions. |
+| `get_recent_network_calls` | HTTP call summaries: method, URL, status code, duration. Filterable by URL substring and status code. |
+| `get_network_call_detail` | Full request/response headers and bodies for a specific call (gzip/brotli decompressed). |
+| `get_recent_rtm_events` | RTM event summaries: type, direction, channel, timestamp. Filterable by type, direction, channel. Uses subtypes (e.g. `message_changed`, not `message`). |
+| `get_rtm_event_detail` | Full RTM event JSON payload for a specific event. |
+| `get_recent_clogs` | Analytics event summaries: name and timestamp. Filterable by event name substring. Persists from app start. |
+| `get_clog_detail` | Full clog JSON payload for a specific event. |
+| `wait_for_events` | Block until matching events arrive via SSE stream. Idle-timeout based, not polling. |
+| `search` | Full-text search across network, RTM, and clog buffers. |
+| `get_app_state` | Current Activity/Fragment state via `dumpsys`. Shows visible screen, parameters, tab state. |
+| `get_recent_logs` | Logcat entries filtered by tag. For Timber debug logs (`FKDebug`, `SlackRadar`, etc.). |
+| `screenshot` | Capture device screen as PNG. 720px default, `full_res=true` for full resolution. |
+| `record_screen` | Record short screen video (MP4). Default 5s, max 30s. |
+| `clear_buffers` | Clear all captured network calls and RTM events from device and local buffers. |
+| `_radar_session_enable` | Enable radar for the session. Called by `/radar-enable` skill. |
+| `_radar_session_disable` | Disable radar for the session. Called by `/radar-disable` skill. |
+
+## Architecture
+
+```
+Mobile debug build (device)
+  +-- Local socket (platform-specific)
+        +-- HTTP endpoints + SSE streaming
+              |
+              | port forwarding (adb forward / iproxy / etc.)
+              |
+MCP server (Node.js, runs on developer machine)
+  +-- DeviceTransport (AndroidTransport, future: IosTransport)
+  +-- Stdio transport -> Claude Code
+        +-- 16 tools: ping, network, rtm, clogs, search, ...
+```
+
+All device-specific logic lives behind the `DeviceTransport` interface (`src/transport.ts`). The MCP server, tools, SSE streaming, and session management are fully platform-agnostic.
+
+**Adding a new platform**: implement `DeviceTransport` in `src/<platform>.ts`, add a case to `createTransport()` in `src/index.ts`. No other files change.
+
+## Security
+
+* **No TCP port on device.** Uses platform-specific local sockets, only reachable via port forwarding. Requires physical USB or explicit debug pairing.
+* **Debug builds only.** Release builds bind a no-op implementation. Server code is eliminated at compile time.
+* **Lazy activation.** Dormant until explicitly triggered.
+* **Auto-shutdown.** Device-side server shuts down after idle timeout (default 5 minutes). Zero cost when unused.
+
+## Data Capture
+
+What gets captured depends on the in-app server implementation. The MCP server is agnostic to the data source. The Android implementation captures:
+
+* **Network calls**: OkHttp interceptor. Ring buffer: 200 calls.
+* **RTM events**: WebSocket listener. Ring buffer: 500 events.
+* **Clogs**: Analytics interceptor. Ring buffer: 500 events. Persists across radar activation cycles.
+
+All data is in-memory only. No disk writes.
+
+### What gets captured, in detail
+
+This tool captures unredacted network traffic from your debug Slack build, including:
+
+* URL query parameters (tokens can appear here)
+* `Authorization` headers and cookies
+* `Set-Cookie` response headers (session tokens)
+* Request and response bodies, up to 64 KB per body, for JSON, form, text, and XML content types
+* RTM WebSocket payloads (every sent and received message)
+* Analytics (clog) events serialized as JSON
+* Screenshots and short screen recordings on demand
+* Logcat entries filtered by tag
+
+Auth tokens and session cookies will appear in captured data. Captured data flows to your MCP client (Claude Code), which may send relevant portions to the configured AI provider per its own data handling policy.
+
+### Use against workspaces you are signed into as yourself
+
+The tool is intended for debugging the Slack Android app against your own sessions. Do not share captured data (screenshots, log exports, tool transcripts) externally without first redacting auth material. Treat anything radar captures with the same care you would treat a `curl` transcript of an authenticated API call.
+
+## Local Development
+
+```bash
+npm install
+npm run build        # Compile TypeScript to dist/
+npm start            # Run the server (stdio transport)
+npm run watch        # TypeScript compiler in watch mode
+npm test             # Unit tests
+npm run test:smoke   # Smoke tests
+npm run test:all     # Both
+```
+
+## Troubleshooting
+
+**"ADB port forwarding failed"**
+Ensure a device is connected (`adb devices` should show exactly one device). If using wireless debug, confirm the pairing is active.
+
+**"Radar not responding"**
+The device-side server may have auto-shut down. Use `/radar-enable` to restart it.
+
+**"Session disabled"**
+Two consecutive connection failures disable the session. Use `/radar-enable` to reconnect.
+
+**Work profile devices**
+The MCP server auto-detects the Android user ID via `ps` and targets the broadcast accordingly. No manual `--user` flag needed.
+
+**Tools not appearing after setup**
+Restart your Claude Code session. MCP servers are registered at session start.

package/dist/android.d.ts

@@ -0,0 +1,25 @@
+import type { DeviceTransport } from "./transport.js";
+/**
+ * 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.
+ */
+export declare function parseUserFromPsOutput(psOutput: string): string;
+export declare class AndroidTransport implements DeviceTransport {
+    readonly platform = "android";
+    private portForwarded;
+    private detectedUserId;
+    private currentTimeoutMinutes;
+    private radarEnabled;
+    ensureForward(): boolean;
+    activate(timeoutMinutes: number): void;
+    resetState(): void;
+    isForwarded(): boolean;
+    getTimeoutMinutes(): number;
+    screenshot(fullRes: boolean): string;
+    recordScreen(durationS: number): string;
+    getAppState(): string;
+    getRecentLogs(tag: string, limit: number, grep?: string): string[];
+    private detectDebugBuildUser;
+}

package/dist/android.js

@@ -0,0 +1,127 @@
+import { execSync } from "child_process";
+import os from "os";
+import path from "path";
+const RADAR_PORT = 8099;
+const SOCKET_NAME = "slack-radar";
+const ENABLE_ACTION = "slack.debug.ENABLE_RADAR";
+/**
+ * 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.
+ */
+export function parseUserFromPsOutput(psOutput) {
+    if (!psOutput || !psOutput.trim())
+        return "0";
+    const lines = psOutput.trim().split("\n");
+    // Collect all user IDs from matching lines
+    const userIds = [];
+    for (const line of lines) {
+        const match = line.match(/u(\d+)_/);
+        if (match)
+            userIds.push(match[1]);
+    }
+    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];
+}
+export class AndroidTransport {
+    platform = "android";
+    portForwarded = false;
+    detectedUserId = null;
+    currentTimeoutMinutes = 5;
+    radarEnabled = false;
+    ensureForward() {
+        if (this.portForwarded)
+            return true;
+        try {
+            execSync(`adb forward tcp:${RADAR_PORT} localabstract:${SOCKET_NAME}`, {
+                timeout: 5000,
+            });
+            this.portForwarded = true;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    activate(timeoutMinutes) {
+        const timeout = timeoutMinutes || this.currentTimeoutMinutes;
+        if (this.radarEnabled && timeout === this.currentTimeoutMinutes)
+            return;
+        try {
+            const userId = this.detectDebugBuildUser();
+            execSync(`adb shell am broadcast --user ${userId} -a ${ENABLE_ACTION} --ei timeout_minutes ${timeout}`, { timeout: 5000 });
+            this.currentTimeoutMinutes = timeout;
+            this.radarEnabled = true;
+        }
+        catch {
+            // Broadcast failed — device may not be connected
+        }
+    }
+    resetState() {
+        this.portForwarded = false;
+        this.detectedUserId = null;
+        this.radarEnabled = false;
+    }
+    isForwarded() {
+        return this.portForwarded;
+    }
+    getTimeoutMinutes() {
+        return this.currentTimeoutMinutes;
+    }
+    screenshot(fullRes) {
+        const tmpFile = path.join(os.tmpdir(), `slack-radar-screenshot-${Date.now()}.png`);
+        const devicePath = "/data/local/tmp/slack-radar-screenshot.png";
+        execSync(`adb shell screencap -p ${devicePath}`, { timeout: 10000 });
+        execSync(`adb pull ${devicePath} "${tmpFile}"`, { timeout: 10000 });
+        execSync(`adb shell rm ${devicePath}`, { timeout: 5000 });
+        if (!fullRes) {
+            try {
+                execSync(`sips -Z 720 "${tmpFile}" 2>/dev/null`, { timeout: 5000 });
+            }
+            catch {
+                // Resize failed; keep full res
+            }
+        }
+        return tmpFile;
+    }
+    recordScreen(durationS) {
+        const duration = Math.min(Math.max(durationS, 1), 30);
+        const tmpFile = path.join(os.tmpdir(), `slack-radar-recording-${Date.now()}.mp4`);
+        const devicePath = "/data/local/tmp/slack-radar-recording.mp4";
+        execSync(`adb shell screenrecord --time-limit ${duration} --size 720x1280 ${devicePath}`, { timeout: (duration + 5) * 1000 });
+        execSync(`adb pull ${devicePath} "${tmpFile}"`, { timeout: 10000 });
+        execSync(`adb shell rm ${devicePath}`, { timeout: 5000 });
+        return tmpFile;
+    }
+    getAppState() {
+        return execSync(`adb shell "dumpsys activity activities | grep -A 5 'com.Slack.internal'"`, { timeout: 10000, encoding: "utf-8" }).trim();
+    }
+    getRecentLogs(tag, limit, grep) {
+        let cmd = `adb logcat -d | grep -F "${tag}" | tail -${limit}`;
+        if (grep) {
+            cmd = `adb logcat -d | grep -F "${tag}" | grep -i "${grep.replace(/"/g, '\\"')}" | tail -${limit}`;
+        }
+        const output = execSync(cmd, {
+            timeout: 10000,
+            shell: "/bin/zsh",
+            encoding: "utf-8",
+        });
+        return output.trim().split("\n").filter(Boolean);
+    }
+    detectDebugBuildUser() {
+        if (this.detectedUserId !== null)
+            return this.detectedUserId;
+        try {
+            const ps = execSync(`adb shell "ps -A -o USER,NAME 2>/dev/null | grep Slack | grep debug"`, { timeout: 5000, encoding: "utf-8" }).trim();
+            this.detectedUserId = parseUserFromPsOutput(ps);
+        }
+        catch {
+            this.detectedUserId = "0";
+        }
+        return this.detectedUserId;
+    }
+}

package/dist/constants.d.ts

@@ -0,0 +1,6 @@
+/** Port used to reach the on-device radar HTTP server via forwarding. */
+export declare const RADAR_PORT = 8099;
+/** Host address for the forwarded connection. */
+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;

package/dist/constants.js

@@ -0,0 +1,6 @@
+/** Port used to reach the on-device radar HTTP server via forwarding. */
+export const RADAR_PORT = 8099;
+/** Host address for the forwarded connection. */
+export const RADAR_HOST = "127.0.0.1";
+/** Max events to retain in each local SSE buffer. */
+export const MAX_LOCAL_BUFFER = 500;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import fs from "fs";
+import http from "http";
+import { AndroidTransport } from "./android.js";
+import { RADAR_HOST, RADAR_PORT } from "./constants.js";
+import { connectStream, destroyStream, waitForEvents, clearLocalBuffers, isStreamConnected, localNetworkBuffer, localRtmBuffer, setTransport, } from "./stream.js";
+import { TOOL_DEFINITIONS, SERVER_INSTRUCTIONS } from "./tools.js";
+// --- Platform selection ---
+function createTransport() {
+    const platformArg = process.argv.find((a) => a.startsWith("--platform="));
+    const platform = platformArg?.split("=")[1] ?? "android";
+    switch (platform) {
+        case "android":
+            return new AndroidTransport();
+        default:
+            throw new Error(`Unsupported platform: ${platform}. Supported: android`);
+    }
+}
+const device = createTransport();
+setTransport(device);
+let sessionEnabled = false;
+function radarRequest(requestPath) {
+    return new Promise((resolve, reject) => {
+        const req = http.get({
+            host: RADAR_HOST,
+            port: RADAR_PORT,
+            path: requestPath,
+            timeout: 10000,
+        }, (res) => {
+            let data = "";
+            res.on("data", (chunk) => {
+                data += chunk;
+            });
+            res.on("end", () => {
+                try {
+                    resolve(JSON.parse(data));
+                }
+                catch {
+                    resolve({ raw: data });
+                }
+            });
+        });
+        req.on("error", reject);
+        req.on("timeout", () => {
+            req.destroy();
+            reject(new Error("Request timed out"));
+        });
+    });
+}
+async function callRadar(requestPath) {
+    if (!device.ensureForward()) {
+        return {
+            error: "Port forwarding failed. Ensure a device is connected and the debug build is running.",
+        };
+    }
+    device.activate(device.getTimeoutMinutes());
+    connectStream();
+    try {
+        return await radarRequest(requestPath);
+    }
+    catch {
+        device.resetState();
+        destroyStream();
+        if (!device.ensureForward()) {
+            sessionEnabled = false;
+            return {
+                error: "Device not connected or radar not running. Session disabled. Use /radar-enable to reconnect.",
+            };
+        }
+        device.activate(device.getTimeoutMinutes());
+        connectStream();
+        try {
+            return await radarRequest(requestPath);
+        }
+        catch (e2) {
+            sessionEnabled = false;
+            return {
+                error: `Radar not responding: ${e2.message}. Session disabled. Use /radar-enable to reconnect.`,
+            };
+        }
+    }
+}
+function textResult(data, isError = false) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: typeof data === "string" ? data : JSON.stringify(data, null, 2),
+            },
+        ],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+// --- Tool handlers ---
+async function handleSessionEnable(args) {
+    const timeout = args?.timeout_minutes || 5;
+    sessionEnabled = true;
+    const forwarded = device.ensureForward();
+    if (!forwarded) {
+        sessionEnabled = false;
+        return textResult({
+            error: "Port forwarding failed. Ensure a device is connected.",
+            enabled: false,
+            platform: device.platform,
+        }, true);
+    }
+    device.activate(timeout);
+    connectStream();
+    await new Promise((r) => setTimeout(r, 500));
+    try {
+        const status = await radarRequest("/api/ping");
+        return textResult({
+            enabled: true,
+            platform: device.platform,
+            stream_connected: isStreamConnected(),
+            ...status,
+        });
+    }
+    catch {
+        return textResult({
+            enabled: true,
+            platform: device.platform,
+            stream_connected: isStreamConnected(),
+            ping: "failed",
+            note: "Radar activated but ping failed. Device may need a moment.",
+        });
+    }
+}
+function handleSessionDisable() {
+    sessionEnabled = false;
+    destroyStream();
+    clearLocalBuffers();
+    return textResult({
+        enabled: false,
+        note: "Radar disabled. Use /radar-enable to reconnect.",
+    });
+}
+async function handleWaitForEvents(args) {
+    if (!isStreamConnected()) {
+        if (!device.ensureForward()) {
+            return textResult({ error: "Not connected. Ensure device is connected and radar is enabled." }, true);
+        }
+        device.activate(device.getTimeoutMinutes());
+        connectStream();
+        await new Promise((r) => setTimeout(r, 1000));
+    }
+    const events = await waitForEvents({
+        event_type: args?.event_type,
+        channel: args?.channel,
+        source: args?.source,
+        timeout_ms: args?.timeout_ms,
+        idle_timeout_ms: args?.idle_timeout_ms,
+    });
+    return textResult({
+        event_count: events.length,
+        events,
+        stream_connected: isStreamConnected(),
+    });
+}
+function handleGetAppState() {
+    try {
+        const output = device.getAppState();
+        return textResult(output);
+    }
+    catch (e) {
+        return textResult({ error: `App state query failed: ${e.message}` }, true);
+    }
+}
+function handleGetRecentLogs(args) {
+    try {
+        const lines = device.getRecentLogs(args.tag, args.limit || 50, args.grep);
+        return textResult({ tag: args.tag, lines, count: lines.length });
+    }
+    catch (e) {
+        return textResult({ error: `Log query failed: ${e.message}`, lines: [] }, true);
+    }
+}
+function handleScreenshot(args) {
+    try {
+        const fullRes = args?.full_res === true;
+        const tmpFile = device.screenshot(fullRes);
+        const stats = fs.statSync(tmpFile);
+        return textResult({
+            file: tmpFile,
+            size_bytes: stats.size,
+            full_res: fullRes,
+            hint: "Use the Read tool to view this image.",
+        });
+    }
+    catch (e) {
+        return textResult({ error: `Screenshot failed: ${e.message}` }, true);
+    }
+}
+function handleRecordScreen(args) {
+    try {
+        const duration = Math.min(Math.max(args?.duration_s || 5, 1), 30);
+        const tmpFile = device.recordScreen(duration);
+        const stats = fs.statSync(tmpFile);
+        return textResult({
+            file: tmpFile,
+            size_bytes: stats.size,
+            duration_s: duration,
+        });
+    }
+    catch (e) {
+        return textResult({ error: `Recording failed: ${e.message}` }, true);
+    }
+}
+async function handleClearBuffers() {
+    clearLocalBuffers();
+    const result = await callRadar("/api/clear");
+    return textResult(result, !!result.error);
+}
+async function handlePing(args) {
+    if (args?.timeout_minutes) {
+        device.activate(args.timeout_minutes);
+    }
+    const result = await callRadar("/api/ping");
+    if (!result.error) {
+        result.stream_connected = isStreamConnected();
+        result.local_network_buffer = localNetworkBuffer.length;
+        result.local_rtm_buffer = localRtmBuffer.length;
+        result.timeout_minutes = device.getTimeoutMinutes();
+        result.platform = device.platform;
+    }
+    return textResult(result, !!result.error);
+}
+function buildApiPath(name, args) {
+    switch (name) {
+        case "get_recent_network_calls": {
+            const a = args;
+            const params = new URLSearchParams();
+            if (a?.limit)
+                params.set("limit", String(a.limit));
+            if (a?.url_filter)
+                params.set("url_filter", a.url_filter);
+            if (a?.status_code)
+                params.set("status_code", String(a.status_code));
+            const qs = params.toString();
+            return `/api/network${qs ? "?" + qs : ""}`;
+        }
+        case "get_network_call_detail": {
+            const a = args;
+            return `/api/network/${a.id}`;
+        }
+        case "get_recent_rtm_events": {
+            const a = args;
+            const params = new URLSearchParams();
+            if (a?.limit)
+                params.set("limit", String(a.limit));
+            if (a?.event_type)
+                params.set("event_type", a.event_type);
+            if (a?.direction)
+                params.set("direction", a.direction);
+            if (a?.channel)
+                params.set("channel", a.channel);
+            const qs = params.toString();
+            return `/api/rtm${qs ? "?" + qs : ""}`;
+        }
+        case "get_rtm_event_detail": {
+            const a = args;
+            return `/api/rtm/${a.id}`;
+        }
+        case "get_recent_clogs": {
+            const a = args;
+            const params = new URLSearchParams();
+            if (a?.limit)
+                params.set("limit", String(a.limit));
+            if (a?.name)
+                params.set("name", a.name);
+            const qs = params.toString();
+            return `/api/clogs${qs ? "?" + qs : ""}`;
+        }
+        case "get_clog_detail": {
+            const a = args;
+            return `/api/clogs/${a.id}`;
+        }
+        case "search": {
+            const a = args;
+            const params = new URLSearchParams();
+            params.set("q", a.query);
+            if (a?.limit)
+                params.set("limit", String(a.limit));
+            return `/api/search?${params.toString()}`;
+        }
+        default:
+            return null;
+    }
+}
+// --- MCP Server ---
+const server = new Server({ name: "slack-radar", version: "1.1.0" }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOL_DEFINITIONS,
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request, _extra) => {
+    const { name, arguments: args } = request.params;
+    const toolArgs = (args ?? {});
+    if (name === "_radar_session_enable") {
+        return handleSessionEnable(toolArgs);
+    }
+    if (name === "_radar_session_disable") {
+        return handleSessionDisable();
+    }
+    if (!sessionEnabled && name !== "ping") {
+        return textResult({
+            error: "Radar is not active. Use /radar-enable to connect, or ask about the device to auto-enable.",
+        }, true);
+    }
+    if (name === "wait_for_events") {
+        return handleWaitForEvents(toolArgs);
+    }
+    if (name === "get_app_state") {
+        return handleGetAppState();
+    }
+    if (name === "get_recent_logs") {
+        return handleGetRecentLogs(toolArgs);
+    }
+    if (name === "screenshot") {
+        return handleScreenshot(toolArgs);
+    }
+    if (name === "record_screen") {
+        return handleRecordScreen(toolArgs);
+    }
+    if (name === "clear_buffers") {
+        return handleClearBuffers();
+    }
+    if (name === "ping") {
+        return handlePing(toolArgs);
+    }
+    const apiPath = buildApiPath(name, toolArgs);
+    if (apiPath === null) {
+        return textResult(`Unknown tool: ${name}`, true);
+    }
+    const result = await callRadar(apiPath);
+    return textResult(result, !!result.error);
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/stream.d.ts

@@ -0,0 +1,31 @@
+import http from "http";
+import type { DeviceTransport } from "./transport.js";
+/** Set the transport used to check forwarding state. Call once at startup. */
+export declare function setTransport(t: DeviceTransport): void;
+export interface RadarEvent {
+    [key: string]: unknown;
+}
+export interface ParsedSSE {
+    type: "network" | "rtm";
+    event: RadarEvent;
+}
+export declare const localNetworkBuffer: RadarEvent[];
+export declare const localRtmBuffer: RadarEvent[];
+export declare function isStreamConnected(): boolean;
+export declare function clearLocalBuffers(): void;
+export declare function getStreamConnection(): http.ClientRequest | null;
+export declare function destroyStream(): void;
+/**
+ * Push an event into the appropriate local buffer, enforcing MAX_LOCAL_BUFFER.
+ * Exported for testability.
+ */
+export declare function bufferEvent(parsed: ParsedSSE): void;
+export interface WaitForEventsArgs {
+    event_type?: string;
+    channel?: string;
+    source?: string;
+    timeout_ms?: number;
+    idle_timeout_ms?: number;
+}
+export declare function waitForEvents({ event_type, channel, source, timeout_ms, idle_timeout_ms, }: WaitForEventsArgs): Promise<RadarEvent[]>;
+export declare function connectStream(): void;

package/dist/stream.js

@@ -0,0 +1,137 @@
+import http from "http";
+import { RADAR_HOST, RADAR_PORT, MAX_LOCAL_BUFFER } from "./constants.js";
+let transport = null;
+/** Set the transport used to check forwarding state. Call once at startup. */
+export function setTransport(t) {
+    transport = t;
+}
+export const localNetworkBuffer = [];
+export const localRtmBuffer = [];
+let streamConnection = null;
+let streamConnected = false;
+const eventWaiters = [];
+export function isStreamConnected() {
+    return streamConnected;
+}
+export function clearLocalBuffers() {
+    localNetworkBuffer.length = 0;
+    localRtmBuffer.length = 0;
+}
+export function getStreamConnection() {
+    return streamConnection;
+}
+export function destroyStream() {
+    if (streamConnection) {
+        streamConnection.destroy();
+        streamConnection = null;
+        streamConnected = false;
+    }
+}
+/**
+ * Push an event into the appropriate local buffer, enforcing MAX_LOCAL_BUFFER.
+ * Exported for testability.
+ */
+export function bufferEvent(parsed) {
+    if (parsed.type === "network") {
+        localNetworkBuffer.push(parsed.event);
+        if (localNetworkBuffer.length > MAX_LOCAL_BUFFER)
+            localNetworkBuffer.shift();
+    }
+    else if (parsed.type === "rtm") {
+        localRtmBuffer.push(parsed.event);
+        if (localRtmBuffer.length > MAX_LOCAL_BUFFER)
+            localRtmBuffer.shift();
+    }
+    notifyWaiters(parsed);
+}
+function notifyWaiters(parsed) {
+    for (const waiter of eventWaiters) {
+        const e = parsed.event;
+        const eventType = e.event_type;
+        const channel = e.channel;
+        const matchesType = !waiter.eventType ||
+            (eventType && eventType.toLowerCase() === waiter.eventType.toLowerCase());
+        const matchesChannel = !waiter.channel ||
+            (channel && channel.toLowerCase() === waiter.channel.toLowerCase());
+        const matchesSource = !waiter.source || parsed.type === waiter.source;
+        if (matchesType && matchesChannel && matchesSource) {
+            waiter.matches.push(e);
+            waiter.lastMatchTime = Date.now();
+            if (waiter.idleTimer)
+                clearTimeout(waiter.idleTimer);
+            waiter.idleTimer = setTimeout(() => {
+                waiter.resolve(waiter.matches);
+            }, waiter.idleTimeoutMs);
+        }
+    }
+}
+export function waitForEvents({ event_type, channel, source, timeout_ms = 30000, idle_timeout_ms = 3000, }) {
+    return new Promise((resolve) => {
+        const waiter = {
+            eventType: event_type,
+            channel,
+            source,
+            idleTimeoutMs: idle_timeout_ms,
+            matches: [],
+            lastMatchTime: null,
+            idleTimer: null,
+            resolve: (result) => {
+                cleanup();
+                resolve(result);
+            },
+        };
+        function cleanup() {
+            const idx = eventWaiters.indexOf(waiter);
+            if (idx >= 0)
+                eventWaiters.splice(idx, 1);
+            if (waiter.idleTimer)
+                clearTimeout(waiter.idleTimer);
+            if (maxTimer)
+                clearTimeout(maxTimer);
+        }
+        eventWaiters.push(waiter);
+        const maxTimer = setTimeout(() => {
+            waiter.resolve(waiter.matches);
+        }, timeout_ms);
+    });
+}
+export function connectStream() {
+    if (streamConnection || !transport?.isForwarded())
+        return;
+    const req = http.get({ host: RADAR_HOST, port: RADAR_PORT, path: "/api/stream", timeout: 0 }, (res) => {
+        streamConnected = true;
+        let partial = "";
+        res.on("data", (chunk) => {
+            partial += chunk.toString();
+            const lines = partial.split("\n");
+            partial = lines.pop();
+            for (const line of lines) {
+                if (!line.startsWith("data: "))
+                    continue;
+                try {
+                    const parsed = JSON.parse(line.slice(6));
+                    bufferEvent(parsed);
+                }
+                catch {
+                    // Malformed SSE line — skip
+                }
+            }
+        });
+        res.on("end", () => {
+            streamConnection = null;
+            streamConnected = false;
+            setTimeout(connectStream, 2000);
+        });
+        res.on("error", () => {
+            streamConnection = null;
+            streamConnected = false;
+            setTimeout(connectStream, 2000);
+        });
+    });
+    req.on("error", () => {
+        streamConnection = null;
+        streamConnected = false;
+        setTimeout(connectStream, 2000);
+    });
+    streamConnection = req;
+}

package/dist/tools.d.ts

@@ -0,0 +1,22 @@
+export declare const SERVER_INSTRUCTIONS: string;
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+export declare const TOOL_DEFINITIONS: ToolDefinition[];
+/**
+ * Check whether a tool call should be blocked by the session gate.
+ * Returns an error response object if blocked, or null if allowed.
+ */
+export declare function sessionGate(toolName: string, sessionEnabled: boolean): {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    isError: boolean;
+} | null;

package/dist/tools.js

@@ -0,0 +1,231 @@
+export const SERVER_INSTRUCTIONS = [
+    "Slack Radar provides on-device debugging tools for the Slack Android app via ADB.",
+    "",
+    "SESSION STATE:",
+    "Radar starts DISABLED each session. All tools except ping return an error until enabled.",
+    "Use /radar-enable to activate, /radar-disable to deactivate.",
+    "",
+    "AUTO-ENABLE: When the user asks an obvious device question, invoke the Skill tool with",
+    'skill="radar-enable" FIRST, then proceed with the radar tool call. No need to ask.',
+    "Obvious device questions include: clogs, network calls, RTM events, screenshots,",
+    "app state, device logs, or any reference to what is happening on the connected device.",
+    "",
+    "TIMEOUT: The device-side radar auto-shuts down after idle. On tool call failure,",
+    "the session flips to disabled. Tell the user and offer to re-enable.",
+    "",
+    "When to use:",
+    '- "what am I looking at" / "what screen is this" -> screenshot',
+    '- "what just happened" / "what\'s going on" -> get_recent_network_calls + get_recent_rtm_events',
+    '- "why isn\'t this loading" / "this is broken" -> screenshot + get_recent_network_calls(status_code=400 or 500)',
+    '- "watch what happens when I..." -> clear_buffers then wait_for_events (DO NOT filter unless the user specifies a type)',
+    '- "did that clog fire" / "check analytics" -> get_recent_clogs(name="...")',
+    '- "what API call was that" -> get_recent_network_calls then get_network_call_detail',
+    '- "did I get X" / "did X happen" -> search(query="X") across ALL buffers, not just one',
+    '- "check the debug logs" -> get_recent_logs(tag="...")',
+    "",
+    "Key behaviors:",
+    "- Network/RTM buffers clear on shutdown. Clogs persist from app start.",
+    "- If ping fails, do NOT retry. Tell the user and fall back to code-only analysis.",
+    "- Fetch details eagerly. When results reveal interesting events, get their detail immediately.",
+    "- 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.",
+    "- Screenshots default to 720px. Use full_res=true only when detail matters.",
+    "- Setup: /slack-radar-setup",
+].join("\n");
+export const TOOL_DEFINITIONS = [
+    {
+        name: "ping",
+        description: "Check if Slack Radar is running. Returns uptime, buffer sizes, remaining session time, and stream status.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                timeout_minutes: {
+                    type: "number",
+                    description: "Set or extend the auto-shutdown timeout in minutes (default: 5).",
+                },
+            },
+        },
+    },
+    {
+        name: "get_recent_network_calls",
+        description: "Get recent HTTP network calls captured from the Slack Android app.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: { type: "number", description: "Max number of calls to return (default: 50)" },
+                url_filter: { type: "string", description: "Filter calls by URL substring" },
+                status_code: { type: "number", description: "Filter by HTTP status code" },
+            },
+        },
+    },
+    {
+        name: "get_network_call_detail",
+        description: "Get full details of a specific network call by ID, including request/response headers and bodies.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "number", description: "The call ID from get_recent_network_calls" },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        name: "get_recent_rtm_events",
+        description: "Get recent RTM (Real Time Messaging) event summaries.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: { type: "number", description: "Max number of events to return (default: 50)" },
+                event_type: { type: "string", description: "Filter by event type/subtype" },
+                direction: { type: "string", description: "Filter by event direction" },
+                channel: { type: "string", description: "Filter by channel ID" },
+            },
+        },
+    },
+    {
+        name: "get_rtm_event_detail",
+        description: "Get full details of a specific RTM event by ID, including the complete JSON payload.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "number", description: "The event ID from get_recent_rtm_events" },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        name: "get_recent_clogs",
+        description: "Get recent clog (analytics) event summaries. Returns event name and timestamp. Use get_clog_detail for the full JSON payload.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: { type: "number", description: "Max number of clogs to return (default: 50)" },
+                name: { type: "string", description: "Filter by event name substring" },
+            },
+        },
+    },
+    {
+        name: "get_clog_detail",
+        description: "Get full details of a specific clog event by ID, including the complete JSON payload.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "number", description: "The clog ID from get_recent_clogs" },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        name: "wait_for_events",
+        description: "Wait for matching events to arrive in real-time via the SSE stream.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                event_type: { type: "string", description: "RTM event type to wait for" },
+                channel: { type: "string", description: "Filter by channel ID" },
+                source: { type: "string", description: "Wait for network calls or RTM events (default: both)" },
+                timeout_ms: { type: "number", description: "Max time to wait in ms (default: 30000)" },
+                idle_timeout_ms: { type: "number", description: "Resolve after this many ms of silence (default: 3000)" },
+            },
+        },
+    },
+    {
+        name: "search",
+        description: "Search across all captured network calls and RTM events.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Search term" },
+                limit: { type: "number", description: "Max results per category (default: 20)" },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "get_app_state",
+        description: "Get the current app state from the device.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "get_recent_logs",
+        description: "Get recent logcat entries from the connected device, filtered by tag.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                tag: { type: "string", description: "Logcat tag to filter by" },
+                limit: { type: "number", description: "Max number of lines to return (default: 50)" },
+                grep: { type: "string", description: "Optional text to grep within the filtered output" },
+            },
+            required: ["tag"],
+        },
+    },
+    {
+        name: "screenshot",
+        description: "Capture a screenshot from the connected Android device.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                full_res: { type: "boolean", description: "Capture at full resolution (default: false)" },
+            },
+        },
+    },
+    {
+        name: "record_screen",
+        description: "Record a short screen video from the connected Android device.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                duration_s: { type: "number", description: "Recording duration in seconds (default: 5, max: 30)" },
+            },
+        },
+    },
+    {
+        name: "clear_buffers",
+        description: "Clear all captured network calls and RTM events from both device and local buffers.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "_radar_session_enable",
+        description: "Enable Slack Radar for this session. Sets up ADB forwarding, activates the device-side server, and connects the SSE stream. Called by /radar-enable skill.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                timeout_minutes: { type: "number", description: "Device-side auto-shutdown timeout in minutes (default: 5)" },
+            },
+        },
+    },
+    {
+        name: "_radar_session_disable",
+        description: "Disable Slack Radar for this session. Tears down the SSE stream and clears local buffers. Called by /radar-disable skill.",
+        inputSchema: { type: "object", properties: {} },
+    },
+];
+/**
+ * Check whether a tool call should be blocked by the session gate.
+ * Returns an error response object if blocked, or null if allowed.
+ */
+export function sessionGate(toolName, sessionEnabled) {
+    // Session enable/disable are always allowed
+    if (toolName === "_radar_session_enable" || toolName === "_radar_session_disable") {
+        return null;
+    }
+    // ping is allowed even when disabled
+    if (toolName === "ping") {
+        return null;
+    }
+    if (!sessionEnabled) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: "Radar is not active. Use /radar-enable to connect, or ask about the device to auto-enable.",
+                    }),
+                },
+            ],
+            isError: true,
+        };
+    }
+    return null;
+}

package/dist/transport.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Platform-agnostic interface for device communication.
+ *
+ * Each platform (Android, iOS) implements this interface to handle
+ * port forwarding, server activation, screenshots, logs, and other
+ * device-specific operations. The MCP server and tool handlers
+ * interact only through this interface.
+ */
+export interface DeviceTransport {
+    /** Human-readable platform name (e.g. "android", "ios"). */
+    readonly platform: string;
+    /**
+     * Set up port forwarding so the device's radar HTTP server is
+     * reachable at localhost:RADAR_PORT. Returns true on success.
+     */
+    ensureForward(): boolean;
+    /**
+     * Activate the on-device radar server. May be a no-op if the
+     * platform activates automatically.
+     *
+     * @param timeoutMinutes Auto-shutdown timeout in minutes
+     */
+    activate(timeoutMinutes: number): void;
+    /** Reset all connection state (forwarding, activation, caches). */
+    resetState(): void;
+    /** Whether forwarding has been established. */
+    isForwarded(): boolean;
+    /** Current auto-shutdown timeout in minutes. */
+    getTimeoutMinutes(): number;
+    /**
+     * Capture a screenshot from the connected device.
+     * Returns the local file path to the saved image.
+     *
+     * @param fullRes If true, capture at full resolution
+     */
+    screenshot(fullRes: boolean): string;
+    /**
+     * Record a short screen video from the connected device.
+     * Returns the local file path to the saved video.
+     *
+     * @param durationS Recording duration in seconds
+     */
+    recordScreen(durationS: number): string;
+    /**
+     * Get the current app state from the device (visible screens,
+     * fragments, arguments, etc.). Returns a human-readable string.
+     */
+    getAppState(): string;
+    /**
+     * Get recent log entries filtered by tag.
+     *
+     * @param tag Log tag to filter by
+     * @param limit Max number of lines
+     * @param grep Optional text to further filter
+     * @returns Array of matching log lines
+     */
+    getRecentLogs(tag: string, limit: number, grep?: string): string[];
+}

package/dist/transport.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@slack/radar-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for on-device debugging of the Slack Android app via ADB",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "slack-radar-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean",
+    "build": "tsc && chmod +x dist/index.js",
+    "start": "node dist/index.js",
+    "watch": "tsc --watch",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "test:smoke": "npm run build && bash tests/smoke.sh",
+    "test:all": "npm run test && npm run test:smoke",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "slack",
+    "android",
+    "debugging",
+    "adb"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://slack-github.com/slack/slack-radar-mcp"
+  },
+  "bugs": {
+    "url": "https://slack-github.com/slack/slack-radar-mcp/issues"
+  },
+  "homepage": "https://slack-github.com/slack/slack-radar-mcp#readme",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.2"
+  }
+}