Metaplex Agent Registry

@three-ws/metaplex-agent-mcp

通过任意 MCP 客户端，在 Solana 上将 AI Agent 部署到 Metaplex Agent Registry。

一个流程即可铸造 Metaplex Core 资产并注册其 EIP-8004 Agent 身份（如果符合 Solana 的 1232 字节限制，则使用单笔原子交易；否则依次执行创建和注册，具体方式与 Genesis 333 上链时完全一致），让 Agent 显示在 metaplex.com/agents 上，并拥有内置钱包、信誉页面和浏览器页面。默认输出会精确复现 three.ws Genesis 333 铸造的格式，并已与链上实时资产逐字节验证：

• 资产元数据使用独立完整的 data:application/json;base64 URI（包含 name、image、animation_url GLB）
• Royalties 插件（向所有者支付 5%）、VerifiedCreators（签名钱包）、ImmutableMetadata
• AgentIdentity 插件携带 eip-8004#registration-v1 文档（model.uri、active、x402Support、registrations、supportedTrust）

两种签名方式，均由用户自行托管：

• Agent 使用自己的密钥对（SOLANA_SECRET_KEY）签名：mint_onchain_agent。
• 用户使用 Phantom、Solflare、Backpack、Ledger 或任意 Solana 钱包签名：prepare_agent_mint 构建交易，由钱包签名，再通过 send_signed_transaction 广播。密钥不会接触服务器。

主网部署需支付固定 0.02 SOL 费用，与铸造在同一笔交易中完成，这笔费用将用于 $THREE 回购。持有 $THREE 可先将费用减半，随后免除；devnet 不收取费用。每次预览都会显示费用和收款方，然后才会签名。请参阅 $THREE：部署费用与持有者豁免。

所有操作都是真实的：使用真正的 Metaplex 程序和 Solana，并支持在 devnet 上免费端到端演练。

安装

npm install -g @three-ws/metaplex-agent-mcp
# or run ad hoc
npx -y @three-ws/metaplex-agent-mcp

设置

Claude Code：

claude mcp add metaplex-agent -e SOLANA_SECRET_KEY=<base58> -- npx -y @three-ws/metaplex-agent-mcp

Cursor / 任意 MCP 客户端（mcp.json）：

{
	"mcpServers": {
		"metaplex-agent": {
			"command": "npx",
			"args": ["-y", "@three-ws/metaplex-agent-mcp"],
			"env": { "SOLANA_SECRET_KEY": "<base58 secret key>" }
		}
	}
}

SOLANA_SECRET_KEY 是可选项：所有读取工具以及完整的 Phantom/Solflare 流程都可以在不设置它的情况下使用。

快速开始

先在 devnet 上免费演练，然后再部署到主网：

1. agent_wallet {}                                → confirm the signer is funded
2. mint_onchain_agent { name: "Astra", description: "…",
     image: "https://…png", model_url: "https://…glb",
     x402_support: true, network: "devnet" }      → preview (nothing broadcast)
3. …same call with confirm: true                  → minted + registered, links returned
4. get_onchain_agent { asset: "<returned asset>", network: "devnet" }

主网部署费用约为 0.027 SOL：约 0.007 SOL 用于 Core 租金、身份 PDA 租金和网络费用，另加固定的 0.02 SOL 部署费，用于 $THREE 回购。持有 $THREE 可将这笔费用减半，随后免除；devnet 则免费。请参阅 $THREE。

工具

工具	功能
mint_onchain_agent	铸造并注册，由你的密钥签名（符合条件时使用原子交易，否则自动拆分）。confirm:true 用于确认支出；其他任何值都会返回完整预览。
prepare_agent_mint	构建相同的铸造流程，供外部钱包（wallet 参数）签名。返回 txs_base64，其中已由新资产密钥对共同签名；使用 signTransaction / signAllTransactions 签名。
send_signed_transaction	按顺序广播由钱包签名的交易，轮询每笔交易直至确认，并处理创建与注册之间的传播延迟。
register_agent_identity	将已铸造的 Core 资产登记到 Agent Registry（幂等；签名者必须是资产权限方）。
get_onchain_agent	读取任意已注册 Agent 的信息：资产、插件、解码后的元数据和注册文档、身份 PDA、内置钱包及余额。
agent_wallet	查看资产的内置钱包（mpl-core Asset Signer PDA）、任意地址或已配置的签名者，并获取实时 SOL 余额。
build_registration	完全离线生成 EIP-8004 注册 JSON 和 data: URI。
list_onchain_agents	从 three.ws 实时 /api/deployments 数据源获取最新注册（默认使用 Solana；设置 all_chains:true 也会包含 EVM ERC-8004）。
three_status	计算下一次部署的费用：费用标准、钱包实时 $THREE 余额和等级，以及公开的回购记录。

$THREE：部署费用与持有者豁免

主网部署收取固定的 0.02 SOL 费用。关于这笔费用，有三点需要注意：

