Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
fix(avatar-agent-mcp): document and harden the .sol resolver's not-registered path
nirholasabd324709e68
diff --git a/packages/avatar-agent-mcp/README.md b/packages/avatar-agent-mcp/README.mdindex 4e33d2230..162f88171 100644--- a/packages/avatar-agent-mcp/README.md+++ b/packages/avatar-agent-mcp/README.md@@ -83,7 +83,7 @@ Once connected, ask your client in plain language:> Inspect `https://three.ws/avatars/cz.glb` — how many triangles? Then validate it against the Khronos spec and optimize it with Draco.-Runs `inspect_glb` → `validate_glb` → `optimize_glb({ draco: true })`, returning the smaller GLB inline.+Runs `inspect_glb` → `validate_glb` → `optimize_glb({ draco: true })`, returning the rewritten GLB inline with honest before/after sizes. Note that `cz.glb` already ships `EXT_meshopt_compression` + WebP textures, so re-encoding it with Draco reports a **negative** `savedBytes`: the pipeline never hides that, and an uncompressed source is where the wins actually are.> Spawn the `cz` avatar, give him shades, mint him a `three`-prefixed Solana wallet, pull a snapshot of $THREE, and have him say "we're so back."@@ -101,7 +101,7 @@ Every tool ships [MCP tool annotations](https://modelcontextprotocol.io/specific| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- || `inspect_glb` | Mesh / material / texture / animation / skin breakdown, bounding box, vertex and triangle counts. `@gltf-transform/core`. || `validate_glb` | Runs Khronos's official `gltf-validator`; returns errors, warnings, infos, hints with JSON pointers. |-| `optimize_glb` | Dedup → prune → weld → optional Draco. Returns the optimized bytes inline with before/after sizes. Draco- and meshopt-compressed inputs are decoded on read, so a compressed avatar works like any other. |+| `optimize_glb` | Dedup → prune → weld → optional Draco. Returns the rewritten bytes inline with before/after sizes and a signed `savedBytes` (negative when re-encoding an already-compressed model costs more than it saves). Draco- and meshopt-compressed inputs are decoded on read, so a compressed avatar works like any other. || `thumbnail_glb` | Renders any GLB to a PNG via three.ws's hosted three-light rig + auto-framing camera. Returns base64 PNG inline. || `viewer_url` | Builds a `three.ws/viewer?...` URL + paste-ready iframe for any GLB or avatar session (background, auto-rotate, camera preset or explicit orbit, AR mode, dimensions). |@@ -143,7 +143,7 @@ Every tool ships [MCP tool annotations](https://modelcontextprotocol.io/specific| Tool | What it does || ----------------- | ---------------------------------------------------------------------------------------------------------- |-| `ens_sns_resolve` | Resolves `.eth` (ENS) and `.sol` (Bonfida SNS) names to addresses, with reverse + favorite-domain lookups. |+| `ens_sns_resolve` | Resolves `.eth` (ENS) and `.sol` (SNS) names to addresses, with reverse + favorite-domain lookups. SNS is read straight from the SPL Name Service accounts on your `SOLANA_RPC_URL`, so it depends on no third-party name service. |## How atomic pump.fun works@@ -165,7 +165,7 @@ Per-tool environment variables (all optional — set only what you use):| 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 traffic. |-| `ETH_RPC_URL` | `ens_sns_resolve` | Optional — falls back to ethers' default public providers. Alias: `MAINNET_RPC_URL`. |+| `ETH_RPC_URL` | `ens_sns_resolve` (`.eth` lane) | Strongly recommended. Without it ethers falls back to its shared community endpoints, which are throttled hard enough that `.eth` lookups routinely time out. `.sol` needs nothing here. Alias: `MAINNET_RPC_URL`. || `HELIUS_API_KEY` | `pump_snapshot` (enhanced) | Adds exact supply + DAS data. || `NVIDIA_API_KEY` | `speak` (free lane) | NVIDIA NIM key (`nvapi-…`) — leads the TTS provider chain with Magpie TTS. || `OPENAI_API_KEY` | `speak` (paid backstop) | Used against `api.openai.com/v1/audio/speech` when the free lane is unavailable. |@@ -176,6 +176,7 @@ Per-tool environment variables (all optional — set only what you use):| `MAX_SOL_PER_TX` | execution tools | Per-transaction spend cap in SOL. Default `0.5`. || `REQUIRE_CONFIRM` | execution tools | Default on: execution calls refuse until re-issued with `confirm: true`. Set `0`/`false` to disable. || `RECIPIENT_ALLOWLIST` | execution tools | Optional comma-separated base58 pubkeys. When set, SOL destinations (`wallet_send`, the `pump_collect_fees` drain target) must be in the list. |+| `NAME_RESOLVE_TIMEOUT_MS` | `ens_sns_resolve` | Budget for one lane of a name lookup. Default `15000`. Raise it when pointing at a slow self-hosted RPC. || `VIEWER_BASE` | `viewer_url` | Defaults to `https://three.ws/viewer`. Override to point links at a self-hosted viewer. || `THREE_WS_BASE` | hosted rendering / animation catalog | Defaults to `https://three.ws`. Override only when self-hosting the three.ws backend. |diff --git a/packages/avatar-agent-mcp/src/lib/ens-sns.js b/packages/avatar-agent-mcp/src/lib/ens-sns.jsindex abe04c178..cdea6c655 100644--- a/packages/avatar-agent-mcp/src/lib/ens-sns.js+++ b/packages/avatar-agent-mcp/src/lib/ens-sns.js@@ -127,10 +127,23 @@ async function resolveSns(name) {};}-export async function resolveName(name) {+/**+ * Decide which lane(s) an input belongs to, before any network call is made.+ * A bare label (no suffix) is an SNS label: `.sol` is the only namespace where+ * the suffix is optional. Exported so the routing is testable without a chain.+ *+ * @param {unknown} name+ * @returns {{ trimmed: string, isEns: boolean, isSol: boolean }}+ */+export function classifyName(name) {const trimmed = String(name || '').trim().toLowerCase();const isEns = ENS_RE.test(trimmed);const isSol = /\.sol$/.test(trimmed) || (!isEns && SOL_RE.test(trimmed));+ return { trimmed, isEns, isSol };+}++export async function resolveName(name) {+ const { trimmed, isEns, isSol } = classifyName(name);const tasks = [];if (isEns) tasks.push(['ens', resolveEns(trimmed).catch((e) => ({ error: e?.message || 'ens failed' }))]);diff --git a/packages/avatar-schema/README.md b/packages/avatar-schema/README.mdindex 370322921..a93567c6b 100644--- a/packages/avatar-schema/README.md+++ b/packages/avatar-schema/README.md@@ -38,9 +38,12 @@ npm install @three-ws/avatar-schema## Usage```js+import { readFile } from 'node:fs/promises';import { validate, assertValid } from '@three-ws/avatar-schema';-const manifest = await (await fetch('https://three.ws/avatars/nicholas.eth.json')).json();+// A manifest you scaffolded with @three-ws/avatar-cli, or fetched from wherever+// you host it (IPFS, S3, your own resolver).+const manifest = JSON.parse(await readFile('./manifest.json', 'utf8'));const result = validate(manifest);if (!result.valid) {@@ -52,15 +55,26 @@ assertValid(manifest);```The raw JSON Schema is exported separately so you can bind it to any validator-(Python `jsonschema`, Go `gojsonschema`, etc.):+(Python `jsonschema`, Go `gojsonschema`, etc.). It is a `.json` file, so Node's+ESM loader needs the import attribute:```js-import schema from '@three-ws/avatar-schema/schema'; // ./schema/avatar.v1.json+import schema from '@three-ws/avatar-schema/schema' with { type: 'json' };// or the version-pinned subpath:-import schemaV1 from '@three-ws/avatar-schema/schema/v1';+import schemaV1 from '@three-ws/avatar-schema/schema/v1' with { type: 'json' };```-It's also resolvable by absolute URL: <https://three.ws/schema/avatar.v1.json>.+On Node versions without import attributes, or from CommonJS, use `require`:++```js+import { createRequire } from 'node:module';+const schema = createRequire(import.meta.url)('@three-ws/avatar-schema/schema');+```++The already-parsed object is also a named export of the package root+(`import { schema } from '@three-ws/avatar-schema'`), which needs neither.++The schema is served at its `$id` too: <https://three.ws/schema/avatar.v1.json>.## Manifest fields