@three-ws/avatar-agent 1.0.0

package/src/lib/pumpfun.js

@@ -0,0 +1,175 @@
+// pump.fun + on-chain snapshot data. Pulls live numbers from public APIs
+// and the Solana RPC. No fallbacks, no mocked numbers — if a source is
+// unreachable the field is null so callers see the gap clearly.
+//
+// Sources:
+//   - Jupiter Lite price API (lite-api.jup.ag/price/v3)
+//   - Dexscreener tokens API (api.dexscreener.com/latest/dex/tokens/<mint>)
+//   - pump.fun frontend-api-v3 (frontend-api-v3.pump.fun/coins/<mint>)
+//   - Solana getTokenLargestAccounts via the configured RPC
+//   - Optional Helius DAS getAsset (HELIUS_API_KEY)
+
+import { Connection, PublicKey } from '@solana/web3.js';
+
+import { HELIUS_API_KEY, SOLANA_RPC_URL } from '../config.js';
+
+async function fetchJson(url, init = {}, timeoutMs = 8000) {
+	const controller = new AbortController();
+	const t = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		const res = await fetch(url, { ...init, signal: controller.signal });
+		if (!res.ok) throw new Error(`${url} → HTTP ${res.status}`);
+		return await res.json();
+	} finally {
+		clearTimeout(t);
+	}
+}
+
+export async function getJupiterPrice(mint) {
+	try {
+		const data = await fetchJson(`https://lite-api.jup.ag/price/v3?ids=${mint}`);
+		const entry = data?.[mint];
+		if (!entry) return null;
+		return {
+			usdPrice: entry.usdPrice ?? null,
+			priceChange24hPct: entry.priceChange24h ?? null,
+			liquidityUsd: entry.liquidity ?? null,
+			decimals: entry.decimals ?? null,
+			blockId: entry.blockId ?? null,
+		};
+	} catch (err) {
+		return { error: err.message };
+	}
+}
+
+export async function getDexscreener(mint) {
+	try {
+		const data = await fetchJson(`https://api.dexscreener.com/latest/dex/tokens/${mint}`);
+		const pairs = Array.isArray(data?.pairs) ? data.pairs : [];
+		if (pairs.length === 0) return null;
+		const pair = pairs.reduce((best, p) => {
+			const v = Number(p?.volume?.h24 || 0);
+			return v > (best?.vol || 0) ? { pair: p, vol: v } : best;
+		}, null)?.pair;
+		if (!pair) return null;
+		return {
+			volume24hUsd: Number(pair.volume?.h24 || 0),
+			priceUsd: pair.priceUsd ? Number(pair.priceUsd) : null,
+			priceChange24hPct: pair.priceChange?.h24 ?? null,
+			liquidityUsd: pair.liquidity?.usd ?? null,
+			fdvUsd: pair.fdv ?? null,
+			marketCapUsd: pair.marketCap ?? null,
+			pairAddress: pair.pairAddress,
+			dex: pair.dexId,
+			chain: pair.chainId,
+			url: pair.url,
+			txns24h: pair.txns?.h24 ?? null,
+		};
+	} catch (err) {
+		return { error: err.message };
+	}
+}
+
+export async function getPumpFunMeta(mint) {
+	try {
+		const data = await fetchJson(`https://frontend-api-v3.pump.fun/coins/${mint}`);
+		if (!data || data.error) return null;
+		return {
+			name: data.name || null,
+			symbol: data.symbol || null,
+			description: data.description || null,
+			imageUrl: data.image_uri || null,
+			twitter: data.twitter || null,
+			telegram: data.telegram || null,
+			website: data.website || null,
+			creator: data.creator || null,
+			createdAtMs: data.created_timestamp || null,
+			complete: !!data.complete,
+			marketCapUsd: data.usd_market_cap ?? null,
+			marketCapQuote: data.market_cap ?? null,
+			totalSupply: data.total_supply_str || data.total_supply || null,
+			poolAddress: data.pool_address || null,
+			lastTradeTimestampMs: data.last_trade_timestamp || null,
+			athMarketCapUsd: data.ath_market_cap ?? null,
+			athMarketCapTimestampMs: data.ath_market_cap_timestamp || null,
+			program: data.program || null,
+		};
+	} catch (err) {
+		return { error: err.message };
+	}
+}
+
+export async function getTopHolders(mint) {
+	try {
+		const conn = new Connection(SOLANA_RPC_URL, 'confirmed');
+		const res = await conn.getTokenLargestAccounts(new PublicKey(mint));
+		const top = (res?.value || []).map((acct) => ({
+			address: acct.address.toBase58(),
+			uiAmount: acct.uiAmount,
+			amount: acct.amount,
+			decimals: acct.decimals,
+		}));
+		return {
+			topHolderCount: top.length,
+			topHolders: top,
+		};
+	} catch (err) {
+		return { error: err.message };
+	}
+}
+
+export async function getHeliusInfo(mint) {
+	if (!HELIUS_API_KEY) return null;
+	try {
+		const url = `https://mainnet.helius-rpc.com/?api-key=${HELIUS_API_KEY}`;
+		const body = {
+			jsonrpc: '2.0',
+			id: 'getAsset',
+			method: 'getAsset',
+			params: { id: mint, options: { showFungible: true } },
+		};
+		const data = await fetchJson(url, {
+			method: 'POST',
+			headers: { 'content-type': 'application/json' },
+			body: JSON.stringify(body),
+		});
+		const supply = data?.result?.token_info?.supply ?? null;
+		const decimals = data?.result?.token_info?.decimals ?? null;
+		const priceInfo = data?.result?.token_info?.price_info ?? null;
+		return {
+			supply: supply !== null ? String(supply) : null,
+			decimals,
+			heliusPriceUsd: priceInfo?.price_per_token ?? null,
+		};
+	} catch (err) {
+		return { error: err.message };
+	}
+}
+
+export async function snapshot(mint) {
+	const [price, ds, meta, holders, helius] = await Promise.all([
+		getJupiterPrice(mint),
+		getDexscreener(mint),
+		getPumpFunMeta(mint),
+		getTopHolders(mint),
+		getHeliusInfo(mint),
+	]);
+	return {
+		token: mint,
+		fetchedAt: new Date().toISOString(),
+		price,
+		volume24h: ds,
+		meta,
+		holders,
+		helius,
+		image: meta?.imageUrl || null,
+		pumpUrl: `https://pump.fun/coin/${mint}`,
+		sources: {
+			price: 'https://lite-api.jup.ag/price/v3',
+			volume24h: 'https://api.dexscreener.com',
+			meta: 'https://frontend-api-v3.pump.fun',
+			holders: SOLANA_RPC_URL,
+			helius: HELIUS_API_KEY ? 'https://mainnet.helius-rpc.com' : null,
+		},
+	};
+}

