@three-ws/avatar-agent 1.0.0

package/src/tools/spawn-avatar.js

@@ -0,0 +1,60 @@
+// `spawn_avatar` — create an in-process avatar session, either from a
+// curated default (default / cz) or from a custom GLB URL. Returns a
+// session id that other tools reference (dress_avatar, viewer_url, etc.).
+
+import { z } from 'zod';
+
+import { createSession, findAvatar, viewerUrlFor } from '../lib/avatars.js';
+
+export const def = {
+	name: 'spawn_avatar',
+	title: 'Spawn a 3D avatar session',
+	description:
+		'Spawn a 3D avatar from a curated default (preset="default" or "cz") or from a custom GLB URL. Returns a sessionId other tools (dress_avatar, viewer_url, speak) reference, plus the avatar GLB URL and a ready-to-open three.ws viewer link.',
+	inputSchema: {
+		preset: z.enum(['default', 'cz']).optional()
+			.describe('Pick a curated default avatar.'),
+		glbUrl: z.string().url().optional()
+			.describe('Custom GLB URL — overrides preset.'),
+		name: z.string().max(80).optional()
+			.describe('Display name for the avatar persona.'),
+		voice: z
+			.enum(['alloy', 'ash', 'ballad', 'coral', 'echo', 'fable', 'nova', 'onyx', 'sage', 'shimmer', 'verse'])
+			.optional()
+			.describe('OpenAI TTS voice the speak tool should use for this session.'),
+		persona: z.string().max(500).optional()
+			.describe('Short persona/personality blurb (used by callers; not enforced server-side).'),
+	},
+	async handler(args) {
+		const { preset, glbUrl, name, voice, persona } = args || {};
+		if (!preset && !glbUrl) {
+			return {
+				ok: false,
+				error: 'invalid_input',
+				message: 'Provide either preset ("default" / "cz") or glbUrl.',
+			};
+		}
+		let glb;
+		if (glbUrl) {
+			glb = glbUrl;
+		} else {
+			const a = findAvatar(preset);
+			if (!a) {
+				return { ok: false, error: 'unknown_preset', message: `No default avatar named "${preset}". Call list_avatars.` };
+			}
+			glb = a.glb;
+		}
+		const session = createSession({ glb, name, voice, persona });
+		return {
+			ok: true,
+			sessionId: session.id,
+			avatar: session.avatar,
+			name: session.name,
+			voice: session.voice,
+			persona: session.persona,
+			pose: session.pose,
+			viewerUrl: viewerUrlFor(session),
+			createdAt: session.createdAt,
+		};
+	},
+};

package/src/tools/speak.js

