avatar-agent-mcp

<p align="center"> <a href="https://three.ws"><img src="https://three.ws/three-ws-mcp-icon.svg" alt="three.ws" width="88" height="88"></a> </p> <h1 align="center">@three-ws/avatar-agent</h1> <p align="center"><strong>一个MCP服务器，可以将任何GLB转换为3D AI代理——检查/验证/优化模型，然后赋予Solana钱包、语音和pump.fun能力。</strong></p> <p align="center"> <a href="https://www.npmjs.com/package/@three-ws/avatar-agent"><img alt="npm" src="https://img.shields.io/npm/v/@three-ws/avatar-agent?logo=npm&color=cb3837"></a> <a href="https://www.npmjs.com/package/@three-ws/avatar-agent"><img alt="downloads" src="https://img.shields.io/npm/dm/@three-ws/avatar-agent?color=cb3837"></a> <img alt="license" src="https://img.shields.io/npm/l/@three-ws/avatar-agent?color=3b82f6"> <img alt="node" src="https://img.shields.io/node/v/@three-ws/avatar-agent?color=339933&logo=node.js"> <a href="https://modelcontextprotocol.io"><img alt="mcp" src="https://img.shields.io/badge/Model%20Context%20Protocol-✓-9945FF"></a> <a href="https://registry.modelcontextprotocol.io/?q=io.github.nirholas"><img alt="MCP Registry" src="https://img.shields.io/badge/MCP%20Registry-io.github.nirholas-0ea5e9"></a> </p> <p align="center"> <a href="#安装">安装</a> · <a href="#设置">设置</a> · <a href="#快速开始">快速开始</a> · <a href="#工具">工具</a> · <a href="#需求">需求</a> · <a href="https://three.ws">three.ws</a> </p> --- > 一个单一的Model Context Protocol服务器，它同时具备两种功能。它是一个通用的**3D工具包**——`inspect_glb`、`validate_glb`、`optimize_glb`、`thumbnail_glb`和`viewer_url`对任何GLB/glTF模型都有效，不需要头像，由`@gltf-transform/core`和Khronos官方的`gltf-validator`提供支持。它也是一个**3D AI代理**——生成一个带有纹理的GLB头像，赋予它一个语音（OpenAI TTS），一个Solana钱包，并运行pump.fun操作（Jupiter交换，原子Jito捆绑启动，创作者费用收集）。由[three.ws](https://three.ws)构建和维护。注册名称：`io.github.nirholas/3D-AI-Agent-Avatar`。 对于一个轻量级、只读的头像查看器（无钱包，无签名），请参见配套包[`@three-ws/avatar-mcp`](https://www.npmjs.com/package/@three-ws/avatar-mcp），它在聊天中直接渲染一个实时、可旋转的链上头像。 ## 安装 ```bash npm install @three-ws/avatar-agent ``` 使用`npx`直接运行（无需安装）或全局安装CLI： ```bash npx -y @three-ws/avatar-agent # MCP stdio 服务器 npm install -g @three-ws/avatar-agent # 暴露 `three-avatar-agent` ``` ## 设置 将服务器添加到您的MCP客户端。**Claude Code**，一行： ```bash claude mcp add avatar-agent -- npx -y @three-ws/avatar-agent ``` **Claude Desktop / Cursor**（JSON配置）： ```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检查完整的工具界面： ```bash 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` 头像，给他戴上墨镜，创建一个带有 `three` 前缀的Solana钱包，拉取 $THREE 的快照，并让他说“我们又回来了。” 运行 `spawn_avatar` → `dress_avatar` → `wallet_create({ vanityPrefix: "three" })` → `pump_snapshot` → `speak`。 ## 工具 所有20种工具都是免费的MCP工具——没有每调用一次的x402费用。标记为**执行**的工具会签署并广播真实的Solana交易，这些交易会移动真实的资金；为它们配置客户端的工具审批流程。 每个工具都附带[MCP工具注释](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-annotations)：读取操作会宣传 `readOnlyHint: true`，而四种执行工具（`wallet_send`、`pump_buy`、`pump_launch`、`pump_collect_fees`）被标记为 `destructiveHint: true`，因此支持注释的MCP客户端（Claude Code、Claude Desktop、Cursor）在运行它们之前会提示确认。提示是建议性的——服务器端的 `REQUIRE_CONFIRM` 门控和支出上限（参见[安全](#安全)）无论客户端如何都适用。 ### 3D工具包——适用于任何GLB，无需头像 | 工具 | 功能 | | --- | --- | | `inspect_glb` | 网格/材质/纹理/动画/皮肤分解，边界框，顶点和三角形计数。 `@gltf-transform/core`。 | | `validate_glb` | 运行Khronos官方的 `gltf-validator`；返回错误，警告，信息，提示和JSON指针。 | | `optimize_glb` | 消除重复 → 精简 → 焊接 → 可选Draco。返回优化的字节内联，包含前后大小。 | | `thumbnail_glb` | 通过three.ws托管的three-light rig + 自动框架相机将任何GLB渲染为PNG。返回base64 PNG内联。 | | `viewer_url` | 为任何GLB或头像会话（背景，自动旋转，相机预设或显式轨道，AR模式，尺寸）构建 `three.ws/viewer?...` URL + 可粘贴的iframe。 | ### 头像 | 工具 | 功能 | | --- | --- | | `list_avatars` | 默认GLB头像（`default`，`cz`），配件和姿势预设的目录。 | | `list_animations` | three.ws的姿势预设（T姿势，挥手，思考者，跳跃，舞蹈，warrior2，...）按类别分组的实时获取。 | | `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` | 在主网上发送SOL。 **执行**。 | ### pump.fun | 工具 | 功能 | | --- | --- | | `pump_snapshot` | 市场实时快照：USD价格（Jupiter），24小时交易量 + DEX（Dexscreener），pump.fun元数据，顶级持有者分布。传递 `target: "three"` 以获取 $THREE，当设置了 `THREE_MINT` 时。只读，无签名者。 | | `pump_buy` | Jupiter交换，直接或 **Jito捆绑**（资助者→买家转账 + 交换原子）。接受任何运行时铸造的代币。 **执行**。 | | `pump_launch` | **原子启动** 通过Jito捆绑：独立的资助者和创建者钱包，两个交易在同一区块中。上传元数据到pump.fun IPFS（如果未提供URI）。 **执行**。 | | `pump_collect_fees` | **原子收集**：`collectCoinCreatorFee` + 排干到一个安全钱包，单个交易内使用Jito捆绑 — 抵抗泄露的创建者密钥。 **执行**。 | ### 身份 | 工具 | 功能 | | --- | --- | | `ens_sns_resolve` | 将 `.eth`（ENS）和 `.sol`（Bonfida SNS）名称解析为地址，并进行反向和最喜欢的域名查找。 | ## 原子pump.fun工作原理 `pump_launch` 和 `pump_collect_fees` 工具封装了两种模式： - **启动** — 创建交易的 `payerKey` 是 **创建者** 钱包，因此链上 `creator` 字段（接收pump.fun创作者费用永远）是创建者钱包。创建者不需要持有SOL：资助者在同一个Jito捆绑的交易中转账租金 + 小费。两个交易要么都成功，要么都失败。 - **收集** — 即使共享或泄露了创建者密钥，收集和排干也作为单个交易在一个Jito捆绑中进行，因此没有竞争者可以在 `collectCoinCreatorFee` 和排干之间插入交易。 如果您开始遇到 `Bundles must write lock at least one tip account`，[Jito提示账户列表](https://docs.jito.wtf/)已经轮换。 这些工具接受运行时提供的任意铸造代币 — 用于启动和管理您自己的代币的通用管道。 **$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` | 可选 — 默认为ethers的默认公共提供程序。 | | `HELIUS_API_KEY` | `pump_snapshot`（增强） | 添加确切的供应 + DAS数据。 | | `NVIDIA_API_KEY` | `speak`（免费通道） | NVIDIA NIM密钥（`nvapi-…`）— 在TTS提供链中领先，带有Magpie 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` | 固定一个商业OK版本，例如最新的 `tencent/hunyuan-3d-3.1`。 | | `SOLANA_SECRET_KEY` | `wallet_send` / `pump_buy` 默认签名者 | 按调用的 `secret`参数覆盖。像现金一样对待。 | | `THREE_MINT` | `pump_snapshot` / `pump_buy` 快捷方式 | 设置工具接受 `target: "three"`。 | | `MAX_SOL_PER_TX` | 执行工具 | 每笔交易的交易上限为SOL。默认 `0.5`。 | | `REQUIRE_CONFIRM` | 执行工具 | 默认开启：执行调用在重新发出 `confirm: true` 之前拒绝。设为 `0`/`false` 以禁用。 | ## 安全 `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）绑定每个发送、购买、提示和排干的服务器端。 ## 链接 - 首页：https://three.ws - 配套包：[`@three-ws/avatar-mcp`](https://www.npmjs.com/package/@three-ws/avatar-mcp) — MCP的实时只读头像查看器 - 更新日志：https://three.ws/changelog - 问题：https://github.com/nirholas/three.ws/issues - 许可证：Apache-2.0 — 参见 [LICENSE](./LICENSE) --- <p align="center"> _{three.ws SDK 套件的一部分 — 3D AI 代理、链上身份和代理支付。<br/> <a href="https://three.ws">网站</a> · <a href="https://three.ws/changelog">更新日志</a> · <a href="https://github.com/nirholas/three.ws">GitHub</a>} </p> ## 许可证 Copyright © 2026 nirholas. All rights reserved. 本软件是专有的 — 参见 [LICENSE](./LICENSE)。除非版权所有者明确书面许可，否则不得授予任何权利。