package/src/lib/render.js

@@ -0,0 +1,76 @@
+// Client helpers for the three.ws server-side render endpoints. The
+// MCP doesn't ship a renderer itself — chromium is too heavy for an
+// npm-installed local server. Instead we POST to three.ws's hosted
+// headless-chromium pipeline (the same renderer that powers OG cards),
+// stream the PNG back, and return it as a base64 data URL plus the
+// upstream URL so callers can choose whichever they want.
+
+import { THREE_WS_BASE } from '../config.js';
+
+const DEFAULT_MAX_INLINE = 4 * 1024 * 1024;
+
+async function postPng(path, body, { maxInlineBytes = DEFAULT_MAX_INLINE } = {}) {
+	const url = `${THREE_WS_BASE}${path}`;
+	const t0 = Date.now();
+	const r = await fetch(url, {
+		method: 'POST',
+		headers: { 'content-type': 'application/json' },
+		body: JSON.stringify(body),
+	});
+	const durationMs = Date.now() - t0;
+	if (!r.ok) {
+		// Try to surface the JSON error envelope three.ws returns.
+		let detail = null;
+		try {
+			detail = await r.json();
+		} catch {
+			detail = { error_description: await r.text().catch(() => '') };
+		}
+		return {
+			ok: false,
+			status: r.status,
+			error: detail?.error || 'render_failed',
+			message: detail?.error_description || `HTTP ${r.status}`,
+			endpoint: url,
+			durationMs,
+		};
+	}
+	const buf = Buffer.from(await r.arrayBuffer());
+	const meta = {
+		width: Number(r.headers.get('x-render-width')) || null,
+		height: Number(r.headers.get('x-render-height')) || null,
+		background: r.headers.get('x-render-background') || null,
+		pose: r.headers.get('x-render-pose') || null,
+		poseLabel: r.headers.get('x-render-pose-label') || null,
+	};
+	const inline = buf.length <= maxInlineBytes;
+	return {
+		ok: true,
+		status: r.status,
+		endpoint: url,
+		durationMs,
+		sizeBytes: buf.length,
+		mime: 'image/png',
+		dataUrl: inline ? `data:image/png;base64,${buf.toString('base64')}` : null,
+		omittedInline: !inline,
+		meta,
+	};
+}
+
+export async function renderGlbThumbnail({ glbUrl, width, height, background, maxInlineBytes }) {
+	return postPng('/api/render/glb', { glbUrl, width, height, background }, { maxInlineBytes });
+}
+
+export async function renderAvatarClipRemote({ glbUrl, width, height, background, posePresetId, cameraOrbit, expression, maxInlineBytes }) {
+	return postPng(
+		'/api/render/avatar-clip',
+		{ glbUrl, width, height, background, posePresetId, cameraOrbit, expression },
+		{ maxInlineBytes },
+	);
+}
+
+export async function fetchPoseCatalogRemote() {
+	const r = await fetch(`${THREE_WS_BASE}/api/render/avatar-clip`, { method: 'GET' });
+	if (!r.ok) throw new Error(`Pose catalog fetch failed: HTTP ${r.status}`);
+	return r.json();
+}

