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
// three.ws 3D Studio MCP — generation tools.
//
// text_to_3d / image_to_3d submit a reconstruction job and return a job handle.
// Both accept a quality tier (draft/standard/high), a generation path ("image"
// reference-image reconstruction, the platform-keyed default, or "geometry"
// native text/image→mesh, BYOK), and a three.ws-branded `engine` selector
// (see the ENGINES map). generation_status polls any job — it is engine-aware,
// decoding the forge job token to route geometry jobs.
// auto_rig_model adds a skeleton + skin weights to a static mesh (rerig).
// preview_3d renders any GLB inline. remove_background strips image backgrounds.
// remesh_model converts, simplifies, and repairs meshes.
// stylize_model applies one-click geometric filters (voxel/brick/voronoi/lowpoly).
// retexture_model paints a new texture onto a mesh from a text prompt.
// retexture_region (magic brush) repaints only a masked UV region, preserving the rest.
// pose_model maps a prompt to a deterministic pose-studio seed + joint rotations.
// direct_prompt (IBM Granite) rewrites a rough idea into an optimized 3D spec.
// generate_material (IBM Granite) emits a glTF PBR material from a description.
import { createHash } from 'node:crypto';
import { limits } from '../../_lib/rate-limit.js';
import { assertSafePublicUrl, fetchSafePublicUrlPinned, MaxBytesExceededError } from '../../_lib/ssrf-guard.js';
import { createRegenProvider as createReplicateProvider } from '../../_providers/replicate.js';
import { createRegenProvider as createGcpProvider } from '../../_providers/gcp.js';
import { isFbxMeshUrl, SEGMENT_FBX_MESSAGE, STYLIZE_FBX_MESSAGE } from '../../_lib/mesh-input.js';
import { BYOK_PROVIDER_FACTORIES, isByokGeometryBackend } from '../../_providers/byok-registry.js';
import { textToImage } from '../text-to-image.js';
import {
PATHS,
DEFAULT_PATH,
TIER_IDS,
DEFAULT_TIER,
BACKENDS,
resolveTier,
resolveBackendId,
estimateEtaSeconds,
estimateCredits,
isSelfHostBackend,
coldStartSecondsFor,
} from '../../_lib/forge-tiers.js';
import { laneHealthSnapshot } from '../../_lib/forge-lane-health.js';
import { resolveProviderKey } from '../../_lib/forge-provider-key.js';
import { encodeJobToken, decodeJobToken } from '../../_lib/forge-job-token.js';
import { watsonxConfig, watsonxChatComplete } from '../../_lib/watsonx.js';
import { llmComplete } from '../../_lib/llm.js';
import { createAvatar, storageKeyFor } from '../../_lib/avatars.js';
import { putObject } from '../../_lib/r2.js';
import { isValidGlbHeader, inspectGlb } from '../../_lib/glb-inspect.js';
import { buildSpatialArtifact } from '../../_lib/spatial-mcp.js';
import { env } from '../../_lib/env.js';
import {
createPersona,
getPersona,
touchPersona,
personaPublicView,
isPersonaId,
} from '../../_lib/persona-store.js';
import { expressionForText, expressionFor } from '../../../src/embodiment/emotion.js';
import { embodimentArtifact } from '../../_lib/embodiment-artifact.js';
import { PRESETS, PRESET_GROUPS } from '../../../src/pose-presets.js';
import {
renderModelViewerHtml,
safeCssValue,
safeCssLength,
safeHttpsUrl,
} from '../../_mcp/render.js';
function rpcError(code, message, data) {
const e = new Error(message);
e.code = code;
e.data = data;
return e;
}
function rateKey(auth) {
return auth.userId || auth.rateKey || 'anon';
}
// MCP tool annotations (2025-06-18 spec). destructiveHint defaults to TRUE
// when omitted, so every tool sets all four hints explicitly. The generation
// and mesh-op tools create new assets/jobs (never overwrite the source), so
// they are non-read-only, non-destructive, and non-idempotent.
const GENERATIVE_ANNOTATIONS = {
readOnlyHint: false,
destructiveHint: false,
idempotentHint: false,
openWorldHint: true,
};
async function enforce(limiter, auth) {
const rl = await limiter(rateKey(auth));
if (!rl.success) {
throw rpcError(-32000, 'rate_limited', {
retry_after: Math.ceil((rl.reset - Date.now()) / 1000),
});
}
}
// Resolve the best available provider for a given mode.
// GCP takes priority when the service URL is configured for that mode;
// falls back to Replicate for the standard reconstruct/remesh/retex/rerig modes.
function regenProvider(mode = 'reconstruct') {
const gcpKey = process.env?.GCP_RECONSTRUCTION_KEY;
if (gcpKey) {
try {
const gcp = createGcpProvider();
if (gcp.supportsMode(mode)) return gcp;
} catch {
// fall through to Replicate
}
}
try {
return createReplicateProvider();
} catch (err) {
throw rpcError(-32000, '3D generation is not configured', { reason: err.message });
}
}
// Region (magic-brush) edits MUST run on the GCP texture worker — the Replicate
// path has no masked-inpaint model, so we never silently fall back to it and
// drop the mask. Require GCP explicitly and fail with a clear message otherwise.
function regionProvider() {
if (process.env?.GCP_RECONSTRUCTION_KEY) {
try {
const gcp = createGcpProvider();
if (gcp.supportsMode('retex_region')) return gcp;
} catch {
// fall through to the explicit error below
}
}
throw rpcError(
-32000,
'Region retexture requires the GCP texture worker (set GCP_RECONSTRUCTION_KEY and GCP_TEXTURE_URL).',
);
}
// Validate via the shared DNS-resolving SSRF guard: https-only, the hostname is
// resolved and every A/AAAA record is checked against the full private/loopback/
// link-local/ULA/IPv4-mapped/metadata blocklist (covering 172.16/12, [::1],
// fc00::/7, fe80::/10, ::ffff: and decimal/hex IP encodings the old ad-hoc
// prefix checks missed). Async because it performs DNS resolution.
async function isPublicHttpsUrl(s) {
try {
await assertSafePublicUrl(String(s), { allowHttp: false });
return true;
} catch {
return false;
}
}
const POLL_HINT =
'Call generation_status with this job_id to check progress. ' +
'Reconstruction typically finishes in 30–90 seconds.';
// An MCP tool call is one-shot text, not a pollable UI — so the honesty bar
// (CLAUDE.md: no fabricated progress) means baking the REAL eta_seconds this
// job was submitted with into the poll instruction, not a generic static
// range. Falls back to `fallback` (a category-appropriate static estimate)
// only when the caller genuinely has no eta signal for this lane.
function pollHint(etaSeconds, fallback) {
const eta = Number(etaSeconds) > 0 ? Math.round(Number(etaSeconds)) : null;
if (eta == null) return `Call generation_status with this job_id to check progress. ${fallback}`;
return `Call generation_status with this job_id to check progress — usually ~${eta}s.`;
}
// Ceiling on a GLB copied into durable storage by save_avatar. Matches the
// reconstruct + forge pipelines so a runaway model can't ingest an unbounded blob.
const MAX_GLB_BYTES = 64 * 1024 * 1024;
// How long save_avatar will wait for one GLB download. A model URL that accepts
// the connection and then stalls used to hold the MCP call open for the whole
// invocation and return nothing; bounded, it fails with an answer the caller can
// act on.
const GLB_FETCH_TIMEOUT_MS = 30_000;
// Fetch a caller-supplied GLB into a Buffer, so save_avatar can persist its own
// durable copy before the provider's delivery URL expires. Routed through the
// pinned SSRF guard rather than a bare fetch for three reasons: the hostname is
// re-resolved and IP-pinned, closing the DNS-rebinding window that the
// isPublicHttpsUrl() check at the call site leaves open; the size ceiling is
// enforced WHILE streaming, so an oversized or lying host is torn down instead
// of buffered; and redirects are re-validated hop by hop. The declared-length
// and post-read checks stay as defense in depth.
async function fetchGlbBuffer(url) {
let resp;
try {
resp = await fetchSafePublicUrlPinned(
url,
{ signal: AbortSignal.timeout(GLB_FETCH_TIMEOUT_MS) },
{ allowHttp: false, maxBytes: MAX_GLB_BYTES },
);
} catch (err) {
if (err instanceof MaxBytesExceededError) {
throw rpcError(-32000, `GLB too large to save (max ${MAX_GLB_BYTES} bytes).`);
}
const reason = err?.name === 'TimeoutError' ? 'timed out' : err?.message || 'unreachable';
throw rpcError(-32000, `Could not fetch the GLB (${reason}).`);
}
if (!resp.ok) throw rpcError(-32000, `Could not fetch the GLB (${resp.status}).`);
const declared = Number(resp.headers.get('content-length') || 0);
if (declared && declared > MAX_GLB_BYTES) {
throw rpcError(-32000, `GLB too large to save (${declared} bytes; max ${MAX_GLB_BYTES}).`);
}
const buf = Buffer.from(await resp.arrayBuffer());
if (buf.length > MAX_GLB_BYTES) {
throw rpcError(
-32000,
`GLB too large to save (${buf.length} bytes; max ${MAX_GLB_BYTES}).`,
);
}
return buf;
}
function viewerArtifact({ glbUrl, name, options = {} }) {
const html = renderModelViewerHtml({
src: glbUrl,
name: name || '3D model',
poster: safeHttpsUrl(options.poster),
background: safeCssValue(options.background, 'transparent'),
height: safeCssLength(options.height, '480px'),
width: safeCssLength(options.width, '100%'),
autoRotate: options.auto_rotate !== false,
ar: options.ar !== false,
cameraOrbit: safeCssValue(options.camera_orbit, ''),
});
return {
type: 'resource',
resource: { uri: glbUrl, mimeType: 'text/html', text: html },
};
}
// Inline artifact for a captured point cloud (.ply). model-viewer can't render a
// raw point cloud, so we embed the three.ws WebGL point-cloud viewer (/capture in
// chrome-less embed mode) pointed at the .ply via its ?src= deep link.
function pointCloudArtifact({ plyUrl, name }) {
const viewer = `${env.APP_ORIGIN}/capture?embed=1&src=${encodeURIComponent(plyUrl)}`;
const safeName = String(name || 'Captured 3D scene').replace(/[&<>"]/g, (c) =>
({ '&': '&', '<': '<', '>': '>', '"': '"' })[c]);
const html =
`<!doctype html><html><head><meta charset="utf-8"><title>${safeName}</title>` +
`<style>html,body{margin:0;height:100%;background:#0a0a0a}iframe{border:0;width:100%;height:100%;display:block}</style>` +
`</head><body><iframe src="${viewer}" sandbox="allow-scripts allow-same-origin" allow="fullscreen" title="${safeName}"></iframe></body></html>`;
return {
type: 'resource',
resource: { uri: plyUrl, mimeType: 'text/html', text: html },
};
}
// The inline "living body" artifact (buildEmbedUrl + embodimentArtifact) is shared
// with the free studio in api/_lib/embodiment-artifact.js so both front doors drive
// the SAME hosted embed page.
// Annotations for the persona lifecycle tools. create mints a new body (write,
// non-destructive). get is a pure read. say is a render directive that also bumps
// the persona's turn counter — a write, never destructive.
const PERSONA_CREATE_ANNOTATIONS = {
readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true,
};
const PERSONA_READ_ANNOTATIONS = {
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false,
};
const PERSONA_SAY_ANNOTATIONS = {
readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false,
};
// ── Quality tier + generation path/engine (shared by text_to_3d/image_to_3d) ──
// Mirrors the /api/forge axes: `path` ("image" vs "geometry"), `tier`
// (draft/standard/high poly budget), and `backend` — exposed as the white-labeled
// three.ws `engine` vocabulary (ENGINES, above) rather than vendor ids. The
// default — path "image", engine "auto" — keeps the existing fast platform-keyed
// reconstruction untouched.
function parsePathArg(args) {
const p = typeof args?.path === 'string' ? args.path.trim() : '';
return PATHS.includes(p) ? p : DEFAULT_PATH;
}
function parseTierArg(args) {
const t = typeof args?.tier === 'string' ? args.tier.trim() : '';
return TIER_IDS.includes(t) ? t : DEFAULT_TIER;
}
const TIER_PROP = {
type: 'string',
enum: TIER_IDS,
default: DEFAULT_TIER,
description:
'Quality tier: draft (~12k poly, fast), standard (~30k, balanced), high (~200k + PBR, slower). Honoured by the poly-aware engines (the geometry, sculpt, and detail engines); the default image engine records it as provenance.',
};
const PATH_PROP = {
type: 'string',
enum: PATHS,
default: DEFAULT_PATH,
description:
'Generation path: "image" (reference-image reconstruction on the platform-keyed image engine, the default) or "geometry" (native text/image→mesh on a geometry engine — cleaner topology, but bring-your-own-key: needs your own provider key).',
};
const MCP_UNSELECTABLE_BACKENDS = new Set([
// replicate_byok runs on the platform reconstruction path with the caller's
// own Replicate account; that BYOK-token routing only exists on /api/forge, so
// it isn't offered over MCP.
'replicate_byok',
// huggingface is the free Spaces image→3D lane, but it is wired ONLY on
// /api/forge (runHfImageLane). The MCP studio path reconstructs via Replicate/GCP
// (regenProvider), so selecting it here would silently run a DIFFERENT, paid
// engine. Hide it until the free Spaces lane is wired into the MCP path rather
// than advertise a free engine that doesn't run here. Free text→3D over MCP is
// the separate forge_free tool, which targets the NVIDIA lane via /api/forge.
'huggingface',
]);
// ── White-labeled engine taxonomy ────────────────────────────────────────────
// The MCP wire speaks only in three.ws-branded engine names; the underlying
// generation vendors never surface in a tool schema, response, or artifact. Each
// public engine maps to one internal forge backend. Legacy vendor ids are still
// ACCEPTED on input as hidden back-compat aliases (resolveEngineArg), but only
// the branded names are advertised. The default is "auto" — the platform picks
// the best engine for the chosen path and tier.
const ENGINES = Object.freeze({
'three-image': Object.freeze({ internal: 'trellis', label: 'three.ws Image engine' }),
'three-geometry': Object.freeze({ internal: 'meshy', label: 'three.ws Geometry engine' }),
'three-geometry-pro': Object.freeze({ internal: 'tripo', label: 'three.ws Geometry Pro engine' }),
'three-sculpt': Object.freeze({ internal: 'rodin', label: 'three.ws Sculpt engine' }),
'three-detail': Object.freeze({ internal: 'hunyuan3d', label: 'three.ws Detail engine' }),
'three-instant': Object.freeze({ internal: 'stability', label: 'three.ws Instant engine' }),
'three-sketch': Object.freeze({ internal: 'triposg', label: 'three.ws Sketch engine' }),
});
// Internal backend id → branded engine id, for shaping responses. Every platform
// image lane (the hosted, self-hosted, and free reconstruction backends) presents
// as the single "three.ws Image engine" — the caller never learns which one ran.
const INTERNAL_TO_ENGINE = Object.freeze({
trellis: 'three-image',
nvidia: 'three-image',
trellis2: 'three-image',
trellis_selfhost: 'three-image',
modly: 'three-image',
modly_hunyuan: 'three-image',
huggingface: 'three-image',
replicate_byok: 'three-image',
meshy: 'three-geometry',
tripo: 'three-geometry-pro',
rodin: 'three-sculpt',
hunyuan3d: 'three-detail',
stability: 'three-instant',
triposg: 'three-sketch',
});
function engineIdFor(internalId) {
return INTERNAL_TO_ENGINE[internalId] || 'three-image';
}
function engineLabelFor(internalId) {
return ENGINES[engineIdFor(internalId)]?.label || 'three.ws engine';
}
// Map a caller's engine argument to an internal backend id. Accepts a branded
// engine id (preferred), "auto"/empty (→ undefined, the platform picks), or a
// legacy vendor id (hidden back-compat, excluding the never-selectable lanes).
// Anything unrecognised falls through to undefined so resolveBackendId applies
// the platform default — forgiving at the boundary, never a hard 422.
function resolveEngineArg(args) {
const raw = typeof args?.backend === 'string' ? args.backend.trim() : '';
if (!raw || raw === 'auto') return undefined;
if (ENGINES[raw]) return ENGINES[raw].internal;
if (BACKENDS[raw] && !MCP_UNSELECTABLE_BACKENDS.has(raw)) return raw;
return undefined;
}
const BACKEND_PROP = {
// Intentionally no `enum`: branded names are the advertised vocabulary (below),
// but legacy vendor ids are still accepted silently for back-compat, which a
// strict enum would reject. resolveEngineArg validates and normalizes instead.
type: 'string',
default: 'auto',
description:
'three.ws generation engine. "auto" (default) lets the platform pick the best engine for the chosen path and tier. Override with: three-image (image-reconstruction), three-geometry or three-geometry-pro (native text/image→mesh, clean quad topology), three-sculpt (high-poly detail), three-instant (fast single-image), three-sketch (sketch→mesh). An engine that does not serve the chosen path is ignored.',
};
// "needs a BYOK key" — a designed, branchable result (mirrors /api/forge's
// needs_key state), not an error: the geometry providers have no platform key,
// so a caller without one is told exactly how to enable the path.
// Honest cold-start signal for a self-hosted lane, mirroring api/forge.js: true
// only when the shared liveness probe reached the worker but it answered slowly
// (a scale-to-zero container spinning up). Without this an MCP caller is handed a
// warm ETA while the GPU is still booting, which reads as a stalled job.
async function coldStartFor(backendId) {
if (!isSelfHostBackend(backendId) || !coldStartSecondsFor(backendId)) return false;
try {
const snap = await laneHealthSnapshot([backendId]);
const rec = snap.byId[backendId];
return Boolean(rec && rec.status === 'ok' && rec.warm === false);
} catch {
return false;
}
}
function needsKeyResult(backendId) {
const meta = BACKENDS[backendId];
// The bring-your-own-key path is the one place a credential provider name must
// be disclosed — the caller has to know which key to supply. The engine itself
// is still presented under its three.ws brand.
const provider = meta?.byok || backendId;
return {
content: [
{
type: 'text',
text:
`The ${engineLabelFor(backendId)} runs on a bring-your-own-key provider. ` +
`Send your ${provider} key as the "x-forge-provider-key" request header (or store a ${provider} key on your three.ws account) and retry, ` +
'or use the default image path (omit "path", or set path="image").',
},
],
structuredContent: {
status: 'needs_key',
engine: engineIdFor(backendId),
provider,
},
isError: true,
};
}
// Submit a native geometry-first job (Meshy/Tripo, BYOK) and shape the MCP
// response. Returns a needs_key result when no key is available. The job handle
// is a forge token so generation_status routes the poll back to this provider.
async function submitGeometryJob({
req,
args,
backendId,
isImageMode,
prompt,
primaryImage,
tier,
path,
}) {
const providerName = BACKENDS[backendId].byok; // 'meshy' | 'tripo' | 'rodin' | 'stability'
const key = await resolveProviderKey(req, args, providerName);
if (!key) return needsKeyResult(backendId);
let gp;
try {
gp = BYOK_PROVIDER_FACTORIES[providerName](key);
} catch {
return needsKeyResult(backendId);
}
let submitted;
if (isImageMode) {
submitted = await gp.imageTo3d({ imageUrl: primaryImage, prompt: prompt || undefined, tier });
} else if (typeof gp.textToGeometry === 'function') {
submitted = await gp.textToGeometry({ prompt, tier });
} else {
// Image-only engine asked to run text→3D.
return {
content: [
{
type: 'text',
text: `The ${engineLabelFor(backendId)} reconstructs from a reference image — use image_to_3d with this engine, or drop it to run text→3D.`,
},
],
structuredContent: {
status: 'failed',
error: 'engine_image_only',
engine: engineIdFor(backendId),
},
isError: true,
};
}
// Synchronous completion (the instant single-image engine): the GLB is already
// persisted to R2, so there is no job to poll — return it done.
if (!submitted.taskId && submitted.resultGlbUrl) {
return {
content: [
{
type: 'text',
text: `Generated a 3D model on the ${engineLabelFor(backendId)} (${path} path, ${tier.id} tier).\nGLB: ${submitted.resultGlbUrl}`,
},
],
structuredContent: {
status: 'done',
glb_url: submitted.resultGlbUrl,
mode: isImageMode ? 'image_to_3d' : 'text_to_3d',
path,
tier: tier.id,
engine: engineIdFor(backendId),
prompt: prompt || null,
source_image_url: isImageMode ? primaryImage : null,
},
};
}
const token = encodeJobToken({
provider: providerName,
kind: submitted.kind,
taskId: submitted.taskId,
});
const cold = await coldStartFor(backendId);
const etaSeconds = estimateEtaSeconds({ backendId, tier, cold });
return {
content: [
{
type: 'text',
text:
`Started ${isImageMode ? 'image-to-3D' : 'text-to-3D'} on the ${engineLabelFor(backendId)} ` +
`(${path} path, ${tier.id} tier).\nJob ID: ${token}\n` +
(cold
? `That worker scales to zero, so it is booting now (about ${coldStartSecondsFor(backendId)}s). The job is accepted and starts the moment it answers.\n`
: '') +
pollHint(etaSeconds, 'Reconstruction typically finishes in 30–90 seconds.'),
},
],
structuredContent: {
job_id: token,
status: 'queued',
mode: isImageMode ? 'image_to_3d' : 'text_to_3d',
path,
tier: tier.id,
engine: engineIdFor(backendId),
prompt: prompt || null,
source_image_url: isImageMode ? primaryImage : null,
cold_start: cold,
cold_start_seconds: cold ? coldStartSecondsFor(backendId) : undefined,
eta_seconds: etaSeconds,
estimated_credits: estimateCredits({ backendId, path, tier }),
},
};
}
// Poll whichever upstream owns a job. A bare id (legacy / image-TRELLIS path)
// polls Replicate. A forge token (f1.*) decodes to the geometry provider
// (Meshy/Tripo, BYOK re-resolved per poll) or the self-hosted GCP backend.
async function pollAnyProvider(req, jobId) {
const token = decodeJobToken(jobId);
if (token) {
if (BYOK_PROVIDER_FACTORIES[token.provider]) {
const key = await resolveProviderKey(req, null, token.provider);
if (!key) {
return {
status: 'failed',
error: 'Your provider API key is required to check this job. Send it as the x-forge-provider-key header and retry.',
};
}
const gp = BYOK_PROVIDER_FACTORIES[token.provider](key);
return gp.status({ kind: token.kind, taskId: token.taskId });
}
if (token.provider === 'gcp') {
let gcp;
try {
gcp = createGcpProvider();
} catch {
return {
status: 'failed',
error: 'The self-hosted reconstruction backend is not configured.',
};
}
return gcp.status(token.taskId);
}
return regenProvider().status(token.taskId);
}
return regenProvider().status(jobId);
}
// ── pose_model: deterministic preset selection (ported from the pose-seed tool) ─
function poseTokensOf(str) {
return String(str || '')
.toLowerCase()
.split(/[^a-z0-9]+/g)
.filter(Boolean);
}
const POSE_INDEX = PRESETS.map((preset) => {
const idTokens = poseTokensOf(preset.id);
const labelTokens = poseTokensOf(preset.label);
const groupTokens = poseTokensOf(preset.group);
return {
preset,
all: new Set([...idTokens, ...labelTokens, ...groupTokens]),
idTokens,
labelTokens,
};
});
function scorePosePreset(promptTokens, entry) {
let score = 0;
for (const t of promptTokens) {
if (entry.all.has(t)) score += 3;
else {
for (const tok of [...entry.idTokens, ...entry.labelTokens]) {
if (tok.includes(t) || t.includes(tok)) {
score += 1;
break;
}
}
}
}
return score;
}
function pickPosePreset(prompt) {
const tokens = poseTokensOf(prompt);
const deterministic = () => {
const hash = createHash('sha256').update(String(prompt)).digest();
return {
entry: POSE_INDEX[hash.readUInt32BE(0) % POSE_INDEX.length],
score: 0,
reason: 'no-match-deterministic-pick',
};
};
if (tokens.length === 0) return deterministic();
let best = null;
let bestScore = -1;
for (const entry of POSE_INDEX) {
const sc = scorePosePreset(tokens, entry);
if (sc > bestScore) {
best = entry;
bestScore = sc;
}
}
if (bestScore <= 0) return deterministic();
return { entry: best, score: bestScore, reason: 'token-match' };
}
const POSE_PREVIEW_BASE = process.env.MCP_POSE_PREVIEW_BASE || 'https://three.ws/pose';
// ── Authoring model for direct_prompt / generate_material ──────────────────────
// Both tools ask a language model for a small strict-JSON document. IBM Granite
// (watsonx.ai) leads where it is configured, and the shared free-first chain
// (llmComplete, the same ladder forge-enhance and the prompt director ride)
// backs it up. Previously both tools hard-threw when WATSONX_API_KEY was unset,
// which made them permanently dead on any deployment without an IBM key even
// though a healthy LLM chain was one call away. Only an exhausted chain errors.
const GRANITE_TIMEOUT_MS = 20_000;
async function graniteChatComplete({ system, user, maxTokens, temperature, tool }) {
let lastError = null;
const cfg = watsonxConfig();
if (cfg.configured) {
try {
const out = await watsonxChatComplete(cfg, {
messages: [
{ role: 'system', content: system },
{ role: 'user', content: user },
],
maxTokens,
temperature,
});
if (out?.text) return out;
} catch (err) {
lastError = err;
}
}
try {
const out = await llmComplete({
system,
user,
maxTokens,
timeoutMs: GRANITE_TIMEOUT_MS,
track: { tool },
});
if (out?.text) return out;
} catch (err) {
lastError = err;
}
throw rpcError(
-32000,
`No language model answered: ${lastError?.message || 'no provider is configured on this server'}.`,
);
}
function stripJsonFence(text) {
const raw = String(text || '').trim();
return raw.startsWith('```') ? raw.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '') : raw;
}
export const toolDefs = [
{
name: 'text_to_3d',
title: 'Generate a 3D model from a text prompt',
annotations: GENERATIVE_ANNOTATIONS,
description:
'Turn a text description into a textured 3D model (GLB). Runs a fast text-to-image pass, then reconstructs a mesh from that image with the three.ws image engine. Returns a job_id (poll with generation_status) plus the intermediate preview image. Best results: a single, clearly described object, e.g. "a worn leather armchair", "a low-poly red fox", "a sci-fi helmet". Use this to make a new object from words; call image_to_3d instead when you already have a picture, and run auto_rig_model on the result when it needs to move.',
inputSchema: {
type: 'object',
properties: {
prompt: {
type: 'string',
minLength: 3,
maxLength: 1000,
description: 'What to generate. Describe one subject clearly.',
},
aspect_ratio: {
type: 'string',
enum: ['1:1', '4:3', '3:4', '16:9', '9:16'],
default: '1:1',
description:
'Aspect ratio of the intermediate reference image (image path only).',
},
tier: TIER_PROP,
path: PATH_PROP,
backend: BACKEND_PROP,
},
required: ['prompt'],
additionalProperties: false,
},
async handler(args, auth, req) {
await enforce(limits.mcp3dGenerate, auth);
const path = parsePathArg(args);
const tier = resolveTier(parseTierArg(args));
const backendId = resolveBackendId({ path, backend: resolveEngineArg(args) });
// BYOK geometry-style engines (the geometry/sculpt/instant engines) — native text→mesh.
// Routed by registry membership, not just path, so an explicitly chosen
// BYOK backend is honoured even if its default path is "image".
if (isByokGeometryBackend(BACKENDS[backendId])) {
return submitGeometryJob({
req,
args,
backendId,
isImageMode: false,
prompt: args.prompt,
primaryImage: null,
tier,
path,
});
}
// Image path (default): synthesize a reference image, then reconstruct.
const provider = regenProvider();
const { imageUrl, model } = await textToImage(args.prompt, {
aspectRatio: args.aspect_ratio || '1:1',
});
// Only poly-aware backends accept a budget; TRELLIS would 422 on an
// unknown field, so the tier rides along as provenance only there.
const params = { image: imageUrl, prompt: args.prompt };
if (BACKENDS[backendId].polyControl) {
params.target_polycount = tier.polycount;
params.tier = tier.id;
}
const job = await provider.submit({ mode: 'reconstruct', params });
return {
content: [
{
type: 'text',
text:
`Started generating a 3D model for "${args.prompt}" (${tier.id} tier).\n` +
`Reference image: ${imageUrl}\n` +
`Job ID: ${job.extJobId}\n` +
pollHint(job.eta, 'Reconstruction typically finishes in 30–90 seconds.'),
},
],
structuredContent: {
job_id: job.extJobId,
status: 'queued',
prompt: args.prompt,
path,
tier: tier.id,
engine: engineIdFor(backendId),
preview_image_url: imageUrl,
text_to_image_model: model,
eta_seconds: job.eta,
},
};
},
},
{
name: 'image_to_3d',
title: 'Reconstruct a 3D model from one or more images',
annotations: GENERATIVE_ANNOTATIONS,
description:
'Reconstruct a textured 3D model (GLB) from a reference image using the three.ws image engine. Pass a single image_url, or image_urls (2-4 views of the SAME object from different angles: front, back, left, right) for multi-view reconstruction, which removes the back-of-object hallucination of single-image reconstruction. Returns a job_id to poll with generation_status, plus how many views were fused and which engine handled it. The cleaner the inputs (one subject, plain background, even lighting), the better the mesh. Use this when you have a photo or render of the object; for a text idea call text_to_3d instead, and run remove_background first when the image has a busy background.',
inputSchema: {
type: 'object',
properties: {
image_url: {
type: 'string',
format: 'uri',
description:
'Public https URL of the reference image (PNG/JPG/WebP). Use image_urls for multi-view.',
},
image_urls: {
type: 'array',
items: { type: 'string', format: 'uri' },
minItems: 1,
maxItems: 4,
description:
'1–4 public https URLs of the same object from different angles. Takes precedence over image_url; >1 enables multi-view reconstruction.',
},
prompt: {
type: 'string',
maxLength: 1000,
description: 'Optional text hint passed to the reconstruction model.',
},
tier: TIER_PROP,
path: PATH_PROP,
backend: BACKEND_PROP,
},
additionalProperties: false,
},
async handler(args, auth, req) {
await enforce(limits.mcp3dGenerate, auth);
// Merge the multi-view array form with the single image_url, de-duped
// and order-preserving. image_urls wins when both are present.
const rawViews = Array.isArray(args.image_urls)
? args.image_urls
: typeof args.image_url === 'string'
? [args.image_url]
: [];
const seen = new Set();
const views = [];
for (const v of rawViews) {
if (typeof v !== 'string') continue;
const t = v.trim();
if (!t || seen.has(t)) continue;
seen.add(t);
views.push(t);
}
if (views.length === 0) {
return {
content: [
{ type: 'text', text: 'Error: provide image_url or image_urls (1–4).' },
],
isError: true,
};
}
if (views.length > 4) {
return {
content: [{ type: 'text', text: 'Error: provide between 1 and 4 images.' }],
isError: true,
};
}
for (const v of views) {
if (!(await isPublicHttpsUrl(v))) {
return {
content: [
{
type: 'text',
text: 'Error: every image URL must be a public https URL.',
},
],
isError: true,
};
}
}
const path = parsePathArg(args);
const tier = resolveTier(parseTierArg(args));
const backendId = resolveBackendId({ path, backend: resolveEngineArg(args) });
// BYOK geometry-style engines (the geometry/sculpt/instant engines)
// reconstruct from the primary view; multi-view fusion stays on the
// platform image engine below. Routed by registry membership, not just path.
if (isByokGeometryBackend(BACKENDS[backendId])) {
return submitGeometryJob({
req,
args,
backendId,
isImageMode: true,
prompt: args.prompt,
primaryImage: views[0],
tier,
path,
});
}
const provider = regenProvider();
const reconstructParams = { images: views, prompt: args.prompt };
if (BACKENDS[backendId].polyControl) {
reconstructParams.target_polycount = tier.polycount;
reconstructParams.tier = tier.id;
}
const job = await provider.submit({
mode: 'reconstruct',
sourceUrl: views[0],
params: reconstructParams,
});
const viewsUsed = typeof job.viewsUsed === 'number' ? job.viewsUsed : views.length;
const multiview = Boolean(job.multiview);
const summary =
views.length > 1
? `Started multi-view reconstruction from ${views.length} views (${viewsUsed} fused${multiview ? '' : ', single-view fallback'}).`
: 'Started reconstructing a 3D model from the image.';
return {
content: [
{
type: 'text',
text:
`${summary}\nJob ID: ${job.extJobId}\n` +
pollHint(job.eta, 'Reconstruction typically finishes in 30–90 seconds.'),
},
],
structuredContent: {
job_id: job.extJobId,
status: 'queued',
source_image_url: views[0],
source_image_urls: views,
views_requested: views.length,
views_used: viewsUsed,
multiview,
path,
tier: tier.id,
engine: engineIdFor(job.backend ?? backendId),
eta_seconds: job.eta,
},
};
},
},
{
name: 'generation_status',
title: 'Check a 3D generation job',
// Status poll — pure read; the job state changes between calls.
annotations: {
readOnlyHint: true,
destructiveHint: false,
idempotentHint: false,
openWorldHint: true,
},
description:
'Poll a text_to_3d or image_to_3d job by its job_id. While running it reports the status; when finished it returns the GLB download URL and an inline <model-viewer> artifact; display that text/html resource as an interactive 3D artifact. Call this after any studio tool returns a job_id (text_to_3d, image_to_3d, capture_scene, remesh_model, stylize_model, segment_model, retexture_model, retexture_region, auto_rig_model) and keep polling until it reports done or failed.',
inputSchema: {
type: 'object',
properties: {
job_id: {
type: 'string',
minLength: 1,
maxLength: 200,
description: 'The job_id returned by text_to_3d or image_to_3d.',
},
},
required: ['job_id'],
additionalProperties: false,
},
async handler(args, auth, req) {
await enforce(limits.mcp3dStatus, auth);
const result = await pollAnyProvider(req, args.job_id);
if (result.status === 'done' && result.resultGlbUrl) {
const glbUrl = result.resultGlbUrl;
// A segmentation job carries a parts manifest — surface the named,
// addressable parts (and where to inspect them) alongside the GLB.
if (Array.isArray(result.parts) && result.parts.length) {
const partLines = result.parts
.map((p) => ` • ${p.id} — ${p.name} (${p.face_count} faces, ${p.color})`)
.join('\n');
return {
content: [
{
type: 'text',
text:
`Segmented into ${result.partCount || result.parts.length} parts.\n` +
`Segmented GLB (each part is a named node): ${glbUrl}\n` +
(result.manifestUrl
? `Parts manifest: ${result.manifestUrl}\n`
: '') +
`Parts:\n${partLines}\n` +
'Display the attached text/html resource as an inline 3D artifact.',
},
viewerArtifact({ glbUrl, name: 'Segmented 3D model' }),
],
structuredContent: {
job_id: args.job_id,
status: 'done',
glb_url: glbUrl,
manifest_url: result.manifestUrl || null,
part_count: result.partCount || result.parts.length,
parts: result.parts,
source_faces: result.sourceFaces ?? null,
method: result.segmentMethod || null,
},
};
}
return {
content: [
{
type: 'text',
text:
`Your 3D model is ready.\nGLB: ${glbUrl}\n` +
'Display the attached text/html resource as an inline 3D artifact.',
},
viewerArtifact({ glbUrl, name: '3D model' }),
],
structuredContent: { job_id: args.job_id, status: 'done', glb_url: glbUrl },
};
}
// Scene-capture jobs (capture_scene) finish as a .ply point cloud, not a
// GLB mesh — return the cloud URL + an inline point-cloud viewer artifact.
if (result.status === 'done' && result.resultPointCloudUrl) {
const plyUrl = result.resultPointCloudUrl;
const pts = result.numPoints ? `${result.numPoints.toLocaleString('en-US')} points` : 'point cloud';
const frames = result.frames ? ` from ${result.frames} frames` : '';
return {
content: [
{
type: 'text',
text:
`Your 3D scene is ready — ${pts}${frames}.\nPoint cloud (.ply): ${plyUrl}\n` +
`Explore it: ${env.APP_ORIGIN}/capture?src=${encodeURIComponent(plyUrl)}\n` +
'Display the attached text/html resource as an inline 3D point-cloud viewer.',
},
pointCloudArtifact({ plyUrl, name: 'Captured 3D scene' }),
],
structuredContent: {
job_id: args.job_id,
status: 'done',
point_cloud_url: plyUrl,
num_points: result.numPoints ?? null,
frames: result.frames ?? null,
viewer_url: `${env.APP_ORIGIN}/capture?src=${encodeURIComponent(plyUrl)}`,
},
};
}
if (result.status === 'failed') {
return {
content: [
{
type: 'text',
text: `Generation failed: ${result.error || 'unknown error'}`,
},
],
structuredContent: {
job_id: args.job_id,
status: 'failed',
error: result.error || null,
},
isError: true,
};
}
return {
content: [
{
type: 'text',
text: `Still ${result.status}. ${POLL_HINT}`,
},
],
structuredContent: { job_id: args.job_id, status: result.status },
};
},
},
{
name: 'capture_scene',
title: 'Reconstruct a 3D scene from a video',
annotations: GENERATIVE_ANNOTATIONS,
description:
'Turn a video of a real space (a room, a street, an object walkaround) into an explorable 3D ' +
'point cloud. A feed-forward streaming reconstructor (LingBot-Map) grounds coordinates, reads ' +
'dense geometry, and corrects drift across the whole clip, then returns a coloured .ply point ' +
'cloud. Pass a public https video URL (mp4/mov/webm). Returns a job_id — poll generation_status; ' +
'when finished it returns the point-cloud URL and an inline viewer artifact. Best with steady, ' +
'well-lit footage that orbits or walks through the space. Use this to capture the geometry of a REAL ' +
'scene from footage; text_to_3d and image_to_3d instead synthesize a single object mesh.',
inputSchema: {
type: 'object',
properties: {
video_url: {
type: 'string',
format: 'uri',
description: 'Public https URL of the source video (mp4, mov, or webm).',
},
mode: {
type: 'string',
enum: ['streaming', 'windowed'],
default: 'streaming',
description: 'streaming = default; windowed = for very long clips (>3000 frames).',
},
fps: {
type: 'integer',
minimum: 1,
maximum: 30,
default: 8,
description: 'Frames per second to sample from the video.',
},
keyframe_interval: {
type: 'integer',
minimum: 1,
maximum: 64,
default: 4,
description: 'Cache every N-th frame as a keyframe — lower is denser/slower.',
},
mask_sky: {
type: 'boolean',
default: true,
description: 'Drop sky points from the reconstruction.',
},
max_points: {
type: 'integer',
minimum: 50000,
maximum: 3000000,
default: 1500000,
description: 'Cap on the total points in the output cloud.',
},
},
required: ['video_url'],
additionalProperties: false,
},
async handler(args, auth) {
await enforce(limits.mcp3dGenerate, auth);
if (!(await isPublicHttpsUrl(args.video_url))) {
return {
content: [{ type: 'text', text: 'Error: video_url must be a public https URL.' }],
isError: true,
};
}
let provider;
try {
provider = regenProvider('video2scene');
} catch {
provider = null;
}
if (!provider || !provider.supportsMode('video2scene')) {
return {
content: [{
type: 'text',
text: 'Scene capture is not configured on this server (set GCP_VIDEO2SCENE_URL and GCP_RECONSTRUCTION_KEY).',
}],
isError: true,
};
}
const params = {
mode: args.mode === 'windowed' ? 'windowed' : 'streaming',
fps: args.fps || 8,
keyframe_interval: args.keyframe_interval || 4,
mask_sky: args.mask_sky !== false,
max_points: args.max_points || 1_500_000,
};
const job = await provider.submit({ mode: 'video2scene', sourceUrl: args.video_url, params });
return {
content: [{
type: 'text',
text:
`Started reconstructing a 3D scene from the video (${params.mode}).\n` +
`Job ID: ${job.extJobId}\n` +
pollHint(job.eta, 'Reconstruction typically takes a few minutes for a longer clip.'),
}],
structuredContent: {
job_id: job.extJobId,
status: 'queued',
source_video_url: args.video_url,
mode: params.mode,
eta_seconds: job.eta,
},
};
},
},
{
name: 'preview_3d',
title: 'Preview any GLB as an interactive 3D artifact',
// Builds viewer HTML in-memory — deterministic for the same arguments.
annotations: {
readOnlyHint: true,
destructiveHint: false,
idempotentHint: true,
openWorldHint: true,
},
description:
'Render any public GLB URL as an inline <model-viewer> HTML artifact — orbit controls, AR on mobile, auto-rotate. Display the returned text/html resource as an inline 3D artifact. Use it to view a generated model, or any GLB on the web.',
inputSchema: {
type: 'object',
properties: {
glb_url: {
type: 'string',
format: 'uri',
description: 'Public https URL of a .glb file.',
},
auto_rotate: { type: 'boolean', default: true },
ar: { type: 'boolean', default: true },
background: {
type: 'string',
default: 'transparent',
description: 'CSS background color or gradient.',
},
height: { type: 'string', default: '480px' },
width: { type: 'string', default: '100%' },
camera_orbit: {
type: 'string',
description: 'model-viewer camera-orbit value, e.g. "0deg 80deg 2m".',
},
},
required: ['glb_url'],
additionalProperties: false,
},
async handler(args) {
if (!(await isPublicHttpsUrl(args.glb_url))) {
return {
content: [{ type: 'text', text: 'Error: glb_url must be a public https URL.' }],
isError: true,
};
}
return {
content: [
{
type: 'text',
text: 'Display the attached text/html resource as an inline 3D artifact.',
},
viewerArtifact({ glbUrl: args.glb_url, name: '3D model', options: args }),
],
structuredContent: {
glb_url: args.glb_url,
// Conformant Spatial MCP artifact (specs/SPATIAL_MCP.md) so any
// Spatial-MCP renderer can display this model, not just ours.
spatial: buildSpatialArtifact({
glbUrl: args.glb_url,
kind: 'model',
autoRotate: args.auto_rotate !== false,
cameraOrbit: typeof args.camera_orbit === 'string' ? args.camera_orbit : undefined,
viewerUrl: `https://three.ws/viewer?src=${encodeURIComponent(args.glb_url)}`,
}),
},
};
},
},
{
name: 'remove_background',
title: 'Remove the background from an image',
annotations: GENERATIVE_ANNOTATIONS,
description:
'Strip the background from a photo or illustration with the three.ws background-removal engine. Returns a PNG with a transparent background. Use this before image_to_3d when the source image has a cluttered background, since a clean cutout reconstructs into a cleaner mesh.',
inputSchema: {
type: 'object',
properties: {
image_url: {
type: 'string',
format: 'uri',
description: 'Public https URL of the source image (PNG/JPG/WebP).',
},
model: {
type: 'string',
enum: ['rmbg2', 'birefnet', 'u2net', 'isnet', 'u2net_human_seg', 'silueta'],
default: 'rmbg2',
description:
'Background removal model. rmbg2 is the fast default; birefnet (BiRefNet) keeps hair and thin edges intact at about six times the compute; u2net_human_seg is optimised for people.',
},
},
required: ['image_url'],
additionalProperties: false,
},
async handler(args, auth) {
await enforce(limits.mcp3dGenerate, auth);
if (!(await isPublicHttpsUrl(args.image_url))) {
return {
content: [
{ type: 'text', text: 'Error: image_url must be a public https URL.' },
],
isError: true,
};
}
const provider = regenProvider('rembg');
const job = await provider.submit({
mode: 'rembg',
sourceUrl: args.image_url,
params: { model: args.model || 'rmbg2' },
});
return {
content: [
{
type: 'text',
text:
`Background removal started.\nJob ID: ${job.extJobId}\n` +
pollHint(job.eta, 'Typically completes in 3–10 seconds.'),
},
],
structuredContent: {
job_id: job.extJobId,
status: 'queued',
source_image_url: args.image_url,
eta_seconds: job.eta,
},
};
},
},
{
name: 'remesh_model',
title: 'Remesh, simplify, repair, or convert a 3D model',
annotations: GENERATIVE_ANNOTATIONS,
description:
'Process an existing GLB/GLTF/OBJ/FBX/STL/PLY/OFF/DAE mesh: fix holes and degenerate geometry, reduce face count via quadric decimation, or convert to a different format (including FBX with skeleton for Unity/Unreal: a convert of a rigged GLB keeps its bones, skin weights, and blendshapes). Returns a clean GLB (or the requested format) job_id to poll with generation_status. Use this to repair, decimate, or convert a mesh before shipping it; for a stylized look call stylize_model, and for a new surface texture call retexture_model.',
inputSchema: {
type: 'object',
properties: {
mesh_url: {
type: 'string',
format: 'uri',
description: 'Public https URL of the source mesh (GLB/GLTF/OBJ/FBX/STL/PLY/OFF/DAE; FBX must be binary, 7.1 or later).',
},
operation: {
type: 'string',
enum: ['full', 'simplify', 'repair', 'convert'],
default: 'full',
description:
'full = repair + simplify; simplify = face reduction only; repair = hole-fill + normal fix; convert = format change only.',
},
target_faces: {
type: 'integer',
minimum: 1000,
maximum: 500000,
default: 50000,
description: 'Target polygon count for simplification.',
},
output_format: {
type: 'string',
enum: ['glb', 'obj', 'stl', 'ply', 'usdz', '3mf', 'fbx'],
default: 'glb',
description:
"Target format. fbx + operation=convert preserves a rigged GLB's skeleton, skin weights, and blendshapes (for Unity/Unreal); other operations produce a static fbx.",
},
},
required: ['mesh_url'],
additionalProperties: false,
},
async handler(args, auth) {
await enforce(limits.mcp3dGenerate, auth);
if (!(await isPublicHttpsUrl(args.mesh_url))) {
return {
content: [
{ type: 'text', text: 'Error: mesh_url must be a public https URL.' },
],
isError: true,
};
}
const provider = regenProvider('remesh');
const job = await provider.submit({
mode: 'remesh',
sourceUrl: args.mesh_url,
params: {
operation: args.operation || 'full',
target_faces: args.target_faces || 50_000,
output_format: args.output_format || 'glb',
},
});
return {
content: [
{
type: 'text',
text:
`Mesh processing started (${args.operation || 'full'}).\nJob ID: ${job.extJobId}\n` +
pollHint(job.eta, 'Typically completes in 10–60 seconds.'),
},
],
structuredContent: {
job_id: job.extJobId,
status: 'queued',
source_mesh_url: args.mesh_url,
operation: args.operation || 'full',
eta_seconds: job.eta,
},
};
},
},
{
name: 'stylize_model',
title: 'Apply a one-click geometric stylization filter to a 3D model',
annotations: GENERATIVE_ANNOTATIONS,
description:
'Transform any GLB/GLTF/OBJ/STL/PLY/OFF/DAE mesh into a stylized variant with a single geometry pass: ' +
'no model inference, fast and cheap. FBX is not accepted; convert it to GLB with remesh_model first. ' +
'Styles: "voxel" (blocky cubes on a grid), "brick" ' +
'(voxels + studs, LEGO-like), "voronoi" (open strut-and-node lattice shell), "lowpoly" ' +
'(decimated + hard flat-shaded facets). Source color is preserved where the style allows. ' +
'Returns a job_id to poll with generation_status; typically completes in 10-40 seconds. ' +
'Use this for a quick voxel, brick, lattice, or low-poly look on an existing mesh; to change surface colour call retexture_model instead.',
inputSchema: {
type: 'object',
properties: {
mesh_url: {
type: 'string',
format: 'uri',
description: 'Public https URL of the source mesh (GLB/GLTF/OBJ/STL/PLY/OFF/DAE; not FBX).',
},
style: {
type: 'string',
enum: ['voxel', 'brick', 'voronoi', 'lowpoly'],
default: 'voxel',
description:
'voxel = blocky cubes; brick = voxels + studs (LEGO-like); voronoi = open lattice shell; lowpoly = faceted flat-shaded.',
},
resolution: {
type: 'integer',
minimum: 8,
maximum: 120,
description:
'Style-specific density (clamped per style): voxel/brick = grid resolution, voronoi = cell density, lowpoly = detail level. Omit for a sensible per-style default.',
},
output_format: {
type: 'string',
enum: ['glb', 'obj', 'stl', 'ply'],
default: 'glb',
},
},
required: ['mesh_url'],
additionalProperties: false,
},
async handler(args, auth) {
await enforce(limits.mcp3dGenerate, auth);
if (!(await isPublicHttpsUrl(args.mesh_url))) {
return {
content: [
{ type: 'text', text: 'Error: mesh_url must be a public https URL.' },
],
isError: true,
};
}
if (isFbxMeshUrl(args.mesh_url)) {
return { content: [{ type: 'text', text: `Error: ${STYLIZE_FBX_MESSAGE}` }], isError: true };
}
const provider = regenProvider('stylize');
const style = args.style || 'voxel';
const job = await provider.submit({
mode: 'stylize',
sourceUrl: args.mesh_url,
params: {
style,
resolution: Number.isInteger(args.resolution) ? args.resolution : null,
output_format: args.output_format || 'glb',
},
});
return {
content: [
{
type: 'text',
text:
`Stylization started (${style}).\nJob ID: ${job.extJobId}\n` +
pollHint(job.eta, 'Typically completes in 10–40 seconds.'),
},
],
structuredContent: {
job_id: job.extJobId,
status: 'queued',
source_mesh_url: args.mesh_url,
style,
eta_seconds: job.eta,
},
};
},
},
{
name: 'segment_model',
title: 'Split a 3D model into named, separable parts',
annotations: GENERATIVE_ANNOTATIONS,
description:
'Segment a GLB/OBJ/STL/PLY mesh into meaningful parts with clean boundaries: head/torso/limbs on a character, body/wheels on a vehicle. Splits at physically disconnected shells and at concave creases (the minima rule), then names each part by region and tints it a distinct colour. Returns a GLB whose nodes ARE the parts (so each can be hidden, recoloured, replaced, or exported on its own) plus a parts manifest. Poll with generation_status; the result lists every part with its id, name, face count, and colour. Pass only_part to export a single part on its own. Use this before hiding, recolouring, replacing, or exporting individual parts of a model; to repaint one area of the surface without splitting the mesh call retexture_region instead.',
inputSchema: {
type: 'object',
properties: {
mesh_url: {
type: 'string',
format: 'uri',
description:
'Public https URL of the source mesh (GLB/GLTF/OBJ/STL/PLY/OFF/DAE). FBX is refused: convert it with remesh_model first.',
},
method: {
type: 'string',
enum: ['auto', 'connected', 'crease'],
default: 'auto',
description:
'auto = disconnected shells + concave-crease splitting inside each shell (best); connected = split only at disconnected shells; crease = minima-rule crease splitting over the whole mesh.',
},
max_parts: {
type: 'integer',
minimum: 2,
maximum: 64,
default: 24,
description:
'Upper bound on parts. Smaller fragments are merged into neighbours until the count fits.',
},
min_part_faces: {
type: 'integer',
minimum: 4,
maximum: 100000,
default: 64,
description:
'Parts smaller than this many faces are merged into their largest neighbour.',
},
crease_angle: {
type: 'number',
minimum: 5,
maximum: 170,
default: 40,
description:
'Dihedral angle (degrees) above which a concave edge is treated as a part boundary. Lower = more parts.',
},
only_part: {
type: 'string',
maxLength: 64,
description:
'Optional: export just this part by id ("part_03") or name ("upper-left"). Run once without it to discover part ids.',
},
},
required: ['mesh_url'],
additionalProperties: false,
},
async handler(args, auth) {
await enforce(limits.mcp3dGenerate, auth);
if (!(await isPublicHttpsUrl(args.mesh_url))) {
return {
content: [
{ type: 'text', text: 'Error: mesh_url must be a public https URL.' },
],
isError: true,
};
}
if (isFbxMeshUrl(args.mesh_url)) {
return { content: [{ type: 'text', text: `Error: ${SEGMENT_FBX_MESSAGE}` }], isError: true };
}
const provider = regenProvider('segment');
const job = await provider.submit({
mode: 'segment',
sourceUrl: args.mesh_url,
params: {
method: args.method || 'auto',
max_parts: args.max_parts || 24,
min_part_faces: args.min_part_faces || 64,
crease_angle: args.crease_angle ?? 40,
only_part: args.only_part,
},
});
return {
content: [
{
type: 'text',
text:
`Segmentation started (${args.method || 'auto'}).\nJob ID: ${job.extJobId}\n` +
`${pollHint(job.eta, 'Typically completes in 10–60 seconds.')} When done it lists every named part.`,
},
],
structuredContent: {
job_id: job.extJobId,
status: 'queued',
source_mesh_url: args.mesh_url,
method: args.method || 'auto',
eta_seconds: job.eta,
},
};
},
},
{
name: 'retexture_model',
title: 'Paint a new texture onto a 3D model from a text prompt',
annotations: GENERATIVE_ANNOTATIONS,
description:
'Generate a fresh texture for an untextured or poorly-textured GLB with the three.ws depth-guided multi-view texturing engine. Renders the mesh from 8 viewpoints, generates coherent texture views guided by your prompt, and back-projects them onto the UV atlas. Returns a job_id to poll with generation_status. Use this to repaint a whole model from a prompt; to change only one area call retexture_region instead.',
inputSchema: {
type: 'object',
properties: {
mesh_url: {
type: 'string',
format: 'uri',
description: 'Public https URL of the source GLB mesh.',
},
prompt: {
type: 'string',
minLength: 3,
maxLength: 500,
description:
'Texture description, e.g. "worn leather armour, dark brown, scratched metal buckles".',
},
negative_prompt: {
type: 'string',
maxLength: 200,
default: 'blurry, low quality, distorted, watermark',
},
num_views: {
type: 'integer',
enum: [4, 8],
default: 8,
description: '4 = faster; 8 = better coverage.',
},
texture_size: {
type: 'integer',
enum: [512, 1024, 2048],
default: 1024,
},
material_class: {
type: 'string',
enum: ['person', 'metal', 'wood', 'fabric', 'plastic', 'glass'],
description:
'Optional. Bakes measured real-world roughness/metallic values for this material family instead of a flat guess, and nudges the prompt with material-appropriate descriptors (e.g. "metal" adds brushed-metal micro-detail cues).',
},
},
required: ['mesh_url', 'prompt'],
additionalProperties: false,
},
async handler(args, auth) {
await enforce(limits.mcp3dGenerate, auth);
if (!(await isPublicHttpsUrl(args.mesh_url))) {
return {
content: [
{ type: 'text', text: 'Error: mesh_url must be a public https URL.' },
],
isError: true,
};
}
const provider = regenProvider('retex');
const job = await provider.submit({
mode: 'retex',
sourceUrl: args.mesh_url,
params: {
prompt: args.prompt,
negative_prompt: args.negative_prompt,
num_views: args.num_views || 8,
texture_size: args.texture_size || 1024,
material_class: args.material_class || null,
},
});
return {
content: [
{
type: 'text',
text:
`Texture generation started for "${args.prompt}".\nJob ID: ${job.extJobId}\n` +
pollHint(job.eta, 'Typically completes in 2–5 minutes.'),
},
],
structuredContent: {
job_id: job.extJobId,
status: 'queued',
source_mesh_url: args.mesh_url,
prompt: args.prompt,
eta_seconds: job.eta,
},
};
},
},
{
name: 'retexture_region',
title: "Repaint one masked region of a model's texture (magic brush)",
annotations: GENERATIVE_ANNOTATIONS,
description:
'Surgically repaint ONLY a region of an existing texture from a prompt and/or colour, ' +
'leaving the rest of the surface untouched and feathering the seam so the edit is invisible. ' +
'Real UV-space texture inpainting — fix a seam, recolour one panel, add a logo to a chest plate. ' +
"Supply mask_url: a UV-space mask PNG in the model's own UV layout where WHITE marks the area to " +
'repaint and black is preserved. Safe to run repeatedly — chain passes by feeding the previous ' +
'result GLB back in as mesh_url. Returns a job_id to poll with generation_status. ' +
'Use this to fix or recolour one area of an already textured model; to repaint the whole surface call retexture_model instead.',
inputSchema: {
type: 'object',
properties: {
mesh_url: {
type: 'string',
format: 'uri',
description: 'Public https URL of the textured GLB to edit.',
},
mask_url: {
type: 'string',
format: 'uri',
description:
'Public https URL of the UV-space mask PNG (white = repaint, black = keep), ' +
'in the same UV layout as the mesh.',
},
prompt: {
type: 'string',
maxLength: 500,
description:
'What to paint into the masked region, e.g. "weathered copper plate".',
},
color: {
type: 'string',
pattern: '^#?[0-9a-fA-F]{3}([0-9a-fA-F]{3})?$',
description: 'Optional target colour as a hex value, e.g. "#1e90ff".',
},
negative_prompt: {
type: 'string',
maxLength: 300,
default: 'blurry, low quality, distorted, watermark, seam',
},
texture_size: {
type: 'integer',
enum: [512, 1024, 2048],
default: 1024,
},
strength: {
type: 'number',
minimum: 0.2,
maximum: 1,
default: 0.85,
description:
'How aggressively to regenerate the region (higher = more change).',
},
feather: {
type: 'integer',
minimum: 1,
maximum: 128,
default: 24,
description: 'Seam feather radius in atlas pixels — larger blends softer.',
},
},
required: ['mesh_url', 'mask_url'],
additionalProperties: false,
},
async handler(args, auth) {
await enforce(limits.mcp3dGenerate, auth);
if (!(await isPublicHttpsUrl(args.mesh_url))) {
return {
content: [
{ type: 'text', text: 'Error: mesh_url must be a public https URL.' },
],
isError: true,
};
}
if (!(await isPublicHttpsUrl(args.mask_url))) {
return {
content: [
{ type: 'text', text: 'Error: mask_url must be a public https URL.' },
],
isError: true,
};
}
if (!args.prompt && !args.color) {
return {
content: [
{
type: 'text',
text: 'Error: provide a prompt and/or a color for the region.',
},
],
isError: true,
};
}
const provider = regionProvider();
const job = await provider.submit({
mode: 'retex_region',
sourceUrl: args.mesh_url,
params: {
prompt: args.prompt || '',
negative_prompt: args.negative_prompt,
mask: args.mask_url,
color: args.color || null,
texture_size: args.texture_size || 1024,
strength: args.strength ?? 0.85,
feather: args.feather ?? 24,
},
});
return {
content: [
{
type: 'text',
text:
`Region retexture started${args.prompt ? ` for "${args.prompt}"` : ''}.\n` +
`Job ID: ${job.extJobId}\n` +
`${pollHint(job.eta, 'Typically completes in 30–90 seconds.')} ` +
'To stack edits, feed the resulting GLB back in as mesh_url.',
},
],
structuredContent: {
job_id: job.extJobId,
status: 'queued',
source_mesh_url: args.mesh_url,
mask_url: args.mask_url,
prompt: args.prompt || null,
color: args.color || null,
eta_seconds: job.eta,
},
};
},
},
{
name: 'auto_rig_model',
title: 'Auto-rig a static 3D model (skeleton + skin weights)',
annotations: GENERATIVE_ANNOTATIONS,
description:
'Turn a static GLB mesh into an animation-ready character: adds a humanoid skeleton and per-vertex skin weights via the three.ws rig pipeline. Use this after text_to_3d or image_to_3d when the model should move: generate a mesh, rig it, then drive it with apply_animation or pose_model. Returns a job_id; poll generation_status for the rigged GLB.',
inputSchema: {
type: 'object',
properties: {
glb_url: {
type: 'string',
format: 'uri',
description: 'Public https URL of the static GLB mesh to rig.',
},
},
required: ['glb_url'],
additionalProperties: false,
},
async handler(args, auth) {
await enforce(limits.mcp3dGenerate, auth);
if (!(await isPublicHttpsUrl(args.glb_url))) {
return {
content: [{ type: 'text', text: 'Error: glb_url must be a public https URL.' }],
isError: true,
};
}
const provider = regenProvider('rerig');
if (!provider.supportsMode('rerig')) {
return {
content: [
{
type: 'text',
text: 'Auto-rigging is not configured on this deployment.',
},
],
isError: true,
};
}
const job = await provider.submit({
mode: 'rerig',
sourceUrl: args.glb_url,
params: {},
});
return {
content: [
{
type: 'text',
text:
`Auto-rigging started.\nJob ID: ${job.extJobId}\n` +
'Poll with generation_status — when done it returns a rigged, animation-ready GLB. Typically completes in 30–90 seconds.',
},
],
structuredContent: {
job_id: job.extJobId,
status: 'queued',
source_glb_url: args.glb_url,
eta_seconds: typeof job.eta === 'number' ? job.eta : null,
},
};
},
},
{
name: 'pose_model',
title: 'Resolve a text prompt to a pose-studio seed + joint rotations',
// Pure local computation over the in-repo preset library — deterministic
// ("the same prompt always yields the same pose"), no external calls,
// nothing persisted.
annotations: {
readOnlyHint: true,
destructiveHint: false,
idempotentHint: true,
openWorldHint: false,
},
description:
'Map a natural-language pose description to a deterministic pose-studio seed and the full Euler joint-rotation map for the three.ws humanoid mannequin, picked from the in-repo preset library. Returns the preset id, the complete pose (radians per joint), a stable seed, and a previewUrl on three.ws/pose. Deterministic: the same prompt always yields the same pose. Same engine as the free local @three-ws/pose npm package. Use this to pose a character rigged with auto_rig_model or to get a reproducible pose link from a description; for motion over time call apply_animation instead.',
inputSchema: {
type: 'object',
properties: {
prompt: {
type: 'string',
minLength: 1,
maxLength: 500,
description:
'Pose description, e.g. "warrior stance", "wave hello", "sitting cross-legged".',
},
},
required: ['prompt'],
additionalProperties: false,
},
async handler(args) {
const picked = pickPosePreset(args.prompt);
const preset = picked.entry.preset;
const seed = createHash('sha256')
.update(`${args.prompt}|${preset.id}`)
.digest('hex')
.slice(0, 16);
const previewUrl = `${POSE_PREVIEW_BASE}?seed=${encodeURIComponent(seed)}&preset=${encodeURIComponent(preset.id)}`;
return {
content: [
{
type: 'text',
text: `Pose "${preset.label}" (${preset.group}) — seed ${seed}.\nPreview: ${previewUrl}`,
},
],
structuredContent: {
seed,
preset_id: preset.id,
preset_label: preset.label,
group: preset.group,
parameters: preset.pose,
preview_url: previewUrl,
match: { score: picked.score, reason: picked.reason },
groups: PRESET_GROUPS,
},
};
},
},
{
name: 'direct_prompt',
title: 'Optimize a rough idea into a 3D-generation prompt (IBM Granite)',
annotations: GENERATIVE_ANNOTATIONS,
description:
'Rewrite a rough idea into an optimized text_to_3d prompt using IBM Granite. Returns one clean single-subject description plus structured directives (subject, style, materials, colors, detail) that produce cleaner meshes. Use this before text_to_3d when a prompt is vague, conflicting, or multi-subject. Requires IBM watsonx.ai credentials on the server.',
inputSchema: {
type: 'object',
properties: {
idea: {
type: 'string',
minLength: 1,
maxLength: 2000,
description:
'The rough idea or prompt to optimize, e.g. "some kind of cool dragon thing".',
},
style: {
type: 'string',
maxLength: 200,
description:
'Optional style hint, e.g. "low-poly", "realistic", "stylized PBR".',
},
},
required: ['idea'],
additionalProperties: false,
},
async handler(args, auth) {
await enforce(limits.mcp3dGenerate, auth);
const system =
'You are a 3D-generation prompt director. Given a rough idea, produce a prompt that yields a single, clearly-described object for image-to-3D reconstruction. Return ONLY valid JSON with keys: "prompt" (one concise sentence describing ONE subject), "subject", "style", "materials" (array), "colors" (array), "detail" (one of draft|standard|high), "notes". No markdown, no prose outside the JSON.';
const user = args.style ? `${args.idea}\n\nPreferred style: ${args.style}` : args.idea;
const result = await graniteChatComplete({
system,
user,
maxTokens: 700,
temperature: 0.3,
tool: 'mcp3d-direct-prompt',
});
let parsed = null;
try {
parsed = JSON.parse(stripJsonFence(result.text));
} catch {
// The model didn't return clean JSON: surface the raw text below.
}
if (!parsed || typeof parsed.prompt !== 'string') {
return {
content: [{ type: 'text', text: result.text }],
structuredContent: {
ok: true,
optimized_prompt: null,
raw_response: result.text,
model: result.model,
},
};
}
return {
content: [{ type: 'text', text: `Optimized prompt: ${parsed.prompt}` }],
structuredContent: {
ok: true,
optimized_prompt: parsed.prompt,
spec: parsed,
model: result.model,
usage: result.usage,
},
};
},
},
{
name: 'generate_material',
title: 'Generate a glTF PBR material from a description (IBM Granite)',
annotations: GENERATIVE_ANNOTATIONS,
description:
'Generate a physically-based (PBR) glTF 2.0 material from a text description using IBM Granite: base color, metallic, roughness, and emissive factors. Returns a pbrMetallicRoughness material object you can attach to a generated mesh. Use this to get material values for a mesh you are assembling yourself; to paint real texture images onto a model call retexture_model instead. Requires IBM watsonx.ai credentials on the server.',
inputSchema: {
type: 'object',
properties: {
description: {
type: 'string',
minLength: 3,
maxLength: 500,
description:
'Material to describe, e.g. "worn copper, scratched, slightly oxidized".',
},
name: {
type: 'string',
maxLength: 100,
description: 'Optional material name.',
},
},
required: ['description'],
additionalProperties: false,
},
async handler(args, auth) {
await enforce(limits.mcp3dGenerate, auth);
const system =
'You are a 3D material author. Given a description, return ONLY a valid glTF 2.0 material JSON object with keys: "name", "pbrMetallicRoughness" { "baseColorFactor": [r,g,b,a] (0-1), "metallicFactor" (0-1), "roughnessFactor" (0-1) }, "emissiveFactor": [r,g,b] (0-1), "doubleSided" (bool), and a "_notes" string. No markdown, no prose outside the JSON.';
const user = args.name
? `Name: ${args.name}\nMaterial: ${args.description}`
: args.description;
const result = await graniteChatComplete({
system,
user,
maxTokens: 600,
temperature: 0.2,
tool: 'mcp3d-generate-material',
});
let material = null;
try {
material = JSON.parse(stripJsonFence(result.text));
} catch {
// Fall through to raw text when the model returns non-JSON.
}
if (!material || typeof material !== 'object') {
return {
content: [{ type: 'text', text: result.text }],
structuredContent: {
ok: true,
material: null,
raw_response: result.text,
model: result.model,
},
};
}
if (args.name && !material.name) material.name = args.name;
return {
content: [
{
type: 'text',
text: `Generated glTF material${material.name ? ` "${material.name}"` : ''}.`,
},
],
structuredContent: { ok: true, material, model: result.model, usage: result.usage },
};
},
},
{
name: 'save_avatar',
title: 'Save a generated GLB as a durable, named avatar',
// Each call mints a fresh slug + storage object — additive, never
// overwrites, so non-idempotent and non-destructive.
annotations: GENERATIVE_ANNOTATIONS,
description:
'Persist a generated GLB (e.g. the glb_url returned by generation_status) as a durable avatar in your three.ws library. The mesh is copied into our own storage so it survives the provider URL expiring, then registered as a named avatar you own. Returns avatar_id, slug, model_url, and a view_url. This is the bridge from the studio to the avatar system: after saving, get_avatar, render_avatar_image, embeds, and on-chain identity all work on the result. Use this after generation_status returns a finished glb_url worth keeping, since provider URLs expire. Requires you to be signed in.',
inputSchema: {
type: 'object',
properties: {
glb_url: {
type: 'string',
format: 'uri',
description:
'Public https URL of the GLB to save (e.g. from generation_status).',
},
name: {
type: 'string',
minLength: 1,
maxLength: 80,
description: 'A name for the avatar, 1–80 characters.',
},
visibility: {
type: 'string',
enum: ['public', 'unlisted', 'private'],
default: 'unlisted',
description:
'public = listed in the gallery; unlisted = anyone with the link; private = only you.',
},
source_prompt: {
type: 'string',
maxLength: 1000,
description:
'Optional: the prompt that generated this model, kept as provenance.',
},
tags: {
type: 'array',
items: { type: 'string', minLength: 1, maxLength: 40 },
maxItems: 20,
description: 'Optional tags for organizing and searching your library.',
},
},
required: ['glb_url', 'name'],
additionalProperties: false,
},
scope: 'avatars:write',
async handler(args, auth) {
await enforce(limits.mcp3dGenerate, auth);
if (!auth.userId) {
return {
content: [
{
type: 'text',
text:
'Sign in to save an avatar. Saving writes to your three.ws library, ' +
'so it needs a signed-in account (an OAuth bearer token), not an ' +
'anonymous pay-per-call session.',
},
],
structuredContent: { status: 'sign_in_required' },
isError: true,
};
}
if (!(await isPublicHttpsUrl(args.glb_url))) {
return {
content: [{ type: 'text', text: 'Error: glb_url must be a public https URL.' }],
isError: true,
};
}
const buf = await fetchGlbBuffer(args.glb_url);
const info = isValidGlbHeader(buf) ? inspectGlb(buf) : null;
if (!info) {
return {
content: [
{
type: 'text',
text: 'Error: that URL did not return a valid GLB (binary glTF). Pass a .glb model URL.',
},
],
isError: true,
};
}
const visibility = ['public', 'unlisted', 'private'].includes(args.visibility)
? args.visibility
: 'unlisted';
const name = String(args.name).trim().slice(0, 80);
// Random suffix (matches the reconstruct pipeline) so re-saving the same
// model never collides on the per-owner unique slug constraint.
const slug = `studio-${Math.random().toString(36).slice(2, 8)}`;
const storageKey = storageKeyFor({ userId: auth.userId, slug });
await putObject({
key: storageKey,
body: buf,
contentType: 'model/gltf-binary',
metadata: { source: 'studio', user_id: auth.userId },
});
const tags = Array.isArray(args.tags)
? args.tags
.map((t) => String(t).trim())
.filter(Boolean)
.slice(0, 20)
: [];
const avatar = await createAvatar({
userId: auth.userId,
storageKey,
input: {
slug,
name,
description: null,
size_bytes: buf.length,
content_type: 'model/gltf-binary',
source: 'studio',
source_meta: {
source_glb_url: args.glb_url,
source_prompt: args.source_prompt ?? null,
is_rigged: info.isRigged ?? null,
mesh_count: info.meshCount ?? null,
animation_count: info.animationCount ?? null,
},
visibility,
tags,
checksum_sha256: null,
parent_avatar_id: null,
},
});
const viewUrl = `${env.APP_ORIGIN}/avatars/${avatar.id}`;
return {
content: [
{
type: 'text',
text:
`Saved "${avatar.name}" to your library (${visibility}).\n` +
`Avatar ID: ${avatar.id}\nView: ${viewUrl}\n` +
'Render it with render_avatar_image, or fetch it with get_avatar.',
},
],
structuredContent: {
avatar_id: avatar.id,
slug: avatar.slug,
model_url: avatar.model_url,
view_url: viewUrl,
visibility,
},
};
},
},
{
name: 'create_agent_persona',
title: 'Mint a persistent, living agent persona from a rigged GLB',
annotations: PERSONA_CREATE_ANNOTATIONS,
description:
'Turn a generated GLB into a NAMED, persistent agent body: a "persona" the agent reuses across turns and across sessions. The mesh is copied into durable storage so the body survives the provider URL expiring, then registered under a stable persona_id. The returned text/html resource renders the LIVING body inline: it idles between turns, and persona_say makes it lip-sync and emote a reply. The persona_id is the capability: keep it and pass it to get_agent_persona or persona_say later to bring the exact same body back. Use this once a rigged model should become a recurring character the agent speaks through; to keep a GLB in your avatar library instead call save_avatar. No sign-in required.',
inputSchema: {
type: 'object',
properties: {
glb_url: {
type: 'string',
format: 'uri',
description: 'Public https URL of the rigged GLB to embody (e.g. from generation_status).',
},
name: {
type: 'string',
minLength: 1,
maxLength: 80,
description: 'A display name for the persona, 1–80 characters.',
},
voice: {
type: 'string',
maxLength: 64,
description: 'Optional voice id/name to speak with (used for TTS-driven lip-sync when available).',
},
source_prompt: {
type: 'string',
maxLength: 1000,
description: 'Optional: the prompt that generated this body, kept as provenance.',
},
},
required: ['glb_url', 'name'],
additionalProperties: false,
},
async handler(args, auth) {
await enforce(limits.mcp3dGenerate, auth);
if (!(await isPublicHttpsUrl(args.glb_url))) {
return {
content: [{ type: 'text', text: 'Error: glb_url must be a public https URL.' }],
isError: true,
};
}
const buf = await fetchGlbBuffer(args.glb_url);
const info = isValidGlbHeader(buf) ? inspectGlb(buf) : null;
if (!info) {
return {
content: [
{ type: 'text', text: 'Error: that URL did not return a valid GLB (binary glTF). Pass a .glb model URL.' },
],
isError: true,
};
}
const record = await createPersona({
name: args.name,
glbUrl: args.glb_url,
glbBuffer: buf,
voice: args.voice ?? null,
sourcePrompt: args.source_prompt ?? null,
ownerId: auth.userId ?? null,
look: {
rigged: info.isRigged ?? null,
mesh_count: info.meshCount ?? null,
animation_count: info.animationCount ?? null,
},
});
const persona = personaPublicView(record);
return {
content: [
{
type: 'text',
text:
`Minted "${persona.name}" as a living persona.\n` +
`Persona ID: ${persona.persona_id}\n` +
(persona.look?.rigged ? 'Rig: humanoid — full body animation + lip-sync.\n' : 'Rig: static/non-humanoid — will fall back to the default rig gracefully.\n') +
'Display the attached text/html resource to see the body. ' +
'Call persona_say with this persona_id to make it speak a reply, or get_agent_persona to bring it back in a future session.',
},
embodimentArtifact({ persona, state: 'idle' }),
],
structuredContent: { ...persona, status: 'created' },
};
},
},
{
name: 'get_agent_persona',
title: 'Reload a persisted persona by id (continuity across sessions)',
annotations: PERSONA_READ_ANNOTATIONS,
description:
'Bring back a previously minted persona by its persona_id: the SAME body and identity, in a fresh session. Returns the persona name, its GLB, accumulated turn count, and the inline living-body artifact. Use this when a conversation starts and the user returns to a named agent.',
inputSchema: {
type: 'object',
properties: {
persona_id: {
type: 'string',
minLength: 8,
maxLength: 64,
description: 'The persona_id returned by create_agent_persona.',
},
},
required: ['persona_id'],
additionalProperties: false,
},
async handler(args, auth) {
await enforce(limits.mcp3dStatus, auth);
if (!isPersonaId(args.persona_id)) {
return {
content: [{ type: 'text', text: 'Error: that is not a valid persona_id.' }],
structuredContent: { status: 'invalid_id' },
isError: true,
};
}
const record = await getPersona(args.persona_id);
if (!record) {
return {
content: [{ type: 'text', text: 'No persona found for that id. Mint one with create_agent_persona.' }],
structuredContent: { status: 'not_found' },
isError: true,
};
}
const persona = personaPublicView(record);
return {
content: [
{
type: 'text',
text:
`Welcome back, ${persona.name}.\n` +
`Persona ID: ${persona.persona_id}\n` +
`Turns spoken so far: ${persona.turn_count}.\n` +
'Display the attached text/html resource to see the body; call persona_say to make it speak.',
},
embodimentArtifact({ persona, state: 'idle' }),
],
structuredContent: { ...persona, status: 'loaded' },
};
},
},
{
name: 'persona_say',
title: 'Speak a reply through a persona: lip-sync + emotion + gesture',
annotations: PERSONA_SAY_ANNOTATIONS,
description:
"Make a persona PERFORM a reply: the body lip-syncs the text and shows the matching expression and body gesture. Pass the persona_id and the exact text the agent is saying this turn; the emotion is detected from the text automatically (or override it). The returned text/html resource animates the body for this turn; display it alongside the spoken reply. Use this whenever the persona speaks, on every turn, with the persona_id from create_agent_persona or get_agent_persona.",
inputSchema: {
type: 'object',
properties: {
persona_id: {
type: 'string',
minLength: 8,
maxLength: 64,
description: 'The persona to speak through.',
},
text: {
type: 'string',
minLength: 1,
maxLength: 2000,
description: 'The reply text the agent is saying this turn — drives lip-sync and emotion.',
},
emotion: {
type: 'string',
enum: ['neutral', 'joy', 'sad', 'angry', 'surprised', 'thinking'],
description: 'Optional explicit emotion override; omit to auto-detect from the text.',
},
},
required: ['persona_id', 'text'],
additionalProperties: false,
},
async handler(args, auth) {
await enforce(limits.mcp3dGenerateFree, auth);
if (!isPersonaId(args.persona_id)) {
return {
content: [{ type: 'text', text: 'Error: that is not a valid persona_id.' }],
structuredContent: { status: 'invalid_id' },
isError: true,
};
}
const record = await getPersona(args.persona_id);
if (!record) {
return {
content: [{ type: 'text', text: 'No persona found for that id. Mint one with create_agent_persona.' }],
structuredContent: { status: 'not_found' },
isError: true,
};
}
const expr = args.emotion
? { ...expressionFor(args.emotion, 0.85), scores: {} }
: expressionForText(args.text);
const updated = await touchPersona(args.persona_id);
const persona = personaPublicView(updated || record);
return {
content: [
{
type: 'text',
text:
`${persona.name} says it with a ${expr.emotion} expression` +
(expr.gesture ? ` and a ${expr.gesture} gesture` : '') +
`. Display the attached text/html resource — the body lip-syncs the reply and emotes.`,
},
embodimentArtifact({
persona,
state: 'speaking',
text: args.text,
emotion: expr.emotion,
intensity: expr.intensity,
gesture: expr.gesture,
}),
],
structuredContent: {
persona_id: persona.persona_id,
name: persona.name,
glb_url: persona.glb_url,
text: args.text,
emotion: expr.emotion,
intensity: expr.intensity,
gesture: expr.gesture,
turn_count: persona.turn_count,
status: 'spoken',
},
};
},
},
];