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

Companion: Shadow Monitor (Chrome extension)

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

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

Related MCP server: cdp-tools-mcp

MCP vs Skill (what you need)

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"]
    }
  }
}

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

bundleId is optional when only one bundle is loaded.

Optional settings

Commands (developers)

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

Development

npm install
npm run build
npm start
npm test

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

MIT — see LICENSE.