内容
# 光谱代理MCP
AI-first **WebGL 1/2** 调试MCP服务器，基于Spector.js构建，专为代码代理（Cursor / Claude / Codex）与[Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp)协作而设计。
## 功能特点
- 共享Chrome CDP连接（无需第二个浏览器）
- `debugSessionId` 与 chrome-devtools-mcp 协作
- 概要优先的工具 + 诊断规则（`WEBGL-*`）
- `skills/` 下的技能包（路由器 + 专用剧本）
- 错误固定装置 + 评估，用于代理工作流的回归
## 快速开始
### 1. Chrome远程调试
```bash
# macOS 示例
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
--remote-debugging-port=9222 \
--user-data-dir=/tmp/chrome-webgl-debug
```
### 2. 运行已发布包
```bash
npx -y spector-agent-mcp --browser-url http://127.0.0.1:9222
```
### 3. MCP 配置
通用MCP客户端配置：
```json
{
"mcpServers": {
"spector-agent": {
"command": "npx",
"args": ["-y", "spector-agent-mcp", "--browser-url", "http://127.0.0.1:9222"]
}
}
}
```
`adapters/` 下的适配器模板也使用已发布的 `npx -y spector-agent-mcp` 入口。在仓库开发中，运行 `pnpm install && pnpm build` 并将MCP命令指向 `node packages/cli/dist/cli.js`。
还需要在主机上配置 **chrome-devtools** MCP。模板：
- Cursor：`adapters/cursor/mcp.json`
- Codex：`adapters/codex/config.toml`
- Claude 插件：`adapters/claude-plugin/`
### 4. 代理工作流（简要）
1. `webgl_debug_playbook({ goal, url })` — 确定性工具序列
2. 使用 chrome-devtools 工具重现 / 打开 URL
3. `webgl_bind_target` → `webgl_runtime_install`
4. 阶段观察：`webgl_set_marker` / `webgl_screenshot_canvas` / `webgl_read_console`
5. `webgl_capture_frame({ includeThumbnails: true })` → `webgl_run_diagnostics` → 通过 `webgl_list_visual_attachments` 的 FBO
6. 修复工作区代码 → 重新捕获 → `webgl_diff_captures`
剧本：`skills/webgl-goal-driven-debug/SKILL.md`，`skills/webgl-debugging/SKILL.md`
与 Spector.js 的差距分析：`docs/ai-debug-toolchain-gap.md`
## 工具列表（概要）
| 分组 | 工具 |
|-------|--------|
| 会话 | `webgl_session_create`，`webgl_session_status`，`webgl_list_targets`，`webgl_bind_target`，`webgl_unbind_target`，`webgl_runtime_install`，`webgl_runtime_status` |
| 捕获 | `webgl_list_canvases`，`webgl_select_canvas`，`webgl_capture_frame`，`webgl_capture_sequence`，`webgl_capture_commands`，`webgl_list_captures`，`webgl_get_capture_overview` |
| 实时 / 阶段 | `webgl_set_marker`，`webgl_clear_marker`，`webgl_runtime_log`，`webgl_screenshot_canvas`，`webgl_read_console`，`webgl_list_visual_attachments`，`webgl_get_visual_attachment` |
| 检查 | `webgl_list_draw_calls`，`webgl_get_command_details`，`webgl_list_programs`，`webgl_get_program_details`，`webgl_list_textures`，`webgl_list_framebuffers`，`webgl_get_state_diff`，`webgl_search_capture` |
| 诊断 | `webgl_run_diagnostics`，`webgl_get_finding_details`，`webgl_diff_captures`，`webgl_generate_report`，`webgl_list_rules`，`webgl_debug_playbook` |
| 存储 | `webgl_export_capture`，`webgl_delete_capture`，`webgl_cleanup_store`，`webgl_open_capture_viewer` |
安全默认值：CDP仅限于显式允许的环回主机，运行时注入仅限于本地或 `--allowed-origins` 目标，捕获的大小/保留有界，并且除非显式启用 `--allow-page-evaluate`，否则不注册通用 `webgl_page_evaluate` 工具。优先使用Chrome DevTools MCP进行页面评估和交互。
流式HTTP也可用，具备安全默认值：
```bash
export SPECTOR_AGENT_MCP_HTTP_TOKEN="replace-with-at-least-24-random-characters"
npx -y spector-agent-mcp --transport http
```
它监听 `127.0.0.1:9230/mcp`，需要Bearer身份验证，并隔离MCP会话。非环回监听需要 `--allow-remote-http` 和显式的 `--http-allowed-hosts` 允许列表。有关所有使用模式，请参见 [`docs/usage.md`](./docs/usage.md)。
## 技能包
```text
skills/
webgl-debugging/ # 主路由器
webgl-goal-driven-debug/ # URL+目标 → 捕获 → 修复 → 验证
webgl-black-screen/
webgl-shader-debugging/
webgl-texture-framebuffer/
webgl-state-corruption/
webgl-geometry-draw/
webgl-performance-regression/
webgl-verify-fix/
webgl-framework-adapters/
```
## 固定装置和评估
- 固定装置：`packages/test-fixtures/errors/*`
- 评估场景：`evals/evals.json`
- 报告评分器：`evals/graders/grade-report.mjs`
## 文档
- [`docs/architecture.md`](./docs/architecture.md)
- [`docs/protocol.md`](./docs/protocol.md) — `debugSessionId` 协作
- [`docs/diagnostics.md`](./docs/diagnostics.md) — 规则列表
- [`docs/security.md`](./docs/security.md)
- [`docs/usage.md`](./docs/usage.md) — 生成的安装和传输指南
- [`docs/tools.md`](./docs/tools.md) — 生成的工具模式和注释
- [`docs/contributing-rules.md`](./docs/contributing-rules.md)
## 许可证
MIT — 参见 `LICENSE` / `NOTICE`（如适用，请注明Spector.js遗产）。
