Spector.js MCP Server

April 14, 2026 · View on GitHub

An MCP (Model Context Protocol) server that lets AI assistants debug any WebGL website using Spector.js — a WebGL debugger.

Load any URL, capture WebGL frames, and inspect draw calls, shaders, textures, and GL state — all from your AI-powered editor.

This server lives inside the Spector.js repository at mcp/.

Architecture

AI Assistant ←→ MCP Server (stdio) ←→ Playwright (headless Chromium) ←→ Any WebGL Website + Spector.js

The server launches a headless browser, navigates to any URL, injects Spector.js at runtime, and exposes WebGL debugging capabilities as MCP tools.

When running from within the Spector.js repo, the server uses the locally built dist/spector.bundle.js from the repo root. This means you can test MCP tooling against local Spector.js changes without publishing. If the local bundle isn't found, it falls back to the npm-installed spectorjs package.

Tools

ToolDescription
load_urlNavigate to any URL and prepare for WebGL debugging. Works with any WebGL site.
load_playgroundConvenience shortcut: load a Babylon.js Playground by snippet ID. Returns source code + screenshot.
take_screenshotScreenshot the current canvas.

Canvas Selection

ToolDescription
list_canvasesList all canvas elements on the page with WebGL context info.
select_canvasSelect which canvas to target when there are multiple on the page.

Capture & Inspection

ToolDescription
capture_frameCapture a single WebGL frame. Returns summary stats (commands, draw calls, programs, errors).
get_draw_callsList all draw calls from the last capture with command IDs, names, and arguments.
get_command_detailsGet full WebGL state at a specific command (blend, depth, stencil, bound textures, etc.).
get_shadersGet shader program source code (vertex + fragment) with compile/link status.
get_texturesList texture uploads with dimensions, format, and type.
get_webgl_stateCompare initial vs final GL state for the frame — shows what changed.

Diagnostics

ToolDescription
get_context_infoWebGL context details: version, extensions, capabilities, renderer.
get_console_logsBrowser console errors/warnings — catches JS errors and WebGL warnings.

Setup

Prerequisites

  • Node.js 18+

Install

From the Spector.js repository root:

npm run mcp:install
npm run mcp:build

Or manually:

cd mcp
npm install
npx playwright install chromium
npm run build

Configure MCP Client

Replace <SPECTOR_REPO> with the absolute path to your Spector.js repo clone.

Claude Code / Copilot CLI — add to your MCP settings:

{
  "mcpServers": {
    "spector": {
      "command": "node",
      "args": ["<SPECTOR_REPO>/mcp/dist/index.js"]
    }
  }
}

VS Code (Copilot) — add to .vscode/mcp.json:

{
  "servers": {
    "spector": {
      "type": "stdio",
      "command": "node",
      "args": ["<SPECTOR_REPO>/mcp/dist/index.js"]
    }
  }
}

Typical Workflows

Debug any WebGL site

  1. Load a URL:

    "Load https://playground.babylonjs.com and capture a frame"

  2. Inspect rendering:

    "Show me the draw calls and shaders" "Get the GL state at draw call #15"

Debug a Babylon.js Playground

  1. Load by snippet:

    "Load playground #6FVG3Y and show me the code"

  2. Capture and analyze:

    "Capture a frame. Are there any GL errors?"

Multi-canvas pages

  1. Discover canvases:

    "List the canvases on this page"

  2. Switch targets:

    "Select canvas #2 and capture a frame"

Project Structure

mcp/
├── src/
│   ├── index.ts             # MCP server entry point with tool registrations
│   ├── browser-manager.ts   # BrowserManager class for Playwright browser lifecycle
│   ├── spector-bridge.ts    # Spector.js injection and frame capture
│   ├── capture-analyzer.ts  # Pure functions for analyzing capture data
│   ├── constants.ts         # Shared constants (timeouts, GL format maps)
│   ├── errors.ts            # Custom error hierarchy
│   └── types.ts             # Type definitions
├── dist/                    # Compiled output (generated by npm run build)
├── package.json
└── tsconfig.json

Development

npm run dev     # Run with tsx (no build needed)
npm run build   # Build to dist/
npm start       # Run the built version
npm test        # Run unit tests

Testing

npm test

Runs unit tests for the capture analyzer via Jest. Tests cover the pure analysis functions in src/capture-analyzer.ts (draw call extraction, shader parsing, texture enumeration, state diffing).

Dependencies