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

Related MCP server: Kaboom Browser AI Devtools MCP

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)

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