Spector.js MCP Server

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

Navigation

Tool	Description
load_url	Navigate to any URL and prepare for WebGL debugging. Works with any WebGL site.
load_playground	Convenience shortcut: load a Babylon.js Playground by snippet ID. Returns source code + screenshot.
take_screenshot	Screenshot the current canvas.

Canvas Selection

Tool	Description
list_canvases	List all canvas elements on the page with WebGL context info.
select_canvas	Select which canvas to target when there are multiple on the page.

Capture & Inspection

Tool	Description
capture_frame	Capture a single WebGL frame. Returns summary stats (commands, draw calls, programs, errors).
get_draw_calls	List all draw calls from the last capture with command IDs, names, and arguments.
get_command_details	Get full WebGL state at a specific command (blend, depth, stencil, bound textures, etc.).
get_shaders	Get shader program source code (vertex + fragment) with compile/link status.
get_textures	List texture uploads with dimensions, format, and type.
get_webgl_state	Compare initial vs final GL state for the frame — shows what changed.

Diagnostics

Tool	Description
get_context_info	WebGL context details: version, extensions, capabilities, renderer.
get_console_logs	Browser 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

• @modelcontextprotocol/sdk — MCP server framework
• Playwright — headless browser automation
• Spector.js — WebGL debugger (injected into the page at runtime)
• Zod — schema validation