shadow-monitor-mcp

Open-source MCP server that lets any AI agent inspect Shadow Monitor capture files (uat-report-*.json.gz) — locally, with no upload.

Works with any client that speaks MCP 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` · `npx -y shadow-monitor-mcp`
GitHub	`yurii-mandzii/shadow-monitor-mcp`
Claude one-click	`shadow-monitor-mcp.mcpb` (all releases)
Agent Skill	`SKILL.md` (optional — teaches the agent when to call the tools)
License	MIT
Needs	Node.js 20+ 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
User guide	Guide
Homepage	Docs site
Source	github.com/yurii-mandzii/shadow-monitor
Support / Privacy	Support · Privacy

Install the extension → add your UAT domain in Settings.
Hard-reload the tab (Cmd/Ctrl+Shift+R).
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 — click through; no coding required).

Option A — One command (MCP + skill together)

Open Terminal / PowerShell, paste, Enter:

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`

Download shadow-monitor-mcp.mcpb
Double-click it, or Claude Desktop → Settings → Extensions → Install Extension…

Any MCP client — paste 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

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.

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

Or zip manually: folder shadow-monitor-bundles/ containing SKILL.md.

Cursor / Claude Code (filesystem)

init also copies 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)
`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

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 first.

Development

npm install
npm run build
npm start
npm test

Capture format: shadow-monitor README · BUNDLE_FORMAT.md.

MIT — see LICENSE.