@three-ws/avatar-agent 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 three.ws
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# 3D AI Agent Avatar
+
+> **The MCP server for 3D + AI agents.** Inspect, validate, and optimize any GLB. Spawn a textured 3D avatar with a Solana wallet, a voice, and full pump.fun powers — including atomic Jito-bundled launches and creator-fee collection.
+
+[![npm](https://img.shields.io/npm/v/%40three-ws%2Favatar-agent?style=flat-square&color=9945FF)](https://www.npmjs.com/package/@three-ws/avatar-agent)
+[![license](https://img.shields.io/badge/license-MIT-14F195?style=flat-square)](./LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A520-9945FF?style=flat-square)](https://nodejs.org)
+[![mcp](https://img.shields.io/badge/Model%20Context%20Protocol-✓-9945FF?style=flat-square)](https://modelcontextprotocol.io)
+
+Registry name: **`io.github.nirholas/3D-AI-Agent-Avatar`** · npm: **`@three-ws/avatar-agent`**
+
+A single MCP server that's two things at once:
+
+1. **A general-purpose 3D toolkit** — `inspect_glb`, `validate_glb`, `optimize_glb`, `viewer_url` work on **any** GLB/glTF model, no avatar required. Powered by `@gltf-transform/core` + Khronos's official `gltf-validator`.
+2. **A full 3D agent in a box** — spawn a textured GLB avatar, give it a voice (OpenAI TTS), a Solana wallet, and pump.fun trading powers (Jupiter swaps, atomic Jito-bundled launches, creator-fee collection).
+
+Install it once. Your Claude / Cursor / Continue / Cline can now:
+
+- **Inspect any GLB** — meshes, materials, textures, animations, bounding box, vertex + triangle counts.
+- **Validate any GLB** against the Khronos glTF 2.0 spec (the same engine behind gltf.report).
+- **Optimize a GLB** — dedup, prune, weld, Draco-compress; get the smaller file back inline.
+- **Build a viewer URL** for any GLB so humans see it in WebGL with one click.
+- **Spawn a 3D avatar** from the curated defaults (`default`, `cz`) or any GLB URL.
+- **Dress it** — hats, glasses, earrings, poses.
+- **Generate a fresh avatar** from a text prompt via Replicate (Hunyuan-3D).
+- **Give it a voice** — OpenAI TTS, 11 voices.
+- **Hand it a Solana wallet** — vanity-grind a `three…` address in milliseconds.
+- **Read live pump.fun data** — Jupiter price, Dexscreener volume, pump.fun meta, holders.
+- **Buy any token** — Jupiter swap, optionally inside a sniper-resistant Jito bundle.
+- **Launch a coin atomically** — separate funder + creator wallets, both txs in the same block.
+- **Collect creator fees atomically** — collect + drain to a safe wallet in one tx.
+- **Resolve names** — ENS (`.eth`) and SNS (`.sol`).
+
+Built and maintained by [three.ws](https://three.ws). Atomic pump.fun pieces are ported from [nirholas/atomic](https://github.com/nirholas/atomic).
+
+---
+
+## Quick start (Claude Desktop / Cursor / Continue)
+
+Add this to your MCP config:
+
+```json
+{
+	"mcpServers": {
+		"3d-ai-agent-avatar": {
+			"command": "npx",
+			"args": ["-y", "@three-ws/avatar-agent"],
+			"env": {
+				"SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com",
+				"OPENAI_API_KEY": "sk-...",
+				"THREE_MINT": "<the $three CA on pump.fun>"
+			}
+		}
+	}
+}
+```
+
+Restart your client. Ask it: **"Inspect https://three.ws/avatars/cz.glb, then spawn CZ, give him shades, and read me the latest snapshot for $three."**
+
+---
+
+## Two 30-second demos
+
+### 3D toolkit demo (no avatar required)
+
+```
+You ▸ Inspect this GLB: https://three.ws/avatars/cz.glb — how many triangles?
+      Then validate it against the Khronos spec and optimize it with Draco.
+```
+
+Runs:
+1. `inspect_glb({ url })` → mesh/material/animation breakdown + triangle count + bbox
+2. `validate_glb({ url })` → official Khronos report
+3. `optimize_glb({ url, draco: true })` → dedup → prune → weld → Draco, returns the smaller GLB inline
+
+### Avatar agent demo
+
+```
+You ▸ Spawn cz, give him shades, mint him a "three"-prefixed wallet,
+     pull a snapshot of $three, and have him say "we're so back."
+```
+
+Behind the scenes the MCP runs:
+
+1. `spawn_avatar({ preset: "cz", voice: "onyx" })` → returns a `sessionId` + viewer URL
+2. `dress_avatar({ sessionId, accessoryIds: ["glasses-shades"] })`
+3. `wallet_create({ sessionId, vanityPrefix: "three" })` → base58 pubkey starting with `three…`
+4. `pump_snapshot({ token: "three" })` → live Jupiter price, Dexscreener volume, holders
+5. `speak({ sessionId, text: "we're so back" })` → mp3 base64 the client plays
+
+---
+
+## Tool surface (20 tools)
+
+### 3D toolkit (works on any GLB)
+| Tool | What it does |
+|---|---|
+| `inspect_glb` | Mesh / material / animation / skin breakdown + bounding box + vertex & triangle counts. `@gltf-transform/core`. |
+| `validate_glb` | Run Khronos's official `gltf-validator` on a GLB; errors, warnings, infos, hints with JSON pointers. |
+| `optimize_glb` | Dedup → prune → weld → optional Draco. Returns optimized bytes inline + before/after sizes. |
+| `thumbnail_glb` | **Render any GLB to a PNG** via three.ws's hosted three-light rig + auto-framing camera. Same pipeline as OG cards. Returns base64 PNG inline. |
+| `viewer_url` | Build a `three.ws/viewer?...` URL + ready-to-paste iframe snippet for any GLB or avatar session. Supports background, auto-rotate, camera preset OR explicit orbit, AR mode, dimensions. |
+
+### Avatar
+| Tool | What it does |
+|---|---|
+| `list_avatars` | Catalog of default GLB avatars (`default`, `cz`), accessories, and pose presets. |
+| `list_animations` | Live fetch of three.ws's 24 pose presets (T-pose, wave, thinker, jump, dance, warrior2, …) grouped by category. |
+| `spawn_avatar` | Create an avatar session from a preset or custom GLB URL. Returns `sessionId`. |
+| `dress_avatar` | Apply accessories + pose to a session. |
+| `render_avatar` | **Render a posed avatar to a PNG** — pose preset + camera orbit (theta/phi/radius) + ARKit-52 facial expression. Same rig + lighting as the three.ws customizer's save-snapshot. |
+| `generate_avatar` | Text/image-to-3D via Replicate. New session preloaded with the generated GLB. |
+
+### Voice
+| Tool | What it does |
+|---|---|
+| `speak` | OpenAI TTS — synthesize speech in the avatar's voice. Returns base64 audio. |
+
+### Wallet
+| Tool | What it does |
+|---|---|
+| `wallet_create` | Generate a Solana keypair. Optional vanity grinder (`vanityPrefix: "three"`). |
+| `wallet_balance` | Read SOL + all SPL token balances (incl. Token-2022). |
+| `wallet_send` | Send SOL on mainnet. **Execution action.** |
+
+### pump.fun
+| Tool | What it does |
+|---|---|
+| `pump_snapshot` | Live market snapshot: price, volume, holders, meta. Pass `target: "three"` for $three. |
+| `pump_buy` | Jupiter swap, direct or **Jito-bundled** (funder→buyer transfer + swap atomic). **Execution action.** |
+| `pump_launch` | **Atomic launch** via Jito bundle: separate funder + creator wallets, both txs same block. Uploads metadata to pump.fun IPFS if no URI is supplied. **Execution action.** |
+| `pump_collect_fees` | **Atomic collect**: `collectCoinCreatorFee` + drain to safe wallet in one tx inside a Jito bundle — leaked-creator-key resistant. **Execution action.** |
+
+### Identity
+| Tool | What it does |
+|---|---|
+| `ens_sns_resolve` | Resolve `.eth` (ENS) and `.sol` (Bonfida SNS) names to addresses with reverse + favorite-domain lookups. |
+
+---
+
+## Environment variables
+
+| Variable | Required for | Notes |
+|---|---|---|
+| `SOLANA_RPC_URL` | All Solana ops | Defaults to `https://api.mainnet-beta.solana.com`. Bring your own (Helius/QuickNode/Triton) for production. |
+| `ETH_RPC_URL` | `ens_sns_resolve` | Optional — falls back to ethers' default public providers. |
+| `HELIUS_API_KEY` | `pump_snapshot` (enhanced) | Adds exact supply + DAS data. |
+| `OPENAI_API_KEY` | `speak` | Used directly against `api.openai.com/v1/audio/speech`. |
+| `REPLICATE_API_TOKEN` | `generate_avatar` | |
+| `REPLICATE_TEXT_TO_AVATAR_MODEL` | `generate_avatar` | Pin a commercial-OK version, e.g. latest `tencent/hunyuan-3d-3.1`. |
+| `SOLANA_SECRET_KEY` | `wallet_send` / `pump_buy` default signer | Per-call `secret` args override. Treat like cash. |
+| `THREE_MINT` | `pump_snapshot` / `pump_buy` shorthand | Set so tools accept `target: "three"`. |
+
+---
+
+## Atomic pump.fun, briefly
+
+The `pump_launch` and `pump_collect_fees` tools wrap the pattern from [nirholas/atomic](https://github.com/nirholas/atomic). Two things matter:
+
+**Launch:** the create tx's `payerKey` is the **creator** wallet, not the funder — so the on-chain `creator` field (which receives pump.fun creator fees forever) is the creator wallet. But the creator doesn't need to hold SOL: the funder transfers rent + tip in Tx1 of the same Jito bundle. Either both land or neither does.
+
+**Collect:** even if a creator key is shared / leaked, the collect-and-drain runs as a single tx inside a Jito bundle. No competing collector can interleave a tx between `collectCoinCreatorFee` and the drain, even with the same key.
+
+If you start hitting `Bundles must write lock at least one tip account`, the [Jito tip account list](https://docs.jito.wtf/) has rotated — refresh `src/lib/jito.js`.
+
+---
+
+## Running locally
+
+```bash
+npm install @three-ws/avatar-agent
+npx three-avatar-agent             # MCP stdio server
+npx @modelcontextprotocol/inspector npx three-avatar-agent   # GUI
+```
+
+Or clone this repo:
+
+```bash
+git clone https://github.com/nirholas/three.ws.git
+cd three.ws/packages/avatar-agent-mcp
+npm install
+npm start
+```
+
+---
+
+## Safety
+
+`pump_buy`, `pump_launch`, `pump_collect_fees`, and `wallet_send` all execute real on-chain transactions and move real funds. The MCP makes no judgment about the input — if your client tells it to send 100 SOL to a random address with a valid signer, it will. Configure your client's tool-approval flow accordingly.
+
+Secrets are never logged or persisted. Secrets returned by `wallet_create` are returned ONCE — store them yourself.
+
+---
+
+## License
+
+MIT © 2026 three.ws
+
+Powered by the [Model Context Protocol](https://modelcontextprotocol.io), the [@nirholas/pump-sdk](https://www.npmjs.com/package/@nirholas/pump-sdk), and Jito's [Block Engine](https://docs.jito.wtf/).

package/package.json

@@ -0,0 +1,74 @@
+{
+	"name": "@three-ws/avatar-agent",
+	"version": "1.0.0",
+	"mcpName": "io.github.nirholas/3D-AI-Agent-Avatar",
+	"description": "3D AI Agent Avatar — MCP server that spawns a textured GLB avatar, inspects/validates/optimizes any 3D model, gives the agent a Solana wallet + a voice, and ships full pump.fun powers (atomic Jito-bundled launches + creator-fee collection). Powered by three.ws.",
+	"type": "module",
+	"author": "nirholas <hello@three.ws>",
+	"license": "MIT",
+	"homepage": "https://three.ws",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/nirholas/three.ws.git",
+		"directory": "packages/avatar-agent-mcp"
+	},
+	"bugs": {
+		"url": "https://github.com/nirholas/three.ws/issues"
+	},
+	"keywords": [
+		"mcp",
+		"model-context-protocol",
+		"three.ws",
+		"avatar",
+		"3d",
+		"glb",
+		"solana",
+		"pump.fun",
+		"jito",
+		"atomic-bundle",
+		"wallet",
+		"tts",
+		"ai-agent",
+		"agent-payments",
+		"$three"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE",
+		"server.json"
+	],
+	"bin": {
+		"three-avatar-agent": "./src/index.js",
+		"three-avatar-agent-mcp": "./src/index.js"
+	},
+	"main": "./src/index.js",
+	"exports": {
+		".": "./src/index.js"
+	},
+	"engines": {
+		"node": ">=20"
+	},
+	"scripts": {
+		"start": "node src/index.js",
+		"inspect": "npx -y @modelcontextprotocol/inspector node src/index.js"
+	},
+	"dependencies": {
+		"@gltf-transform/core": "^4.3.0",
+		"@gltf-transform/extensions": "^4.3.0",
+		"@gltf-transform/functions": "^4.3.0",
+		"@modelcontextprotocol/sdk": "^1.29.0",
+		"@nirholas/pump-sdk": "^1.30.0",
+		"@solana/spl-token": "^0.4.14",
+		"@solana/web3.js": "^1.98.4",
+		"bs58": "^6.0.0",
+		"draco3dgltf": "^1.5.7",
+		"ethers": "^6.16.0",
+		"form-data": "^4.0.5",
+		"gltf-validator": "^2.0.0-dev.3.10",
+		"zod": "^3.23.8"
+	}
+}

package/server.json

@@ -0,0 +1,75 @@
+{
+	"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+	"name": "io.github.nirholas/3D-AI-Agent-Avatar",
+	"description": "3D AI Agent Avatar — spawn a textured GLB avatar, inspect/validate/optimize any 3D model, give the agent a Solana wallet + a voice, and ship full pump.fun powers (atomic Jito-bundled launches + creator-fee collection).",
+	"repository": {
+		"url": "https://github.com/nirholas/three.ws",
+		"source": "github"
+	},
+	"version": "1.0.0",
+	"packages": [
+		{
+			"registryType": "npm",
+			"identifier": "@three-ws/avatar-agent",
+			"version": "1.0.0",
+			"transport": {
+				"type": "stdio"
+			},
+			"environmentVariables": [
+				{
+					"name": "SOLANA_RPC_URL",
+					"description": "Solana mainnet RPC endpoint. Defaults to https://api.mainnet-beta.solana.com — bring your own (Helius / QuickNode / Triton) for production traffic.",
+					"format": "string",
+					"isRequired": false,
+					"default": "https://api.mainnet-beta.solana.com"
+				},
+				{
+					"name": "ETH_RPC_URL",
+					"description": "Ethereum mainnet RPC for ENS resolution. Optional — falls back to ethers' default public providers.",
+					"format": "string",
+					"isRequired": false
+				},
+				{
+					"name": "HELIUS_API_KEY",
+					"description": "Optional Helius API key — enables exact supply + DAS data in pump_snapshot.",
+					"format": "string",
+					"isRequired": false,
+					"isSecret": true
+				},
+				{
+					"name": "OPENAI_API_KEY",
+					"description": "Required for the speak tool (OpenAI TTS).",
+					"format": "string",
+					"isRequired": false,
+					"isSecret": true
+				},
+				{
+					"name": "REPLICATE_API_TOKEN",
+					"description": "Required for the generate_avatar tool (Replicate text/image-to-3D).",
+					"format": "string",
+					"isRequired": false,
+					"isSecret": true
+				},
+				{
+					"name": "REPLICATE_TEXT_TO_AVATAR_MODEL",
+					"description": "Replicate version hash pinned for text-to-3D — recommended: latest tencent/hunyuan-3d-3.1.",
+					"format": "string",
+					"isRequired": false
+				},
+				{
+					"name": "SOLANA_SECRET_KEY",
+					"description": "Optional default base58 Solana secret for wallet_send / pump_buy. Per-call secret args override this. Treat like cash.",
+					"format": "string",
+					"isRequired": false,
+					"isSecret": true
+				},
+				{
+					"name": "THREE_MINT",
+					"description": "Optional pump.fun mint address for $three so tools accept target=\"three\" as shorthand.",
+					"format": "string",
+					"isRequired": false
+				}
+			]
+		}
+	]
+}

package/src/config.js

@@ -0,0 +1,31 @@
+// Centralized env access. The MCP server is user-keyed: every Solana
+// signing operation requires the user to supply a keypair via env or via
+// tool arguments. We never sign on behalf of someone with a baked-in key.
+
+export function env(key, fallback) {
+	const v = process.env[key];
+	return v !== undefined && String(v).trim() !== '' ? String(v).trim() : fallback;
+}
+
+export const SOLANA_RPC_URL = env('SOLANA_RPC_URL', 'https://api.mainnet-beta.solana.com');
+export const ETH_RPC_URL = env('ETH_RPC_URL') || env('MAINNET_RPC_URL') || null;
+export const HELIUS_API_KEY = env('HELIUS_API_KEY', '');
+export const OPENAI_API_KEY = env('OPENAI_API_KEY', '');
+export const REPLICATE_API_TOKEN = env('REPLICATE_API_TOKEN', '');
+export const REPLICATE_TEXT_TO_AVATAR_MODEL = env('REPLICATE_TEXT_TO_AVATAR_MODEL', '');
+
+// Optional default signer for Solana ops. Tools that sign accept a `secret`
+// argument that overrides this on a per-call basis.
+export const SOLANA_DEFAULT_SECRET = env('SOLANA_SECRET_KEY') || env('FUNDER_SECRET') || '';
+
+// $three is the official three.ws token on pump.fun. Used as the canonical
+// example mint in tool examples and README demos.
+export const THREE_MINT = env(
+	'THREE_MINT',
+	// Placeholder until the user pins their real $three CA. Override via
+	// the THREE_MINT env var when running the MCP.
+	'',
+);
+
+export const VIEWER_BASE = env('VIEWER_BASE', 'https://three.ws/viewer');
+export const THREE_WS_BASE = env('THREE_WS_BASE', 'https://three.ws');

package/src/index.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+// @three-ws/avatar-agent — MCP server entry point.
+//
+// Boots a Model Context Protocol server over stdio that gives any AI
+// assistant a 3D avatar, a Solana wallet, a voice, and full pump.fun
+// powers (snapshots + Jupiter buys + atomic Jito-bundled launches +
+// creator-fee collection).
+//
+// Run standalone:
+//   node packages/avatar-agent-mcp/src/index.js
+//
+// Or wire into Claude Desktop / Cursor — see README.md.
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+import { def as inspectGlb } from './tools/inspect-glb.js';
+import { def as validateGlb } from './tools/validate-glb.js';
+import { def as optimizeGlb } from './tools/optimize-glb.js';
+import { def as thumbnailGlb } from './tools/thumbnail-glb.js';
+import { def as viewerUrl } from './tools/viewer-url.js';
+import { def as listAvatars } from './tools/list-avatars.js';
+import { def as listAnimations } from './tools/list-animations.js';
+import { def as spawnAvatar } from './tools/spawn-avatar.js';
+import { def as dressAvatar } from './tools/dress-avatar.js';
+import { def as renderAvatar } from './tools/render-avatar.js';
+import { def as generateAvatar } from './tools/generate-avatar.js';
+import { def as speak } from './tools/speak.js';
+import { def as walletCreate } from './tools/wallet-create.js';
+import { def as walletBalance } from './tools/wallet-balance.js';
+import { def as walletSend } from './tools/wallet-send.js';
+import { def as pumpSnapshot } from './tools/pump-snapshot.js';
+import { def as pumpBuy } from './tools/pump-buy.js';
+import { def as pumpLaunch } from './tools/pump-launch.js';
+import { def as pumpCollect } from './tools/pump-collect.js';
+import { def as ensSnsResolve } from './tools/ens-sns-resolve.js';
+
+const TOOLS = [
+	// 3D toolkit — universal GLB / glTF tools
+	inspectGlb,
+	validateGlb,
+	optimizeGlb,
+	thumbnailGlb,
+	viewerUrl,
+	// Avatar
+	listAvatars,
+	listAnimations,
+	spawnAvatar,
+	dressAvatar,
+	renderAvatar,
+	generateAvatar,
+	speak,
+	// Wallet
+	walletCreate,
+	walletBalance,
+	walletSend,
+	// pump.fun
+	pumpSnapshot,
+	pumpBuy,
+	pumpLaunch,
+	pumpCollect,
+	// Identity
+	ensSnsResolve,
+];
+
+async function main() {
+	const server = new McpServer(
+		{ name: '3d-ai-agent-avatar', version: '1.0.0' },
+		{
+			capabilities: { tools: {} },
+			instructions:
+				'3D AI Agent Avatar — a complete 3D MCP toolkit plus a Solana-wallet-bearing, pump.fun-trading avatar agent. ' +
+				'3D tools (work on any GLB URL, no avatar required): inspect_glb returns mesh/material/animation/bbox stats; ' +
+				'validate_glb runs the official Khronos validator; optimize_glb runs dedup/prune/weld/Draco and returns the ' +
+				'smaller GLB inline; thumbnail_glb renders any GLB to a PNG via three.ws\'s hosted three-light rig (the same ' +
+				'pipeline that generates OG cards); viewer_url builds a three.ws/viewer link + iframe embed. ' +
+				'Avatar flow: list_avatars → list_animations → spawn_avatar (preset "default"/"cz" or any GLB) → dress_avatar → ' +
+				'render_avatar (pose + camera orbit + ARKit-52 expression → real PNG) → speak. generate_avatar text/image-to-3D ' +
+				'via Replicate. wallet_create (optional vanity grinder) gives the avatar a Solana wallet; wallet_balance, ' +
+				'wallet_send for SOL ops. ' +
+				'pump.fun: pump_snapshot for live market data (target="three" for $three); pump_buy via Jupiter, optional Jito ' +
+				'bundle; pump_launch is an atomic Jito-bundled launch with separate funder + creator; pump_collect_fees drains ' +
+				'pump.fun creator-fee vaults atomically. ens_sns_resolve for .eth / .sol names.',
+		},
+	);
+
+	for (const tool of TOOLS) {
+		server.registerTool(
+			tool.name,
+			{
+				title: tool.title,
+				description: tool.description,
+				inputSchema: tool.inputSchema,
+			},
+			async (args, extra) => {
+				try {
+					const result = await tool.handler(args, extra);
+					const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+					return { content: [{ type: 'text', text }] };
+				} catch (err) {
+					const payload = {
+						ok: false,
+						error: err?.code || 'unhandled',
+						message: err?.message || String(err),
+					};
+					return {
+						content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+						isError: true,
+					};
+				}
+			},
+		);
+	}
+
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	console.error(`[3d-ai-agent-avatar] connected over stdio with ${TOOLS.length} tools`);
+}
+
+main().catch((err) => {
+	console.error('[3d-ai-agent-avatar] fatal:', err);
+	process.exit(1);
+});

package/src/lib/atomic-collect.js

@@ -0,0 +1,141 @@
+// Atomic pump.fun creator-fee collection via a Jito bundle.
+//
+// Ported from nirholas/atomic's collect-jito.js. Single tx in the bundle:
+//   1. Funder pays fee + tip
+//   2. Creator signs `collectCoinCreatorFee` (drains pump.fun's vault to creator)
+//   3. Creator signs a SystemProgram transfer of the freshly-collected SOL
+//      to a safe DESTINATION wallet
+//
+// All three steps live in one tx, so even if the creator key is leaked /
+// shared, no other holder of that key can interleave a tx between the
+// collect and the drain.
+
+import {
+	PublicKey,
+	SystemProgram,
+	TransactionMessage,
+	VersionedTransaction,
+	ComputeBudgetProgram,
+	LAMPORTS_PER_SOL,
+} from '@solana/web3.js';
+
+import { bs58encode, getConnection, keypairFromSecret } from './solana.js';
+import { randomTipAccount, submitBundle, waitForSignatures } from './jito.js';
+
+// Rent-exempt minimum for a bare system account. Leaving exactly this in
+// the creator keeps the account alive without locking up unnecessary SOL.
+const RENT_EXEMPT_LAMPORTS = 890_880;
+
+export async function atomicCollect({
+	funderSecret,
+	creatorSecret,
+	destination,
+	jitoTipSol = 0.005,
+	priorityMicroLamports = 3_000_000,
+	bufferLamports = RENT_EXEMPT_LAMPORTS,
+	minVaultSol = 0.001,
+}) {
+	if (!destination) throw new Error('atomicCollect: destination is required');
+	const destinationPk = new PublicKey(destination);
+	const funder = keypairFromSecret(funderSecret);
+	const creator = keypairFromSecret(creatorSecret);
+
+	const pumpSdkPkg = await import('@nirholas/pump-sdk');
+	const OnlinePumpSdk = pumpSdkPkg.OnlinePumpSdk || pumpSdkPkg.default?.OnlinePumpSdk;
+	if (!OnlinePumpSdk) {
+		throw new Error('@nirholas/pump-sdk: OnlinePumpSdk export missing');
+	}
+	const conn = getConnection();
+	const sdk = new OnlinePumpSdk(conn);
+
+	const vaultBalance = await sdk.getCreatorVaultBalance(creator.publicKey);
+	const vaultLamports = Number(vaultBalance);
+	if (vaultLamports < Math.floor(minVaultSol * LAMPORTS_PER_SOL)) {
+		return {
+			ok: false,
+			code: 'vault_too_small',
+			vaultSol: vaultLamports / LAMPORTS_PER_SOL,
+			minSol: minVaultSol,
+		};
+	}
+
+	const creatorPreBal = await conn.getBalance(creator.publicKey, 'confirmed');
+	const transferAmount = creatorPreBal + vaultLamports - bufferLamports;
+	if (transferAmount <= 0) {
+		return {
+			ok: false,
+			code: 'nothing_to_drain',
+			vaultSol: vaultLamports / LAMPORTS_PER_SOL,
+			creatorPreBalSol: creatorPreBal / LAMPORTS_PER_SOL,
+		};
+	}
+
+	const funderBal = await conn.getBalance(funder.publicKey, 'confirmed');
+	const needed = (jitoTipSol + 0.002) * LAMPORTS_PER_SOL;
+	if (funderBal < needed) {
+		const err = new Error(
+			`Funder needs >= ${(needed / LAMPORTS_PER_SOL).toFixed(4)} SOL; has ${(funderBal / LAMPORTS_PER_SOL).toFixed(4)} SOL.`,
+		);
+		err.code = 'insufficient_funds';
+		throw err;
+	}
+
+	const tipAccount = randomTipAccount();
+	const collectIxs = await sdk.collectCoinCreatorFeeInstructions(creator.publicKey, funder.publicKey);
+	const { blockhash } = await conn.getLatestBlockhash('confirmed');
+
+	const msg = new TransactionMessage({
+		payerKey: funder.publicKey,
+		recentBlockhash: blockhash,
+		instructions: [
+			ComputeBudgetProgram.setComputeUnitPrice({ microLamports: priorityMicroLamports }),
+			ComputeBudgetProgram.setComputeUnitLimit({ units: 100_000 }),
+			SystemProgram.transfer({
+				fromPubkey: funder.publicKey,
+				toPubkey: tipAccount,
+				lamports: Math.floor(jitoTipSol * LAMPORTS_PER_SOL),
+			}),
+			...collectIxs,
+			SystemProgram.transfer({
+				fromPubkey: creator.publicKey,
+				toPubkey: destinationPk,
+				lamports: transferAmount,
+			}),
+		],
+	}).compileToV0Message();
+
+	const tx = new VersionedTransaction(msg);
+	tx.sign([funder, creator]);
+
+	// Simulate first so we surface program errors before paying the tip.
+	const sim = await conn.simulateTransaction(tx, { sigVerify: false, replaceRecentBlockhash: false });
+	if (sim.value.err) {
+		return {
+			ok: false,
+			code: 'simulation_failed',
+			err: sim.value.err,
+			logs: sim.value.logs,
+		};
+	}
+
+	const bundle = [bs58encode(tx.serialize())];
+	const { bundleId, explorer } = await submitBundle(bundle);
+	const sig = bs58encode(tx.signatures[0]);
+	const wait = await waitForSignatures(conn, [sig], { timeoutMs: 60_000, intervalMs: 2_000 });
+
+	return {
+		ok: wait.ok,
+		bundleId,
+		bundleExplorer: explorer,
+		signature: sig,
+		statuses: wait.statuses,
+		err: wait.err,
+		creator: creator.publicKey.toBase58(),
+		destination,
+		drainedLamports: transferAmount,
+		drainedSol: transferAmount / LAMPORTS_PER_SOL,
+		vaultLamports,
+		vaultSol: vaultLamports / LAMPORTS_PER_SOL,
+		txExplorer: `https://solscan.io/tx/${sig}`,
+	};
+}