canvas3d-mcp

Servidor MCP que dá a agentes de IA olhos e instrumentos para criar arte e jogos em <canvas> HTML: modelos 3D (Three.js, WebGL puro, Canvas 2D por software), ilustração 2D, UI de jogos, pixel art e jogos 2D/3D jogáveis (com playtest automatizado). Suporta projetos multi-arquivo (a pasta do HTML de entrada é servida inteira).

A IA escreve um arquivo HTML auto-contido; o servidor renderiza em Chromium headless e devolve:

• render_scene — screenshots multi-ângulo (front/side/top/three-quarter ou ângulos custom, close-up via distance_factor < 1) ou frames sequenciais de animação (animation_frames + frame_interval_ms). A IA passa a ver o que criou e itera.
• validate_scene — relatório JSON estruturado: erros de página/console, canvas em branco, e (com Three.js registrado) checks profundos do grafo de cena: objetos flutuando, sem luzes, fora do frustum, transform NaN, texturas sem UV, clipping de câmera etc. Para pixel art (window.__pix): ANTI_ALIASING (pixels borrados/fora da grade) e PALETTE_OVERFLOW. Cada issue vem com severidade e sugestão de correção.
• interact_scene — playtest: executa um roteiro de inputs (teclas seguradas, cliques, esperas) intercalado com screenshots e leituras de window.__state(), para a IA verificar que o gameplay funciona (player anda? pula? pontua?). Inclui estimativa de FPS.
• inspect_scene — dump da árvore de cena Three.js com bounding boxes em coordenadas de mundo, para raciocinar sobre posicionamento exato.
• get_guidelines — guias (workflow, ofício 3D geral, texturização, armadilhas por tecnologia, ilustração 2D + UI de jogos, pixel art).

Bibliotecas de helpers servidas em /__helpers/ para o HTML da IA:

Lib	Para	Destaques
three-helpers.js	Three.js	register(), anchor(), mirrorX(), frameCamera(), threePointLights(), applyTexture()
canvas3d.js	Canvas 2D	mini-engine 3D por software (C3D): primitivas, câmera orbital, flat shading
webgl-helpers.js	WebGL puro	GLH: shaders prontos, malhas com UVs, mat4, orbitCamera, upload de texturas
texture-helpers.js	todas	TEX: texturas procedurais (wood, brick, marble, noise, bump...) sem rede
draw2d.js	ilustração 2D / UI	D2D: camadas com transform, formas/gradientes/sombras, UI de jogos (panel, healthBar, button), ticker de animação
pixel-helpers.js	pixel art	PIX: grade lógica exibida nítida, paletas retrô (Game Boy, PICO-8, NES...), Bresenham, flood fill, dithering, espelhamento, outline, sprites, animação por frames
game2d.js	jogos 2D	G2D: loop com timestep fixo, input com edge detection, entidades/tags, colisão AABB, tilemap por strings com moveEntity (física de plataforma), câmera follow/shake, tweens, partículas, cenas
game3d.js	jogos 3D	G3D: bootstrap de mundo (luzes + registro automático), character controller (WASD+pulo+gravidade), câmera 3ª pessoa, colisores AABB moveAndCollide, raycast pick, spawner

Setup

npm install
npx playwright install chromium

Registrar no Claude Code

# escopo do projeto atual:
claude mcp add canvas3d -- npx tsx "C:\Users\use\Desktop\ESTUDO\3d canvas improve\src\index.ts"

# ou disponível em todos os projetos:
claude mcp add --scope user canvas3d -- npx tsx "$PWD\src\index.ts"


# para confirmar
claude mcp list

Depois peça, por exemplo: "usando as tools do canvas3d, crie um robô 3D em Three.js — leia get_guidelines('workflow') primeiro e itere com render/validate até ficar bom".

O loop que a IA segue

1. get_guidelines("workflow") → convenções e snippets
2. escreve o HTML (com helpers, registrando window.__scene ou window.__setView)
3. render_scene → olha todos os ângulos
4. validate_scene → corrige errors, depois warnings
5. repete até imagem + relatório ficarem bons

Desenvolvimento

npm test            # vitest: unit + integração (Playwright real)
npm run typecheck   # tsc --noEmit
npx tsx scripts/smoke-render.ts examples/good-threejs-robot.html   # render direto, salva JPGs
npx tsx scripts/smoke-mcp.ts                                       # smoke da camada MCP via stdio

Estrutura: src/ (servidor MCP + pipeline Playwright + análise), src/probe/injected/ (scripts injetados na página), helpers/ (libs servidas ao HTML), guidelines/ (guias), examples/ (cenas boas + defects/ que disparam cada validador), tests/.

Notas de plataforma (descobertas empiricamente nesta máquina)

• WebGL headless funciona sem flags (SwiftShader). Override: CANVAS3D_BROWSER_ARGS.
• O primeiro contexto WebGL criado logo após o launch do browser é perdido (corrida de init do processo GPU). Mitigado por warmup no launch + reload automático da página quando o snapshot detecta contexto perdido.
• Canvas WebGL "render-once" pode capturar em branco (buffer descartado após present). O probe força preserveDrawingBuffer: true e o servidor chama window.__redraw antes de capturar.