Skip to content

Commit e4ebf8a

Browse files
sebavansebavan
authored
Add MCP server (#345)
* Move tests to their own folder * fix * Add MCP server * fix changelogs
1 parent 14f7374 commit e4ebf8a

20 files changed

Lines changed: 9774 additions & 1 deletion

‎.github/workflows/githubActions.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,12 @@ jobs:
2323
npm run build --if-present
2424
env:
2525
CI: true
26+
- name: Run unit tests
27+
run: npm run test:unit
28+
- name: MCP - install & build
29+
run: |
30+
cd mcp
31+
npm install
32+
npm run build
33+
- name: MCP - run tests
34+
run: npm run mcp:test

‎documentation/changeLogs.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
Please, find below the per release summary of the contribution added to the project per version. Each of the listed versions is having its corresponding tag in the repo.
66

77
## v0.9.33
8+
* Add [Offscreen canvas support](https://github.com/BabylonJS/Spector.js/pull/345)
89
* Add [Offscreen canvas support](https://github.com/BabylonJS/Spector.js/pull/343)
910
* Add [Typescript typings](https://github.com/BabylonJS/Spector.js/pull/339)
1011
* Migrate [MVX to React](https://github.com/BabylonJS/Spector.js/pull/338)

‎mcp/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
node_modules/
2+
dist/

‎mcp/README.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# Spector.js MCP Server
2+
3+
An MCP (Model Context Protocol) server that lets AI assistants debug **any WebGL website** using [Spector.js](https://spector.babylonjs.com/) — a WebGL debugger.
4+
5+
Load any URL, capture WebGL frames, and inspect draw calls, shaders, textures, and GL state — all from your AI-powered editor. Works with Three.js, Babylon.js, PlayCanvas, raw WebGL, and any other WebGL-based site.
6+
7+
This server lives inside the Spector.js repository at `mcp/`.
8+
9+
## Architecture
10+
11+
```
12+
AI Assistant ←→ MCP Server (stdio) ←→ Playwright (headless Chromium) ←→ Any WebGL Website + Spector.js
13+
```
14+
15+
The server launches a headless browser, navigates to any URL, injects Spector.js at runtime, and exposes WebGL debugging capabilities as MCP tools.
16+
17+
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.
18+
19+
## Tools
20+
21+
### Navigation
22+
| Tool | Description |
23+
|------|-------------|
24+
| `load_url` | Navigate to any URL and prepare for WebGL debugging. Works with any WebGL site. |
25+
| `load_playground` | Convenience shortcut: load a Babylon.js Playground by snippet ID. Returns source code + screenshot. |
26+
| `take_screenshot` | Screenshot the current canvas. |
27+
28+
### Canvas Selection
29+
| Tool | Description |
30+
|------|-------------|
31+
| `list_canvases` | List all canvas elements on the page with WebGL context info. |
32+
| `select_canvas` | Select which canvas to target when there are multiple on the page. |
33+
34+
### Capture & Inspection
35+
| Tool | Description |
36+
|------|-------------|
37+
| `capture_frame` | Capture a single WebGL frame. Returns summary stats (commands, draw calls, programs, errors). |
38+
| `get_draw_calls` | List all draw calls from the last capture with command IDs, names, and arguments. |
39+
| `get_command_details` | Get full WebGL state at a specific command (blend, depth, stencil, bound textures, etc.). |
40+
| `get_shaders` | Get shader program source code (vertex + fragment) with compile/link status. |
41+
| `get_textures` | List texture uploads with dimensions, format, and type. |
42+
| `get_webgl_state` | Compare initial vs final GL state for the frame — shows what changed. |
43+
44+
### Diagnostics
45+
| Tool | Description |
46+
|------|-------------|
47+
| `get_context_info` | WebGL context details: version, extensions, capabilities, renderer. |
48+
| `get_console_logs` | Browser console errors/warnings — catches JS errors and WebGL warnings. |
49+
50+
## Setup
51+
52+
### Prerequisites
53+
- Node.js 18+
54+
55+
### Install
56+
57+
From the Spector.js repository root:
58+
59+
```bash
60+
npm run mcp:install
61+
npm run mcp:build
62+
```
63+
64+
Or manually:
65+
66+
```bash
67+
cd mcp
68+
npm install
69+
npx playwright install chromium
70+
npm run build
71+
```
72+
73+
### Configure MCP Client
74+
75+
Replace `<SPECTOR_REPO>` with the absolute path to your Spector.js repo clone.
76+
77+
**Claude Code / Copilot CLI** — add to your MCP settings:
78+
```json
79+
{
80+
"mcpServers": {
81+
"spector": {
82+
"command": "node",
83+
"args": ["<SPECTOR_REPO>/mcp/dist/index.js"]
84+
}
85+
}
86+
}
87+
```
88+
89+
**VS Code (Copilot)** — add to `.vscode/mcp.json`:
90+
```json
91+
{
92+
"servers": {
93+
"spector": {
94+
"type": "stdio",
95+
"command": "node",
96+
"args": ["<SPECTOR_REPO>/mcp/dist/index.js"]
97+
}
98+
}
99+
}
100+
```
101+
102+
## Typical Workflows
103+
104+
### Debug any WebGL site
105+
1. **Load a URL:**
106+
> "Load https://threejs.org/examples/#webgl_animation_keyframes and capture a frame"
107+
108+
2. **Inspect rendering:**
109+
> "Show me the draw calls and shaders"
110+
> "Get the GL state at draw call #15"
111+
112+
### Debug a Babylon.js Playground
113+
1. **Load by snippet:**
114+
> "Load playground #6FVG3Y and show me the code"
115+
116+
2. **Capture and analyze:**
117+
> "Capture a frame. Are there any GL errors?"
118+
119+
### Multi-canvas pages
120+
1. **Discover canvases:**
121+
> "List the canvases on this page"
122+
123+
2. **Switch targets:**
124+
> "Select canvas #2 and capture a frame"
125+
126+
## Project Structure
127+
128+
```
129+
mcp/
130+
├── src/
131+
│ ├── index.ts # MCP server entry point with tool registrations
132+
│ ├── browser-manager.ts # BrowserManager class for Playwright browser lifecycle
133+
│ ├── spector-bridge.ts # Spector.js injection and frame capture
134+
│ ├── capture-analyzer.ts # Pure functions for analyzing capture data
135+
│ ├── constants.ts # Shared constants (timeouts, GL format maps)
136+
│ ├── errors.ts # Custom error hierarchy
137+
│ └── types.ts # Type definitions
138+
├── dist/ # Compiled output (generated by npm run build)
139+
├── package.json
140+
└── tsconfig.json
141+
```
142+
143+
## Development
144+
145+
```bash
146+
npm run dev # Run with tsx (no build needed)
147+
npm run build # Build to dist/
148+
npm start # Run the built version
149+
npm test # Run unit tests
150+
```
151+
152+
## Testing
153+
154+
```bash
155+
npm test
156+
```
157+
158+
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).
159+
160+
## Dependencies
161+
162+
- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) — MCP server framework
163+
- [Playwright](https://playwright.dev/) — headless browser automation
164+
- [Spector.js](https://github.com/BabylonJS/Spector.js) — WebGL debugger (injected into the page at runtime)
165+
- [Zod](https://zod.dev/) — schema validation

‎mcp/jest.config.js‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
/** @type {import('jest').Config} */
2+
export default {
3+
preset: 'ts-jest/presets/default-esm',
4+
testEnvironment: 'node',
5+
roots: ['<rootDir>/src'],
6+
testMatch: ['**/*.test.ts'],
7+
moduleFileExtensions: ['ts', 'js', 'json'],
8+
extensionsToTreatAsEsm: ['.ts'],
9+
moduleNameMapper: {
10+
'^(\\.{1,2}/.*)\\.js$': '$1',
11+
},
12+
transform: {
13+
'^.+\\.ts$': ['ts-jest', {
14+
useESM: true,
15+
tsconfig: 'tsconfig.json',
16+
}],
17+
},
18+
};

0 commit comments

Comments
 (0)