Skip to main content
Glama
shadow-monitor-mcp

shadow-monitor-mcp

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


Related MCP server: FlowLens MCP

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.

Available Tools

11 tools
bundle_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

    A4/5.0

    Scored across 11 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -