DeltaScope MCP

中文 · 日本語 · English

面向文本模型的前端动态调试 MCP — 让纯文本模型拥有解析前端动画的能力。

核心理念

• 初始静态界面图谱 → page_map 输出页面结构（landmarks / interactives / panels / overlays）
• 后续增量 delta → timeline_get_delta 输出语义事件时间线
• 聚焦订阅追踪 → focus_set 只追踪关心的元素，节省 token

快速开始

用户：直接在 MCP 客户端配置 "command": "npx", "args": ["-y", "delta-scope@latest"] 即可，详见下方 MCP 客户端配置。

MCP 客户端配置

DeltaScope 是 stdio 传输的 MCP 服务器。无需手动安装，npx 会自动处理一切。

npx -y 会自动下载 delta-scope 及其依赖（含 Playwright + Chromium），首次启动约需 30s 下载浏览器，之后秒启。

A. 标准 mcpServers JSON 格式（大多数客户端）

以下客户端均使用相同的 JSON 结构，仅配置文件路径不同：

{
  "mcpServers": {
    "delta-scope": {
      "command": "npx",
      "args": ["-y", "delta-scope@latest"]
    }
  }
}

| 客户端 | 配置文件路径 | 备注 | |--------|-------------|------| | Claude Desktop | macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonWindows: %APPDATA%\Claude\claude_desktop_config.json | 重启生效 | | Claude Code | 项目级 .mcp.json 或 ~/.claude.json | 也可 CLI：claude mcp add --transport stdio --scope project delta-scope -- npx -y delta-scope@latest | | Cursor | 项目根目录 .cursor/mcp.json | MCP 面板查看绿色状态 | | Windsurf | macOS/Linux: ~/.codeium/windsurf/mcp_config.jsonWindows: %APPDATA%\Codeium\Windsurf\mcp_config.json | Settings → Cascade → MCP Servers | | Antigravity | ~/.gemini/antigravity/mcp_config.json | 通过 MCP Store 面板管理 | | Roo Code / ZooCode | 项目级 .roo/mcp.json（原 Roo Code 已更名 ZooCode） | 全局配置亦可 | | Kiro | 项目级 .kiro/settings/mcp.json 或全局 ~/.kiro/settings/mcp.json | 支持 disabled / autoApprove 字段 | | KimiCode | ~/.kimi/mcp.json 或项目级 .kimi/mcp.json | 也可 CLI：kimi mcp add | | OpenClaw | ~/.openclaw/openclaw.json 中 mcpServers 字段 | 也可 CLI：openclaw mcp add | | Trae | Settings → MCP 面板添加，支持粘贴标准 JSON | 偏好使用 npx / uvx | | ZCode (Z.AI) | Settings → MCP 面板添加 | 标准 mcpServers JSON |

B. VS Code (Copilot / Continue / GitHub Copilot)

VS Code 使用嵌套的 mcp → servers 结构（不是 "mcp.servers" 扁平键）：

settings.json 或 .vscode/mcp.json：

{
  "mcp": {
    "servers": {
      "delta-scope": {
        "command": "npx",
        "args": ["-y", "delta-scope@latest"]
      }
    }
  }
}

也可通过 CLI 添加：

code --add-mcp '{"name":"delta-scope","command":"npx","args":["-y","delta-scope@latest"]}'

C. OpenCode / KiloCode

OpenCode 和 KiloCode 使用 mcp 键（非 mcpServers），配置在 opencode.json（OpenCode）或 kilo.jsonc（KiloCode）中：

{
  "mcp": {
    "delta-scope": {
      "type": "local",
      "command": ["npx", "-y", "delta-scope@latest"]
    }
  }
}

| 客户端 | 配置文件路径 | |--------|-------------| | OpenCode | 项目级 opencode.json 或全局 ~/.config/opencode/opencode.json | | KiloCode | 项目级 kilo.jsonc / .kilo/kilo.jsonc 或全局 ~/.config/kilo/kilo.jsonc |

D. Codex (OpenAI)

Codex 使用 TOML 格式，配置在 ~/.codex/config.toml（全局）或 .codex/config.toml（项目级）：

[mcp_servers.delta-scope]
command = "npx"
args = ["-y", "delta-scope@latest"]

E. HermesAgent (Nous Research)

HermesAgent 使用 YAML 格式，配置在 ~/.hermes/config.yaml：

