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
// `mesh_forge` — paid MCP tool: text → textured 3D GLB, as a model chain.
//
// Pricing: $0.25 USDC, settled `exact` on Solana.
//
// This is a thin, x402-gated client over the three.ws production pipeline — it
// does NOT hold any generation credentials itself. The npx-distributed MCP
// server can run anywhere; all GPU/LLM work happens on three.ws prod (which
// holds the Replicate / watsonx keys). The x402 USDC payment is what gates the
// call.
//
// The generation logic lives in `_studio-core.js` (runMeshForge) so every stdio
// tool that generates a mesh shares ONE implementation and never drifts. The
// hosted FREE 3D Studio endpoint (/api/mcp-studio) drives the same /api/forge
// pipeline through its own client, api/_mcp-studio/forge-client.js. Two modes:
// • text→3D — IBM Granite directs the prompt, FLUX renders a reference image,
// then TRELLIS / Hunyuan3D reconstruct a textured GLB.
// • image→3D — a caller-supplied image_url (or 1–4 multi-view image_urls) is
// reconstructed directly.
//
// Environment (all optional — sensible prod defaults):
// MESH_FORGE_API_BASE — three.ws origin. Default https://three.ws
// MESH_FORGE_DIRECTOR — "0" to skip the prompt-director stage. Default on.
// MESH_FORGE_DIRECTOR_MODEL — model id for direction, resolved by the server's
// anonymous chat chain. Default server default.
// MESH_FORGE_TIMEOUT_MS — overall reconstruct poll budget. Default 180000.
// MESH_FORGE_POLL_MS — poll interval. Default 3000.
import { z } from 'zod';
import { paid } from '../payments.js';
import { jsonSchemaFromZod } from './_shared.js';
import { runMeshForge } from './_studio-core.js';
const TOOL_NAME = 'mesh_forge';
const TOOL_DESCRIPTION =
'Generate a textured 3D GLB model from a text prompt, a single reference image, OR 2-4 reference views of the same object. In text mode, a chain of specialist models runs: an IBM Granite "prompt director" rewrites the prompt into an optimized 3D spec, FLUX renders a reference image, then Microsoft TRELLIS / Tencent Hunyuan3D reconstruct the mesh. In image mode, a supplied image_url is reconstructed directly. In multi-view mode, pass image_urls (1-4 angles such as front/back/left/right) and the backend fuses them for a higher-fidelity mesh with no hallucinated back. Returns the GLB URL, a three.ws viewer link, how many views were fused, which backend handled it, the directed prompt (text mode), and timing. Feed the GLB to rig_mesh for a rigged, animation-ready model. Use this when you have reference images or want the directed text chain; for a free text-only draft, call forge_free instead. Paid: $0.25 USDC.';
const inputZodShape = {
prompt: z
.string()
.min(3)
.max(1000)
.describe('Text→3D: natural-language description of the single object to model, e.g. "a worn leather armchair". Optional when image_url is provided (then used only as guidance).')
.optional(),
image_url: z
.string()
.url()
.describe('Image→3D: an http(s) URL to a reference image to reconstruct directly. When set, the prompt-director and text-to-image stages are skipped.')
.optional(),
image_urls: z
.array(z.string().url())
.min(1)
.max(4)
.describe('Multi-view → 3D: 1–4 http(s) URLs of the SAME object from different angles (e.g. front, back, left, right). More than one view enables multi-view reconstruction, which removes the back-of-object guesswork of single-image reconstruction. Takes precedence over image_url.')
.optional(),
aspect_ratio: z
.enum(['1:1', '4:3', '3:4', '16:9', '9:16'])
.describe('Reference image aspect ratio (text mode). Default 1:1 (best for isolated objects).')
.optional(),
direct: z
.boolean()
.describe('Run the IBM Granite prompt-director stage to optimize the prompt before generation (text mode only). Default true.')
.optional(),
};
const inputJsonSchema = jsonSchemaFromZod(inputZodShape);
export async function buildMeshForgeTool() {
const handler = await paid(
{
toolName: TOOL_NAME,
description: TOOL_DESCRIPTION,
scheme: 'exact',
priceUsd: '$0.25',
inputSchema: inputJsonSchema,
example: { prompt: 'a worn leather armchair, brass studs', aspect_ratio: '1:1' },
outputExample: {
ok: true,
glbUrl: 'https://three.ws/cdn/creations/abc123/mesh.glb',
preview: 'https://three.ws/viewer?src=https%3A%2F%2Fthree.ws%2Fcdn%2F...',
prompt: 'a worn leather armchair, brass studs',
imageUrls: null,
viewsRequested: 0,
viewsUsed: 1,
multiview: false,
backend: 'replicate',
directedPrompt: 'A single worn brown leather wingback armchair with brass stud trim...',
directed: true,
jobId: 'k7m2q9x4',
creationId: 'abc123',
referenceImageUrl: 'https://replicate.delivery/.../ref.png',
durationMs: 96000,
},
},
(args) => runMeshForge(args),
);
return {
name: TOOL_NAME,
title: 'Text → 3D mesh ($0.25)',
description: TOOL_DESCRIPTION,
inputSchema: inputZodShape,
// Creates a hosted mesh artifact via external generation APIs; destroys
// nothing, and every call mints a fresh asset.
annotations: {
readOnlyHint: false,
destructiveHint: false,
idempotentHint: false,
openWorldHint: true,
},
handler,
};
}