Skip to main content
Glama

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: chrome-dev-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)

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

License

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

Available Tools

39 tools
webgl_bind_targetBind page targetA
Idempotent

Bind a page target by targetId, debugSessionId, url+title, or urlPattern. Prefer debugSessionId set via chrome-devtools-mcp.

Inputs: url, title, targetId, urlPattern, +1 more.

webgl_capture_commandsCapture N GL commandsB

Spector startCapture for a fixed command count — capture an arbitrary stage without waiting for a full frame boundary.

Inputs: commandCount (required), label, canvasId, timeoutMs, +5 more.

webgl_capture_frameCapture next frameA

Capture the next WebGL frame. Auto-connects, binds readiness checks, installs runtime if needed. Returns summary + resource URIs (not full JSON).

Inputs: label, canvasId, timeoutMs, canvasIndex, +5 more.

webgl_capture_sequenceCapture frame sequenceC

Capture a limited sequence of frames (max 5).

Inputs: label, canvasId, timeoutMs, frameCount, +6 more.

webgl_cleanup_storeCleanup storeB
DestructiveIdempotent

Evict captures by TTL, per-session cap, and max store size.

Inputs: ttlDays, maxStoreSizeMb, maxCapturesPerSession.

webgl_clear_markerClear Spector markerA
Idempotent

Clear the current Spector.js marker.

Inputs: no named parameters.

webgl_debug_playbookGoal-driven debug playbookA
Read-onlyIdempotent

Given a URL/goal/symptoms, return a deterministic multi-phase tool sequence for AI automated WebGL debugging (attach → capture → diagnose → fix → verify).

Inputs: goal (required), url, symptoms.

webgl_delete_captureDelete captureB
Destructive

Delete a stored capture and its artifacts.

Inputs: captureId (required).

webgl_diff_capturesDiff capturesB

Semantically compare two captures (findings, programs, draw counts).

Inputs: afterCaptureId (required), beforeCaptureId (required).

webgl_export_captureExport captureB
Idempotent

Export a capture tree (manifest, capture, findings, report) to a directory.

Inputs: destDir (required), captureId (required), overwrite.

webgl_generate_reportGenerate reportB
Idempotent

Generate Markdown and/or JSON diagnostic report for a capture.

Inputs: captureId (required), format.

webgl_get_capture_overviewCapture overviewC
Read-onlyIdempotent

Get a stored capture summary and resource URIs.

Inputs: captureId (required).

webgl_get_command_detailsCommand detailsB
Read-onlyIdempotent

Get details for a single command with optional field includes.

Inputs: captureId (required), commandId (required), include.

webgl_get_finding_detailsFinding detailsA
Read-onlyIdempotent

Get full evidence and hypotheses for a diagnostic finding.

Inputs: captureId (required), findingId (required).

webgl_get_program_detailsProgram detailsC
Read-onlyIdempotent

Get shader sources and link/compile status for a program.

Inputs: captureId (required), programId (required), includeSources.

webgl_get_state_diffState diffC
Read-onlyIdempotent

Get initial vs final GL state differences for a capture.

Inputs: captureId (required).

webgl_get_visual_attachmentGet visual attachmentB
Read-onlyIdempotent

Resolve a single FBO/canvas screenshot path for AI inspection (Read tool can open the absolute file path).

Inputs: captureId (required), commandId (required), attachmentName, attachmentIndex.

webgl_list_canvasesList WebGL canvasesA
Idempotent

Enumerate WebGL/WebGL2 canvases on the bound page.

Inputs: no named parameters.

webgl_list_capturesList capturesB
Read-onlyIdempotent

List stored captures, optionally filtered by session.

Inputs: sessionId.

webgl_list_draw_callsList draw callsB
Read-onlyIdempotent

Paginated list of draw/clear commands for a capture.

Inputs: captureId (required), page, names, status, +5 more.

webgl_list_framebuffersList framebuffersC
Read-onlyIdempotent

List framebuffers and attachments from a capture.

Inputs: captureId (required).

webgl_list_programsList programsA
Read-onlyIdempotent

List shader programs in a capture.

Inputs: captureId (required).

