Skip to content

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.

9.3 KB
Raw Blame
import { limits } from '../../_lib/rate-limit.js';
import { fetchModel, FetchModelError } from '../../_lib/fetch-model.js';
import { inspectModel, suggestOptimizations } from '../../_lib/model-inspect.js';
import { describeModel, diffDescriptions, formatText } from '@three-ws/glb-diff';
import { validateBytes } from 'gltf-validator';

function rpcError(code, message, data) {
	const e = new Error(message);
	e.code = code;
	e.data = data;
	return e;
}

async function safeFetchModel(url) {
	try {
		return await fetchModel(url);
	} catch (e) {
		if (e instanceof FetchModelError) throw new Error(`fetch failed: ${e.message} (${e.code})`);
		throw e;
	}
}

// MCP tool annotations (2025-06-18 spec): all three tools are deterministic,
// pure inspections of a caller-supplied URL: same file, same report.
// destructiveHint defaults to TRUE when omitted, so it is set explicitly.
const INSPECTION_ANNOTATIONS = {
	readOnlyHint: true,
	destructiveHint: false,
	idempotentHint: true,
	openWorldHint: true,
};

function formatValidationSummary(s, messages) {
	const head =
		`glTF-Validator report for ${s.filename} (${(s.fileSize / 1024).toFixed(1)} KB)\n` +
		`Errors: ${s.numErrors}, Warnings: ${s.numWarnings}, Infos: ${s.numInfos}, Hints: ${s.numHints}` +
		(s.truncated ? ' (truncated)' : '');
	if (!messages.length) return head;
	const lines = messages.slice(0, 40).map((m) => {
		const sev = ['ERR', 'WRN', 'INF', 'HNT'][m.severity] || '?';
		const ptr = m.pointer ? ` @ ${m.pointer}` : '';
		return `  [${sev}] ${m.code}: ${m.message}${ptr}`;
	});
	const more = messages.length > 40 ? `\n  … ${messages.length - 40} more` : '';
	return `${head}\n${lines.join('\n')}${more}`;
}

function formatInspection(info) {
	const c = info.counts;
	const tex = info.textures.length
		? info.textures
				.map(
					(t) =>
						`  • ${t.name || '(unnamed)'}: ${t.mimeType} ${t.width}×${t.height}, ${(t.byteSize / 1024).toFixed(1)} KB`,
				)
				.join('\n')
		: '  (none)';
	return [
		`Model: ${info.filename} (${(info.fileSize / 1024 / 1024).toFixed(2)} MB, ${info.container})`,
		`Generator: ${info.generator || 'unknown'} · glTF ${info.version || '?'}`,
		`Scenes: ${c.scenes}, Nodes: ${c.nodes}, Meshes: ${c.meshes}, Materials: ${c.materials}, Textures: ${c.textures}`,
		`Animations: ${c.animations}, Skins: ${c.skins}`,
		`Vertices: ${c.totalVertices.toLocaleString()}, Triangles: ${c.totalTriangles.toLocaleString()}`,
		`Indexed primitives: ${c.indexedPrimitives}, Non-indexed: ${c.nonIndexedPrimitives}`,
		`Extensions used: ${info.extensionsUsed.join(', ') || '(none)'}`,
		`Textures:\n${tex}`,
	].join('\n');
}

function formatSuggestions(suggestions) {
	if (!suggestions.length) return 'No suggestions.';
	return suggestions
		.map((s) => {
			const tag =
				{ info: 'INFO', warn: 'WARN', critical: 'CRIT' }[s.severity] ||
				s.severity.toUpperCase();
			const est = s.estimate ? ` (${s.estimate})` : '';
			return `[${tag}] ${s.id}: ${s.message}${est}`;
		})
		.join('\n');
}

