# 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).