内容
# shadow-monitor-mcp
开源 **MCP 服务器**，允许 **任何 AI 代理** 检查 [Shadow Monitor](https://chromewebstore.google.com/detail/shadow-monitor/medbegkecifnhagdgfionmfmpcacheib) 捕获的文件（`uat-report-*.json.gz`）——本地运行，无需上传。
与 **任何支持 [MCP](https://modelcontextprotocol.io) 的客户端**配合使用，通过标准输入/输出：Cursor、Claude Desktop、Claude Code、Windsurf、VS Code Copilot Chat、Continue、Cline、Zed等。
```
Shadow Monitor (Chrome) 记录 UAT 会话
↓
你下载 uat-report-….json.gz
↓
这个 MCP 服务器为你的 AI 加载它
```
| | |
| --- | --- |
| **npm** | [`shadow-monitor-mcp`](https://www.npmjs.com/package/shadow-monitor-mcp) · `npx -y shadow-monitor-mcp` |
| **GitHub** | [`yurii-mandzii/shadow-monitor-mcp`](https://github.com/yurii-mandzii/shadow-monitor-mcp) |
| **Claude 一键安装** | [`shadow-monitor-mcp.mcpb`](https://github.com/yurii-mandzii/shadow-monitor-mcp/releases/latest/download/shadow-monitor-mcp.mcpb) ([所有版本](https://github.com/yurii-mandzii/shadow-monitor-mcp/releases)) |
| **代理技能** | [`SKILL.md`](./SKILL.md)（可选 - 教导代理 **何时** 调用工具） |
| **许可证** | MIT |
| **依赖** | [Node.js 20+](https://nodejs.org/)（MCP 使用，Chrome 扩展单独运行） |
---
## 配套工具：Shadow Monitor（Chrome 扩展）
此 MCP **不** 记录浏览器。捕获来自扩展：
| | |
| --- | --- |
| **Chrome 应用商店** | [Shadow Monitor](https://chromewebstore.google.com/detail/shadow-monitor/medbegkecifnhagdgfionmfmpcacheib) |
| **用户指南** | [指南](https://yurii-mandzii.github.io/shadow-monitor/guide/) |
| **首页** | [文档站点](https://yurii-mandzii.github.io/shadow-monitor/) |
| **源码** | [github.com/yurii-mandzii/shadow-monitor](https://github.com/yurii-mandzii/shadow-monitor) |
| **支持 / 隐私** | [支持](https://yurii-mandzii.github.io/shadow-monitor/support/) · [隐私](https://yurii-mandzii.github.io/shadow-monitor/privacy/) |
1. 安装扩展 → 添加你的 UAT 域名到设置。
2. 重新加载标签页（**Cmd/Ctrl+Shift+R**）。
3. 重现错误 → **下载** → 获取 `uat-report-*.json.gz`（通常在 `Downloads/uat-capture` 下）。
---
## MCP 与技能（你需要什么）
| 组件 | 描述 | 是否必需？ |
| --- | --- | --- |
| **MCP 服务器** | 实际工具（`load_bundle`、`find_errors`等） | **是** - 没有它，代理无法检查文件 |
| **代理技能** | 一个简短的攻略（`SKILL.md`），告诉“当用户粘贴 `uat-report-*.json.gz`时，调用 `load_bundle` - 不要直接读取文件” | **否** - 但强烈推荐，以便代理行为正确 |
你可以 **一起** 或 **分别** 安装它们（MCP 通过 UI / `.mcpb`，技能通过 `init` 或复制）。
---
## 安装 MCP
你需要 **Node.js 20+**（下载 LTS 安装程序 - 点击下一步；不需要编码）。
### 选项 A - 一条命令（MCP + 技能一起）
打开终端 / PowerShell，粘贴，Enter：
```bash
npx -y shadow-monitor-mcp init --client all
```
为 Claude Desktop + Cursor + Claude Code 注册服务器 **和** 安装代理技能。然后重启你的 AI 应用（Claude Desktop：完全退出并使用 **Cmd+Q**）。
仅限一个应用？使用 `--client cursor`、`--client desktop` 或 `--client claude-code`。
### 选项 B - UI / 点击安装（仅 MCP）
#### Claude Desktop - 一键安装 `.mcpb`
1. 下载 **[shadow-monitor-mcp.mcpb](https://github.com/yurii-mandzii/shadow-monitor-mcp/releases/latest/download/shadow-monitor-mcp.mcpb)**
2. 双击它，**或** Claude Desktop → **设置 → 扩展 → 安装扩展…**
#### 任意 MCP 客户端 - 粘贴 JSON
```json
{
"mcpServers": {
"shadow-monitor": {
"command": "npx",
"args": ["-y", "shadow-monitor-mcp"]
}
}
}
```
| 应用 | 位置 |
| --- | --- |
| **Cursor** | 设置 → **工具和 MCP** → 添加 / 编辑 MCP 配置 |
| **Claude Desktop** | 设置 → 开发者，或 `claude_desktop_config.json` |
| **其他** | 他们的 MCP / 自定义工具设置 - 相同的 JSON |
### 选项 C - 从 git 克隆
```bash
cd shadow-monitor-mcp
npm install && npm run build && npm run init:all
```
---
## 安装技能（可选，单独安装）
技能教导 Claude/Cursor 调用 `load_bundle` 而不是直接读取报告。
### Claude Desktop（自定义 → 技能中使用）
`~/.claude/skills/` **仅限 Claude Code** - Desktop **不** 列出这些文件。
1. 运行 `npx -y shadow-monitor-mcp init --client desktop`（或 `all`）- 它写入
**`~/Downloads/shadow-monitor-bundles.zip`**
2. Claude Desktop → **自定义 → 技能 → 添加 → 上传技能**
3. 上传该 ZIP → 启用技能
4. 确保 **设置 → 功能 → 代码执行和文件创建** 已启用
或手动压缩：包含 [`SKILL.md`](./SKILL.md) 的 `shadow-monitor-bundles/` 文件夹。
### Cursor / Claude Code（文件系统）
`init` 还会将 [`SKILL.md`](./SKILL.md) 复制到：
- Cursor → `~/.cursor/skills/shadow-monitor-bundles/`
- Claude Code → `~/.claude/skills/shadow-monitor-bundles/`
---
## 使用它
在任何连接的代理聊天中，粘贴绝对路径：
> 检查 `/Users/you/Downloads/uat-capture/uat-report-2026-07-27T07-34-55-912Z.json.gz` 并告诉我出了什么问题。
预期流程：`load_bundle` → `bundle_overview` → `find_errors` → 深入网络 / 控制台 / 操作。
- 路径必须是绝对的（`/Users/…` 或 `C:\Users\…`）。
- 不要将 `.json.gz` 名称视为技能 / 斜杠命令。
- 加密导出：向 `load_bundle` 传递 `passphrase`。
---
## 工具
| 工具 | 功能 |
| --- | --- |
| `check_bundle` | 廉价探测：此路径是可用的 Shadow Monitor `.json` / `.json.gz`？ |
| `load_bundle` | 加载 `.json` / `.json.gz` / 加密报告 |
| `bundle_overview` | 错误、慢速请求、操作、导航 |
| `bundle_metadata` | 模式、页面、窗口、计数 |
| `find_errors` | 网络 + 控制台失败 |
| `search_network` | 筛选请求 |
| `get_network_request` | 通过 ID 获取完整请求 |
| `get_console_event` | 通过 ID 获取完整控制台事件 |
| `get_user_actions` | 点击 / 导航故事时间线 |
| `get_action_replay` | 单个操作的 rrweb 片段 |
| `get_semantics` | 预计算的语义（模式 2/3） |
`bundleId` 在只加载一个包时是可选的。
---
## 可选设置
| 环境变量 | 效果 |
| --- | --- |
| `SHADOW_MONITOR_FORMAT=toon` | 更小的列表响应（[TOON](https://github.com/toon-format/toon)） |
| `SHADOW_MONITOR_REDACT=false` | 保留签名 URL 参数 / 授权头原始 |
---
## 命令（开发人员）
| 命令 | 目的 |
| --- | --- |
| `npm run build` | 编译 → `dist/` |
| `npm run init` / `init:cursor` / `init:all` | 注册 MCP + 技能 |
| `npm run init:print` | 预览配置，不写入任何内容 |
| `npm start` | 运行 MCP 服务器（标准输入/输出） |
| `npm test` | 格式 / token 测试 |
| `npm run test:smoke -- <bundle>` | 针对报告进行端到端测试 |
| `npm run pack:mcpb` | 在本地构建 `shadow-monitor-mcp.mcpb` |
```bash
npx -y shadow-monitor-mcp init --client all
npx -y shadow-monitor-mcp init --launch npx # 客户端使用 npx（默认安装后）
npx -y shadow-monitor-mcp init --launch local # 客户端使用绝对 dist/cli.js
npx -y shadow-monitor-mcp init --no-skill # 仅 MCP
npx -y shadow-monitor-mcp init --print
```
---
## 故障排除
| 问题 | 解决方法 |
| --- | --- |
| `404 shadow-monitor-mcp` | 包尚未在 npm 上发布 - 使用选项 C 从克隆或发布资产中的 `.mcpb` |
| 服务器断开连接 | Node 20+，重启应用，检查 MCP 配置 / `.mcpb` 安装 |
| Claude Desktop 忽略配置 | 完全退出（**Cmd+Q**）并重新打开 |
| 代理直接读取 `.json.gz` | 安装技能（`init` 或复制 `SKILL.md`） |
| 没有报告文件 | 首先安装 [Chrome 扩展](https://chromewebstore.google.com/detail/shadow-monitor/medbegkecifnhagdgfionmfmpcacheib) |
---
## 开发
```bash
npm install
npm run build
npm start
npm test
```
捕获格式：[shadow-monitor README](https://github.com/yurii-mandzii/shadow-monitor#readme) · [BUNDLE_FORMAT.md](https://github.com/yurii-mandzii/shadow-monitor/blob/main/BUNDLE_FORMAT.md).
MIT — 见 [LICENSE](./LICENSE).
