Content
# spector-agent-mcp
AI-first **WebGL 1/2** debugging MCP server built on Spector.js, designed for Code Agents (Cursor / Claude / Codex) collaborating with [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp).
## Features
- Shared-Chrome CDP attach (no second browser)
- `debugSessionId` collaboration with chrome-devtools-mcp
- Summary-first tools + diagnostic rules (`WEBGL-*`)
- Skill Pack under `skills/` (router + specialized playbooks)
- Error fixtures + evals for regression of agent workflows
## Quick start
### 1. Chrome remote debugging
```bash
# macOS example
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
--remote-debugging-port=9222 \
--user-data-dir=/tmp/chrome-webgl-debug
```
### 2. Run the published package
```bash
npx -y spector-agent-mcp --browser-url http://127.0.0.1:9222
```
### 3. MCP config
Generic MCP client configuration:
```json
{
"mcpServers": {
"spector-agent": {
"command": "npx",
"args": ["-y", "spector-agent-mcp", "--browser-url", "http://127.0.0.1:9222"]
}
}
}
```
Adapter templates under `adapters/` also use the published `npx -y spector-agent-mcp` entry. For repository development, run `pnpm install && pnpm build` and point the MCP command at `node packages/cli/dist/cli.js` instead.
Also configure **chrome-devtools** MCP in your host. Templates:
- Cursor: `adapters/cursor/mcp.json`
- Codex: `adapters/codex/config.toml`
- Claude plugin: `adapters/claude-plugin/`
### 4. Agent workflow (short)
1. `webgl_debug_playbook({ goal, url })` — deterministic tool sequence
2. Reproduce with chrome-devtools tools / open URL
3. `webgl_bind_target` → `webgl_runtime_install`
4. Stage observe: `webgl_set_marker` / `webgl_screenshot_canvas` / `webgl_read_console`
5. `webgl_capture_frame({ includeThumbnails: true })` → `webgl_run_diagnostics` → FBO via `webgl_list_visual_attachments`
6. Fix workspace code → re-capture → `webgl_diff_captures`
Playbooks: `skills/webgl-goal-driven-debug/SKILL.md`, `skills/webgl-debugging/SKILL.md`
Gap analysis vs Spector.js: `docs/ai-debug-toolchain-gap.md`
## Tool list (summary)
| Group | Tools |
|-------|--------|
| Session | `webgl_session_create`, `webgl_session_status`, `webgl_list_targets`, `webgl_bind_target`, `webgl_unbind_target`, `webgl_runtime_install`, `webgl_runtime_status` |
| Capture | `webgl_list_canvases`, `webgl_select_canvas`, `webgl_capture_frame`, `webgl_capture_sequence`, `webgl_capture_commands`, `webgl_list_captures`, `webgl_get_capture_overview` |
| Live / stage | `webgl_set_marker`, `webgl_clear_marker`, `webgl_runtime_log`, `webgl_screenshot_canvas`, `webgl_read_console`, `webgl_list_visual_attachments`, `webgl_get_visual_attachment` |
| Inspect | `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` |
| Diagnostics | `webgl_run_diagnostics`, `webgl_get_finding_details`, `webgl_diff_captures`, `webgl_generate_report`, `webgl_list_rules`, `webgl_debug_playbook` |
| Store | `webgl_export_capture`, `webgl_delete_capture`, `webgl_cleanup_store`, `webgl_open_capture_viewer` |
Security defaults: CDP is limited to explicitly allowlisted loopback hosts, runtime injection is limited to local or `--allowed-origins` targets, captures are size/retention bounded, and the generic `webgl_page_evaluate` tool is not registered unless `--allow-page-evaluate` is explicitly enabled. Prefer Chrome DevTools MCP for page evaluation and interaction.
Streamable HTTP is also available with secure defaults:
```bash
export SPECTOR_AGENT_MCP_HTTP_TOKEN="replace-with-at-least-24-random-characters"
npx -y spector-agent-mcp --transport http
```
It listens on `127.0.0.1:9230/mcp`, requires Bearer authentication, and isolates MCP sessions. Non-loopback listening requires both `--allow-remote-http` and an explicit `--http-allowed-hosts` allowlist. See [`docs/usage.md`](./docs/usage.md) for all usage modes.
## Skill Pack
```text
skills/
webgl-debugging/ # main router
webgl-goal-driven-debug/ # URL+goal → capture → fix → verify
webgl-black-screen/
webgl-shader-debugging/
webgl-texture-framebuffer/
webgl-state-corruption/
webgl-geometry-draw/
webgl-performance-regression/
webgl-verify-fix/
webgl-framework-adapters/
```
## Fixtures & evals
- Fixtures: `packages/test-fixtures/errors/*`
- Eval scenarios: `evals/evals.json`
- Report grader: `evals/graders/grade-report.mjs`
## Docs
- [`docs/architecture.md`](./docs/architecture.md)
- [`docs/protocol.md`](./docs/protocol.md) — `debugSessionId` collaboration
- [`docs/diagnostics.md`](./docs/diagnostics.md) — rule list
- [`docs/security.md`](./docs/security.md)
- [`docs/usage.md`](./docs/usage.md) — generated install and transport guide
- [`docs/tools.md`](./docs/tools.md) — generated tool schemas and annotations
- [`docs/contributing-rules.md`](./docs/contributing-rules.md)
## License
MIT — see `LICENSE` / `NOTICE` (Spector.js heritage noted where applicable).
