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.

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.js
index 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.mjs
index 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.mjs
index 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.',
+ ],
]);
// ---------------------------------------------------------------------------