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): return the render inline and stop reporting a busy host as a missing Blender
nirholas3c8439581c89
diff --git a/packages/blender-mcp/src/config.js b/packages/blender-mcp/src/config.jsindex c812893f6..1cd9a7629 100644--- a/packages/blender-mcp/src/config.js+++ b/packages/blender-mcp/src/config.js@@ -47,6 +47,20 @@ export const WORKDIR = path.resolve(env('BLENDER_MCP_WORKDIR', path.join(os.tmpd// unattended deployments and the tool is not advertised at all.export const ALLOW_PYTHON = boolean('BLENDER_MCP_ALLOW_PYTHON', true);+// Longest edge of the render copy returned inline in a tool result. A tool+// result travels through the model's context, so the image that goes back is a+// scaled copy; the full-resolution PNG is always written to disk.+export const INLINE_IMAGE_MAX_PX = positiveNumber('BLENDER_MCP_INLINE_IMAGE_PX', 768);++// Hard ceiling on the inlined bytes. Past this the image is left on disk and the+// response says so, rather than blowing up the caller's context.+export const INLINE_IMAGE_MAX_BYTES = positiveNumber('BLENDER_MCP_INLINE_IMAGE_BYTES', 1500000);++// How many Blender processes may run at once. Each one costs a few hundred MB,+// and a parallel agent issuing several calls at once on a small machine pushed+// the host into spawn failures that surfaced as a bogus "Blender not found".+export const MAX_CONCURRENCY = positiveNumber('BLENDER_MCP_MAX_CONCURRENCY', 2);+// three.ws deployment backing blender_forge_import.export const THREE_WS_BASE = env('THREE_WS_BASE', 'https://three.ws').replace(/\/+$/, '');diff --git a/packages/blender-mcp/src/index.js b/packages/blender-mcp/src/index.jsindex b2c5e3350..a36636fa5 100644--- a/packages/blender-mcp/src/index.js+++ b/packages/blender-mcp/src/index.js@@ -81,13 +81,19 @@ export function buildServer() {try {const result = await tool.handler(args, extra);const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);- return { content: [{ type: 'text', text }] };+ // A tool may return extra MCP content blocks alongside its JSON+ // payload. blender_render uses this to hand back the rendered+ // image itself, so the caller can SEE the model in the same call+ // instead of needing filesystem access it may not have.+ const attachments = tool.attachments ? await tool.attachments(result) : [];+ return { content: [{ type: 'text', text }, ...attachments] };} catch (err) {const payload = {ok: false,error: err?.code || 'unhandled',message: err?.message || String(err),...(err?.status ? { status: err.status } : {}),+ ...(err?.diagnostics ? { diagnostics: err.diagnostics } : {}),...(err?.traceback ? { traceback: err.traceback } : {}),...(err?.log ? { blender_log: err.log } : {}),};diff --git a/packages/blender-mcp/src/lib/blender.js b/packages/blender-mcp/src/lib/blender.jsindex 98dde63a9..18f1385f8 100644--- a/packages/blender-mcp/src/lib/blender.js+++ b/packages/blender-mcp/src/lib/blender.js@@ -18,7 +18,7 @@ import os from 'node:os';import path from 'node:path';import { fileURLToPath } from 'node:url';-import { BLENDER_PATH, JOB_TIMEOUT_MS, WORKDIR } from '../config.js';+import { BLENDER_PATH, JOB_TIMEOUT_MS, MAX_CONCURRENCY, WORKDIR } from '../config.js';const HERE = path.dirname(fileURLToPath(import.meta.url));export const RUNNER_PATH = path.join(HERE, '..', 'py', 'runner.py');@@ -30,6 +30,7 @@ const MIN_VERSION = [3, 0];const LOG_TAIL_BYTES = 4000;let cached = null;+let inFlight = null;function candidatePaths() {const found = [];@@ -55,29 +56,46 @@ function candidatePaths() {return found;}+/**+ * Probe one candidate with `--version`.+ *+ * Returns `{ version, tuple }` on success, or `{ error }` naming what went+ * wrong. The distinction matters: a spawn that fails because the host is out of+ * memory is transient and worth retrying, while a binary that is not Blender+ * never will be. Collapsing both into "not found" is what turns a busy machine+ * into a message telling the user to install software they already have.+ */function runVersion(binary) {return new Promise((resolve) => {let child;try {child = spawn(binary, ['--version'], { stdio: ['ignore', 'pipe', 'pipe'] });- } catch {- resolve(null);+ } catch (err) {+ resolve({ error: `spawn failed: ${err.message}`, transient: true });return;}let out = '';- const timer = setTimeout(() => child.kill('SIGKILL'), 20000);+ let timedOut = false;+ const timer = setTimeout(() => {+ timedOut = true;+ child.kill('SIGKILL');+ }, 20000);child.stdout.on('data', (chunk) => {out += chunk;});- child.on('error', () => {+ child.on('error', (err) => {clearTimeout(timer);- resolve(null);+ resolve({ error: `spawn failed: ${err.message}`, transient: true });});child.on('close', () => {clearTimeout(timer);+ if (timedOut) {+ resolve({ error: '--version did not answer within 20s', transient: true });+ return;+ }const match = /Blender\s+(\d+)\.(\d+)(?:\.(\d+))?/i.exec(out);if (!match) {- resolve(null);+ resolve({ error: 'ran, but did not identify itself as Blender', transient: false });return;}resolve({@@ -96,18 +114,29 @@ function runVersion(binary) {*/export async function resolveBlender() {if (cached) return cached;+ // Parallel tool calls must share one discovery pass. Without this, several+ // calls each spawn their own `--version` probes at the same moment, which is+ // exactly the memory pressure that makes probing fail.+ if (inFlight) return inFlight;+ inFlight = discoverBlender().finally(() => {+ inFlight = null;+ });+ return inFlight;+}- const tried = [];- for (const candidate of candidatePaths()) {- if (tried.includes(candidate)) continue;- tried.push(candidate);+async function probeCandidates(candidates) {+ const diagnostics = [];+ for (const candidate of candidates) {try {await access(candidate, constants.X_OK);} catch {- continue;+ continue; // Nothing there: not worth reporting, the list is speculative.}const info = await runVersion(candidate);- if (!info) continue;+ if (info.error) {+ diagnostics.push({ path: candidate, problem: info.error, transient: info.transient });+ continue;+ }if (info.tuple[0] < MIN_VERSION[0] || (info.tuple[0] === MIN_VERSION[0] && info.tuple[1] < MIN_VERSION[1])) {throw Object.assign(new Error(@@ -116,23 +145,55 @@ export async function resolveBlender() {{ code: 'blender_too_old' },);}- cached = { path: candidate, version: info.version, tuple: info.tuple };+ return { found: { path: candidate, version: info.version, tuple: info.tuple }, diagnostics };+ }+ return { found: null, diagnostics };+}++async function discoverBlender() {+ const candidates = [...new Set(candidatePaths())];+ let { found, diagnostics } = await probeCandidates(candidates);++ // A Blender that exists but would not answer is a transient condition on a+ // loaded machine, not a missing install. Give it one more chance before+ // telling anyone their setup is wrong.+ if (!found && diagnostics.some((entry) => entry.transient)) {+ await new Promise((resolve) => setTimeout(resolve, 750));+ const retry = await probeCandidates(diagnostics.filter((entry) => entry.transient).map((entry) => entry.path));+ if (retry.found) found = retry.found;+ else diagnostics = [...diagnostics, ...retry.diagnostics];+ }++ if (found) {+ cached = found;return cached;}+ if (diagnostics.length > 0) {+ throw Object.assign(+ new Error(+ `Blender is installed at ${diagnostics[0].path} but could not be run: ${diagnostics[0].problem}. ` ++ 'On a loaded machine this is usually transient (retry the call); otherwise check that the executable ' ++ 'works by running it yourself, or point BLENDER_PATH at a different one.',+ ),+ { code: 'blender_unusable', diagnostics },+ );+ }+throw Object.assign(new Error('No Blender executable found. Install Blender 3.0 or newer from https://www.blender.org/download/ ' +'and either put it on PATH or set BLENDER_PATH to the executable ' +'(macOS: /Applications/Blender.app/Contents/MacOS/Blender).',),- { code: 'blender_not_found', tried: tried.slice(0, 12) },+ { code: 'blender_not_found', tried: candidates.slice(0, 12) },);}/** Reset the cached executable. Tests use this; nothing else needs it. */export function resetBlenderCache() {cached = null;+ inFlight = null;}function tail(text) {@@ -146,6 +207,27 @@ export async function ensureWorkdir() {return WORKDIR;}+// Blender costs a few hundred MB per process, so unbounded parallelism on a+// small machine turns into spawn failures rather than throughput. Calls queue+// instead of competing.+let running = 0;+const waiting = [];++async function acquireSlot() {+ if (running < MAX_CONCURRENCY) {+ running += 1;+ return;+ }+ await new Promise((resolve) => waiting.push(resolve));+ running += 1;+}++function releaseSlot() {+ running -= 1;+ const next = waiting.shift();+ if (next) next();+}+/*** Run one job through the in-Blender runner and return its payload.*@@ -158,6 +240,7 @@ export async function ensureWorkdir() {export async function runJob(job, { timeoutMs } = {}) {const blender = await resolveBlender();await ensureWorkdir();+ await acquireSlot();const dir = await mkdtemp(path.join(WORKDIR, 'job-'));const jobPath = path.join(dir, 'job.json');const resultPath = path.join(dir, 'result.json');@@ -224,6 +307,7 @@ export async function runJob(job, { timeoutMs } = {}) {}return { ...payload, blender_path: blender.path };} finally {+ releaseSlot();await rm(dir, { recursive: true, force: true });}}diff --git a/packages/blender-mcp/src/tools/render.js b/packages/blender-mcp/src/tools/render.jsindex 67ee346de..7b6cccf3b 100644--- a/packages/blender-mcp/src/tools/render.js+++ b/packages/blender-mcp/src/tools/render.js@@ -9,9 +9,12 @@// CYCLES is the default engine because it renders on CPU; EEVEE needs a real// GPU context, which a headless container usually does not have.+import { readFile, rm } from 'node:fs/promises';+import { z } from 'zod';import { runJob } from '../lib/blender.js';+import { INLINE_IMAGE_MAX_PX, INLINE_IMAGE_MAX_BYTES } from '../config.js';import { resolveInput, resolveOutput } from '../lib/paths.js';export const def = {@@ -22,8 +25,9 @@ export const def = {'Render a still PNG of any 3D file Blender can open (.blend, .glb, .fbx, .obj, .usd and the rest). If the ' +'scene has no camera, one is created and framed to the model; if it has no light, a key light and a lit ' +'world are added, so a bare asset file renders as a usable preview with no setup. A scene that already has ' +- 'its own camera and lighting is rendered as authored. Returns the image path, the engine used, and whether ' +- 'a camera or lights had to be added. Use it to see a model, check a conversion, or produce a thumbnail.',+ 'its own camera and lighting is rendered as authored. The rendered image is returned INLINE alongside the ' ++ 'JSON, so you can actually look at the model in this one call without needing filesystem access, while the ' ++ 'full-resolution PNG is written to disk. Use it to see a model, check a conversion, or produce a thumbnail.',inputSchema: {input: z.string().min(1).describe('Path to the 3D file to render.'),output: z.string().optional().describe('Destination PNG path. Defaults to a .png in the server workdir.'),@@ -41,6 +45,10 @@ export const def = {.optional().describe('Output size as [width, height]. Default [960, 960].'),transparent: z.boolean().optional().describe('Render with a transparent background instead of the world. Default false.'),+ inline_image: z+ .boolean()+ .optional()+ .describe('Return the image inline so you can see it, downscaled to fit the context. Default true.'),},async handler(args) {const input = await resolveInput(args?.input);@@ -53,7 +61,31 @@ export const def = {samples: args?.samples ?? 32,resolution: args?.resolution ?? [960, 960],transparent: args?.transparent === true,+ inline_max_px: args?.inline_image === false ? 0 : INLINE_IMAGE_MAX_PX,});- return { ...payload, ok: true };+ return { ...payload, ok: true, inline_image: args?.inline_image !== false };+ },++ /**+ * Hand the rendered image back as an MCP image block.+ *+ * The scaled copy is read and then deleted: it exists only to travel in this+ * response, and leaving it beside the real output would be litter the caller+ * has to reason about. An image too large to inline is reported in the JSON+ * rather than silently dropped, so the caller knows to read the file.+ */+ async attachments(result) {+ if (!result?.inline_image) return [];+ const path = result.preview || result.output;+ const bytes = result.preview ? result.preview_bytes : result.output_bytes;+ if (!path || !bytes) return [];+ if (bytes > INLINE_IMAGE_MAX_BYTES) {+ result.inline_image_skipped = `the image is ${bytes} bytes, over the ${INLINE_IMAGE_MAX_BYTES} inline limit; read it from ${result.output}`;+ if (result.preview) await rm(path, { force: true });+ return [];+ }+ const data = await readFile(path);+ if (result.preview) await rm(path, { force: true });+ return [{ type: 'image', data: data.toString('base64'), mimeType: 'image/png' }];},};