mcp_servers:
  delta-scope:
    command: "npx"
    args: ["-y", "delta-scope@latest"]

全局安装（可选，启动更快）

如果不想每次 npx 解析，可预先全局安装：

npm install -g delta-scope

之后配置简化为 "command": "delta-scope"（无需 args）。

验证连接

| 客户端 | 验证方式 | |--------|---------| | Claude Code | 输入 /mcp 查看已连接的服务器 | | Claude Desktop | 重启后查看 Settings → Developer → MCP | | Cursor | 查看 MCP 面板是否显示绿色连接状态 | | Windsurf | Settings → Cascade → MCP Servers | | Kiro | 命令面板搜索 "MCP" | | KimiCode | 运行 kimi mcp list 或会话中输入 /mcp | | OpenCode / KiloCode | Settings → MCP 查看服务器列表 | | Codex | 右键齿轮图标打开 config.toml |

开发者：本地源码调试

克隆源码，让 MCP 客户端直连本地代码，改码即生效。

1. 克隆并安装

git clone https://github.com/1deaaa/delta-scope-mcp.git delta-scope && cd delta-scope
npm install
npx playwright install chromium

2. 配置 MCP 客户端指向本地源码

开发态无重启热更新（开发推荐） — 使用源码入口并设置 DELTA_SCOPE_DEV=1：

{
  "mcpServers": {
    "delta-scope-dev": {
      "command": "npx",
      "args": ["--no-install", "tsx", "/absolute/path/to/delta-scope/src/index.ts"],
      "env": { "DELTA_SCOPE_DEV": "1" },
      "cwd": "/absolute/path/to/delta-scope"
    }
  }
}

cwd 是 MCP 宿主的进程启动目录字段，不是 MCP 协议字段；不同宿主可能忽略它。为了让相对入口稳定生效，建议使用绝对路径，并让 cwd 指向仓库根目录。--no-install 会强制使用本地已安装的 tsx，避免开发调试时意外下载其他版本。

开发态会在同一 stdio 进程内更新工具注册层的 callback、描述和 schema，并发送 tools/list_changed；服务进程不会重启，也不会丢失已有浏览器会话。但 tools/list_changed 只是服务端通知，是否立即重新调用 tools/list、丢弃宿主缓存的旧 schema，取决于 MCP 宿主。若宿主缓存旧工具定义，服务端无法强制替换它；无人值守调试应使用支持实时刷新工具列表的宿主，或在宿主提供的刷新机制中显式刷新。

开发态热更新范围是 src/server/register-tools.ts、src/server/schemas.ts 的工具 callback/描述/schema。浏览器端 inject bundle 会在下一次页面挂载或录制初始化时按源码版本重建。timeline/、map/ 等普通业务模块及其有状态实例不承诺在同一进程立即重载；修改这些模块应通过测试进程验证，或在允许时重启 MCP 服务。发布版 npx -y delta-scope 不支持源码热更新，升级 npm 版本后由客户端重新启动服务。

编译模式 — 更接近生产行为，改码后需手动 npm run build：

npm run build

{
  "mcpServers": {
    "delta-scope-dev": {
      "command": "node",
      "args": ["/absolute/path/to/delta-scope/dist/index.js"]
    }
  }
}

将 /absolute/path/to/delta-scope 替换为你本地克隆的绝对路径。

3. 调试工作流

窗口 1（delta-scope 源码）:  编辑器打开 src/  ← AI 在此改码
窗口 2（目标测试项目）:      MCP 已连接 → AI 测试 → 发现问题 → 回窗口 1 修 → 自动生效

npm test             # 测试
npm run typecheck    # 类型检查

工作流

1. session_create     → 创建浏览器会话
2. page_open          → 打开目标页面
3. page_map           → 获取页面结构图谱
4. focus_set          → 设置聚焦目标
5. timeline_start     → 开始录制
6. page_action        → 执行动作（click / hover / type / scroll / keydown）
7. timeline_stop      → 停止录制并编译
8. timeline_get_delta → 获取语义增量
9. timeline_get_anomalies → 获取异常列表

MCP Tools（23 个）