webgl_list_rulesList diagnostic rulesB
Read-onlyIdempotent

List deterministic WebGL diagnostic rule IDs available to webgl_run_diagnostics.

Inputs: profile.

webgl_list_targetsList page targetsA
Read-onlyIdempotent

List Chrome page targets that can be bound for WebGL debugging.

Inputs: no named parameters.

webgl_list_texturesList texturesC
Read-onlyIdempotent

List textures and upload metadata from a capture.

Inputs: captureId (required), page, pageSize.

webgl_list_visual_attachmentsList FBO/canvas visual attachmentsA
Read-onlyIdempotent

List Spector VisualState attachment screenshots persisted for a capture (requires capture with includeThumbnails=true, quickCapture=false).

Inputs: captureId (required).

webgl_open_capture_viewerOpen capture viewerB
Idempotent

Return a local file URL for the read-only Capture Viewer pointing at a stored capture.

Inputs: captureId (required).

webgl_read_consoleRead buffered consoleC
Idempotent

Return recent console API messages collected from the bound page via CDP (log/warn/error).

Inputs: clear, limit, types.

webgl_run_diagnosticsRun diagnosticsB
Idempotent

Run deterministic diagnostic rules on a capture (no LLM). Returns findings summary.

Inputs: captureId (required), profiles, minSeverity, includeSuppressed.

webgl_runtime_installInstall Spector runtimeA
Idempotent

Inject Spector.js into the bound page (early + late install).

Inputs: force.

webgl_runtime_logSpector runtime logA

Write a custom log line into the Spector capture stream (appears as a log command when capturing).

Inputs: message (required).

webgl_runtime_statusRuntime statusA
Read-onlyIdempotent

Check Spector injection, canvas, and context status on the bound page.

Inputs: no named parameters.

webgl_screenshot_canvasScreenshot canvas nowB

Immediate canvas.toDataURL screenshot (not a Spector frame). Useful for any-stage visual checks and goal verification. Saves under the current session screenshots/ folder.

Inputs: label, quality, canvasId, mimeType, +1 more.

webgl_search_captureSearch captureB
Read-onlyIdempotent

Search commands by API name, marker, object name, or stack frame text.

Inputs: captureId (required), api, limit, stack, +2 more.

webgl_select_canvasSelect canvasC
Idempotent

Select the WebGL canvas to capture.

Inputs: canvasId, canvasIndex.

webgl_session_createCreate WebGL debug sessionA

Create a local debug session and connect to Chrome at the configured browser URL.

Inputs: label.

webgl_session_statusSession statusA
Idempotent

Get current session, target binding, and Spector runtime status.

Inputs: no named parameters.

webgl_set_markerSet Spector markerA
Idempotent

Set a Spector.js marker string so subsequent captured commands are tagged (stage annotation at any point).

Inputs: marker (required).

webgl_unbind_targetUnbind page targetA
Idempotent

Detach from the currently bound page target.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 39 tools

    Disambiguation4/5

    Most tools have distinct purposes (e.g., capture commands vs frame vs sequence), but some pairs like webgl_list_captures and webgl_get_capture_overview could cause mild confusion without careful reading of descriptions.

    Naming Consistency5/5

    All tools follow a consistent 'webgl_verb_noun' pattern in snake_case, with no mixed conventions or ambiguous verb styles.

    Tool Count2/5

    At 39 tools, the set is far above the typical 3-15 range, making it overwhelming for an agent to efficiently select among them, even though each tool seems justified.

    Completeness5/5

    The tool set covers the full lifecycle of WebGL debugging: session management, capture (various modes), inspection (commands, programs, textures), diagnostics, comparison, export, and even a guided playbook.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      An MCP server that connects AI agents to a running Chrome tab via the Chrome DevTools Protocol (CDP), enabling runtime debugging and page inspection.
      25
      85 npm
      1
      ISC
    • F
      license
      B
      quality
      C
      maintenance
      MCP server for RenderDoc that enables AI assistants to analyze GPU frame captures (.rdc files) for graphics debugging and performance analysis, with 42 tools covering the full RenderDoc workflow.
      6
      -