3D AI Agent Avatar

@three-ws/avatar-agent

一个 MCP 服务，可将任意 GLB 转换为 3D AI Agent——检查/验证/优化模型，然后为其配备 Solana 钱包、语音和 pump.fun 功能。

安装 · 设置 · 快速开始 · 工具 · 要求 · three.ws

---

一个 Model Context Protocol 服务，同时具备两种用途。它是一个通用的 3D 工具包——inspect_glb、validate_glb、optimize_glb、thumbnail_glb 和 viewer_url 可用于任意 GLB/glTF 模型，无需头像，并由 @gltf-transform/core 和 Khronos 官方的 gltf-validator 提供支持。它也是一个 开箱即用的 3D AI Agent——生成带纹理的 GLB 头像，为其配备语音（OpenAI TTS），提供 Solana 钱包，并运行 pump.fun 操作（Jupiter 兑换、Jito 原子捆绑发行、创作者费用收取）。由 three.ws 构建并维护。注册表名称：io.github.nirholas/3D-AI-Agent-Avatar。

如需轻量、只读的头像查看器（无需钱包，也无需签名），请参阅配套软件包 @three-ws/avatar-mcp，它会在聊天中内嵌呈现可实时旋转的链上头像。

安装

npm install @three-ws/avatar-agent

可直接使用 npx 运行（无需安装），也可全局安装以使用命令行工具：

npx -y @three-ws/avatar-agent          # MCP stdio server
npm install -g @three-ws/avatar-agent  # exposes `three-avatar-agent`

设置

将该服务添加到 MCP 客户端。Claude Code，只需一行：

claude mcp add avatar-agent -- npx -y @three-ws/avatar-agent

Claude Desktop / Cursor（JSON 配置）：

{
	"mcpServers": {
		"avatar-agent": {
			"command": "npx",
			"args": ["-y", "@three-ws/avatar-agent"],
			"env": {
				"SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com",
				"OPENAI_API_KEY": "sk-...",
				"REPLICATE_API_TOKEN": "r8_..."
			}
		}
	}
}

3D 工具（inspect_glb、validate_glb、optimize_glb、thumbnail_glb、viewer_url）和 pump_snapshot 无需环境变量即可使用。语音、生成和签名工具需要在要求中列出的密钥。编辑配置后请重启客户端。

在 GUI 中查看完整的工具列表：

npx -y @modelcontextprotocol/inspector npx -y @three-ws/avatar-agent

快速开始

连接后，用自然语言向客户端提出请求：

检查 https://three.ws/avatars/cz.glb——有多少个三角形？然后根据 Khronos 规范验证它，并使用 Draco 对其进行优化。

依次运行 inspect_glb → validate_glb → optimize_glb({ draco: true })，并以内嵌形式返回重写后的 GLB，同时如实显示优化前后的大小。请注意，cz.glb 已使用 EXT_meshopt_compression 和 WebP 纹理，因此再次使用 Draco 编码会报告一个负数 savedBytes：处理流程绝不会隐瞒这一点，而未压缩的源文件才能真正获得优化效果。

生成 cz 头像，给他戴上墨镜，为他创建一个以 three 为前缀的 Solana 钱包，获取 $THREE 的快照，然后让他说“我们又回来了。”

依次运行 spawn_avatar → dress_avatar → wallet_create({ vanityPrefix: "three" }) → pump_snapshot → speak。

工具

全部 24 个工具都是免费的 MCP 工具：每次调用均不收取 x402 费用。标记为 execution 的工具会签署并广播真实的 Solana 交易，从而转移真实资金；请为客户端配置工具审批流程。

每个工具都提供 MCP 工具注解：读取操作声明 readOnlyHint: true，而四个执行工具（wallet_send、pump_buy、pump_launch、pump_collect_fees）标记为 destructiveHint: true，因此支持注解的 MCP 客户端会在运行这些工具前提示确认。这些提示仅供参考——无论客户端如何配置，服务端的 REQUIRE_CONFIRM 门禁和支出上限（参见安全）都会生效。

3D 工具包 — 适用于任何 GLB，无需头像

工具	功能
inspect_glb	网格／材质／纹理／动画／蒙皮详情、包围盒、顶点和三角形数量。@gltf-transform/core。
validate_glb	运行 Khronos 官方的 gltf-validator；返回带有 JSON 指针的错误、警告、信息和提示。
optimize_glb	去重 → 修剪 → 焊接 → 可选 Draco。返回内联的重写后字节数据，以及优化前后的大小和带符号的 savedBytes（若重新编码已压缩模型导致的体积增加超过节省的空间，该值为负数）。读取时会解码 Draco 和 meshopt 压缩的输入，因此压缩头像也能像其他模型一样使用。
thumbnail_glb	通过 three.ws 托管的三点布光装置和自动取景摄像机，将任意 GLB 渲染为 PNG。返回内联的 base64 PNG。
viewer_url	为任意 GLB 或头像会话生成 three.ws/viewer?... URL 和可直接粘贴的 iframe（支持背景、自动旋转、摄像机预设或显式轨道控制、AR 模式和尺寸）。

