# shadow-monitor-mcp

Open-source **MCP server** that lets **any AI agent** inspect [Shadow Monitor](https://chromewebstore.google.com/detail/shadow-monitor/medbegkecifnhagdgfionmfmpcacheib) capture files (`uat-report-*.json.gz`) — locally, with no upload.

Works with **any client that speaks [MCP](https://modelcontextprotocol.io)** over stdio: Cursor, Claude Desktop, Claude Code, Windsurf, VS Code Copilot Chat, Continue, Cline, Zed, and others.

```
Shadow Monitor (Chrome) records a UAT session
              ↓
     you download uat-report-….json.gz
              ↓
   this MCP server loads it for your AI
```

| | |
| --- | --- |
| **npm** | [`shadow-monitor-mcp`](https://www.npmjs.com/package/shadow-monitor-mcp) · `npx -y shadow-monitor-mcp` |
| **GitHub** | [`yurii-mandzii/shadow-monitor-mcp`](https://github.com/yurii-mandzii/shadow-monitor-mcp) |
| **Claude one-click** | [`shadow-monitor-mcp.mcpb`](https://github.com/yurii-mandzii/shadow-monitor-mcp/releases/latest/download/shadow-monitor-mcp.mcpb) ([all releases](https://github.com/yurii-mandzii/shadow-monitor-mcp/releases)) |
| **Agent Skill** | [`SKILL.md`](./SKILL.md) (optional — teaches the agent *when* to call the tools) |
| **License** | MIT |
| **Needs** | [Node.js 20+](https://nodejs.org/) for the MCP (Chrome extension is separate) |

---

## Companion: Shadow Monitor (Chrome extension)

This MCP does **not** record the browser. Capture comes from the extension:

| | |
| --- | --- |
| **Chrome Web Store** | [Shadow Monitor](https://chromewebstore.google.com/detail/shadow-monitor/medbegkecifnhagdgfionmfmpcacheib) |
| **User guide** | [Guide](https://yurii-mandzii.github.io/shadow-monitor/guide/) |
| **Homepage** | [Docs site](https://yurii-mandzii.github.io/shadow-monitor/) |
| **Source** | [github.com/yurii-mandzii/shadow-monitor](https://github.com/yurii-mandzii/shadow-monitor) |
| **Support / Privacy** | [Support](https://yurii-mandzii.github.io/shadow-monitor/support/) · [Privacy](https://yurii-mandzii.github.io/shadow-monitor/privacy/) |

1. Install the extension → add your UAT domain in Settings.
2. Hard-reload the tab (**Cmd/Ctrl+Shift+R**).
3. Reproduce the bug → **Download** → get `uat-report-*.json.gz` (often under `Downloads/uat-capture`).

---

## MCP vs Skill (what you need)

| Piece | What it is | Required? |
| --- | --- | --- |
| **MCP server** | The actual tools (`load_bundle`, `find_errors`, …) | **Yes** — without it the agent cannot inspect the file |
| **Agent Skill** | A short playbook (`SKILL.md`) that says “when the user pastes a `uat-report-*.json.gz`, call `load_bundle` — don’t raw-read the file” | **No** — but strongly recommended so the agent behaves correctly |

You can install them **together** (Option A) or **separately** (MCP via UI / `.mcpb`, skill via `init` or copy).

---

## Install the MCP

You need **Node.js 20+** once ([download the LTS installer](https://nodejs.org/) — click through; no coding required).

### Option A — One command (MCP + skill together)

Open Terminal / PowerShell, paste, Enter:

```bash
npx -y shadow-monitor-mcp init --client all
```

Registers the server for Claude Desktop + Cursor + Claude Code **and** installs the Agent Skill. Then restart your AI app (Claude Desktop: fully quit with **Cmd+Q**).

Only one app? Use `--client cursor`, `--client desktop`, or `--client claude-code`.

### Option B — UI / click (MCP only)

#### Claude Desktop — one-click `.mcpb`

1. Download **[shadow-monitor-mcp.mcpb](https://github.com/yurii-mandzii/shadow-monitor-mcp/releases/latest/download/shadow-monitor-mcp.mcpb)**
2. Double-click it, **or** Claude Desktop → **Settings → Extensions → Install Extension…**

#### Any MCP client — paste JSON

```json
{
  "mcpServers": {
    "shadow-monitor": {
      "command": "npx",
      "args": ["-y", "shadow-monitor-mcp"]
    }
  }
}
```

| App | Where |
| --- | --- |
| **Cursor** | Settings → **Tools & MCP** → add / edit MCP config |
| **Claude Desktop** | Settings → Developer, or `claude_desktop_config.json` |
| **Others** | Their MCP / custom-tools settings — same JSON |

### Option C — From a git clone

```bash
cd shadow-monitor-mcp
npm install && npm run build && npm run init:all
```

---

## Install the skill (optional, separate is fine)

The skill teaches Claude/Cursor to call `load_bundle` instead of raw-reading the report.

### Claude Desktop (what you use in Customize → Skills)

`~/.claude/skills/` is **Claude Code only** — Desktop does **not** list those files.

1. Run `npx -y shadow-monitor-mcp init --client desktop` (or `all`) — it writes  
   **`~/Downloads/shadow-monitor-bundles.zip`**
2. Claude Desktop → **Customize → Skills → Add → Upload a skill**
3. Upload that ZIP → enable the skill  
4. Ensure **Settings → Capabilities → Code execution and file creation** is on

Or zip manually: folder `shadow-monitor-bundles/` containing [`SKILL.md`](./SKILL.md).

### Cursor / Claude Code (filesystem)

`init` also copies [`SKILL.md`](./SKILL.md) into:

- Cursor → `~/.cursor/skills/shadow-monitor-bundles/`
- Claude Code → `~/.claude/skills/shadow-monitor-bundles/`

---

## Use it

In any connected agent chat, paste an **absolute** path:

> Investigate `/Users/you/Downloads/uat-capture/uat-report-2026-07-27T07-34-55-912Z.json.gz` and show me what failed.

Expected flow: `load_bundle` → `bundle_overview` → `find_errors` → drill into network / console / actions.

- Path must be absolute (`/Users/…` or `C:\Users\…`).
- Don’t treat the `.json.gz` name as a skill / slash-command.
- Encrypted exports: pass `passphrase` to `load_bundle`.

---

## Tools

| Tool | What it does |
| --- | --- |
| `check_bundle` | Cheap probe: is this path a workable Shadow Monitor `.json` / `.json.gz`? |
| `load_bundle` | Load `.json` / `.json.gz` / encrypted report |
| `bundle_overview` | Errors, slow requests, actions, navigation |
| `bundle_metadata` | Schema, page, window, counts |
| `find_errors` | Network + console failures |
| `search_network` | Filter requests |
| `get_network_request` | Full request by id |
| `get_console_event` | Full console event by id |
| `get_user_actions` | Click / navigate story timeline |
| `get_action_replay` | rrweb slice for one action |
| `get_semantics` | Pre-computed semantics (schema 2/3) |

`bundleId` is optional when only one bundle is loaded.

---

## Optional settings

| Env | Effect |
| --- | --- |
| `SHADOW_MONITOR_FORMAT=toon` | Smaller list responses ([TOON](https://github.com/toon-format/toon)) |
| `SHADOW_MONITOR_REDACT=false` | Keep signed-URL params / auth headers raw |

---

## Commands (developers)

| Command | Purpose |
| --- | --- |
| `npm run build` | Compile → `dist/` |
| `npm run init` / `init:cursor` / `init:all` | Register MCP + skill |
| `npm run init:print` | Preview config, write nothing |
| `npm start` | Run MCP server (stdio) |
| `npm test` | Format / token tests |
| `npm run test:smoke -- <bundle>` | End-to-end against a report |
| `npm run pack:mcpb` | Build `shadow-monitor-mcp.mcpb` locally |

```bash
npx -y shadow-monitor-mcp init --client all
npx -y shadow-monitor-mcp init --launch npx      # client uses npx (default after npm install)
npx -y shadow-monitor-mcp init --launch local    # client uses absolute dist/cli.js
npx -y shadow-monitor-mcp init --no-skill        # MCP only
npx -y shadow-monitor-mcp init --print
```

---

## Troubleshooting

| Problem | Fix |
| --- | --- |
| `404 shadow-monitor-mcp` | Package not on npm yet — use Option C from a clone, or the `.mcpb` release asset. |
| Server disconnected | Node 20+, restart the app, check MCP config / `.mcpb` install. |
| Claude Desktop ignores config | Fully quit (**Cmd+Q**) and reopen. |
| Agent raw-reads the `.json.gz` | Install the skill (`init`, or copy `SKILL.md`). |
| No report file | Install the [Chrome extension](https://chromewebstore.google.com/detail/shadow-monitor/medbegkecifnhagdgfionmfmpcacheib) first. |

---

## Development

```bash
npm install
npm run build
npm start
npm test
```

Capture format: [shadow-monitor README](https://github.com/yurii-mandzii/shadow-monitor#readme) · [BUNDLE_FORMAT.md](https://github.com/yurii-mandzii/shadow-monitor/blob/main/BUNDLE_FORMAT.md).

MIT — see [LICENSE](./LICENSE).