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
// MCP tools for the Garment Forge: agents generate wearable, rigged catalog
// garments from a text prompt and follow the job to its published manifest.
//
// The heavy pipeline runs on the garment-forge Cloud Run worker
// (workers/garment-forge/README.md): Vertex reference image → GPU mesh fleet
// → composed onto the canonical body → auto-rigged → validated against the
// 6 rules of specs/GARMENT_MANIFEST.md → published to the public wardrobe
// catalog. These tools are the agent-facing face of the same lane the
// /api/garment-forge HTTP route exposes; the worker's bearer secret stays
// server-side.
import { limits } from '../../_lib/rate-limit.js';
import { fetchUpstream } from '../../_lib/upstream-fetch.js';
const GARMENT_SLOTS = [
'top', 'bottom', 'footwear', 'outerwear', 'hair', 'headwear', 'glasses', 'accessory',
];
const CATALOG_URL = 'https://storage.googleapis.com/three-ws-garments/garments/catalog.json';
const JOB_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
function rpcError(code, message, data) {
const e = new Error(message);
e.code = code;
e.data = data;
return e;
}
function workerConfig() {
const base = (process.env.GCP_GARMENT_FORGE_URL || '').replace(/\/$/, '');
const key = process.env.GCP_RECONSTRUCTION_KEY || '';
if (!base || !key) {
throw rpcError(
-32001,
'garment generation is not configured (GCP_GARMENT_FORGE_URL / GCP_RECONSTRUCTION_KEY unset)',
);
}
return { base, key };
}
export const toolDefs = [
{
name: 'generate_garment',
scope: 'avatars:write',
title: 'Generate a wearable garment from a text prompt',
annotations: {
readOnlyHint: false,
destructiveHint: false,
idempotentHint: false,
openWorldHint: true,
},
description:
'Turn a text prompt (e.g. "a red varsity jacket") into a rigged, wearable garment ' +
'published to the three.ws wardrobe catalog. The pipeline generates a reference ' +
'image, sculpts a PBR mesh on the GPU fleet, skins it to the canonical humanoid ' +
'skeleton, and validates it (including the 60% bind-coverage gate) before ' +
'publishing garment.glb + manifest.json + thumbnail. Runs asynchronously for ' +
'about 7 minutes; poll with garment_status. The finished piece appears in the ' +
'public catalog automatically and attaches to any humanoid avatar. Use this when ' +
'nothing in list_garment_catalog fits and the user wants a new wearable item made.',
inputSchema: {
type: 'object',
properties: {
prompt: {
type: 'string',
minLength: 3,
maxLength: 500,
description: 'Describe the garment (fabric, color, style).',
},
slot: {
type: 'string',
enum: GARMENT_SLOTS,
description: 'Wardrobe slot the garment occupies.',
},
},
required: ['prompt', 'slot'],
additionalProperties: false,
},
async handler(args, auth) {
const rl = await limits.mcp3dGenerate(auth.userId || auth.rateKey);
if (!rl.success) {
throw rpcError(-32000, 'rate_limited', {
retry_after: Math.ceil((rl.reset - Date.now()) / 1000),
});
}
const { base, key } = workerConfig();
const res = await fetchUpstream(`${base}/generate`, {
method: 'POST',
headers: { authorization: `Bearer ${key}`, 'content-type': 'application/json' },
body: JSON.stringify({ prompt: args.prompt, slot: args.slot }),
}, { name: 'garment-worker', timeoutMs: 30_000, attempts: 2, okWhen: () => true }).catch(() => null);
if (!res || !res.ok) {
throw new Error(`garment worker ${res ? `returned ${res.status}` : 'unreachable'}`);
}
const job = await res.json();
return {
content: [{
type: 'text',
text:
`Garment job ${job.job_id} queued (slot: ${args.slot}). The pipeline takes ` +
'about 7 minutes; call garment_status with this job_id to follow ' +
'image → mesh → compose → rig → extract → validate → publish.',
}],
structuredContent: { job_id: job.job_id, status: job.status || 'queued', eta_seconds: 450 },
};
},
},
{
name: 'garment_status',
title: 'Check a garment generation job',
annotations: {
readOnlyHint: true,
destructiveHint: false,
idempotentHint: false,
openWorldHint: true,
},
description:
'Poll a generate_garment job. While running, reports the pipeline stage. When ' +
'done, returns the published glb_url, manifest_url, thumbnail, measured bind ' +
'coverage, and the occluded body regions. At that point the garment is already ' +
'live in the wardrobe catalog. Use this after generate_garment to follow the job ' +
'until it finishes.',
inputSchema: {
type: 'object',
properties: {
job_id: { type: 'string', description: 'Job id returned by generate_garment.' },
},
required: ['job_id'],
additionalProperties: false,
},
async handler(args, auth) {
const rl = await limits.mcp3dStatus(auth.userId || auth.rateKey);
if (!rl.success) {
throw rpcError(-32000, 'rate_limited', {
retry_after: Math.ceil((rl.reset - Date.now()) / 1000),
});
}
if (!JOB_ID_RE.test(args.job_id)) throw new Error('malformed job id');
const { base, key } = workerConfig();
const res = await fetchUpstream(`${base}/jobs/${args.job_id}`, {
headers: { authorization: `Bearer ${key}` },
}, { name: 'garment-worker', timeoutMs: 15_000, attempts: 2, okWhen: () => true }).catch(() => null);
if (!res) throw new Error('garment worker unreachable');
if (res.status === 404) throw new Error('no such garment job');
if (!res.ok) throw new Error(`garment worker returned ${res.status}`);
const job = await res.json();
const pub = {
job_id: job.job_id,
status: job.status,
stage: job.stage || null,
glb_url: job.glb_url || null,
manifest_url: job.manifest_url || null,
thumb_url: job.thumb_url || null,
coverage: typeof job.coverage === 'number' ? job.coverage : null,
occludes: Array.isArray(job.occludes) ? job.occludes : null,
garment_id: job.garment_id || null,
error: job.error || null,
};
// A job can finish without the worker reporting coverage. `null * 100`
// is 0, so interpolating it directly announced a measured "0.0%" bind
// coverage, a number the pipeline never produced and one that reads as
// a failure of the 60% gate the garment actually passed.
const coverageText =
pub.coverage === null
? 'coverage not reported'
: `coverage ${(pub.coverage * 100).toFixed(1)}%`;
const line = pub.status === 'done'
? `Garment ${pub.garment_id} published: ${pub.glb_url} (${coverageText}, occludes ${pub.occludes?.join(', ') || 'nothing'}).`
: pub.status === 'failed'
? `Garment job failed: ${pub.error}`
: `Garment job ${pub.status}, stage: ${pub.stage}.`;
return {
content: [{ type: 'text', text: line }],
structuredContent: pub,
};
},
},
{
name: 'list_garment_catalog',
title: 'List the wardrobe garment catalog',
annotations: {
readOnlyHint: true,
destructiveHint: false,
idempotentHint: false,
openWorldHint: true,
},
description:
'Fetch the public three.ws wardrobe catalog: every published garment manifest ' +
'(id, slot, name, GLB url, thumbnail, occluded regions). Any entry attaches to ' +
'any humanoid avatar via the additive wardrobe. Use this to pick an existing ' +
'garment before generating a new one with generate_garment.',
inputSchema: {
type: 'object',
properties: {
slot: {
type: 'string',
enum: GARMENT_SLOTS,
description: 'Optional: only garments for this slot.',
},
},
additionalProperties: false,
},
async handler(args, auth) {
const rl = await limits.mcp3dStatus(auth.userId || auth.rateKey);
if (!rl.success) {
throw rpcError(-32000, 'rate_limited', {
retry_after: Math.ceil((rl.reset - Date.now()) / 1000),
});
}
const res = await fetchUpstream(CATALOG_URL, {}, { name: 'gcs-garments', timeoutMs: 15_000, attempts: 2, okWhen: () => true }).catch(() => null);
if (!res || !res.ok) throw new Error('garment catalog unreachable');
const raw = await res.json();
const garments = (Array.isArray(raw) ? raw : [])
.filter((m) => !args.slot || m?.slot === args.slot)
.map((m) => ({
id: m.id,
name: m.name,
slot: m.slot,
version: m.version,
glb_url: m.model?.uri || null,
thumbnail: m.preview?.thumbnail || null,
occludes: m.occludes || [],
license: m.license,
}));
return {
content: [{
type: 'text',
text: garments.length
? garments.map((g) => `${g.slot}/${g.id} v${g.version}: ${g.name}`).join('\n')
: 'The catalog is empty for that filter.',
}],
structuredContent: { garments, count: garments.length },
};
},
},
];