shadow-monitor-mcp
This server lets AI agents inspect Shadow Monitor UAT session capture files (.json, .json.gz, or encrypted) locally via MCP tools.
Load & Validate Bundles: Use
load_bundleto load a capture file into memory, supporting encrypted bundles with a passphrase.check_bundlequickly verifies if a file is a valid Shadow Monitor bundle before loading.Bundle Overview: Get high-level aggregates with
bundle_overview, including error totals, network status/method breakdowns, slowest/largest requests, console levels, user-action kinds, and navigation timeline.Metadata: Retrieve lightweight metadata via
bundle_metadata—schema version, capture window, page info, user agent, QA/bug notes, and event counts.Find Errors:
find_errorslists network failures (failed/aborted/blocked, 4xx/5xx) and console errors (optionally warnings) in chronological order, with response body previews.Search Network Requests:
search_networkfilters requests by URL substring, HTTP method, status code range, failure flag, resource type, MIME type, body content, or minimum duration; supports pagination.Inspect a Network Request:
get_network_requestreturns full detail for a request by ID—headers, request/response bodies, with optional redaction of sensitive values.Inspect a Console Event:
get_console_eventprovides level, message/args, stack trace, and originating URL for a console event by ID.User Actions Timeline:
get_user_actionsreturns the full time-ordered list of clicks, navigations, form submissions, etc., optionally filtered by action type and source.Action Replay:
get_action_replayextracts rrweb events for a specific user-action step, enabling playback of that moment.Pre‑computed Semantics:
get_semanticsaccesses curated summaries (schema 2/3) including state at capture, error summaries, annotated user actions, network summary, and page navigations—ideal for rapid triage.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@shadow-monitor-mcp load my uat-capture file and find all errors"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 AInpm |
|
GitHub | |
Claude one-click | |
Agent Skill |
|
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 | |
User guide | |
Homepage | |
Source | |
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 underDownloads/uat-capture).
Related MCP server: FlowLens MCP
MCP vs Skill (what you need)
Piece | What it is | Required? |
MCP server | The actual tools ( | Yes — without it the agent cannot inspect the file |
Agent Skill | A short playbook ( | 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 allRegisters 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 |
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:allInstall 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(orall) — it writes~/Downloads/shadow-monitor-bundles.zipClaude 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.gzand show me what failed.
Expected flow: load_bundle → bundle_overview → find_errors → drill into network / console / actions.
Path must be absolute (
/Users/…orC:\Users\…).Don’t treat the
.json.gzname as a skill / slash-command.Encrypted exports: pass
passphrasetoload_bundle.
Tools
Tool | What it does |
| Cheap probe: is this path a workable Shadow Monitor |
| Load |
| Errors, slow requests, actions, navigation |
| Schema, page, window, counts |
| Network + console failures |
| Filter requests |
| Full request by id |
| Full console event by id |
| Click / navigate story timeline |
| rrweb slice for one action |
| Pre-computed semantics (schema 2/3) |
bundleId is optional when only one bundle is loaded.
Optional settings
Env | Effect |
| Smaller list responses (TOON) |
| Keep signed-URL params / auth headers raw |
Commands (developers)
Command | Purpose |
| Compile → |
| Register MCP + skill |
| Preview config, write nothing |
| Run MCP server (stdio) |
| Format / token tests |
| End-to-end against a report |
| Build |
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 --printTroubleshooting
Problem | Fix |
| Package not on npm yet — use Option C from a clone, or the |
Server disconnected | Node 20+, restart the app, check MCP config / |
Claude Desktop ignores config | Fully quit (Cmd+Q) and reopen. |
Agent raw-reads the | Install the skill ( |
No report file | Install the Chrome extension first. |
Development
npm install
npm run build
npm start
npm testCapture format: shadow-monitor README · BUNDLE_FORMAT.md.
MIT — see LICENSE.
Available Tools
11 toolsbundle_metadataBundle metadataA
Lightweight metadata for a loaded bundle without any event data: schema version, generation time, page, capture window, counts, capture-start context (URL, title, user agent), userDescription (QA bug note), page.navigation / color scheme, journey session list, and load info.
Inputs: bundleId.
bundle_overviewBundle overviewA
High-level aggregates for a loaded bundle: page, capture window, event counts, network status/method breakdown, slowest and largest requests, error totals, console levels, user-action kinds, and the navigation timeline. Prefers the bundle's pre-computed semantics when present (schema 2/3); falls back to scanning events for schema 1. Use this first to orient before drilling in.
Inputs: bundleId.
check_bundleCheck if a file is a Shadow Monitor bundleA
Cheap probe of a local path: does it look like a workable Shadow Monitor diagnostic export (.json or .json.gz, any folder/name)? Returns workable / looksLikeShadowMonitor, encoding, encrypted, schemaVersion, and hints. Does not index events — use before load_bundle when the path is unfamiliar, or when load_bundle might fail.
Inputs: path (required), passphrase.
find_errorsFind errorsA
Return network and console errors in time order. Network errors are failed/aborted requests, blocked (status 0), and 4xx/5xx responses (phase:"start" begin-markers are excluded). Console errors are level matching /error/i or uncaught===true (and level=warn when includeWarnings is true). Each row carries the event id (string like "e_3069") for get_network_request / get_console_event. Network rows include responseBodyPreview so API error messages are visible without a detail call.
Inputs: limit, bundleId, includeWarnings.
get_action_replayGet action replay (rrweb slice)A
Return the raw rrweb events for one user-action step, with the FullSnapshot anchor prepended so a viewer can render just that step. Pass actionId (from get_user_actions) or explicit fromTs/toTs. This can be large — optional maxEvents caps the returned list. Does not change get_user_actions (which only returns the lightweight rrweb window pointer).
Inputs: toTs, fromTs, actionId, bundleId, +2 more.
get_console_eventGet console eventA
Return the full detail of one captured console event by its event id (string like "e_3068", or bare number). Includes level, message/args, stack trace, and originating URL.
Inputs: id (required), redact, bundleId.
get_network_requestGet network requestA
Return the full detail of one captured network request by its event id (pass the string id from find_errors/search_network, e.g. "e_3069"; bare numbers like 3069 are also accepted). Includes headers and request/response bodies. Very large bodies are truncated with the original length noted. Signed-URL params and sensitive headers are redacted by default; pass redact=false to see raw values.
Inputs: id (required), redact, bundleId.
get_semanticsGet bundle semanticsA
Return the bundle's pre-computed semantics block when present (schema 2/3): stateAtCapture (last click target, last error, window), errorSummary (curated console/network failures), userActions (with text/selector/label), networkSummary, and pageNavigations. Prefer this for UAT triage orientation; use find_errors / get_* for per-event drill-down.
Inputs: bundleId.
get_user_actionsGet user actionsA
Return the full time-ordered user-action timeline (never just the last action — that lives on stateAtCapture.lastUserAction / bundle_overview). DEFAULT types are the story timeline: click, submit, navigate, toggle, select (plus dblclick/contextmenu/page_load) — NOT raw text inputs. Pass types:["input"] explicitly to see keystroke commits. source "auto" (default) uses semantics.userActions only when that list is genuinely populated (≥3 story actions, or the bundle has type:"action" events); otherwise reconstructs from rrweb so today's thin-semantics bundles still get the full ~20-row story. Explicit source "semantics" / "rrweb" force one path. Response includes actionsSource: "semantics" | "rrweb". Each action includes an rrweb window { fromTs, toTs, anchorId } for get_action_replay. Default limit 50.
Inputs: limit, types, offset, source, +1 more.
load_bundleLoad a Shadow Monitor bundleA
Load and index a Shadow Monitor diagnostic bundle from a local file path. Handles plain JSON, gzip (.json.gz), and per-bundle encrypted exports (supply passphrase for the latter). Returns a bundleId used by the other tools, plus a quick summary. Loading the same path twice reuses the existing handle unless reload is true.
Inputs: path (required), reload, bundleId, passphrase.
search_networkSearch network requestsA
Filter the captured network requests and return compact rows (id, time, method, status, url, duration, type, size). Combine any filters: urlContains, method, exact status or statusMin/statusMax, failed, resourceType, mimeType, bodyContains (searches request + response bodies), minDurationMs. Filters match the raw captured values; displayed urls are field-hygiened. Paginate with limit/offset. Fetch full detail with get_network_request using a row's id (string like "e_3069").
Inputs: limit, failed, method, offset, +9 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools target a clear, distinct retrieval path: loading/checking, network search/detail, console detail, and user-action replay. The main ambiguity is among bundle_metadata, bundle_overview, and get_semantics, which all surface summary-level bundle information, though their descriptions clarify different use cases.
The naming is largely consistent, with lowercase snake_case and a dominant verb_noun pattern like load_bundle, check_bundle, find_errors, search_network, and get_*. bundle_metadata and bundle_overview deviate slightly by leading with the noun, but the overall pattern is still predictable and readable.
11 tools is well-scoped for a diagnostic bundle inspection server. Each tool corresponds to a meaningful stage or data type in the workflow, from validation and loading to overview, error discovery, network/console drill-down, user actions, replay, and semantics.
The tool set covers the core diagnostic workflow comprehensively: load/validate bundles, orient with overview/semantics, search network and errors, fetch event details, and replay user actions. Minor gaps exist, such as no general non-error console search and no explicit bundle unload/cleanup, but they do not break the primary use case.
Maintenance
Related MCP Connectors
Live browser debugging for AI assistants — DOM, console, network via MCP.
Debug webhooks from your AI agent: inspect and replay captured webhooks on localhost.
Bug tracking for AI agents: session replay, console/network logs, repro packs, test plans, evidence.
Captured web interfaces, screenshots, flows and structured evidence for AI coding agents.
Related MCP Servers
- FlicenseNot gradedqualityAmaintenanceEnables coding agents to inspect recorded browser flows—including user actions, network, console, storage, DOM events, and screen recordings—for debugging, bug reporting, regression testing, and Playwright test generation.-
- FlicenseNot gradedqualityAmaintenanceEnables coding agents to inspect recorded browser flows, including user actions, network activity, console logs, storage, DOM events, and screen recordings, so they can debug issues and perform regression testing without reproducing them.-
- FlicenseNot gradedqualityAmaintenanceEnables coding agents to inspect recorded browser flows—including user actions, network activity, console output, storage, DOM events, and screen recordings—for debugging, bug reporting, and regression testing without reproducing the issue.-
- FlicenseNot gradedqualityAmaintenanceEnables coding agents to inspect recorded browser flows—including user actions, network, console, storage, DOM events, and screen recordings—for debugging, bug reporting, regression testing, and generating Playwright tests.-