@@ -0,0 +1,92 @@
+// `speak` — synthesize audio for the avatar via OpenAI's text-to-speech
+// API. Returns the audio as a base64 data URL by default so clients can
+// embed it directly. The avatar's voice (set when spawn_avatar runs) is
+// used unless explicitly overridden.
+//
+// Requires OPENAI_API_KEY in the MCP server's environment.
+
+import { z } from 'zod';
+
+import { OPENAI_API_KEY } from '../config.js';
+import { getSession, updateSession } from '../lib/avatars.js';
+
+const VOICES = ['alloy', 'ash', 'ballad', 'coral', 'echo', 'fable', 'nova', 'onyx', 'sage', 'shimmer', 'verse'];
+const MODELS = ['tts-1', 'tts-1-hd', 'gpt-4o-mini-tts'];
+const FORMATS = {
+	mp3: 'audio/mpeg',
+	opus: 'audio/ogg',
+	aac: 'audio/aac',
+	flac: 'audio/flac',
+	wav: 'audio/wav',
+	pcm: 'audio/pcm',
+};
+
+export const def = {
+	name: 'speak',
+	title: 'Avatar speaks (OpenAI TTS)',
+	description:
+		'Synthesize speech for an avatar session via OpenAI TTS and return a base64 audio data URL the client can play. Picks the session\'s configured voice unless overridden. Requires OPENAI_API_KEY on the MCP server.',
+	inputSchema: {
+		sessionId: z.string().optional()
+			.describe('Avatar session id (optional — when omitted, voice falls back to the override or "nova").'),
+		text: z.string().min(1).max(4096).describe('Text the avatar should say.'),
+		voice: z.enum(VOICES).optional().describe('Override the session voice for this call.'),
+		model: z.enum(MODELS).optional().describe('TTS model (default gpt-4o-mini-tts).'),
+		format: z.enum(Object.keys(FORMATS)).optional().describe('Audio format (default mp3).'),
+		speed: z.number().min(0.5).max(2.0).optional().describe('Playback speed multiplier.'),
+	},
+	async handler(args) {
+		if (!OPENAI_API_KEY) {
+			return {
+				ok: false,
+				error: 'not_configured',
+				message: 'OPENAI_API_KEY is not set on the MCP server. Set it to enable TTS.',
+			};
+		}
+		const { sessionId, text } = args || {};
+		const session = sessionId ? getSession(sessionId) : null;
+		if (sessionId && !session) {
+			return { ok: false, error: 'unknown_session', message: `No session ${sessionId}.` };
+		}
+		const voice = args.voice || session?.voice || 'nova';
+		const model = args.model || 'gpt-4o-mini-tts';
+		const format = args.format || 'mp3';
+		const speed = typeof args.speed === 'number' ? args.speed : 1.0;
+		const mime = FORMATS[format];
+
+		const t0 = Date.now();
+		const r = await fetch('https://api.openai.com/v1/audio/speech', {
+			method: 'POST',
+			headers: {
+				authorization: `Bearer ${OPENAI_API_KEY}`,
+				'content-type': 'application/json',
+			},
+			body: JSON.stringify({ input: text, voice, model, response_format: format, speed }),
+		});
+		if (!r.ok) {
+			const errText = await r.text().catch(() => '');
+			return {
+				ok: false,
+				error: 'tts_failed',
+				status: r.status,
+				message: errText.slice(0, 500),
+			};
+		}
+		const buf = Buffer.from(await r.arrayBuffer());
+		const base64 = buf.toString('base64');
+		const dataUrl = `data:${mime};base64,${base64}`;
+		if (session) updateSession(session.id, { lastSpoken: text.slice(0, 200) });
+		return {
+			ok: true,
+			sessionId: session?.id || null,
+			voice,
+			model,
+			format,
+			mime,
+			sizeBytes: buf.length,
+			durationMs: Date.now() - t0,
+			audio: dataUrl,
+			text,
+		};
+	},
+};

package/src/tools/thumbnail-glb.js

@@ -0,0 +1,35 @@
+// `thumbnail_glb` — render any public GLB URL to a PNG via three.ws's
+// hosted headless-chromium pipeline (the same three-light rig and
+// bounding-box framing that powers three.ws OG cards).
+//
+// Returns a base64 PNG data URL the client can display inline, plus
+// width/height and the upstream endpoint that produced it.
+//
+// This is the single most-requested capability for any 3D MCP — without
+// it the agent is "blind" to how a model actually looks.
+
+import { z } from 'zod';
+
+import { renderGlbThumbnail } from '../lib/render.js';
+
+export const def = {
+	name: 'thumbnail_glb',
+	title: 'Render a GLB to a PNG thumbnail',
+	description:
+		'Render any public GLB URL to a PNG via three.ws\'s hosted three-light rig + auto-framing camera. Returns the PNG inline as a base64 data URL (≤ ~4 MB) plus dimensions. Background defaults to #0a0a0a — pass "transparent" for compositing.',
+	inputSchema: {
+		glbUrl: z.string().url().describe('Public http(s) URL of a .glb file.'),
+		width: z.number().int().min(64).max(2048).optional().describe('Output width in pixels (default 1024).'),
+		height: z.number().int().min(64).max(2048).optional().describe('Output height in pixels (default 1024).'),
+		background: z.string().optional().describe('CSS color (e.g. "#0a0a0a") or "transparent". Default "#0a0a0a".'),
+	},
+	async handler(args) {
+		const { glbUrl, width, height, background } = args || {};
+		if (!glbUrl) return { ok: false, error: 'invalid_input', message: 'glbUrl is required' };
+		const out = await renderGlbThumbnail({ glbUrl, width, height, background });
+		return {
+			...out,
+			glbUrl,
+		};
+	},
+};

package/src/tools/validate-glb.js

