3D AI Agent Avatar

@three-ws/avatar-agent

あらゆる GLB を 3D AI エージェントに変える MCP サーバーです。モデルの検査・検証・最適化を行い、Solana ウォレットと音声、pump.fun の機能を追加できます。

インストール · セットアップ · クイックスタート · ツール · 要件 · three.ws

---

1 つの Model Context Protocol サーバーで、2 つの用途に対応します。汎用の 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 が開発・保守しています。レジストリ名：io.github.nirholas/3D-AI-Agent-Avatar。

軽量な読み取り専用アバタービューアー（ウォレットや署名なし）をお探しの場合は、関連パッケージの @three-ws/avatar-mcp をご覧ください。チャット内にオンチェーンアバターをリアルタイムで描画し、回転させて表示します。

インストール

npm install @three-ws/avatar-agent

npx で直接実行する（インストール不要）か、CLI 用にグローバルインストールします。

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

セットアップ

MCP クライアントにサーバーを追加します。Claude Code の場合は 1 行です。

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 のスナップショットを取得して、「we're so back.」と言わせてください。

spawn_avatar → dress_avatar → wallet_create({ vanityPrefix: "three" }) → pump_snapshot → speak を実行します。

ツール

24 種類すべてのツールを無料で利用できる MCP ツールです。呼び出しごとの x402 料金はかかりません。execution と表示されたツールは、実際の資金を移動する Solana トランザクションに署名してブロードキャストします。これらのツールを使う場合は、クライアントのツール承認フローを設定してください。

すべてのツールにはMCP ツールアノテーションが付属しています。読み取りツールは readOnlyHint: true を示し、4 つの実行ツール（wallet_send、pump_buy、pump_launch、pump_collect_fees）には destructiveHint: true が設定されています。そのため、アノテーションに対応した MCP クライアントでは、実行前に確認を求めます。これらのヒントは参考情報です。クライアントにかかわらず、サーバー側の REQUIRE_CONFIRM ゲートと支出上限（Safetyを参照）が適用されます。

3D ツールキット — あらゆる GLB で動作し、アバターは不要です

ツール	機能
inspect_glb	メッシュ／マテリアル／テクスチャ／アニメーション／スキンの内訳、バウンディングボックス、頂点数と三角形数を表示します。@gltf-transform/core。
validate_glb	Khronos 公式の gltf-validator を実行し、JSON ポインター付きのエラー、警告、情報、ヒントを返します。
optimize_glb	重複除去 → プルーニング → 溶接 → オプションで Draco を適用します。最適化前後のサイズと、符号付きの savedBytes（再エンコードのコストが削減量を上回る場合は負の値）とともに、書き換えたバイト列をインラインで返します。Draco および meshopt で圧縮された入力は読み込み時にデコードされるため、圧縮済みのアバターもほかのモデルと同様に扱えます。
thumbnail_glb	three.ws がホストする 3 灯照明セットアップと自動フレーミングカメラを使って、あらゆる GLB を PNG にレンダリングします。base64 PNG をインラインで返します。
viewer_url	あらゆる GLB またはアバターセッション用の three.ws/viewer?... URL と、すぐに貼り付けられる iframe を生成します（背景、自動回転、カメラプリセットまたは明示的な軌道、AR モード、サイズ）。

アバター

ツール	機能
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_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 バンドル（資金提供者から購入者への送金とスワップをアトミックに実行）に対応しています。任意の実行時ミントを受け付けます。実行します。
pump_launch_preview	pump_launch のプレビューを表示します。資金提供者と作成者のアドレス、レンタル料、開発者による購入、バンドルのチップ、資金提供者の合計額、拒否するルールがあればその内容を確認できます。署名、アップロード、ミントは行いません。
pump_launch	Jito バンドルを介してアトミックにローンチします。資金提供者と作成者に別々のウォレットを使い、両方のトランザクションを同じブロック内で実行します。URI が指定されていない場合は、pump.fun の IPFS にメタデータをアップロードします。実行します。
pump_collect_preview	pump_collect_fees のプレビューを表示します。手数料保管庫の現在の残高、残しておくレンタル料、送金先に届く正確な SOL の額、拒否するルールがあればその内容を確認できます。署名は行いません。
pump_collect_fees	アトミックに手数料を回収します。Jito バンドル内の 1 つのトランザクションで、collectCoinCreatorFee と安全なウォレットへの全額送金を実行するため、作成者のキーが漏えいしても耐性があります。実行します。