头像

工具	功能
list_avatars	默认 GLB 头像（default、cz）、配饰和姿势预设目录。
list_animations	实时获取 three.ws 的姿势预设（T 姿势、挥手、思考者、跳跃、跳舞、战士 2 等），并按类别分组。
spawn_avatar	根据预设或自定义 GLB URL 创建头像会话。返回 sessionId。
dress_avatar	为会话应用配饰和姿势。
render_avatar	将摆好姿势的头像渲染为 PNG——包括姿势预设、摄像机轨道（theta／phi／radius）和 ARKit-52 面部表情。
generate_avatar	通过 Replicate（Hunyuan-3D）将文本／图像转换为 3D。新会话会预载生成的 GLB。

语音

工具	功能
speak	以头像的声音合成语音——优先使用免费的 NVIDIA Magpie TTS 通道（NVIDIA_API_KEY），备用方案为 OpenAI TTS（OPENAI_API_KEY）。返回由客户端播放的 base64 音频。

钱包

工具	功能说明
wallet_create	生成 Solana 密钥对。可选自定义靓号生成器（vanityPrefix: "three"）。密钥仅返回一次。
wallet_balance	读取 SOL 和所有 SPL 代币余额（包括 Token-2022）。
wallet_send_preview	预览 wallet_send：发送方、接收方、金额、网络费用、发送前后的余额，以及任何会导致操作被拒绝的规则。不签名。
wallet_send	在主网上发送 SOL。执行操作。

pump.fun

工具	功能说明
pump_snapshot	实时市场快照：USD 价格（Jupiter）、24 小时交易量和 DEX（Dexscreener）、pump.fun 元数据、最大持有者分布。设置 THREE_MINT 后，传入 target: "three" 可查询 $THREE。只读，不需要签名者。
pump_buy_quote	为指定金额和滑点的 pump_buy 报价：SOL 支出、预期和最低代币数量、价格影响、路由和费用。不签名；将其 quote_id 传给 pump_buy。
pump_buy	Jupiter 兑换，支持直接交易或通过 Jito 捆绑交易（资金方→买方转账 + 兑换原子执行）。接受任意运行时 mint。执行操作。
pump_launch_preview	预览 pump_launch：资金方和创建者地址、租金、开发者购买、捆绑小费、资金方总支出，以及任何会导致操作被拒绝的规则。不签名、不上传、不铸造。
pump_launch	通过 Jito 捆绑交易进行原子化发行：使用独立的资金方和创建者钱包，两笔交易位于同一区块中。若未提供 URI，则将元数据上传到 pump.fun IPFS。执行操作。
pump_collect_preview	预览 pump_collect_fees：实时费用金库余额、保留的租金、将到达目标地址的确切 SOL 数量，以及任何会导致操作被拒绝的规则。不签名。
pump_collect_fees	原子化收取：在 Jito 捆绑交易中的一笔交易内执行 collectCoinCreatorFee，并将余额转入安全钱包——降低创建者密钥泄露带来的风险。执行操作。

身份

工具	功能说明
ens_sns_resolve	将 .eth（ENS）和 .sol（SNS）名称解析为地址，并支持反向查询和收藏域名查询。SNS 数据直接从 SOLANA_RPC_URL 上的 SPL Name Service 账户读取，因此不依赖第三方名称服务。

pump.fun 的原子操作机制

pump_launch 和 pump_collect_fees 工具封装了两种模式：

• Launch — 创建交易的 payerKey 是创建者钱包，因此链上 creator 字段（永久接收 pump.fun 创建者费用）就是创建者钱包。创建者无需持有 SOL：资金提供方会在同一个 Jito bundle 的 Tx1 中转入租金和小费。两笔交易要么都上链，要么都不上链。
• Collect — 即使创建者密钥被共享或泄露，收取并转出资金的操作也会作为单笔交易在 Jito bundle 中运行，因此不会有其他收取者在 collectCoinCreatorFee 和转出资金之间插入交易。

如果开始遇到 Bundles must write lock at least one tip account，说明 Jito 小费账户列表 已轮换。

这些工具接受运行时提供的任意 mint，可用于发布和管理自有代币。$THREE（FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump）是 three.ws 推广的唯一代币。

要求

• Node >=20。

各工具的环境变量（均为可选——仅设置你会用到的变量）：