• 费用与创建资产的交易一并支付。 部署失败、被拒绝或过期，都不会转移资金。无需单独付款，也无需对账。
• 签名之前会披露费用。 每次 mint_onchain_agent 预览以及每个 prepare_agent_mint 响应都会返回 deploy_fee_sol 和 deploy_fee_to，并注明对应的等级。
• 费用用于回购 $THREE。 费用会支付至 three.ws $THREE 回购通道所使用的钱包 （代币地址为 FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump）；该通道已回购内容的公开账本位于 /api/three-token/stats。部署是此软件包唯一的收入来源。

持有 $THREE 可降低费用，甚至免除费用：

付款钱包中的 $THREE 数量	部署费用
少于 50,000	0.02 SOL
50,000 或以上	0.01 SOL
250,000 或以上	免费

构建交易时会实时读取链上余额。无需质押、托管、锁定或花费代币即可获得优惠：只需将代币持有在自己的钱包中，优惠就适用于你部署的每个 Agent。Devnet 始终免费，因此完整的端到端演练无需花费。

three_status {}                                  → what your next deploy costs and why
three_status { wallet: "<any base58 address>" }  → price it for someone else's wallet

自托管采用不同经济规则的分叉版本时，可使用 DEPLOY_FEE_SOL、DEPLOY_FEE_WALLET 和 DEPLOY_FEE_ENABLED。

自定义

铸造涉及的每个字段都是可配置参数：所有者、集合、版税基点和分配比例、已验证创作者、不可变元数据、链上 Attributes、永久冻结／转移／销毁代理、AddBlocker、链下元数据属性、external_url、服务、信任模型、注册条目，以及对由你自行托管的文档使用完整的 metadata_uri / registration_uri 覆盖值。默认值为 Genesis 333 的参数，因此只需传入 name、description、image 和 model_url 调用，生成的资产在结构上就与原始资产无法区分。

安全性

• mint_onchain_agent 和 register_agent_identity 仅在 confirm: true 时广播（设置 REQUIRE_CONFIRM=false 可选择退出）；预览不产生费用。
• 密钥始终由你掌控：使用 SOLANA_SECRET_KEY 或每次调用时传入的 secret，绝不使用托管钱包。钱包通道完全无需密钥。
• 消费前会检查余额，RPC 端点必须使用 HTTPS；devnet 是可用于演练的一等目标。

环境变量

变量	默认值	含义
SOLANA_SECRET_KEY	未设置	铸造钱包的 Base58 密钥或 JSON 字节数组。
SOLANA_RPC_URL	公共端点	HTTPS RPC。生产环境流量请使用你自己的端点。
METAPLEX_AGENT_NETWORK	mainnet	默认集群（mainnet 或 devnet）；每个工具也都接受单次调用的 network。
REQUIRE_CONFIRM	true	要求通过 confirm: true 确认后才能消费。
THREE_WS_BASE	https://three.ws	部署信息流和 $THREE 账本的主机。
DEPLOY_FEE_SOL	0.02	主网部署费用，单位为 SOL。
DEPLOY_FEE_WALLET	three.ws 回购钱包	部署费用的收款地址。
DEPLOY_FEE_ENABLED	true	设为 false 可构建不收取费用的分叉版本。
THREE_HALF_PRICE_AT / THREE_FREE_AT	50000 / 250000	可使费用减半或免除的 $THREE 余额。
THREE_MINT	$THREE 铸币地址	仅用于跟踪更新后的规范合约。

库的使用

这些构建器已导出，可直接嵌入（Web 应用、脚本）：

import { buildAgentMint, sendAgentMint, buildUmi, toBase58Signature } from '@three-ws/metaplex-agent-mcp/lib';

const umi = buildUmi({ network: 'devnet', secret: process.env.SOLANA_SECRET_KEY });
const mint = buildAgentMint(umi, {
	network: 'devnet',
	creator: umi.identity.publicKey.toString(),
	name: 'Astra',
	description: 'An autonomous 3D agent',
	image: 'https://example.com/astra.png',
	modelUrl: 'https://example.com/astra.glb',
	x402Support: true,
});
const { signatures, atomic } = await sendAgentMint(umi, mint, { toBase58Signature });

注册和元数据构建器也可以单独从 @three-ws/metaplex-agent-mcp/lib/registration 导入（无依赖、可在浏览器中安全使用），交易构建器则可从 @three-ws/metaplex-agent-mcp/lib/mint 导入。three.ws 的 /deploy-onchain 页面正是基于这些构建器运行的。atomic 为 false 时，combinedBuilder 仍包含完整的铸造流程：将其编译为 Solana 交易 v1（4,096 字节限制）后，创建和注册会在一个原子交易中完成；对于支持 v1 签名的钱包，/deploy-onchain 就是这样处理的。

要求

• Node 20+
• 目标网络上用于铸造的 SOL（主网上每个 Agent 约需 0.027 SOL，持有者豁免时约需 0.007 SOL；devnet 可通过水龙头免费获取）

链接

• three.ws：https://three.ws
• $THREE：https://three.ws/three
• 实时部署动态：https://three.ws/deployments
• Metaplex Agent Registry：https://www.metaplex.com/agents
• Metaplex 文档：https://www.metaplex.com/docs/agents
• 源码：https://github.com/nirholas/three.ws/tree/main/packages/metaplex-agent-mcp