Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(blender-mcp): generate a model from a reference image, not just a prompt
nirholas64fff2980e77
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 1445ac81b..560d038a5 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **Shared avatar and agent links now show a real page to Google, not a loading spinner**: Search engines were shown a different version of every /avatars/... and /agents/... page than people were, and that version had nothing on it: the name and description were hidden in a fallback block that a crawler removes before reading, the rest was a spinner, and the last line of the page sent the crawler straight back to the URL it was already on. Tens of thousands of avatar and agent pages therefore looked identical to Google and were filed as duplicates instead of being listed. Crawlers now get the same content a visitor sees: the name, the description, the rendered card, the creator, the tags, the skills, the on-chain identity, and links onward into the gallery and the directory. A link to an avatar or agent that no longer exists now says so honestly instead of quietly bouncing to a listing page, an id that belongs to the other side of the platform redirects to where it actually lives, and a private agent is no longer readable by anything sending a crawler's name. Signed-in surfaces were also unblocked in robots.txt so their existing no-index instruction can finally be read and obeyed. `[fix, infra]`- **The AgenC task embed now loads even when it is inlined or served from a blob**: The <three-ws-agent> element that shows a 3D avatar reacting to an on-chain AgenC task resolves its mesh decoder relative to its own script address. A copy that had been pasted inline, bundled, or loaded from a blob: or data: URL has no address to resolve against, and the element failed to register before it drew anything. It now falls back to the decoder on three.ws in that case and keeps the same-origin path everywhere else, so the embed works wherever the snippet ends up. (`/agenc/embodied`) `[fix]`- **The Blender tools now show you the render instead of describing it**: Asking an assistant to render a 3D model used to hand back a file path, which is useless if the assistant cannot open files on your disk. The rendered image now comes back with the answer, scaled to fit, while the full-resolution PNG still lands on disk. That turns a look at this model into one step, so an assistant can render, spot the problem, fix it and render again. Reading a file also reports its texture budget now: every image with its resolution and byte size, plus the total, which is usually what actually decides whether a model is small enough to ship, and it was previously reported as nothing more than a count. Two reliability fixes came out of real use: several requests at once now queue instead of all starting Blender at the same moment and exhausting the machine, and when Blender is installed but momentarily will not start you get a message saying exactly that, with the details, rather than being told to install software you already have. `[improvement, feature]`+- **Turn a photo into a 3D model without leaving your editor**: The Blender tools could already build a model from a written description. They now build one from a picture too: point at an image on your machine or a link to one, add a few words to steer it if you like, and the finished model opens in Blender. It runs on the same free lane as the text version and takes about as long. `[feature, sdk]`## 2026-09-05diff --git a/data/changelog.json b/data/changelog.jsonindex 7c6604691..fcac6d16a 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -26842,6 +26842,15 @@"feature","sdk"]+ },+ {+ "date": "2026-09-07",+ "title": "Turn a photo into a 3D model without leaving your editor",+ "summary": "The Blender tools could already build a model from a written description. They now build one from a picture too: point at an image on your machine or a link to one, add a few words to steer it if you like, and the finished model opens in Blender. It runs on the same free lane as the text version and takes about as long.",+ "tags": [+ "feature",+ "sdk"+ ]}]}diff --git a/docs/blender-mcp.md b/docs/blender-mcp.mdindex 854a9af7a..78978cbf4 100644--- a/docs/blender-mcp.md+++ b/docs/blender-mcp.md@@ -172,7 +172,9 @@ This tool runs caller-supplied code with the server's own permissions. See [Secu| Argument | Type | Notes ||---|---|---|-| `prompt` | string, required | One subject, e.g. `a weathered brass diving helmet`. |+| `prompt` | string | One subject, e.g. `a weathered brass diving helmet`. Required unless an image is given; with an image it steers the reconstruction. |+| `image` | string | Local PNG, JPEG or WebP to reconstruct from. Uploaded straight to storage on a presigned PUT, so the bytes never pass through the API. |+| `image_url` | string | A public https image to reconstruct from, instead of uploading one. || `output` | string | Destination. `.glb` keeps the generated bytes untouched; any other extension converts on the way in. || `tier` | enum | `draft`, `standard` (default), `high`. || `lane` | enum | `image` (default, free), `geometry` (Meshy/Tripo, needs a key), `sketch`. |@@ -181,7 +183,9 @@ This tool runs caller-supplied code with the server's own permissions. See [SecuRuns the public [`/api/forge`](./3d-api.md) pipeline: the default image lane (FLUX to TRELLIS) is free and needs no key, wallet, or account. When the output asks for a non-GLB format, the untouched GLB is kept beside it as `<name>.source.glb`, because conversion is lossy for some targets and the original is what the rest of the three.ws pipeline consumes.-Generation runs on a shared GPU lane and typically takes tens of seconds to a couple of minutes.+Generation runs on a shared GPU lane and typically takes tens of seconds to a couple of minutes. A reference image reconstructs in about the same time as a prompt.++If an upload fails, the deployment's object storage is the problem, not your file: `image_url` reaches the same lane without touching the upload path.```blender_forge_import { "prompt": "a weathered brass diving helmet", "output": "helmet.blend" }diff --git a/packages/blender-mcp/README.md b/packages/blender-mcp/README.mdindex b738227bb..8b67bf347 100644--- a/packages/blender-mcp/README.md+++ b/packages/blender-mcp/README.md@@ -71,7 +71,7 @@ Add `"env": { "BLENDER_PATH": "/path/to/blender" }` if Blender is not on `PATH`.| `blender_optimize` | The delivery pass in one call: decimate to a triangle budget, scale oversized textures, purge unreferenced datablocks, and compress the mesh streams with meshopt or Draco. Reports before and after triangles, texture bytes and file size. || `blender_render` | Renders a still PNG and returns it **inline**, so the assistant can actually see the model in one call even with no filesystem access. Ask for several views and it orbits the model, every angle in the same launch. If the file has no camera, one is created and framed to the model's bounding sphere; if it has no light, a key light and a lit world are added. A scene that already has its own camera and lighting renders as authored. || `blender_run_python` | Runs a `bpy` script against a scene, optionally opening a file first and exporting the result afterwards. The escape hatch for anything the other tools do not cover. |-| `blender_forge_import` | Generates a model from a text prompt on the public three.ws Forge pipeline and brings it into Blender, converting on the way in if the output asks for another format. The default image lane is free. |+| `blender_forge_import` | Generates a model from a text prompt **or a reference image** on the public three.ws Forge pipeline and brings it into Blender, converting on the way in if the output asks for another format. The default lane is free. |### Examples@@ -125,6 +125,12 @@ Generate an asset and open it as a `.blend`:blender_forge_import { "prompt": "a weathered brass diving helmet", "output": "helmet.blend" }```+Or reconstruct one from a reference image:++```+blender_forge_import { "image": "./reference.png", "prompt": "a brass diving helmet", "output": "helmet.glb" }+```+## Compressed glTFMeshopt- and Draco-compressed assets are decoded automatically before Blender opens them, in process, with no external binary to install.diff --git a/packages/blender-mcp/package.json b/packages/blender-mcp/package.jsonindex c4b044df6..7db8035c6 100644--- a/packages/blender-mcp/package.json+++ b/packages/blender-mcp/package.json@@ -1,6 +1,6 @@{"name": "@three-ws/blender-mcp",- "version": "0.4.0",+ "version": "0.5.0","mcpName": "io.github.nirholas/blender-mcp","description": "Drive the Blender on your machine from any AI agent, headless. Inspect a 3D file, convert between GLB/glTF/FBX/OBJ/STL/PLY/DAE/USD/Alembic/.blend, render a preview that comes back inline so the assistant can see it, run a bpy script against a scene, and generate a model from a text prompt on the free three.ws Forge lane. Meshopt- and Draco-compressed glTF is decoded automatically. No GUI, no add-on to install, no key.","type": "module",diff --git a/packages/blender-mcp/server.json b/packages/blender-mcp/server.jsonindex 3942bdc17..1525b8b34 100644--- a/packages/blender-mcp/server.json+++ b/packages/blender-mcp/server.json@@ -18,12 +18,12 @@"source": "github","subfolder": "packages/blender-mcp"},- "version": "0.4.0",+ "version": "0.5.0","packages": [{"registryType": "npm","identifier": "@three-ws/blender-mcp",- "version": "0.4.0",+ "version": "0.5.0","runtimeHint": "npx","transport": {"type": "stdio"diff --git a/packages/blender-mcp/src/lib/blender.js b/packages/blender-mcp/src/lib/blender.jsindex 0bcbdf08e..68a7f6bf7 100644--- a/packages/blender-mcp/src/lib/blender.js+++ b/packages/blender-mcp/src/lib/blender.js@@ -13,7 +13,7 @@import { spawn } from 'node:child_process';import { access, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';-import { constants } from 'node:fs';+import { constants, readdirSync } from 'node:fs';import os from 'node:os';import path from 'node:path';import { fileURLToPath } from 'node:url';@@ -46,10 +46,20 @@ function candidatePaths() {found.push('/Applications/Blender.app/Contents/MacOS/Blender');found.push(path.join(os.homedir(), 'Applications/Blender.app/Contents/MacOS/Blender'));} else if (process.platform === 'win32') {+ // Scanned, not enumerated: a hardcoded version list silently stops+ // finding Blender the moment a new release ships. Newest first, so an+ // upgraded machine picks the current install.for (const root of ['C:\\Program Files\\Blender Foundation', 'C:\\Program Files (x86)\\Blender Foundation']) {- for (const version of ['4.5', '4.4', '4.3', '4.2', '4.1', '4.0', '3.6']) {- found.push(path.join(root, `Blender ${version}`, 'blender.exe'));+ let entries = [];+ try {+ entries = readdirSync(root);+ } catch {+ continue;}+ const versions = entries+ .filter((name) => /^Blender\s+\d+\.\d+/i.test(name))+ .sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));+ for (const name of versions) found.push(path.join(root, name, 'blender.exe'));}} else {found.push('/usr/bin/blender', '/usr/local/bin/blender', '/snap/bin/blender', '/opt/blender/blender');diff --git a/packages/blender-mcp/src/lib/forge.js b/packages/blender-mcp/src/lib/forge.jsindex 8fe28ed9a..873279250 100644--- a/packages/blender-mcp/src/lib/forge.js+++ b/packages/blender-mcp/src/lib/forge.js@@ -9,7 +9,8 @@// ComfyUI nodes speak (integrations/_pyclient/three_ws_client.py).import { createWriteStream } from 'node:fs';-import { mkdir, stat } from 'node:fs/promises';+import { mkdir, readFile, stat } from 'node:fs/promises';+import { createHash } from 'node:crypto';import path from 'node:path';import { pipeline } from 'node:stream/promises';import { Readable } from 'node:stream';@@ -79,6 +80,95 @@ export async function catalog() {return forgeRequest('/api/forge', { query: { catalog: '1' } });}+const CONTENT_TYPES = {+ '.png': 'image/png',+ '.jpg': 'image/jpeg',+ '.jpeg': 'image/jpeg',+ '.webp': 'image/webp',+};++/**+ * Presign, upload, and return the public URL of a local reference image.+ *+ * The bytes go straight to object storage on a presigned PUT, so the image+ * never travels through the API and never through this conversation. A+ * deployment without storage configured says so, and the caller can pass a+ * public URL instead.+ *+ * @param {string} filePath Local PNG, JPEG, or WebP.+ * @returns {Promise<{url: string, bytes: number, content_type: string}>}+ */+export async function uploadReferenceImage(filePath) {+ const extension = path.extname(filePath).toLowerCase();+ const contentType = CONTENT_TYPES[extension];+ if (!contentType) {+ throw Object.assign(+ new Error(`Unsupported image type "${extension}". Use PNG, JPEG, or WebP.`),+ { code: 'invalid_content_type' },+ );+ }++ const bytes = await readFile(filePath);+ if (bytes.length === 0) {+ throw Object.assign(new Error(`${filePath} is empty.`), { code: 'invalid_size' });+ }++ const presign = await forgeRequest('/api/forge-upload', {+ method: 'POST',+ body: {+ content_type: contentType,+ size_bytes: bytes.length,+ checksum_sha256: createHash('sha256').update(bytes).digest('hex'),+ },+ });+ if (!presign.upload_url || !presign.public_url) {+ throw Object.assign(+ new Error(+ presign.message ||+ 'This deployment has no object storage configured for image upload. Pass a public https image URL instead.',+ ),+ { code: 'presign_failed' },+ );+ }++ const put = await fetch(presign.upload_url, {+ method: 'PUT',+ headers: presign.headers || { 'content-type': contentType },+ body: bytes,+ });+ if (!put.ok) {+ // The presigned PUT goes straight to object storage, so a failure here is+ // the deployment's storage, not the caller's file. Naming the way around+ // it matters: image-to-3D still works from a public URL, and a bare HTTP+ // status would leave the caller thinking the whole lane is down.+ throw Object.assign(+ new Error(+ `Uploading the reference image to the deployment's object storage failed with HTTP ${put.status}. ` ++ 'Pass a public https image as "image_url" instead, which does not use the upload path.',+ ),+ { code: 'upload_failed', status: put.status },+ );+ }+ return { url: presign.public_url, bytes: bytes.length, content_type: contentType };+}++/**+ * Submit reference images for image-to-3D and return the queued job.+ * @returns {Promise<{job_id: string, backend?: string}>}+ */+export async function submitImageTo3d({ imageUrls, prompt = '', tier = 'standard', backend, lane = 'image' }) {+ const urls = imageUrls.filter((url) => typeof url === 'string' && url.startsWith('https://'));+ if (urls.length === 0) {+ throw Object.assign(new Error('Image-to-3D needs at least one public https image URL.'), {+ code: 'invalid_image_urls',+ });+ }+ const body = { image_urls: urls, tier, path: lane };+ if (prompt.trim()) body.prompt = prompt.trim();+ if (backend) body.backend = backend;+ return submitted(await forgeRequest('/api/forge', { method: 'POST', body }));+}+/*** Submit a text prompt for generation and return the queued job.* @returns {Promise<{job_id: string, backend?: string}>}@@ -86,8 +176,10 @@ export async function catalog() {export async function submitTextTo3d({ prompt, tier = 'standard', backend, aspect_ratio = '1:1', lane = 'image' }) {const body = { prompt, tier, path: lane, aspect_ratio };if (backend) body.backend = backend;- const result = await forgeRequest('/api/forge', { method: 'POST', body });+ return submitted(await forgeRequest('/api/forge', { method: 'POST', body }));+}+function submitted(result) {if (result.error === 'needs_key') {throw Object.assign(new Error(diff --git a/packages/blender-mcp/src/tools/forge-import.js b/packages/blender-mcp/src/tools/forge-import.jsindex b92e0e543..1516db072 100644--- a/packages/blender-mcp/src/tools/forge-import.js+++ b/packages/blender-mcp/src/tools/forge-import.js@@ -11,8 +11,8 @@ import { z } from 'zod';import path from 'node:path';import { runJob } from '../lib/blender.js';-import { downloadGlb, submitTextTo3d, waitForGlb } from '../lib/forge.js';-import { resolveOutput } from '../lib/paths.js';+import { downloadGlb, submitImageTo3d, submitTextTo3d, uploadReferenceImage, waitForGlb } from '../lib/forge.js';+import { resolveInput, resolveOutput } from '../lib/paths.js';import { FORGE_TIMEOUT_MS } from '../config.js';function slug(prompt) {@@ -30,13 +30,27 @@ export const def = {title: 'Generate a 3D model with three.ws and open it in Blender',annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },description:- 'Generate a 3D model from a text prompt on the public three.ws Forge pipeline, then bring it into Blender. ' ++ 'Generate a 3D model from a text prompt OR a reference image on the public three.ws Forge pipeline, then ' ++ 'bring it into Blender. Pass "prompt" to describe it, "image" for a local PNG/JPEG/WebP, or "image_url" for ' ++ 'one already public; an image plus a prompt uses the prompt to steer the reconstruction. ' +'The default image lane (FLUX to TRELLIS) is free and needs no key, wallet, or account. The GLB is saved ' +'locally, and if the output path asks for another format (.blend, .fbx, .obj, .usd) Blender converts it on ' +'the way in. Returns the local path, the hosted GLB URL, and the geometry counts. Generation runs on a ' +'shared GPU lane and typically takes tens of seconds to a couple of minutes. Describe ONE subject per call.',inputSchema: {- prompt: z.string().min(3).describe('What to generate. One subject, e.g. "a weathered brass diving helmet".'),+ prompt: z+ .string()+ .min(3)+ .optional()+ .describe('What to generate. One subject, e.g. "a weathered brass diving helmet". Required unless an image is given.'),+ image: z+ .string()+ .optional()+ .describe('Local PNG, JPEG or WebP to reconstruct from. Uploaded straight to storage on a presigned PUT.'),+ image_url: z+ .string()+ .optional()+ .describe('A public https image to reconstruct from, instead of uploading one.'),output: z.string().optional()@@ -51,16 +65,26 @@ export const def = {},async handler(args) {const prompt = String(args?.prompt ?? '').trim();- const submitted = await submitTextTo3d({- prompt,- tier: args?.tier || 'standard',- backend: args?.backend,- aspect_ratio: args?.aspect_ratio || '1:1',- lane: args?.lane || 'image',- });+ const shared = { tier: args?.tier || 'standard', backend: args?.backend, lane: args?.lane || 'image' };++ let uploaded = null;+ let imageUrl = String(args?.image_url ?? '').trim();+ if (args?.image) {+ uploaded = await uploadReferenceImage(await resolveInput(args.image, 'image'));+ imageUrl = uploaded.url;+ }+ if (!imageUrl && prompt.length < 3) {+ throw Object.assign(new Error('Give a prompt of at least 3 characters, an "image", or an "image_url".'), {+ code: 'invalid_input',+ });+ }++ const submitted = imageUrl+ ? await submitImageTo3d({ imageUrls: [imageUrl], prompt, ...shared })+ : await submitTextTo3d({ prompt, aspect_ratio: args?.aspect_ratio || '1:1', ...shared });const finished = await waitForGlb(submitted.job_id, { timeoutMs: FORGE_TIMEOUT_MS });- const output = await resolveOutput(args?.output, slug(prompt), '.glb');+ const output = await resolveOutput(args?.output, slug(prompt || 'reference-image'), '.glb');const keepsOriginalBytes = output.toLowerCase().endsWith('.glb');// When the caller asked for another format, the untouched GLB is kept// beside it: conversion is lossy for some targets, and the original is@@ -74,7 +98,10 @@ export const def = {return {ok: true,- prompt,+ prompt: prompt || null,+ source: imageUrl ? 'image' : 'text',+ reference_image: imageUrl || null,+ uploaded_bytes: uploaded ? uploaded.bytes : null,job_id: submitted.job_id,backend: finished.backend || submitted.backend,glb_url: finished.glb_url,diff --git a/packages/blender-mcp/test/registration.test.mjs b/packages/blender-mcp/test/registration.test.mjsindex 1ac3da675..d1f6fd307 100644--- a/packages/blender-mcp/test/registration.test.mjs+++ b/packages/blender-mcp/test/registration.test.mjs@@ -98,6 +98,24 @@ test('blender_render is the tool that returns extra content blocks', () => {assert.deepEqual(withAttachments, ['blender_render'], 'only the render tool inlines an image today');});+test('blender_forge_import needs a prompt or an image, and says so offline', async () => {+ const forge = TOOLS.find((t) => t.name === 'blender_forge_import');+ await assert.rejects(+ () => forge.handler({}),+ (err) => err.code === 'invalid_input' && /prompt|image/i.test(err.message),+ 'an empty call must fail locally rather than sending a doomed request',+ );+});++test('blender_forge_import rejects an image type the pipeline cannot read', async () => {+ const forge = TOOLS.find((t) => t.name === 'blender_forge_import');+ await assert.rejects(+ () => forge.handler({ image: fileURLToPath(import.meta.url) }),+ (err) => ['invalid_content_type', 'input_not_found'].includes(err.code),+ 'a .mjs is not a reference image',+ );+});+test('buildServer registers without Blender or network access', () => {const server = buildServer();assert.ok(server, 'buildServer() must return an McpServer');diff --git a/public/changelog.json b/public/changelog.jsonindex 9eb250476..6d06cd8a7 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-09-07T06:19:07.968Z",+ "generated_at": "2026-09-07T06:25:33.785Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws",@@ -114,6 +114,17 @@"feature"]},+ {+ "date": "2026-09-07",+ "type": "update",+ "title": "Turn a photo into a 3D model without leaving your editor",+ "summary": "The Blender tools could already build a model from a written description. They now build one from a picture too: point at an image on your machine or a link to one, add a few words to steer it if you like, and the finished model opens in Blender. It runs on the same free lane as the text version and takes about as long.",+ "link": null,+ "tags": [+ "feature",+ "sdk"+ ]+ },{"date": "2026-09-05","type": "launch",diff --git a/public/changelog.xml b/public/changelog.xmlindex 32a7e58a9..200f5746b 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -86,6 +86,14 @@<category>improvement</category><description>Asking an assistant to render a 3D model used to hand back a file path, which is useless if the assistant cannot open files on your disk. The rendered image now comes back with the answer, scaled to fit, while the full-resolution PNG still lands on disk. That turns a look at this model into one step, so an assistant can render, spot the problem, fix it and render again. Reading a file also reports its texture budget now: every image with its resolution and byte size, plus the total, which is usually what actually decides whether a model is small enough to ship, and it was previously reported as nothing more than a count. Two reliability fixes came out of real use: several requests at once now queue instead of all starting Blender at the same moment and exhausting the machine, and when Blender is installed but momentarily will not start you get a message saying exactly that, with the details, rather than being told to install software you already have.</description></item>+ <item>+ <title>Turn a photo into a 3D model without leaving your editor</title>+ <link>https://three.ws/changelog</link>+ <guid isPermaLink="false">2026-09-07:Turn a photo into a 3D model without leaving your editor</guid>+ <pubDate>Mon, 07 Sep 2026 12:00:00 GMT</pubDate>+ <category>feature</category>+ <description>The Blender tools could already build a model from a written description. They now build one from a picture too: point at an image on your machine or a link to one, add a few words to steer it if you like, and the finished model opens in Blender. It runs on the same free lane as the text version and takes about as long.</description>+ </item><item><title>Docs · Pocket Console</title><link>https://three.ws/docs/pocket</link>diff --git a/public/features.json b/public/features.jsonindex 22c73271b..c43fe88b2 100644--- a/public/features.json+++ b/public/features.json@@ -1,5 +1,5 @@{- "generated_at": "2026-09-07T06:19:07.914Z",+ "generated_at": "2026-09-07T06:25:33.760Z","generated_by": "scripts/build-page-index.mjs from data/pages.json","site": {"name": "three.ws",