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

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 — 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

1. Download shadow-monitor-mcp.mcpb
2. 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.

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.

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.