MCP 服务器

spector-agent-mcp

AI-first WebGL 1/2 debugging MCP server that attaches to Chrome via CDP, enables frame capture and diagnostic analysis, and collaborates with Chrome DevTools MCP for agent-driven debugging workflows.

README

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)

webgl_debug_playbook({ goal, url }) — deterministic tool sequence
Reproduce with chrome-devtools tools / open URL
webgl_bind_target → webgl_runtime_install
Stage observe: webgl_set_marker / webgl_screenshot_canvas / webgl_read_console
webgl_capture_frame({ includeThumbnails: true }) → webgl_run_diagnostics → FBO via webgl_list_visual_attachments
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/