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 会自动处理一切。

一行配置（所有客户端通用）

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

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

Claude Code

# 命令行添加（推荐）
claude mcp add --transport stdio --scope project delta-scope -- npx -y delta-scope@latest

或项目级 .mcp.json：

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

Claude Desktop

编辑 claude_desktop_config.json：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Cursor

项目根目录 .cursor/mcp.json：

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

VS Code (Copilot / Continue)

settings.json：

{
  "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 面板是否显示绿色连接状态

开发者（贡献代码）：

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

# 运行测试
npm test

# 类型检查
npm run typecheck

# 启动服务（开发模式）
npm start

工作流

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 | 采样帧率（整数）。高帧率自动启用 rAF 逐帧+批量优化 |

不传则使用默认值（约 5fps）。

动画追踪机制

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

| 机制 | 语义事件 | 适用场景 | 原理 | |------|---------|---------|------| | 动画观察器 | animation_started / animation_progressed / animation_finished | CSS transition、Web Animations API | 通过 document.getAnimations() 采样动画对象的 playState 和 currentTime | | 焦点观察器 | rect_changed / style_changed | CSS @keyframes animation、JS rAF/setInterval 动画 | 通过 getBoundingClientRect() + getComputedStyle() 轮询焦点元素的样式和几何变化 |

已验证覆盖 41 种动画场景（9 大类别）：

• CSS @keyframes：transform / opacity / size / color / borderRadius / boxShadow / gradient / filter / clipPath
• CSS transition：transform / opacity / color / size / shadow / borderRadius / multi-property
• CSS timing：steps() / cubic-bezier / alternate / reverse / multiple / stagger
• Web Animations API：rotate / translate / scale / opacity / multi-property / composite
• JS rAF 循环：textContent / style.transform / style.width / style.opacity
• setInterval：style.width
• SVG：<animate> / <animateTransform>

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

License

MIT © 2025 Mournight