アイデンティティ

ツール	説明
ens_sns_resolve	.eth（ENS）と .sol（SNS）の名前をアドレスに解決します。逆引きとお気に入りドメインの検索にも対応しています。SNS は SOLANA_RPC_URL 上の SPL Name Service アカウントから直接読み取るため、サードパーティのネームサービスには依存しません。

pump.fun のアトミックな仕組み

pump_launch と pump_collect_fees ツールは、次の 2 つのパターンをラップします。

• 起動 — 作成トランザクションの payerKey は作成者のウォレットです。そのため、オンチェーンの creator フィールド（pump.fun の作成者手数料を永久に受け取る）は作成者のウォレットになります。作成者が SOL を保有している必要はありません。同じ Jito バンドルの Tx1 で資金提供者がレンタル料とチップを送金します。両方のトランザクションが実行されるか、どちらも実行されないかのいずれかです。
• 徴収 — 作成者のキーが共有または漏えいしていても、徴収と引き出しは Jito バンドル内の単一トランザクションとして実行されるため、collectCoinCreatorFee と引き出しの間に競合する徴収者がトランザクションを割り込ませることはできません。

Bundles must write lock at least one tip account が表示されるようになった場合は、Jito のチップアカウント一覧が更新されています。

これらのツールは、実行時に指定された任意のミントを受け付けます。独自のコインを起動・管理するための汎用的な仕組みです。three.ws がプロモーションしているコインは $THREE（FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump）のみです。

要件

• Node >=20。

ツールごとの環境変数（すべて任意です。使用するものだけ設定してください）：

変数	必要な用途	備考
SOLANA_RPC_URL	すべての Solana 操作	デフォルトは https://api.mainnet-beta.solana.com です。本番環境のトラフィックには、ご自身の RPC（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	実行ツール	1 トランザクションあたりの 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 から返される秘密情報は一度だけです。

4 つのレイヤーで、その権限を制御します。

1. ツールのアノテーション — 4 つの実行ツールには destructiveHint: true が設定されているため、アノテーションに対応する MCP クライアント（Claude Code、Claude Desktop、Cursor）では、実行前に確認プロンプトが表示されます。読み取り専用ツールには readOnlyHint: true が設定されているため、安全に自動承認できます。
2. 確認ゲート — REQUIRE_CONFIRM がオンの場合（デフォルト）、すべての実行呼び出しは、クライアントに関係なく、confirm: true を指定して再実行されるまで confirmation_required を返します。
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 の形式が不正であるか、localhost 以外のホストで平文の HTTP が使われています。	https:// の RPC エンドポイントを使用してください（ローカルバリデーターの場合は http://localhost を使用できます）。
bad_policy_config	MAX_SOL_PER_TX（または別のポリシー変数）が、0 以上の数値ではありません。	環境変数の値を修正してください。

ブロードキャスト後に発生した実行エラーには、取引の signature が含まれます。再試行する前に、オンチェーンの最終状態を確認できます。応答が失敗したからといって、資金が移動していないと思い込まないでください。

リンク

• ホームページ：https://three.ws
• 関連パッケージ：@three-ws/avatar-mcp — MCP 用のライブ読み取り専用アバタービューアー
• 変更履歴：https://three.ws/changelog
• Issue：https://github.com/nirholas/three.ws/issues
• ライセンス：Apache-2.0。LICENSE を参照してください。

---

_{three.ws SDK スイートの一部です — 3D AI エージェント、オンチェーン ID、エージェント決済。
ウェブサイト · 変更履歴 · GitHub}