export const toolDefs = [
	{
		name: 'validate_model',
		title: 'Validate glTF/GLB model',
		annotations: INSPECTION_ANNOTATIONS,
		description:
			'Run the Khronos glTF-Validator against a remote GLB or glTF URL. Returns a structured report of errors, warnings, infos, and hints: the authoritative answer to "is this file spec-compliant?". SSRF-hardened: only public https URLs are fetched. Use this before shipping, minting, or embedding a model to catch spec errors; for size and structure stats call inspect_model.',
		inputSchema: {
			type: 'object',
			properties: {
				url: {
					type: 'string',
					format: 'uri',
					description: 'Public https URL of a .glb or .gltf file.',
				},
				max_issues: { type: 'integer', minimum: 1, maximum: 500, default: 100 },
			},
			required: ['url'],
			additionalProperties: false,
		},
		async handler(args, auth) {
			const rl = await limits.mcpValidate(auth.userId || auth.rateKey);
			if (!rl.success)
				throw rpcError(-32000, 'rate_limited', {
					retry_after: Math.ceil((rl.reset - Date.now()) / 1000),
				});
			const { bytes, url, filename } = await safeFetchModel(args.url);
			const max = Math.min(Math.max(args.max_issues || 100, 1), 500);
			const report = await validateBytes(bytes, { maxIssues: max, uri: filename });
			const issues = report?.issues || {};
			const summary = {
				url,
				filename,
				fileSize: bytes.byteLength,
				validatorVersion: report?.validatorVersion,
				mimeType: report?.mimeType,
				numErrors: issues.numErrors ?? 0,
				numWarnings: issues.numWarnings ?? 0,
				numInfos: issues.numInfos ?? 0,
				numHints: issues.numHints ?? 0,
				truncated: !!issues.truncated,
			};
			return {
				content: [
					{ type: 'text', text: formatValidationSummary(summary, issues.messages || []) },
				],
				structuredContent: {
					...summary,
					messages: issues.messages || [],
					info: report?.info || null,
				},
			};
		},
	},
	{
		name: 'inspect_model',
		title: 'Inspect glTF/GLB model',
		annotations: INSPECTION_ANNOTATIONS,
		description:
			'Parse a remote GLB or glTF and return structural stats: scene/node/mesh counts, vertex and triangle totals, material and texture summaries, extensions used. Pure inspection, no optimization advice. Use this to learn what a model contains; for ways to make it smaller call optimize_model, and for spec errors call validate_model.',
		inputSchema: {
			type: 'object',
			properties: {
				url: {
					type: 'string',
					format: 'uri',
					description: 'Public https URL of a .glb or .gltf file.',
				},
			},
			required: ['url'],
			additionalProperties: false,
		},
		async handler(args, auth) {
			const rl = await limits.mcpInspect(auth.userId || auth.rateKey);
			if (!rl.success)
				throw rpcError(-32000, 'rate_limited', {
					retry_after: Math.ceil((rl.reset - Date.now()) / 1000),
				});
			const { bytes, url, filename } = await safeFetchModel(args.url);
			const info = await inspectModel(bytes, { fileSize: bytes.byteLength });
			return {
				content: [{ type: 'text', text: formatInspection({ url, filename, ...info }) }],
				structuredContent: { url, filename, ...info },
			};
		},
	},
	{
		name: 'optimize_model',
		title: 'Suggest optimizations for a glTF/GLB model',
		annotations: INSPECTION_ANNOTATIONS,
		description:
			'Inspect the model and return actionable suggestions for reducing size and draw-call overhead: triangle budget, Draco/Meshopt compression, oversized textures, KTX2 transcoding, non-indexed primitives, redundant materials, and more. Use this when a model is too heavy to load quickly on the web or on mobile; for raw counts without advice call inspect_model.',
		inputSchema: {
			type: 'object',
			properties: {
				url: {
					type: 'string',
					format: 'uri',
					description: 'Public https URL of a .glb or .gltf file.',
				},
			},
			required: ['url'],
			additionalProperties: false,
		},
		async handler(args, auth) {
			const rl = await limits.mcpOptimize(auth.userId || auth.rateKey);
			if (!rl.success)
				throw rpcError(-32000, 'rate_limited', {
					retry_after: Math.ceil((rl.reset - Date.now()) / 1000),
				});
			const { bytes, url, filename } = await safeFetchModel(args.url);
			const info = await inspectModel(bytes, { fileSize: bytes.byteLength });
			const suggestions = suggestOptimizations(info);
			return {
				content: [{ type: 'text', text: formatSuggestions(suggestions) }],
				structuredContent: { url, filename, suggestions, info },
			};
		},
	},
	{
		name: 'diff_models',
		title: 'Diff two glTF/GLB models',
		annotations: INSPECTION_ANNOTATIONS,
		description:
			'Compare two remote GLB or glTF models and return what changed: geometry, hierarchy, materials, textures, skeletons, and animation clips, each classified as added, removed, renamed, moved, or modified, with renames detected by content hash rather than by name. Every change carries a severity (none, cosmetic, minor, major, breaking) so an agent can decide whether an optimized, rigged, or re-exported model is still safe to ship. Breaking means something a consumer references by name is gone: a clip, a joint, a mesh. Use this after optimizing, rigging, or re-exporting a model to confirm the new version is still safe wherever the old one was used.',
		inputSchema: {
			type: 'object',
			properties: {
				before: {
					type: 'string',
					format: 'uri',
					description: 'Public https URL of the baseline .glb or .gltf file.',
				},
				after: {
					type: 'string',
					format: 'uri',
					description: 'Public https URL of the candidate .glb or .gltf file.',
				},
			},
			required: ['before', 'after'],
			additionalProperties: false,
		},
		async handler(args, auth) {
			const rl = await limits.mcpDiff(auth.userId || auth.rateKey);
			if (!rl.success)
				throw rpcError(-32000, 'rate_limited', {
					retry_after: Math.ceil((rl.reset - Date.now()) / 1000),
				});
			// Sequential, so a caller who passed one bad URL learns which one
			// without the server having spent a second full download first.
			const a = await safeFetchModel(args.before);
			const b = await safeFetchModel(args.after);
			const [beforeDesc, afterDesc] = await Promise.all([
				describeModel(a.bytes, { name: a.filename }),
				describeModel(b.bytes, { name: b.filename }),
			]);
			const changeset = diffDescriptions(beforeDesc, afterDesc);
			return {
				content: [{ type: 'text', text: formatText(changeset, { color: false }) }],
				structuredContent: { before: a.url, after: b.url, ...changeset },
			};
		},
	},
];