@@ -0,0 +1,90 @@
+// `validate_glb` — run Khronos's official `gltf-validator` against any
+// GLB URL and surface its findings (errors, warnings, infos, hints) with
+// JSON-pointer locations and severity codes.
+//
+// This is the same validator the glTF Viewer (gltf.report) uses. It
+// checks the entire spec compliance surface: accessor bounds, animation
+// channel targets, image data integrity, extension usage, etc.
+
+import { z } from 'zod';
+import validator from 'gltf-validator';
+
+import { fetchGlbBytes } from '../lib/glb-io.js';
+
+const SEVERITIES = ['error', 'warning', 'info', 'hint'];
+
+function classify(messages = []) {
+	const buckets = { error: [], warning: [], info: [], hint: [] };
+	for (const m of messages) {
+		const sev = SEVERITIES[m.severity] || 'info';
+		buckets[sev].push({
+			code: m.code,
+			message: m.message,
+			pointer: m.pointer || null,
+			offset: m.offset ?? null,
+		});
+	}
+	return buckets;
+}
+
+export const def = {
+	name: 'validate_glb',
+	title: 'Validate a GLB / glTF against the Khronos spec',
+	description:
+		'Run the official Khronos gltf-validator against a GLB URL. Returns errors, warnings, infos, and hints with codes + JSON pointers, plus structural counts (animations, materials, etc.) per the validator\'s info report. The same engine that powers gltf.report.',
+	inputSchema: {
+		url: z.string().describe('Public URL or data: URL of a .glb / .gltf file to validate.'),
+		maxIssues: z.number().int().min(1).max(2000).optional()
+			.describe('Cap on issues returned in each bucket (default 100). Validator may still scan all of them.'),
+	},
+	async handler(args) {
+		const { url } = args || {};
+		if (!url) return { ok: false, error: 'invalid_input', message: 'url is required' };
+		const cap = args?.maxIssues || 100;
+		let bytes;
+		try {
+			bytes = await fetchGlbBytes(url);
+		} catch (err) {
+			return { ok: false, error: 'fetch_failed', message: err.message };
+		}
+
+		let report;
+		try {
+			report = await validator.validateBytes(new Uint8Array(bytes), {
+				uri: url,
+				maxIssues: 2000,
+				externalResourceFunction: async (resourceUri) => {
+					// Fetch buffer/image references that live outside the GLB (rare
+					// for .glb because everything's embedded, but supported here
+					// for .gltf inputs).
+					const r = await fetch(resourceUri);
+					if (!r.ok) throw new Error(`external resource HTTP ${r.status}: ${resourceUri}`);
+					return new Uint8Array(await r.arrayBuffer());
+				},
+			});
+		} catch (err) {
+			return { ok: false, error: 'validator_failed', message: err.message };
+		}
+
+		const buckets = classify(report.issues?.messages || []);
+		for (const k of SEVERITIES) buckets[k] = buckets[k].slice(0, cap);
+
+		return {
+			ok: true,
+			url,
+			sizeBytes: bytes.byteLength,
+			validatorVersion: report.validatorVersion || null,
+			mimeType: report.mimeType || null,
+			validated: report.validatedAt || new Date().toISOString(),
+			summary: {
+				numErrors: report.issues?.numErrors ?? 0,
+				numWarnings: report.issues?.numWarnings ?? 0,
+				numInfos: report.issues?.numInfos ?? 0,
+				numHints: report.issues?.numHints ?? 0,
+				truncated: !!report.issues?.truncated,
+			},
+			info: report.info || null,
+			issues: buckets,
+		};
+	},
+};

package/src/tools/viewer-url.js