变量	必需场景	备注
SOLANA_RPC_URL	所有 Solana 操作	默认为 https://api.mainnet-beta.solana.com。生产流量请使用你自己的服务（Helius / Quicknode / Triton）。
ETH_RPC_URL	ens_sns_resolve（.eth 通道）	强烈建议设置。若不设置，ethers 会退回到共享的社区端点，这些端点限流严重，.eth 查询通常会超时。.sol 无需设置。别名：MAINNET_RPC_URL。
HELIUS_API_KEY	pump_snapshot（增强版）	添加精确的供应量和 DAS 数据。
NVIDIA_API_KEY	speak（免费通道）	NVIDIA NIM 密钥（nvapi-…）——通过 Magpie TTS 在 TTS 服务商链中优先使用。
OPENAI_API_KEY	speak（付费备用方案）	免费通道不可用时，会调用 api.openai.com/v1/audio/speech。
REPLICATE_API_TOKEN	generate_avatar	Replicate 文本/图像转 3D。
REPLICATE_TEXT_TO_AVATAR_MODEL	generate_avatar	固定使用允许商用的版本，例如最新的 tencent/hunyuan-3d-3.1。
SOLANA_SECRET_KEY	wallet_send / pump_buy 的默认签名者	单次调用的 secret 参数优先级更高。别名：FUNDER_SECRET。请妥善保管，如同现金。
THREE_MINT	pump_snapshot / pump_buy 的简写	设置后，工具会接受 target: "three"。默认为规范的 $THREE 铸币地址。
MAX_SOL_PER_TX	执行工具	每笔交易的 SOL 支出上限。默认值为 0.5。
REQUIRE_CONFIRM	执行工具	默认启用：执行调用必须重新发起并设置 confirm: true 才会执行。设置为 0/false 可禁用。
RECIPIENT_ALLOWLIST	执行工具	可选的逗号分隔 base58 公钥列表。设置后，SOL 收款地址（wallet_send 和 pump_collect_fees 的资金转出目标）必须在列表中。
NAME_RESOLVE_TIMEOUT_MS	ens_sns_resolve	单个名称查询通道的时间预算。默认值为 15000。若使用速度较慢的可自托管 RPC，请调高此值。
VIEWER_BASE	viewer_url	默认为 https://three.ws/viewer。可覆盖以将链接指向可自托管的查看器。
THREE_WS_BASE	托管渲染 / 动画目录	默认为 https://three.ws。仅在自托管 three.ws 后端时覆盖此值。

安全性

wallet_send、pump_buy、pump_launch 和 pump_collect_fees 会执行真实的链上交易。服务不会判断输入内容——只要签名者有效，它就会严格按照指令执行。密钥绝不会被记录或持久化；wallet_create 返回的密钥只会返回一次。

以下四层机制可对这项能力加以约束：

1. 工具注释 — 四个执行工具均标记为 destructiveHint: true，因此支持注释的 MCP 客户端（Claude Code、Claude Desktop、Cursor）会在执行前显示确认提示。只读工具标记为 readOnlyHint: true，可以安全地自动批准。
2. 确认门控 — 默认情况下，REQUIRE_CONFIRM 处于开启状态；每次执行调用都会返回 confirmation_required，直到再次调用并附上 confirm: true。此机制独立于客户端。
3. 支出上限 — MAX_SOL_PER_TX（默认值为 0.5 SOL）在服务端限制每次转账、购买、打赏和资金转出。此限制由签名库本身强制执行，因此涵盖所有路径——直接、打包和原子操作。
4. 收款方允许列表 — 设置 RECIPIENT_ALLOWLIST 后，任何不在列表中的 SOL 目的地址都会在构建交易前被拒绝。

错误

工具调用失败时会返回 MCP 错误结果（isError: true），其文本为单个 JSON 对象——{ "ok": false, "error": "<code>", "message": "…" }；如果有可用信息，还会包含 status 或链上 signature：

error	含义	处理方式
confirmation_required	REQUIRE_CONFIRM 处于开启状态时，调用执行工具却未提供 confirm: true。此结果作为普通（非错误）结果返回——这是有意拒绝，而非执行失败。	使用 confirm: true 重新发起相同调用。
over_spend_cap	请求的 SOL 金额超过 MAX_SOL_PER_TX。	降低金额，或在服务环境变量中调高 MAX_SOL_PER_TX（风险由你承担）。
recipient_not_allowed	已设置 RECIPIENT_ALLOWLIST，但目的地址不在列表中。	发送到允许列表中的地址，或扩展列表。
invalid_amount	SOL 金额为零、负数或非数字。	传入一个正数。
vault_too_small / nothing_to_drain	pump_collect_fees 未找到可收取的创建者费用（或仅找到尘埃级别的金额）。	无需操作——等待交易量增加后再查看。
simulation_failed	交易未通过 Solana 预检模拟；没有广播交易。	消息中包含程序日志——修复根本原因后重试。
bad_rpc_url / insecure_rpc_url	SOLANA_RPC_URL 格式错误，或在非本地主机上使用了普通 HTTP。	使用 https:// RPC 端点（本地验证器可使用 http://localhost）。
bad_policy_config	MAX_SOL_PER_TX（或其他策略变量）不是非负数。	修正环境变量的值。

广播后发生的执行错误会包含交易 signature，因此你可以在重试前核实最终链上状态——绝不要认为响应失败就代表资金没有转移。

链接

• 主页：https://three.ws
• 配套程序包：@three-ws/avatar-mcp — 用于 MCP 的实时只读头像查看器
• 更新日志：https://three.ws/changelog
• 问题反馈：https://github.com/nirholas/three.ws/issues
• 许可证：Apache-2.0，详见 LICENSE

---

_{属于 three.ws SDK 套件 — 3D AI Agent、链上身份和 Agent 支付。
网站 · 更新日志 · GitHub}