| 工具 | 说明 | |------|------| | version | 版本信息 | | status | 服务状态 | | session_create | 创建 isolated 模式 Chromium 会话 | | session_attach | 附着到已有 Chromium（CDP 端点） | | session_list | 列出活跃会话 | | session_close | 关闭会话 | | page_open | 打开 URL | | page_reload | 重载页面 | | page_map | 输出页面结构图谱 | | element_search | 多模式元素搜索（semantic / selector / text / relation） | | element_inspect | 元素详细状态（rect / visible / styles / animations） | | focus_set | 设置聚焦目标 | | focus_add | 追加聚焦目标 | | focus_clear | 清除聚焦 | | focus_preview | 预览聚焦范围 | | timeline_start | 开启时间窗（支持自定义采样率） | | page_action | 执行动作 | | timeline_stop | 停止录制并编译 | | timeline_sample | 中间采样 | | timeline_get_delta | 获取语义增量 | | timeline_get_anomalies | 获取异常列表 | | timeline_get_keyframes | 获取关键帧索引 | | timeline_export_bundle | 导出完整 bundle |

8 类异常检测

1. visibility_anomaly — 元素挂载后长时间不可见
2. geometry_anomaly — rect 尺寸为 0 或位置偏移
3. stacking_anomaly — 焦点元素被高 z-index 遮挡
4. animation_mismatch — 动画启动但无样式变化
5. layout_instability — CLS > 0.1
6. main_thread_jank — longtask > 200ms
7. scroll_linked_issue — scroll 后元素脱离 viewport
8. state_render_mismatch — 动作后状态与渲染不一致

技术栈

• MCP SDK: @modelcontextprotocol/sdk ^1.12
• Schema: zod ^3.25
• 浏览器自动化: Playwright ^1.52 (Chromium)
• DOM 增量录制: rrweb ^1.1
• 注入打包: esbuild (IIFE)
• 日志: pino → stderr
• 测试: vitest

项目结构

src/
├── index.ts                    # 入口：stdio transport + graceful shutdown
├── server/
│   ├── create-server.ts        # McpServer 实例化
│   ├── schemas.ts              # Zod input/output schema
│   ├── register-tools.ts       # 统一注册 23 个 tools
│   ├── register-resources.ts   # 注册 resources
│   └── sampling.ts             # Sampling 能力协商
├── session/
│   ├── context.ts              # SessionContext 数据结构
│   ├── launch.ts               # isolated 模式启动
│   ├── attach.ts               # CDP 附着
│   └── session-manager.ts      # 会话生命周期管理器
├── map/
│   ├── page-map.ts             # 页面结构图谱生成
│   ├── accessibility-map.ts    # ARIA 快照
│   ├── selector-engine.ts      # 多模式搜索
│   ├── dom-map.ts              # CDP DOMSnapshot
│   └── focus-engine.ts         # 聚焦引擎
├── runtime/inject/
│   ├── bootstrap.ts            # 注入入口
│   ├── bridge.ts               # 页面↔主进程通信桥
│   ├── rrweb-recorder.ts       # rrweb 录制封装
│   ├── focus-observer.ts       # 聚焦属性轮询
│   ├── animations.ts           # 动画采样
│   └── perf.ts                 # PerformanceObserver
├── cdp/
│   ├── session.ts              # CDPSession 创建
│   ├── domsnapshot.ts          # DOMSnapshot API
│   ├── page.ts                 # Page 布局度量
│   ├── performance.ts          # Performance 监控
│   ├── log.ts                  # Log 域日志收集
│   └── trace.ts                # Tracing 域
├── timeline/
│   ├── model.ts                # Window / RawEvent / SemanticEvent / Anomaly 数据模型
│   ├── compiler.ts             # 语义 delta 编译器
│   ├── delta.ts                # Delta 合并规则
│   ├── summary.ts              # Deterministic summary
│   └── anomalies/              # 8 类异常检测器
├── artifacts/
│   ├── store.ts                # 文件系统存储
│   ├── keyframes.ts            # 关键帧截图
│   └── bundle.ts               # Bundle 导出
├── resources/
│   ├── session-resource.ts     # Session 级资源
│   ├── timeline-resource.ts    # Timeline 资源
│   └── anomaly-resource.ts    # Anomaly 资源
└── utils/
    ├── logger.ts               # pino 日志
    ├── ids.ts                  # 唯一 ID 生成
    ├── time.ts                 # 高精度时间戳
    └── json.ts                 # JSON / NDJSON 工具

