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
import { mintTokenized3dAsset, readTokenized3dAsset, TOKENIZE_3D_ROYALTY_CAP_BPS } from '../../_lib/tokenize-3d.js';
import { priceFor } from '../../_lib/pump-pricing.js';
import { limits } from '../../_lib/rate-limit.js';
// A handled boundary error carries a status + code; surface it as a clean MCP
// tool error (isError) rather than letting an unexpected 500 bubble.
function isHandled(err) {
return err && typeof err.code === 'string' && Number.isInteger(err.status);
}
function toolError(message) {
return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
}
// A mint nobody paid for per call still costs the platform authority its rent
// and fee, so those callers get a small budget per account (or payer).
export async function unpaidMintLimited(network, auth) {
const limiter = network === 'mainnet' ? limits.mcpMint3dUnpaidMainnet : limits.mcpMint3dUnpaidDevnet;
const rl = await limiter(String(auth?.userId || auth?.payer || auth?.rateKey || 'anon'));
if (rl.success) return null;
const retryAfter = Math.max(1, Math.ceil((rl.reset - Date.now()) / 1000));
return {
...toolError(
`Mint limit reached for this account on ${network === 'mainnet' ? 'mainnet' : 'devnet'}. ` +
`Retry in ${retryAfter}s, or pay per mint over x402 to mint without this limit.`,
),
structuredContent: { ok: false, reason: 'rate_limited', retry_after: retryAfter },
};
}
export const toolDefs = [
{
name: 'mint_3d_asset',
scope: 'avatars:write',
title: 'Mint a 3D asset as a Solana NFT',
// Creates an on-chain Core NFT. Not destructive (it mints, never deletes),
// and idempotent: the claim-first guard means repeating a call with the
// same arguments returns the same mint instead of minting twice. Open-world
// (writes to the Solana network). destructiveHint is explicit (spec defaults
// it to true when omitted).
annotations: {
readOnlyHint: false,
destructiveHint: false,
idempotentHint: true,
openWorldHint: true,
},
description:
'Mint a generated or owned GLB as a Metaplex Core NFT on Solana whose media is a ' +
'LIVE, interactive 3D viewer (the rigged glTF model under animation_url, not a static ' +
'image). Bakes provenance (creator, prompt, generation model, parent lineage, timestamp) ' +
'into the metadata AND appends a signed, independently-verifiable record to the ' +
'agent_actions provenance ledger; enforces capped creator royalties on secondary sales. ' +
'Supply an owned avatar_id or a glb_url, and a recipient (owner_wallet, or your OAuth-linked ' +
'Solana wallet). Devnet by default; pass network="mainnet" for a real mainnet mint. Idempotent ' +
'(a repeat call for the same asset returns the same mint). Royalty is capped at ' +
`${TOKENIZE_3D_ROYALTY_CAP_BPS / 100}%. Naming parent_mint (a remix/derivative on mainnet) ` +
"routes the parent creator's royalty slice out of THIS mint's fee as a real on-chain USDC " +
'transfer. Returns the mint address, explorer + viewer links, royalty terms, the provenance ' +
'ledger reference, and (for a remix) the royalty settlement. Priced per call via x402 (USDC); ' +
'an OAuth bearer token bypasses payment within a small per-account mint budget (5 mainnet mints a day). ' +
'Use this when the user wants a model to exist as an ownable, tradable on-chain asset; to read one back call get_3d_asset_onchain.',
inputSchema: {
type: 'object',
properties: {
avatar_id: {
type: 'string',
format: 'uuid',
description: 'An owned avatar to tokenize (its GLB becomes the NFT media).',
},
glb_url: {
type: 'string',
format: 'uri',
description: 'Or a GLB URL to tokenize (absolute http(s)).',
},
owner_wallet: {
type: 'string',
description:
'Recipient Solana wallet (base58). Defaults to your OAuth-linked wallet when omitted.',
},
name: { type: 'string', maxLength: 200, description: 'Display name for the NFT.' },
description: { type: 'string', maxLength: 2000 },
network: {
type: 'string',
enum: ['devnet', 'mainnet'],
default: 'devnet',
description: 'Cluster to mint on. Devnet by default; mainnet is a real mint.',
},
seller_fee_basis_points: {
type: 'integer',
minimum: 0,
maximum: TOKENIZE_3D_ROYALTY_CAP_BPS,
description: `Enforced secondary-sale royalty in basis points. Clamped to the ${TOKENIZE_3D_ROYALTY_CAP_BPS / 100}% hard cap.`,
},
royalty_recipient: {
type: 'string',
description: 'Wallet the royalty routes to (base58). Defaults to the owner.',
},
parent_mint: {
type: 'string',
description: 'Lineage: the asset this was remixed from (baked into provenance).',
},
prompt: { type: 'string', maxLength: 1000, description: 'Generation prompt (provenance).' },
generation_model: { type: 'string', maxLength: 96 },
generation_provider: { type: 'string', maxLength: 64 },
idempotency_key: {
type: 'string',
maxLength: 128,
description: 'Override the derived idempotency key to force-dedupe a specific request.',
},
},
additionalProperties: false,
},
async handler(args, auth) {
try {
// The remix-royalty split (task 4) must only ever split a fee that was
// ACTUALLY collected for this exact call: a genuine per-call x402
// settlement (auth.x402Paid), never a subscription window or an OAuth
// bypass (both real access, but no fresh fee here to split).
const paidPerCall = auth?.source === 'x402' && Boolean(auth?.x402Paid);
const mintFeeAtomicsCollected = paidPerCall
? BigInt(Math.round((priceFor('mint_3d_asset')?.amount_usdc || 0) * 1_000_000))
: 0n;
if (!paidPerCall) {
const limited = await unpaidMintLimited(args.network, auth);
if (limited) return limited;
}
const result = await mintTokenized3dAsset({
avatarId: args.avatar_id,
glbUrl: args.glb_url,
ownerWallet: args.owner_wallet,
requesterId: auth?.userId ?? null,
name: args.name,
description: args.description,
network: args.network || 'devnet',
sellerFeeBasisPoints: args.seller_fee_basis_points,
royaltyRecipient: args.royalty_recipient,
parentMint: args.parent_mint,
prompt: args.prompt,
generationModel: args.generation_model,
generationProvider: args.generation_provider,
idempotencyKey: args.idempotency_key,
mintFeeAtomicsCollected,
// The royalty is paid from the treasury, so it waits for the x402
// settlement that api/mcp.js performs after this handler returns.
deferRoyalty: paidPerCall
? (run) => { (auth.afterSettle ??= []).push(run); }
: undefined,
});
const text =
result.status === 'minted'
? `${result.idempotent ? 'Already minted' : 'Minted'} "${result.name}" on ${result.network}.\n` +
`Mint: ${result.mint}\n` +
`Explorer: ${result.explorer_asset_url}\n` +
(result.explorer_tx_url ? `Tx: ${result.explorer_tx_url}\n` : '') +
`Viewer: ${result.viewer_url}\n` +
`Royalty: ${result.royalty.percent}% (cap ${result.royalty.cap_basis_points / 100}%)` +
(result.royalty.capped ? ` (requested ${result.royalty.requested_basis_points / 100}%, clamped)` : '') +
(result.provenance_ledger
? `\nProvenance: ledger action #${result.provenance_ledger.action_id} (${result.provenance_ledger.signed ? 'signed' : 'unsigned'})`
: '') +
(result.remix_royalty
? result.remix_royalty.paid
? `\nRemix royalty: ${result.remix_royalty.creator_usd} USDC paid to the source creator (${result.remix_royalty.creator_tx})`
: result.remix_royalty.reason === 'pending_payment_settlement'
? '\nRemix royalty: paid to the source creator once your payment settles'
: `\nRemix royalty: not paid (${result.remix_royalty.reason})`
: '')
: `Mint in progress for this asset. Read it back with get_3d_asset_onchain once it confirms.`;
return { content: [{ type: 'text', text }], structuredContent: result };
} catch (err) {
if (isHandled(err)) return toolError(err.message);
throw err;
}
},
},
{
name: 'get_3d_asset_onchain',
title: 'Resolve a 3D NFT to its live asset + provenance',
// A read over live on-chain state: the holder can change between calls, so
// not idempotent. Open-world (reads the Solana network).
annotations: {
readOnlyHint: true,
destructiveHint: false,
idempotentHint: false,
openWorldHint: true,
},
description:
'Resolve a Solana mint address to its live 3D asset: current holder, the interactive ' +
'viewer link + GLB (confirmed live), baked provenance (creator, prompt, model, lineage, ' +
'timestamp), and the enforced on-chain royalty terms. Works on any Metaplex Core mint. ' +
'Assets minted through three.ws also return their platform launch record. Read-only, public. ' +
'Use this to check who holds a 3D NFT and what its provenance and royalty terms are.',
inputSchema: {
type: 'object',
properties: {
mint: { type: 'string', description: 'The Metaplex Core asset (mint) pubkey, base58.' },
network: {
type: 'string',
enum: ['devnet', 'mainnet'],
default: 'devnet',
description: 'Cluster to read (ignored if the mint is in our launch records).',
},
},
required: ['mint'],
additionalProperties: false,
},
async handler(args) {
try {
const data = await readTokenized3dAsset({ mint: args.mint, network: args.network || 'devnet' });
return {
content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
structuredContent: data,
};
} catch (err) {
if (isHandled(err)) return toolError(err.message);
throw err;
}
},
},
];