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
fix(metaplex-mcp): give the mint preview no code path to broadcast, and record the reviewed safety exemptions
nirholas31e486802eaa
diff --git a/packages/metaplex-agent-mcp/src/tools/mint-onchain-agent.js b/packages/metaplex-agent-mcp/src/tools/mint-onchain-agent.jsindex 73db3bc1b..d0237ff63 100644--- a/packages/metaplex-agent-mcp/src/tools/mint-onchain-agent.js+++ b/packages/metaplex-agent-mcp/src/tools/mint-onchain-agent.js@@ -55,7 +55,7 @@ export const def = {secret: z.string().optional().describe('Per-call signing key (base58 secret key or JSON byte array). Overrides SOLANA_SECRET_KEY.'),confirm: z.boolean().optional().describe('Must be true to broadcast. Anything else returns a spend-nothing preview.'),},- handler: (args) => runMint(args, { preview: REQUIRE_CONFIRM && args.confirm !== true }),+ handler: (args) => (REQUIRE_CONFIRM && args.confirm !== true ? previewMint(args) : sendMint(args)),};/**@@ -76,68 +76,82 @@ export const previewDef = {...mintShape,secret: z.string().optional().describe('Per-call signing key (base58 secret key or JSON byte array). Only its public key is read.'),},- handler: (args) => runMint(args, { preview: true }),+ handler: (args) => previewMint(args),};-async function runMint(args, { preview }) {- const network = args.network || NETWORK;- const umi = buildUmi({ network, secret: args.secret, requireSigner: true });- const wallet = umi.identity.publicKey.toString();+/**+ * Everything both paths share: the signer's wallet, the resolved deploy fee and+ * the built (never signed, never sent) mint. buildAgentMint only appends+ * instructions to umi builders, so nothing here touches the chain beyond reads.+ */+async function planMint(args) {+ const network = args.network || NETWORK;+ const umi = buildUmi({ network, secret: args.secret, requireSigner: true });+ const wallet = umi.identity.publicKey.toString();+ const fee = await resolveDeployFee(umi, { network, payer: wallet });+ const mint = buildAgentMint(+ umi,+ mintParams(args, { network, creator: wallet, feeLamports: fee.lamports, feeWallet: fee.wallet }),+ );+ return { network, umi, wallet, fee, mint, total: EST_NETWORK_SOL + fee.sol };+}- const fee = await resolveDeployFee(umi, { network, payer: wallet });- const total = EST_NETWORK_SOL + fee.sol;- const mint = buildAgentMint(- umi,- mintParams(args, { network, creator: wallet, feeLamports: fee.lamports, feeWallet: fee.wallet }),- );- const asset = mint.assetSigner.publicKey.toString();+/**+ * The spend-nothing preview. Deliberately has no path to sendAgentMint, so the+ * preview tool cannot broadcast whatever flags or config say.+ */+async function previewMint(args) {+ const { network, umi, wallet, fee, mint, total } = await planMint(args);+ const balance = await solBalance(umi, wallet);+ return {+ ok: true,+ confirm_required: true,+ wallet_balance_sol: balance,+ balance_covers_cost: balance >= total,+ message:+ `Preview only. Re-issue with confirm:true to mint on ${network} for ~${total} SOL ` ++ `(~${EST_NETWORK_SOL} rent + network fees${fee.sol > 0 ? `, ${fee.sol} SOL deploy fee to ${fee.wallet}` : ', no deploy fee'}).`,+ network,+ paying_wallet: wallet,+ estimated_cost_sol: total,+ network_cost_sol: EST_NETWORK_SOL,+ ...feeBlock(fee),+ asset_metadata: mint.assetMetadata,+ metadata_uri_bytes: mint.metadataUri.length,+ registration: mint.registration,+ };+}- if (preview) {- const balance = await solBalance(umi, wallet);- return {- ok: true,- confirm_required: true,- wallet_balance_sol: balance,- balance_covers_cost: balance >= total,- message:- `Preview only. Re-issue with confirm:true to mint on ${network} for ~${total} SOL ` +- `(~${EST_NETWORK_SOL} rent + network fees${fee.sol > 0 ? `, ${fee.sol} SOL deploy fee to ${fee.wallet}` : ', no deploy fee'}).`,- network,- paying_wallet: wallet,- estimated_cost_sol: total,- network_cost_sol: EST_NETWORK_SOL,- ...feeBlock(fee),- asset_metadata: mint.assetMetadata,- metadata_uri_bytes: mint.metadataUri.length,- registration: mint.registration,- };- }+/** Sign and broadcast the mint. Only mint_onchain_agent reaches this. */+async function sendMint(args) {+ const { network, umi, wallet, fee, mint, total } = await planMint(args);+ const asset = mint.assetSigner.publicKey.toString();- const balance = await solBalance(umi, wallet);- if (balance * LAMPORTS_PER_SOL < EST_MINT_LAMPORTS + EST_REGISTER_LAMPORTS + fee.lamports) {- throw Object.assign(- new Error(- `Wallet ${wallet} holds ${balance} SOL on ${network}; this deploy needs ~${total} SOL. Fund it and retry.`,- ),- { code: 'insufficient_sol' },- );- }+ const balance = await solBalance(umi, wallet);+ if (balance * LAMPORTS_PER_SOL < EST_MINT_LAMPORTS + EST_REGISTER_LAMPORTS + fee.lamports) {+ throw Object.assign(+ new Error(+ `Wallet ${wallet} holds ${balance} SOL on ${network}; this deploy needs ~${total} SOL. Fund it and retry.`,+ ),+ { code: 'insufficient_sol' },+ );+ }- const { signatures, atomic } = await sendAgentMint(umi, mint, { toBase58Signature });+ const { signatures, atomic } = await sendAgentMint(umi, mint, { toBase58Signature });- return {- ok: true,- network,- asset,- atomic,- signatures,- txs: signatures.map((s) => txLink(s, network)),- owner: args.owner || wallet,- agent_wallet: assetSignerAddress(umi, asset),- ...feeBlock(fee),- metadata_uri: mint.metadataUri,- registration: mint.registration,- links: agentLinks(asset, network),- note: 'The agent is live in the Metaplex Agent Registry. DAS indexers surface it within minutes; fund agent_wallet to let the asset act on-chain.',- };+ return {+ ok: true,+ network,+ asset,+ atomic,+ signatures,+ txs: signatures.map((s) => txLink(s, network)),+ owner: args.owner || wallet,+ agent_wallet: assetSignerAddress(umi, asset),+ ...feeBlock(fee),+ metadata_uri: mint.metadataUri,+ registration: mint.registration,+ links: agentLinks(asset, network),+ note: 'The agent is live in the Metaplex Agent Registry. DAS indexers surface it within minutes; fund agent_wallet to let the asset act on-chain.',+ };}diff --git a/packages/metaplex-agent-mcp/test/registration.test.mjs b/packages/metaplex-agent-mcp/test/registration.test.mjsindex 54eebee90..f269a1c50 100644--- a/packages/metaplex-agent-mcp/test/registration.test.mjs+++ b/packages/metaplex-agent-mcp/test/registration.test.mjs@@ -18,11 +18,15 @@ const READ_ONLY_TOOLS = new Set(['build_registration','list_onchain_agents','three_status',+ // Spend-nothing previews of the two execution tools: they read balances and+ // build the transaction, but have no path to sign or send it.+ 'preview_agent_mint',+ 'preview_agent_identity',]);const EXECUTION_TOOLS = new Set(['mint_onchain_agent', 'send_signed_transaction', 'register_agent_identity']);test('exactly the expected tools are registered', () => {- assert.equal(TOOLS.length, 9);+ assert.equal(TOOLS.length, 11);assert.deepEqual(new Set(TOOLS.map((t) => t.name)), new Set([...READ_ONLY_TOOLS, ...EXECUTION_TOOLS]));});diff --git a/scripts/audit-mcp-safety.mjs b/scripts/audit-mcp-safety.mjsindex 53831c955..8ba0dd736 100644--- a/scripts/audit-mcp-safety.mjs+++ b/scripts/audit-mcp-safety.mjs@@ -52,9 +52,10 @@ import { checkTool, extractTools } from './lib/mcp-safety-check.mjs';// because the evidence is not the effect the caller receives. Keyed// `tool:evidence`; every entry states why. Two reviewed categories://-// 1. Read-through cache fills: the caller asked for a read and got a read, and-// the server warmed its own cache on the way. Each write is wrapped-// non-fatally at the source, so a failed write still returns the read.+// 1. Read-through cache fills and observation records: the caller asked for a+// read and got a read, and the server warmed its own cache (or logged what+// it just showed) on the way. Each write is wrapped non-fatally at the+// source, so a failed write still returns the read.// 2. Transaction BUILDERS that broadcast nothing: the handler assembles an// unsigned transaction and returns its bytes for a wallet to sign elsewhere.// Instruction constructors (umi's `transferSol`, Metaplex's `mintAsset`) read@@ -89,6 +90,14 @@ const EXEMPTIONS = new Map(['prepare_agent_mint:funds-transfer','Builder, not sender (category 2). buildAgentMint() calls umi transferSol() to APPEND the mainnet deploy-fee instruction to the mint builder; the handler signs only with the new asset keypair, serializes to txs_base64 with the caller wallet as a noop fee payer, and returns. It never broadcasts. The sibling that does broadcast, mint_onchain_agent, is annotated readOnlyHint:false + destructiveHint:true.',],+ [+ 'preview_agent_mint:funds-transfer',+ 'Builder, not sender (category 2). The handler is previewMint() alone: planMint() runs buildAgentMint(), whose umi transferSol() only APPENDS the deploy-fee instruction to an unsigned builder, then previewMint() reads the wallet balance and returns the cost lines. It has no call path to sendMint()/sendAgentMint() (split out of the shared runMint on purpose so no flag can turn the preview into a send) and nothing is signed. The broadcasting sibling, mint_onchain_agent, is annotated readOnlyHint:false + destructiveHint:true.',+ ],+ [+ 'sentiment_scout:db-write',+ 'Observation record (category 1). On a board read, runSentimentScout() calls recordScoutReads() to upsert what the Scout just showed into sentiment_scout_reads (first sighting kept, latest read overwritten) so the track record can grade it later. Each insert is wrapped in .catch(() => null), so the caller receives the same board whether or not the write lands, and nothing the caller owns changes. The tool never trades.',+ ],]);// ---------------------------------------------------------------------------