语义事件类型（17 种）

| 类型 | 说明 | |------|------| | node_mounted | DOM 节点新增 | | node_unmounted | DOM 节点移除 | | visibility_changed | 可见性变化 | | rect_changed | 位置/尺寸变化 | | style_changed | 样式属性变化 | | text_changed | 文本内容变化 | | entered_viewport | 元素进入视口 | | scroll_changed | 滚动位置变化 | | animation_started | 动画开始 | | animation_progressed | 动画进行中 | | animation_finished | 动画结束 | | layout_shift_detected | 布局偏移 | | longtask_detected | 长任务 | | overlay_appeared | 覆盖层出现 | | overlap_detected | 元素重叠 | | user_action | 用户操作（click/hover/type/scroll/keydown） | | stable | 稳定状态 |

采样配置

timeline_start 支持自定义采样帧率：

{
  "session_id": "sess_xxx",
  "sampling": {
    "fps": 30
  }
}

| 参数 | 默认值 | 范围 | 说明 | |------|--------|------|------| | fps | 动画约 5fps | 1-60 | 目标采样帧率（整数）。60 使用 rAF 尽量逐帧采样，并只记录有可观测变化的样本；1-59 使用定时采样。实际帧数受刷新率、页面可见性、页面负载和动画类型影响 |

不传则使用低开销默认值（动画约 5fps；焦点和滚动观察器使用各自默认间隔）。无限循环 CSS/WAAPI 动画的 delta 会提供当前迭代内的 progress 和 currentIteration。timeline_get_delta 返回压缩后的语义关键点；需要检查逐帧原始样本时调用 timeline_export_bundle，读取导出的 timeline.rawEvents。整页或 body 聚焦会让原始 bundle 快速变大，生产调试应优先聚焦具体动画目标。

SVG 聚焦范围

对 <svg> 根节点调用 focus_set 时，默认只展开第一层可见图层；对 SVG 绘图组（如车轮、角色或路径集合）调用时，默认观察组级变换及父/同级关联，不递归把每个 path、circle、line 变成 60fps 属性观察节点。目标组的后代动画仍会进入 document.getAnimations() 的动画筛选范围。需要查看单个图元的几何或样式时，直接把该图元作为 selector，或显式使用 relation=children，这样可以在细节和采样成本之间做出明确选择。

动画追踪机制

DeltaScope 通过两套独立机制追踪动画，互补覆盖：

| 机制 | 语义事件 | 适用场景 | 原理 | |------|---------|---------|------| | 动画观察器 | animation_started / animation_progressed / animation_finished | CSS transition、CSS @keyframes、Web Animations API（浏览器暴露的动画对象） | 通过 document.getAnimations() 采样动画对象的 playState、currentTime 和目标 selector；原始样本进入导出 bundle，delta 层只保留关键点与异常间隔 | | 焦点观察器 | rect_changed / style_changed | JS rAF/setInterval、未被 document.getAnimations() 暴露的动画或绘制 | 通过 getBoundingClientRect() + getComputedStyle() 观察已聚焦元素；需要将目标和字段加入 focus_set |

生产诊断边界

DeltaScope 记录浏览器可观测的 DOM、几何、样式、动画、用户操作和性能事件。timeline_get_delta 返回压缩后的语义变化，timeline_get_keyframes 返回开始、操作和停止等关键帧的文件索引，timeline_export_bundle 可导出完整原始样本。遇到视觉异常时，应结合 element_inspect 的 rect、styles、animations 与关键帧图像判断；timeline_get_anomalies 返回空数组只表示当前窗口没有匹配到已定义的异常，不代表页面视觉一定正确。

rrweb 同步记录全局 DOM 增量（节点增删、文本变化、滚动、视口变化），作为第三条数据通道。

产物目录与版本控制

DeltaScope 运行会在启动目录（cwd）下生成 .deltascope/sessions/<session-id>/，存放 timeline / anomalies / 关键帧截图 / bundle 等产物，文件数量和体积会随录制快速增长。

必须把它加入版本控制忽略规则，防止 git 跟踪文件大爆炸：

.deltascope/

在你自己的项目里使用 DeltaScope 时，请在该项目的 .gitignore 中加上上面这一行。本仓库自带的 .gitignore 已默认忽略 .deltascope/。

License

MIT © 2025 1deaaa