spector-agent-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@spector-agent-mcp capture a frame and run diagnostics on the WebGL canvas"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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)
debugSessionIdcollaboration with chrome-devtools-mcpSummary-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-debug2. Run the published package
npx -y spector-agent-mcp --browser-url http://127.0.0.1:92223. 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.jsonCodex:
adapters/codex/config.tomlClaude plugin:
adapters/claude-plugin/
4. Agent workflow (short)
webgl_debug_playbook({ goal, url })— deterministic tool sequenceReproduce with chrome-devtools tools / open URL
webgl_bind_target→webgl_runtime_installStage observe:
webgl_set_marker/webgl_screenshot_canvas/webgl_read_consolewebgl_capture_frame({ includeThumbnails: true })→webgl_run_diagnostics→ FBO viawebgl_list_visual_attachmentsFix 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 |
|
Capture |
|
Live / stage |
|
Inspect |
|
Diagnostics |
|
Store |
|
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 httpIt 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.jsonReport grader:
evals/graders/grade-report.mjs
Docs
docs/protocol.md—debugSessionIdcollaborationdocs/diagnostics.md— rule listdocs/usage.md— generated install and transport guidedocs/tools.md— generated tool schemas and annotations
License
MIT — see LICENSE / NOTICE (Spector.js heritage noted where applicable).
Available Tools
39 toolswebgl_bind_targetBind page targetAIdempotent
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 storeBDestructiveIdempotent
Evict captures by TTL, per-session cap, and max store size.
Inputs: ttlDays, maxStoreSizeMb, maxCapturesPerSession.
webgl_clear_markerClear Spector markerAIdempotent
Clear the current Spector.js marker.
Inputs: no named parameters.
webgl_debug_playbookGoal-driven debug playbookARead-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 captureBDestructive
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 captureBIdempotent
Export a capture tree (manifest, capture, findings, report) to a directory.
Inputs: destDir (required), captureId (required), overwrite.
webgl_generate_reportGenerate reportBIdempotent
Generate Markdown and/or JSON diagnostic report for a capture.
Inputs: captureId (required), format.
webgl_get_capture_overviewCapture overviewCRead-onlyIdempotent
Get a stored capture summary and resource URIs.
Inputs: captureId (required).
webgl_get_command_detailsCommand detailsBRead-onlyIdempotent
Get details for a single command with optional field includes.
Inputs: captureId (required), commandId (required), include.
webgl_get_finding_detailsFinding detailsARead-onlyIdempotent
Get full evidence and hypotheses for a diagnostic finding.
Inputs: captureId (required), findingId (required).
webgl_get_program_detailsProgram detailsCRead-onlyIdempotent
Get shader sources and link/compile status for a program.
Inputs: captureId (required), programId (required), includeSources.
webgl_get_state_diffState diffCRead-onlyIdempotent
Get initial vs final GL state differences for a capture.
Inputs: captureId (required).
webgl_get_visual_attachmentGet visual attachmentBRead-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 canvasesAIdempotent
Enumerate WebGL/WebGL2 canvases on the bound page.
Inputs: no named parameters.
webgl_list_capturesList capturesBRead-onlyIdempotent
List stored captures, optionally filtered by session.
Inputs: sessionId.
webgl_list_draw_callsList draw callsBRead-onlyIdempotent
Paginated list of draw/clear commands for a capture.
Inputs: captureId (required), page, names, status, +5 more.
webgl_list_framebuffersList framebuffersCRead-onlyIdempotent
List framebuffers and attachments from a capture.
Inputs: captureId (required).
webgl_list_programsList programsARead-onlyIdempotent
List shader programs in a capture.
Inputs: captureId (required).
webgl_list_rulesList diagnostic rulesBRead-onlyIdempotent
List deterministic WebGL diagnostic rule IDs available to webgl_run_diagnostics.
Inputs: profile.
webgl_list_targetsList page targetsARead-onlyIdempotent
List Chrome page targets that can be bound for WebGL debugging.
Inputs: no named parameters.
webgl_list_texturesList texturesCRead-onlyIdempotent
List textures and upload metadata from a capture.
Inputs: captureId (required), page, pageSize.
webgl_list_visual_attachmentsList FBO/canvas visual attachmentsARead-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 viewerBIdempotent
Return a local file URL for the read-only Capture Viewer pointing at a stored capture.
Inputs: captureId (required).
webgl_read_consoleRead buffered consoleCIdempotent
Return recent console API messages collected from the bound page via CDP (log/warn/error).
Inputs: clear, limit, types.
webgl_run_diagnosticsRun diagnosticsBIdempotent
Run deterministic diagnostic rules on a capture (no LLM). Returns findings summary.
Inputs: captureId (required), profiles, minSeverity, includeSuppressed.
webgl_runtime_installInstall Spector runtimeAIdempotent
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 statusARead-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 captureBRead-onlyIdempotent
Search commands by API name, marker, object name, or stack frame text.
Inputs: captureId (required), api, limit, stack, +2 more.
webgl_select_canvasSelect canvasCIdempotent
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 statusAIdempotent
Get current session, target binding, and Spector runtime status.
Inputs: no named parameters.
webgl_set_markerSet Spector markerAIdempotent
Set a Spector.js marker string so subsequent captured commands are tagged (stage annotation at any point).
Inputs: marker (required).
webgl_unbind_targetUnbind page targetAIdempotent
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
Scored across 39 tools
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.
All tools follow a consistent 'webgl_verb_noun' pattern in snake_case, with no mixed conventions or ambiguous verb styles.
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.
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
Live browser debugging for AI assistants — DOM, console, network via MCP.
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Agent Replay Debugger MCP — record every agent step + deterministic replay. Step-debugger for
A paid remote MCP for AI agent browser DevTools MCP, built to return verdicts, receipts, usage logs,
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceMCP server for browser debugging, inspection, and verification that streams console logs, network errors, and user actions into AI coding assistants.67AGPL 3.0
- AlicenseAqualityBmaintenanceAn MCP server that connects AI agents to a running Chrome tab via the Chrome DevTools Protocol (CDP), enabling runtime debugging and page inspection.2585 npm1ISC
- FlicenseBqualityCmaintenanceMCP 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-
- AlicenseNot gradedqualityDmaintenanceA lightweight MCP server that enables AI assistants to control Chrome DevTools via CDP for debugging tasks like navigation, screenshots, and JavaScript execution.MIT