@@ -0,0 +1,124 @@
+// `viewer_url` — build a shareable three.ws viewer URL for any GLB plus
+// optional embed snippet. Exposes the full set of viewer query params
+// the three.ws web viewer respects: background, auto-rotate, camera
+// preset OR explicit orbit string, AR mode, dimensions, pose, and
+// accessory overlays.
+//
+// Supports an avatar sessionId (uses the session's GLB + accessories +
+// pose as defaults) or a raw GLB URL. No fetch — pure URL composition
+// plus an iframe snippet for sites that want to embed.
+
+import { z } from 'zod';
+
+import { VIEWER_BASE, THREE_WS_BASE } from '../config.js';
+import { findAccessory, getSession } from '../lib/avatars.js';
+
+function escAttr(s) {
+	return String(s).replace(/&/g, '&').replace(/"/g, '"');
+}
+
+export const def = {
+	name: 'viewer_url',
+	title: 'Build a three.ws viewer URL + embed snippet',
+	description:
+		'Build a shareable https://three.ws/viewer?... URL that opens any GLB in three.ws\'s WebGL viewer, plus a ready-to-paste iframe snippet. Supports background, auto-rotate, camera preset OR explicit camera orbit, AR mode (model-viewer), dimensions, pose, and accessory overlay. Accepts a raw glbUrl or a sessionId from spawn_avatar.',
+	inputSchema: {
+		glbUrl: z.string().url().optional().describe('Direct GLB URL. Required if sessionId is omitted.'),
+		sessionId: z.string().optional().describe('Avatar sessionId returned by spawn_avatar. Overrides glbUrl.'),
+		pose: z.string().optional().describe('Pose preset id (e.g. "wave", "tpose"). Call list_animations for the catalog.'),
+		accessoryIds: z.array(z.string()).optional().describe('Accessory ids to attach in the viewer.'),
+		background: z.string().optional()
+			.describe('Background color or gradient (CSS), e.g. "#0a0a0a", "linear-gradient(...)", or "transparent".'),
+		autoRotate: z.boolean().optional().describe('Auto-rotate the model. Default true on the web viewer.'),
+		ar: z.boolean().optional().describe('Enable model-viewer AR buttons on iOS/Android.'),
+		cameraPreset: z.enum(['front', 'three-quarter', 'side', 'back', 'top', 'closeup']).optional()
+			.describe('Named camera framing preset.'),
+		cameraOrbit: z.string().optional()
+			.describe('Explicit camera orbit in model-viewer syntax, e.g. "0deg 80deg 2m". Overrides cameraPreset.'),
+		cameraDistance: z.number().positive().optional().describe('Distance multiplier shorthand (1.0 = default). Used when cameraOrbit is absent.'),
+		cameraAngleDeg: z.number().optional().describe('Yaw in degrees shorthand. Used when cameraOrbit is absent.'),
+		width: z.number().int().min(64).max(4096).optional().describe('Viewer width in pixels (for the iframe snippet).'),
+		height: z.number().int().min(64).max(4096).optional().describe('Viewer height in pixels.'),
+		thumbnailUrl: z.string().url().optional().describe('Optional thumbnail to show in the iframe before the GLB loads.'),
+	},
+	async handler(args) {
+		const {
+			sessionId, glbUrl, pose, accessoryIds, background, autoRotate, ar,
+			cameraPreset, cameraOrbit, cameraDistance, cameraAngleDeg,
+			width, height, thumbnailUrl,
+		} = args || {};
+
+		let resolvedGlb = glbUrl;
+		let resolvedAccessories = accessoryIds;
+		let resolvedPose = pose;
+		let session = null;
+		if (sessionId) {
+			session = getSession(sessionId);
+			if (!session) return { ok: false, error: 'unknown_session', message: `No session ${sessionId}.` };
+			resolvedGlb = session.avatar.glb;
+			if (!resolvedAccessories) resolvedAccessories = session.accessories.map((a) => a.id);
+			if (!resolvedPose) resolvedPose = session.pose;
+		}
+		if (!resolvedGlb) return { ok: false, error: 'invalid_input', message: 'Pass glbUrl or sessionId.' };
+
+		const params = new URLSearchParams({ src: resolvedGlb });
+
+		// Accessories — dedup + verify against the catalog.
+		if (Array.isArray(resolvedAccessories) && resolvedAccessories.length) {
+			const seen = new Set();
+			const verified = [];
+			for (const id of resolvedAccessories) {
+				if (seen.has(id)) continue;
+				seen.add(id);
+				const acc = findAccessory(id);
+				verified.push(acc ? acc.id : id);
+			}
+			params.set('accessories', verified.join(','));
+		}
+		if (resolvedPose && resolvedPose !== 'idle') params.set('pose', resolvedPose);
+
+		// Camera — explicit orbit wins; fallback to preset; fallback to
+		// the dist/yaw shorthand for backward compatibility.
+		if (cameraOrbit) {
+			params.set('camera', cameraOrbit);
+		} else if (cameraPreset) {
+			params.set('camera', cameraPreset);
+		} else {
+			if (typeof cameraDistance === 'number') params.set('camDist', String(cameraDistance));
+			if (typeof cameraAngleDeg === 'number') params.set('camYaw', String(cameraAngleDeg));
+		}
+
+		if (background) params.set('background', background);
+		if (autoRotate === false) params.set('auto_rotate', '0');
+		if (autoRotate === true) params.set('auto_rotate', '1');
+		if (ar) params.set('ar', '1');
+		if (width) params.set('width', String(width));
+		if (height) params.set('height', String(height));
+
+		const viewerUrl = `${VIEWER_BASE}?${params.toString()}`;
+		const iframeWidth = width || 800;
+		const iframeHeight = height || 800;
+		const iframeSnippet =
+			`<iframe src="${escAttr(viewerUrl)}" width="${iframeWidth}" height="${iframeHeight}" ` +
+			`style="border:0;border-radius:12px;background:#0a0a0a" allowfullscreen ` +
+			`allow="autoplay;fullscreen;xr-spatial-tracking" loading="lazy"></iframe>`;
+
+		return {
+			ok: true,
+			viewerUrl,
+			iframeSnippet,
+			glb: resolvedGlb,
+			sessionId: session?.id || null,
+			pose: resolvedPose || null,
+			accessories: Array.isArray(resolvedAccessories) ? resolvedAccessories : null,
+			cameraOrbit: cameraOrbit || (cameraPreset ? `preset:${cameraPreset}` : null),
+			background: background || null,
+			ar: !!ar,
+			thumbnailUrl: thumbnailUrl || null,
+			openGraph: {
+				image: `${THREE_WS_BASE}/api/avatar-og?src=${encodeURIComponent(resolvedGlb)}`,
+				url: viewerUrl,
+			},
+		};
+	},
+};

package/src/tools/wallet-balance.js

@@ -0,0 +1,36 @@
+// `wallet_balance` — read SOL balance and all SPL token balances (both
+// classic SPL + Token-2022) for any Solana pubkey. Read-only, no signer.
+
+import { z } from 'zod';
+
+import { getBalanceSol, getTokenBalances, isValidPubkey } from '../lib/solana.js';
+import { SOLANA_RPC_URL } from '../config.js';
+
+export const def = {
+	name: 'wallet_balance',
+	title: 'Read Solana wallet balances (SOL + SPL tokens)',
+	description:
+		'Return SOL balance and all SPL token balances (including Token-2022) for a Solana pubkey. Uses the configured SOLANA_RPC_URL. Read-only — no signer required.',
+	inputSchema: {
+		pubkey: z.string().min(32).max(64).describe('Base58 Solana pubkey to read.'),
+		includeTokens: z.boolean().optional().describe('Include SPL token accounts (default true).'),
+	},
+	async handler(args) {
+		const { pubkey, includeTokens = true } = args || {};
+		if (!isValidPubkey(pubkey)) {
+			return { ok: false, error: 'invalid_pubkey' };
+		}
+		const sol = await getBalanceSol(pubkey);
+		const tokens = includeTokens ? await getTokenBalances(pubkey) : null;
+		return {
+			ok: true,
+			pubkey,
+			sol: sol.sol,
+			lamports: sol.lamports,
+			tokens,
+			rpc: SOLANA_RPC_URL,
+			explorer: `https://solscan.io/account/${pubkey}`,
+			fetchedAt: new Date().toISOString(),
+		};
+	},
+};

package/src/tools/wallet-create.js

@@ -0,0 +1,67 @@
+// `wallet_create` — generate a fresh Solana keypair locally and (optionally)
+// attach it to an avatar session. With `vanityPrefix` / `vanitySuffix` the
+// tool grinds keys until the base58 pubkey matches — useful for spawning a
+// "three…" or "…wsai" themed wallet on the fly.
+//
+// The secret is returned base58-encoded ONCE. The MCP server does not
+// persist it. The caller is responsible for storing it safely.
+
+import { Keypair } from '@solana/web3.js';
+import { z } from 'zod';
+
+import { bs58encode, grindVanity } from '../lib/solana.js';
+import { getSession, updateSession } from '../lib/avatars.js';
+
+export const def = {
+	name: 'wallet_create',
+	title: 'Create a Solana wallet (optionally vanity-grinded)',
+	description:
+		'Generate a Solana keypair locally. Optionally grind for a base58 prefix/suffix (e.g. "three") and/or attach it to an avatar session. Returns the base58 pubkey and secret ONCE — store the secret yourself; the MCP does not persist it.',
+	inputSchema: {
+		sessionId: z.string().optional().describe('If set, the wallet is attached to this avatar session.'),
+		vanityPrefix: z.string().max(8).optional().describe('Base58 prefix to grind for (e.g. "three"). Up to 8 chars.'),
+		vanitySuffix: z.string().max(8).optional().describe('Base58 suffix to grind for. Up to 8 chars.'),
+		caseSensitive: z.boolean().optional().describe('Match case-sensitively (default true). Base58 has no 0OIl so set false to be permissive.'),
+		maxAttempts: z.number().int().min(1).max(2_000_000).optional()
+			.describe('Cap on grind attempts (default 500_000). Bump for longer prefixes.'),
+	},
+	async handler(args) {
+		const { sessionId, vanityPrefix, vanitySuffix, caseSensitive = true, maxAttempts } = args || {};
+
+		let pubkey;
+		let secret;
+		let grind = null;
+		if (vanityPrefix || vanitySuffix) {
+			grind = grindVanity({ prefix: vanityPrefix, suffix: vanitySuffix, caseSensitive, maxAttempts: maxAttempts || 500_000 });
+			if (!grind.found) {
+				return { ok: false, error: 'vanity_not_found', ...grind };
+			}
+			pubkey = grind.pubkey;
+			secret = grind.secret;
+		} else {
+			const kp = Keypair.generate();
+			pubkey = kp.publicKey.toBase58();
+			secret = bs58encode(kp.secretKey);
+		}
+
+		let session = null;
+		if (sessionId) {
+			session = getSession(sessionId);
+			if (!session) {
+				return { ok: false, error: 'unknown_session', message: `No session ${sessionId}.` };
+			}
+			updateSession(sessionId, { wallet: { pubkey, hasSecret: true } });
+		}
+
+		return {
+			ok: true,
+			pubkey,
+			secret,
+			warning:
+				'This secret is shown ONCE. The MCP server does not persist it. Store it in a password manager or hardware wallet; treat it like cash.',
+			sessionId: session?.id || null,
+			vanity: grind ? { attempts: grind.attempts, durationMs: grind.durationMs } : null,
+			explorer: `https://solscan.io/account/${pubkey}`,
+		};
+	},
+};

package/src/tools/wallet-send.js

@@ -0,0 +1,35 @@
+// `wallet_send` — send SOL from a signer to a destination pubkey. The
+// signer comes from the `secret` arg (preferred) or from SOLANA_SECRET_KEY
+// in the MCP server environment. Returns the on-chain signature and a
+// Solscan link once confirmed.
+
+import { z } from 'zod';
+
+import { sendSol } from '../lib/solana.js';
+
+export const def = {
+	name: 'wallet_send',
+	title: 'Send SOL on Solana mainnet',
+	description:
+		'Send SOL from the configured signer to a destination pubkey. The signer is supplied via the `secret` arg (base58) or via SOLANA_SECRET_KEY env on the MCP server. Returns the confirmed signature and a Solscan link. EXECUTION ACTION — funds move on mainnet.',
+	inputSchema: {
+		to: z.string().min(32).max(64).describe('Destination Solana pubkey.'),
+		sol: z.number().positive().describe('Amount of SOL to send.'),
+		secret: z.string().optional().describe('Base58 secret of the sender. Falls back to SOLANA_SECRET_KEY env.'),
+		priorityMicroLamports: z.number().int().min(0).max(10_000_000).optional()
+			.describe('Compute-unit price (default 100000).'),
+	},
+	async handler(args) {
+		try {
+			const out = await sendSol({
+				secret: args.secret,
+				to: args.to,
+				sol: args.sol,
+				priorityMicroLamports: args.priorityMicroLamports,
+			});
+			return { ok: true, ...out };
+		} catch (err) {
+			return { ok: false, error: err.code || 'send_failed', message: err.message, signature: err.signature || null };
+		}
+	},
+};