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.

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

# 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

npx -y spector-agent-mcp --browser-url http://127.0.0.1:9222

3. MCP config

Generic MCP client configuration:

{
  "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:

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 for all usage modes.

Skill Pack

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/protocol.md — debugSessionId collaboration
• docs/diagnostics.md — rule list
• docs/security.md
• docs/usage.md — generated install and transport guide
• docs/tools.md — generated tool schemas and annotations
• docs/contributing-rules.md

License

MIT — see LICENSE / NOTICE (Spector.js heritage noted where applicable).