package/src/lib/solana.js

@@ -0,0 +1,190 @@
+// Solana primitives: keypair load, balances, transfers.
+//
+// Every signer-required tool accepts an optional base58 `secret` in the
+// tool arguments. If not provided, it falls back to SOLANA_SECRET_KEY /
+// FUNDER_SECRET from the environment. We never embed default keys.
+
+import {
+	Connection,
+	Keypair,
+	PublicKey,
+	SystemProgram,
+	TransactionMessage,
+	VersionedTransaction,
+	ComputeBudgetProgram,
+	LAMPORTS_PER_SOL,
+} from '@solana/web3.js';
+import bs58 from 'bs58';
+
+import { SOLANA_RPC_URL, SOLANA_DEFAULT_SECRET } from '../config.js';
+
+const bs58encode = bs58.default ? bs58.default.encode : bs58.encode;
+const bs58decode = bs58.default ? bs58.default.decode : bs58.decode;
+
+export { bs58encode, bs58decode, LAMPORTS_PER_SOL };
+
+let _conn = null;
+export function getConnection() {
+	if (!_conn) _conn = new Connection(SOLANA_RPC_URL, 'confirmed');
+	return _conn;
+}
+
+export function isValidPubkey(s) {
+	try {
+		new PublicKey(s);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export function keypairFromSecret(secret) {
+	const trimmed = String(secret || '').trim();
+	if (!trimmed) {
+		const err = new Error(
+			'Solana secret required. Pass `secret` (base58) in the tool call, ' +
+				'or set SOLANA_SECRET_KEY in the MCP server environment.',
+		);
+		err.code = 'no_signer';
+		throw err;
+	}
+	const bytes = bs58decode(trimmed);
+	if (bytes.length !== 64) {
+		const err = new Error(`Solana secret must decode to 64 bytes (got ${bytes.length})`);
+		err.code = 'invalid_secret';
+		throw err;
+	}
+	return Keypair.fromSecretKey(bytes);
+}
+
+export function loadSigner(secret) {
+	return keypairFromSecret(secret || SOLANA_DEFAULT_SECRET);
+}
+
+export async function getBalanceSol(pubkeyStr) {
+	const conn = getConnection();
+	const lamports = await conn.getBalance(new PublicKey(pubkeyStr), 'confirmed');
+	return { lamports, sol: lamports / LAMPORTS_PER_SOL };
+}
+
+export async function getTokenBalances(pubkeyStr) {
+	const conn = getConnection();
+	const owner = new PublicKey(pubkeyStr);
+	// SPL Token program — fetch parsed accounts so we get mint + amount cleanly.
+	const TOKEN_PROGRAM = new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA');
+	const TOKEN_2022_PROGRAM = new PublicKey('TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb');
+	const [legacy, t22] = await Promise.all([
+		conn.getParsedTokenAccountsByOwner(owner, { programId: TOKEN_PROGRAM }),
+		conn.getParsedTokenAccountsByOwner(owner, { programId: TOKEN_2022_PROGRAM }),
+	]);
+	const all = [...legacy.value, ...t22.value];
+	return all
+		.map((r) => {
+			const info = r.account.data?.parsed?.info;
+			if (!info) return null;
+			const amount = info.tokenAmount;
+			return {
+				mint: info.mint,
+				owner: info.owner,
+				account: r.pubkey.toBase58(),
+				amount: amount?.amount,
+				uiAmount: amount?.uiAmount,
+				uiAmountString: amount?.uiAmountString,
+				decimals: amount?.decimals,
+			};
+		})
+		.filter(Boolean)
+		.filter((t) => Number(t.uiAmount) > 0);
+}
+
+export async function sendSol({ secret, to, sol, priorityMicroLamports = 100000 }) {
+	if (!isValidPubkey(to)) {
+		const err = new Error(`Destination is not a valid Solana pubkey: ${to}`);
+		err.code = 'invalid_destination';
+		throw err;
+	}
+	const signer = loadSigner(secret);
+	const conn = getConnection();
+	const lamports = Math.floor(Number(sol) * LAMPORTS_PER_SOL);
+	if (!Number.isFinite(lamports) || lamports <= 0) {
+		const err = new Error(`sol must be a positive number (got ${sol})`);
+		err.code = 'invalid_amount';
+		throw err;
+	}
+	const { blockhash, lastValidBlockHeight } = await conn.getLatestBlockhash('confirmed');
+	const msg = new TransactionMessage({
+		payerKey: signer.publicKey,
+		recentBlockhash: blockhash,
+		instructions: [
+			ComputeBudgetProgram.setComputeUnitPrice({ microLamports: priorityMicroLamports }),
+			ComputeBudgetProgram.setComputeUnitLimit({ units: 1000 }),
+			SystemProgram.transfer({
+				fromPubkey: signer.publicKey,
+				toPubkey: new PublicKey(to),
+				lamports,
+			}),
+		],
+	}).compileToV0Message();
+	const tx = new VersionedTransaction(msg);
+	tx.sign([signer]);
+	const sig = await conn.sendTransaction(tx, { maxRetries: 5 });
+	const conf = await conn.confirmTransaction(
+		{ signature: sig, blockhash, lastValidBlockHeight },
+		'confirmed',
+	);
+	if (conf?.value?.err) {
+		const err = new Error(`Transaction failed: ${JSON.stringify(conf.value.err)}`);
+		err.code = 'tx_failed';
+		err.signature = sig;
+		throw err;
+	}
+	return {
+		signature: sig,
+		from: signer.publicKey.toBase58(),
+		to,
+		sol: Number(sol),
+		lamports,
+		explorer: `https://solscan.io/tx/${sig}`,
+	};
+}
+
+// Vanity grinder. Returns the first keypair whose base58 pubkey matches the
+// given prefix and/or suffix (case-sensitive by default). The user can cap
+// max attempts to keep the call bounded.
+export function grindVanity({ prefix = '', suffix = '', caseSensitive = true, maxAttempts = 500_000 }) {
+	const pre = String(prefix || '');
+	const suf = String(suffix || '');
+	if (!pre && !suf) {
+		const err = new Error('Provide at least a prefix or suffix to grind for.');
+		err.code = 'invalid_input';
+		throw err;
+	}
+	const matches = (b58) => {
+		const candidate = caseSensitive ? b58 : b58.toLowerCase();
+		const p = caseSensitive ? pre : pre.toLowerCase();
+		const s = caseSensitive ? suf : suf.toLowerCase();
+		if (p && !candidate.startsWith(p)) return false;
+		if (s && !candidate.endsWith(s)) return false;
+		return true;
+	};
+	const startedAt = Date.now();
+	for (let i = 0; i < maxAttempts; i++) {
+		const kp = Keypair.generate();
+		const b58 = kp.publicKey.toBase58();
+		if (matches(b58)) {
+			return {
+				found: true,
+				attempts: i + 1,
+				durationMs: Date.now() - startedAt,
+				pubkey: b58,
+				secret: bs58encode(kp.secretKey),
+			};
+		}
+	}
+	return {
+		found: false,
+		attempts: maxAttempts,
+		durationMs: Date.now() - startedAt,
+		message: `No match for prefix="${pre}" suffix="${suf}" in ${maxAttempts} attempts. Try a shorter pattern or a higher maxAttempts.`,
+	};
+}

package/src/tools/dress-avatar.js

@@ -0,0 +1,61 @@
+// `dress_avatar` — apply or remove accessories on a spawned avatar session
+// and optionally set the pose. Returns the updated session manifest and a
+// refreshed viewer URL.
+
+import { z } from 'zod';
+
+import { ACCESSORIES, POSE_PRESETS, findAccessory, getSession, updateSession, viewerUrlFor } from '../lib/avatars.js';
+
+export const def = {
+	name: 'dress_avatar',
+	title: 'Apply accessories + pose to a spawned avatar',
+	description:
+		'Apply (or replace) accessories on a spawned avatar session and optionally set a pose. Pass accessoryIds to set the full accessory list (empty array clears them). Pass pose to switch animations. Returns the updated viewer URL.',
+	inputSchema: {
+		sessionId: z.string().describe('Session id returned by spawn_avatar.'),
+		accessoryIds: z.array(z.string()).optional()
+			.describe(`Full list of accessory ids to wear. Allowed: ${ACCESSORIES.map((a) => a.id).join(', ')}. Empty array clears.`),
+		pose: z.string().optional()
+			.describe(`Pose preset. Allowed: ${POSE_PRESETS.join(', ')}.`),
+	},
+	async handler(args) {
+		const { sessionId, accessoryIds, pose } = args || {};
+		const session = getSession(sessionId);
+		if (!session) {
+			return { ok: false, error: 'unknown_session', message: `No session ${sessionId}. Call spawn_avatar first.` };
+		}
+		const patch = {};
+		if (Array.isArray(accessoryIds)) {
+			const resolved = [];
+			const missing = [];
+			for (const id of accessoryIds) {
+				const acc = findAccessory(id);
+				if (!acc) {
+					missing.push(id);
+					continue;
+				}
+				resolved.push(acc);
+			}
+			if (missing.length) {
+				return { ok: false, error: 'unknown_accessory', missing, allowed: ACCESSORIES.map((a) => a.id) };
+			}
+			patch.accessories = resolved;
+		}
+		if (pose) {
+			if (!POSE_PRESETS.includes(pose)) {
+				return { ok: false, error: 'unknown_pose', pose, allowed: POSE_PRESETS };
+			}
+			patch.pose = pose;
+		}
+		const updated = updateSession(sessionId, patch);
+		return {
+			ok: true,
+			sessionId: updated.id,
+			avatar: updated.avatar,
+			accessories: updated.accessories,
+			pose: updated.pose,
+			viewerUrl: viewerUrlFor(updated),
+			lastUpdated: updated.lastUpdated,
+		};
+	},
+};

package/src/tools/ens-sns-resolve.js

@@ -0,0 +1,21 @@
+// `ens_sns_resolve` — resolve human-readable names to on-chain addresses
+// across ENS (Ethereum) and SNS (Solana, Bonfida). Useful for naming
+// avatar wallets ("alice.sol") or sending to ENS addresses without
+// pasting raw hex.
+
+import { z } from 'zod';
+
+import { resolveName } from '../lib/ens-sns.js';
+
+export const def = {
+	name: 'ens_sns_resolve',
+	title: 'Resolve ENS + SNS names to addresses',
+	description:
+		'Resolve a human-readable name to addresses across ENS (Ethereum) and SNS (Solana, Bonfida). For .eth: returns Ethereum address + reverse lookup. For .sol: returns Solana owner wallet + the wallet\'s other owned .sol domains + favorite domain. Names without a suffix are tried against both registries.',
+	inputSchema: {
+		name: z.string().min(1).max(253).describe('Name to resolve, e.g. "vitalik.eth", "bonfida.sol", or bare "vitalik" (tried in both registries).'),
+	},
+	async handler(args) {
+		return await resolveName(args.name);
+	},
+};

package/src/tools/generate-avatar.js

@@ -0,0 +1,165 @@
+// `generate_avatar` — generate a textured GLB from a text prompt or
+// reference image(s) via Replicate. Requires REPLICATE_API_TOKEN and a
+// pinned model version in REPLICATE_TEXT_TO_AVATAR_MODEL (recommended:
+// the latest tencent/hunyuan-3d-3.1 commercial-OK version).
+//
+// On success, the result is a new avatar session preloaded with the
+// generated GLB URL.
+
+import { z } from 'zod';
+
+import { REPLICATE_API_TOKEN, REPLICATE_TEXT_TO_AVATAR_MODEL } from '../config.js';
+import { createSession, viewerUrlFor } from '../lib/avatars.js';
+
+const REPLICATE_BASE = 'https://api.replicate.com/v1';
+
+function authHeaders() {
+	return { authorization: `Bearer ${REPLICATE_API_TOKEN}`, 'content-type': 'application/json' };
+}
+
+function extractGlbUrl(output) {
+	if (!output) return null;
+	if (typeof output === 'string') return output;
+	if (Array.isArray(output)) {
+		for (const v of output) if (typeof v === 'string' && /\.glb(\?|$)/i.test(v)) return v;
+		for (const v of output) if (typeof v === 'string' && /^https?:\/\//.test(v)) return v;
+	}
+	if (typeof output === 'object') {
+		for (const key of ['glb', 'mesh', 'mesh_url', 'output_url', 'url', 'model']) {
+			if (typeof output[key] === 'string') return output[key];
+		}
+	}
+	return null;
+}
+
+async function submitPrediction({ version, input }) {
+	const res = await fetch(`${REPLICATE_BASE}/predictions`, {
+		method: 'POST',
+		headers: authHeaders(),
+		body: JSON.stringify({ version, input }),
+	});
+	const data = await res.json().catch(() => ({}));
+	if (!res.ok) {
+		const err = new Error(data?.detail || data?.title || `replicate returned ${res.status}`);
+		err.code = 'provider_error';
+		throw err;
+	}
+	return data;
+}
+
+async function pollPrediction(predictionId, { timeoutMs, intervalMs }) {
+	const deadline = Date.now() + timeoutMs;
+	let last = null;
+	while (Date.now() < deadline) {
+		const r = await fetch(`${REPLICATE_BASE}/predictions/${encodeURIComponent(predictionId)}`, {
+			headers: authHeaders(),
+		});
+		const data = await r.json().catch(() => ({}));
+		if (!r.ok) {
+			const err = new Error(data?.detail || `replicate poll returned ${r.status}`);
+			err.code = 'provider_error';
+			throw err;
+		}
+		last = data;
+		const s = data.status;
+		if (s === 'succeeded' || s === 'failed' || s === 'canceled') return data;
+		await new Promise((res) => setTimeout(res, intervalMs));
+	}
+	return { ...last, _timedOut: true };
+}
+
+export const def = {
+	name: 'generate_avatar',
+	title: 'Generate a 3D avatar (Replicate text-to-3D)',
+	description:
+		'Generate a textured GLB from a text prompt or reference image URLs via Replicate (Hunyuan-3D 3.1 by default; configurable). Returns the GLB URL and a new avatar session you can dress + animate. Requires REPLICATE_API_TOKEN and REPLICATE_TEXT_TO_AVATAR_MODEL on the MCP server.',
+	inputSchema: {
+		prompt: z.string().max(1000).optional().describe('Text description of the avatar to generate.'),
+		images: z.array(z.string().url()).max(4).optional().describe('Reference image URLs for image-to-3D.'),
+		seed: z.number().int().min(0).max(2147483647).optional(),
+		texture: z.boolean().optional().describe('Request PBR textures when supported (default true).'),
+		name: z.string().max(80).optional().describe('Name for the resulting avatar session.'),
+		voice: z
+			.enum(['alloy', 'ash', 'ballad', 'coral', 'echo', 'fable', 'nova', 'onyx', 'sage', 'shimmer', 'verse'])
+			.optional()
+			.describe('TTS voice the session should use.'),
+	},
+	async handler(args) {
+		if (!REPLICATE_API_TOKEN) {
+			return { ok: false, error: 'not_configured', message: 'REPLICATE_API_TOKEN is not set on the MCP server.' };
+		}
+		if (!REPLICATE_TEXT_TO_AVATAR_MODEL) {
+			return {
+				ok: false,
+				error: 'not_configured',
+				message: 'REPLICATE_TEXT_TO_AVATAR_MODEL is not set. Pin a commercial-OK image/text-to-3D version (e.g. latest tencent/hunyuan-3d-3.1).',
+			};
+		}
+		const { prompt, images, seed, texture, name, voice } = args || {};
+		if (!prompt && (!images || images.length === 0)) {
+			return { ok: false, error: 'invalid_input', message: 'Provide either prompt or images[].' };
+		}
+		const input = {
+			prompt: prompt || undefined,
+			image: images && images.length ? images[0] : undefined,
+			images: images && images.length ? images : undefined,
+			seed: typeof seed === 'number' ? seed : undefined,
+			texture: typeof texture === 'boolean' ? texture : true,
+		};
+		Object.keys(input).forEach((k) => input[k] === undefined && delete input[k]);
+
+		const started = Date.now();
+		let submitted;
+		try {
+			submitted = await submitPrediction({ version: REPLICATE_TEXT_TO_AVATAR_MODEL, input });
+		} catch (err) {
+			return { ok: false, error: err.code || 'provider_error', message: err.message };
+		}
+		const timeoutMs = Number(process.env.REPLICATE_TIMEOUT_MS || '120000');
+		const intervalMs = Number(process.env.REPLICATE_POLL_MS || '2000');
+		const finalState = await pollPrediction(submitted.id, { timeoutMs, intervalMs });
+		const durationMs = Date.now() - started;
+		if (finalState._timedOut) {
+			return {
+				ok: false,
+				error: 'timeout',
+				message: `prediction did not finish within ${timeoutMs}ms`,
+				predictionId: submitted.id,
+				durationMs,
+			};
+		}
+		if (finalState.status === 'failed' || finalState.status === 'canceled') {
+			return {
+				ok: false,
+				error: 'prediction_failed',
+				message: finalState.error || `prediction ended with status ${finalState.status}`,
+				predictionId: submitted.id,
+				durationMs,
+			};
+		}
+		const glbUrl = extractGlbUrl(finalState.output);
+		if (!glbUrl) {
+			return {
+				ok: false,
+				error: 'no_glb_in_output',
+				message: 'prediction succeeded but no GLB url was found in output',
+				rawOutput: finalState.output,
+				predictionId: submitted.id,
+				durationMs,
+			};
+		}
+		const session = createSession({ glb: glbUrl, name, voice });
+		return {
+			ok: true,
+			sessionId: session.id,
+			avatar: session.avatar,
+			predictionId: submitted.id,
+			model: REPLICATE_TEXT_TO_AVATAR_MODEL,
+			prompt: prompt || null,
+			images: images || null,
+			seed: typeof seed === 'number' ? seed : null,
+			durationMs,
+			viewerUrl: viewerUrlFor(session),
+		};
+	},
+};