Threesmith
Provides tools for three.js projects: reviews and fixes code against the installed three.js version, looks up exact APIs, validates shaders and asset paths, runs headless scene checks with screenshots, inspects live scene visibility, measures performance and leaks, builds and lints 3D models, and scans project setup with prioritized fixes.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
three.js ships a release almost every month and removes old APIs. Coding agents learned it from years of code that used
THREE.Geometry, outputEncoding, three/examples/js and import paths that no longer exist, and they cannot see the
canvas they draw on. Threesmith is the check between the agent and your project: the API of the three version you
have installed, a scored review, the assets and decoders the code needs, the live scene in headless Chromium, and
safe, undoable edits. Everything runs locally; nothing leaves the machine.
Without and with
Your agent... | On its own | With Threesmith |
writes three.js |
| 98 rules pinned to the installed release flag each line with the fix; |
calls an API | guesses a name or an import path from memory |
|
writes a shader |
| includes checked against the installed |
loads a model |
|
|
says "it works" | never opened the page |
|
gets a black screen | guesses: more light? move the camera? |
|
fixes a bug | cannot show it was there, or that it is gone |
|
makes it fast | changes things and hopes |
|
ships it | builds once, deploys, sees a 404 |
|
needs a 3D model | needs Blender or a placeholder cube |
|
does not know the project | reads twenty files |
|
Related MCP server: threejs-devtools-mcp
Quickstart
1. See what is wrong. Nothing to install but the package:
npx -y threesmith doctor # what is wrong, grouped by cause, most urgent first, with next steps
npx -y threesmith review # score 0-100, `file:line severity [rule] message Fix: ...`
npx -y threesmith check . # open the page headless, errors and a screenshot2. Give it to your agent. In Claude Code:
/plugin marketplace add laaielichter/Threesmith
/plugin install threesmith@threesmith3. Ask for something. "Find out why the scene is black and fix it." Every three.js file Claude edits is reviewed right after the edit, its errors and broken asset paths go straight back to Claude, and the session starts with a brief of the project.
Install in your agent
Client | How |
Claude Code |
|
Claude Code, MCP only |
|
Codex |
|
Cursor, VS Code | the buttons at the top |
Gemini CLI |
|
Cline and others | llms-install.md, or |
Docker |
|
Run the agent from the project folder, or pass --project <path>. Needs Node.js 22.12+ and three installed in the
project. The browser tools need playwright-core and a Chromium (npx playwright-core install chromium);
threesmith doctor --env shows what is missing.
Made for agents: cheap calls, exact answers
Two profiles.
--tier cheap(the default) gives short, capped output and numbered step-by-step instructions, so small models follow the right order;--tier premiumgives full detail for large models.Tool sets.
--tools coreloads 14 tools; addrun,live,build,modelwhen you need them, or name single tools. A tool list the client pays for in every turn stays small. The server instructions only ever name tools that are loaded.Fix loops that cost less.
three_reviewwithonly_new: trueshows new findings in full, the ones the agent already saw as one short line, and how many are fixed.code+filereviews code before it is saved.Structured results. Review, check and doctor return
structuredContentwith an output schema next to the text.One line per finding.
file:line severity [rule] message Fix: ..., the same in the CLI (--compact), MCP and hooks.Safe writes. Every write (fix, model build, scenario save) is one journal entry that
three_undotakes back; a file changed by hand since is left alone."protect"inthreesmith.json(orTHREESMITH_PROTECT) names folders no write may touch.--read-onlyleaves out the tools that always write and refuses write options.It learns, locally. A finding marked as a false alarm with
three_feedbackis hidden from then on; lessons kept withthree_lesson_addcome back under the same error. Only hashes, counters and scrubbed text, on this machine.
The 31 tools
Set | Tool | What it does |
core |
| Start here when something is broken: versions and imports, why the scene shows nothing, assets that will not load, removed APIs, colour, performance and cleanup, grouped by cause, most urgent first, with what |
core |
| Map the project: bundler and framework, three vs |
core |
| Exact API of a class, member or constant in the installed three: signature, deprecation, import path; did-you-mean for unknown names |
core |
| Find classes, constants and members by part of a name |
core |
| Scored review (0-100) with 98 rules pinned to the installed release; |
core |
| The project's own |
core |
| The renames that mean exactly the same, dry run first, undoable |
core |
| Cause and fix of a console, build or test message (35 kinds), with the right import path for the installed release |
core |
| 100 lessons from real three.js and react-three-fiber projects (symptom, cause, fix, test) by error message, words, rule or topic |
core |
| Keep a lesson learned here, scrubbed of names, paths and code; it comes back under the same error |
core |
| Every review rule with its category, release gating and fix |
core |
| Mark a finding as a false alarm (hidden from then on) or right |
core |
| Undo the last Threesmith writes, newest first |
core |
| Which three release is installed |
run |
| Headless Chromium (software WebGL 2): console and page errors with causes, shader errors at your file and line, failed requests, no context, lost context, blank frames, screenshot, baselines with a diff, interaction steps |
run |
| The live scene graph, camera, draw calls, GPU memory growth, and why each object is not visible |
run |
| Steps (click, press, hold, drag, wheel, frames, eval, until), watched values per frame and step, claims judged at the end, any moment or every frame |
run |
| Keep a passing play run as a regression test in |
run |
| Draw calls, triangles, programs, geometries, textures (exact) and frame-time percentiles with the slowest frames and their cause, against a budget and the last run |
run |
| Repeat a cycle of steps with garbage collection and report what grows per cycle, down to the GPU resources never disposed, by type |
live |
| Keep a headless page open between calls (start, status, stop) |
live |
| Drive that page without reloading: eval JS against the live scene, steps, frames, until, screenshot, inspect, reload, new errors after every answer |
build |
| Every asset path resolved like the dev server and a static host: missing files, wrong capitals, decoder folders, glTF decoders the code never sets up, huge textures, unused files |
build |
| Run the build, check the output (copies of three, missing assets, sub-path URLs, decoders) and open the built page headless |
model |
| One page before you build a model: the nearest ready-made kind, parts, real size, rules, the order of tools |
model |
| What a thing is (English or Dutch): parts, pivots, typical size, variants, usual mistakes |
model |
| The JSON model spec, an example, and the 110 ready-made kinds |
model |
| Build a clean, deterministic |
model |
| A |
model |
| Score a |
model |
| What is in a |
CLI: threesmith doctor | scan | api | search | review | types | fix | rules | undo | lessons | assets | check | inspect | play | scenario | perf | leaks | build | model <inspect|needs|view|lint|identify|brief|spec|kinds|recipes|build> | explain | ci | hook | mcp. threesmith <command> --help lists the options.
The review
Rules are pinned to the installed release: a removed API is an error on a release that removed it and a warning on an older one; a rule whose replacement does not exist yet in your release stays quiet. The categories:
api (28): removed or renamed APIs and their releases, symbols that do not exist in the installed version, TSL names imported from the wrong entry,
three/srcimports, deprecations read from three's own source.correctness (48): code that renders nothing or the wrong thing — no lights, shadows off, renderer never attached,
render(camera, scene),scene.add(gltf), a mixer never updated,getElapsedTime()andgetDelta()on one clock, instance and attribute updates withoutneedsUpdate, raycasting with window instead of canvas coordinates, controls bound todocument, decoders created but never attached; shaders:#includechunks that do not exist in the installed release,onBeforeCompilepatches that do nothing, GLSL3 mistakes, redeclared built-ins, uniforms without{ value }, GLSL materials under WebGPU and node materials under WebGL; React Three Fiber: state set inuseFrame, objects made in render.performance (10): allocations and heavy objects per frame, scene traversal per frame, uncapped pixel ratio, huge shadow maps, many meshes that should be instanced.
lifecycle (3): no resize handling, removed objects never disposed,
dispose()withoutsuper.dispose().color (8): colour textures without
colorSpace, colour management off, EffectComposer without OutputPass or with double gamma,envMapIntensitythat has no effect.
It reads text, not types (three_types adds the type checker for TypeScript). The rules are tested against three's
own examples and addons for false alarms. If a finding is wrong: three_feedback, --disable <rule>, or
// threesmith-disable-next-line <rule> (also -disable-line, -disable-file); an issue with the snippet is the most
useful bug report.
GitHub Action
- uses: laaielichter/Threesmith@main
with:
min-score: 85
check: dist # folder with the built index.html; omit to skip the browser
baseline: home # screenshot baseline in .threesmith/baselines/home.png
comment: true # post the receipt on the pull requestThe receipt (review, check, scenarios) appears in the job summary and optionally as a PR comment. Locally or in any
CI: threesmith ci --check dist --junit junit.xml --sarif threesmith.sarif. Commit .threesmith/baselines/ and
.threesmith/scenarios/; the rest of .threesmith/ is local state and ignored by its own .gitignore.
Limits
WebGL 2 in headless Chromium works in GitHub Actions (SwiftShader software rendering). WebGPU is best effort (
--webgpu), depending on the runner having an adapter.Frame times come from software rendering: compare them before and after on the same machine. Draw calls, triangles, programs and resource counts are exact.
Baselines should be made in the environment that checks them (CI), with the default tolerance.
The API lookup parses the JSDoc in
three/src; it is tested on r187, older releases give thinner answers.The review is heuristic; the asset check follows paths written as text, not paths built at run time.
Benchmarks
bench/ has tasks and a deterministic grader for comparing an agent with and without Threesmith. No results are
published yet; see bench/README.md for the method.
Sister tools
From the same author, local and open source: ReversePort (reverse engineer and port games between engines), Godotwright (check the Godot code your agent writes), Stashpad (agent memory you can trust) and agentdisk (clean up after agents).
Support the project
If Threesmith is useful to you, a ⭐ on GitHub helps other people find it.
Thanks to everyone who has contributed: @chiragjangiir, @timmiballz22 and @IG-ABHINAV.
Develop
npm ci
npm run check # typecheck, tests (incl. headless Chromium), buildTry the Claude Code plugin from this checkout, before a release: npm run build && npm run plugin:local, then start
Claude Code with the claude --plugin-dir ... line it prints.
See AGENTS.md and CONTRIBUTING.md. Threesmith follows the design of its sister project for Godot, Godotwright. MIT licensed, made by laaielichter.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Generate, edit, and deploy immersive 3D/WebGL web projects from any MCP assistant.
Free MCP security tools for AI coding agents. Check npm/PyPI package versions, identify known OSV vulnerabilities, compare with the latest releases, and review up to 3 dependencies before deployment.
Build, run and publish 3D games in the Zero engine from Claude Code, Cursor or Codex, over MCP.
3D avatars, embeds, glTF tools, agent memory, and on-chain agent identity from three.ws.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to inspect and edit live Three.js scenes — objects, materials, shaders, lighting, animation and performance — with zero project changes, previewing tweaks in the browser and converting them into ready-to-paste code. It also supports site performance audits, video frame capture, and Playwright/Puppeteer test integration.5,671 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to inspect and edit live Three.js scenes in the browser — objects, materials, shaders, textures, lights, animation, performance and memory — with 69 tools covering scene trees, screenshots, website audits and video frame capture. Changes can be previewed live with zero project modifications, then converted into ready-to-paste vanilla Three.js or React Three Fiber code.5,671 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to inspect and edit Three.js scenes, materials, shaders, lights, textures, animation, performance, and memory in real time, with live previews convertible into vanilla Three.js or React Three Fiber code. Also supports website audits, video frame capture, and Playwright/Puppeteer workflows.5,671 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to inspect live Three.js scenes in the browser, preview material, lighting, and camera changes without touching project files, and then write the approved tweaks back into source code. Its 69 tools also cover shaders, textures, animation, performance and memory debugging, website audits, and smooth frame capture for video clips.5,671 npmMIT