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
import { hasScope } from '../_lib/auth.js';
import { recordEvent, logger } from '../_lib/usage.js';
import {
priceFor,
findActiveSubscription,
resolveBillingMint,
x402AmountForTool,
} from '../_lib/pump-pricing.js';
import { declareMcpDiscovery } from '../_lib/x402/bazaar-helpers.js';
import { sanitizeToolError } from '../_lib/mcp-error-sanitize.js';
import { GETTING_STARTED_TOOL } from '../_lib/mcp-getting-started.js';
import { TOOL_CATALOG, TOOLS } from './catalog.js';
import { declaredArgs, finishCall, gateCall, listForRequest } from './policy.js';
import { beginMeter, finishMeter, refundMeter } from '../_lib/mcp-credits.js';
// The @three-ws/mcp-policy server id for /api/mcp.
const POLICY_SERVER = 'three.ws';
const CATALOG_BY_NAME = new Map(TOOL_CATALOG.map((t) => [t.name, t]));
import { handleResourceMethod, RESOURCE_CAPABILITIES } from './resources.js';
import { handlePromptMethod, PROMPT_CAPABILITIES } from './prompts.js';
// Tools any caller may invoke with no OAuth token and no x402 payment.
//
// Membership is an explicit allowlist, never "is unpriced": a scoped tool that
// happens to cost nothing (recall, list_my_avatars) still reads account data and
// must stay behind auth. Everything here is a read of an already-public,
// already-published artifact with no caller state in it, which is precisely why
// it is safe to hand to an anonymous client. Per-IP rate limits still apply.
const PUBLIC_TOOLS = new Set([
GETTING_STARTED_TOOL,
// The asset catalog: published CC0 / free-to-use library manifests plus the
// code that renders them. Discovery has to work before a client signs in, or
// nobody discovers anything.
'search_catalog',
'get_catalog_item',
'get_item_source',
// The community skills registry is a public, PR-reviewed catalog of
// instruction files. Browsing it reads nothing about the caller.
'list_available_skills',
// Paired coins on Robinhood Chain: the launchpad's quote registry and its
// coins, read from the chain. Public on-chain state, no caller data.
'paired_markets',
'paired_coins',
'paired_coin',
// Web-domain lookups: the registrar's public availability and prices, no
// caller data. Per-caller hourly limits protect the registrar's daily quota.
'domain_search',
'domain_check',
'domain_pricing',
// The launch-lane comparison is live platform config, no caller data.
'launch_lanes',
// Documentation search reads published docs and nothing about the caller.
'search_docs',
// expand takes a signed, account-bound handle. It is listed here only so a
// signed-in caller's bare request is not sent through the payment challenge;
// an anonymous call gets a designed sign-in message, never data.
'expand',
]);
export function isPublicTool(name) {
return PUBLIC_TOOLS.has(name);
}
/**
* A scoped tool needs the scope on the caller's token. An x402 principal has no
* account, so a priced tool they paid for per call is the one case that stands
* in for the scope: the payment is the authorization.
*/
export function toolScopeSatisfied(tool, auth, name) {
if (!tool.scope || hasScope(auth.scope, tool.scope)) return true;
return auth.source === 'x402' && auth.x402Paid === true && Boolean(priceFor(name));
}
export const PROTOCOL_VERSION = '2025-06-18';
const SERVER_INFO = { name: '3d-agent-mcp', version: '1.0.0' };
const log = logger('mcp');
export function ok(id, result) {
return { jsonrpc: '2.0', id, result };
}
export function rpcError(code, message, data) {
const e = new Error(message);
e.code = code;
e.data = data;
return e;
}
export async function dispatch(msg, auth, req) {
const started = Date.now();
const id = msg.id;
const isNotification = id === undefined;
try {
// Spec-compliant clients send `jsonrpc: "2.0"`, but minimal/legacy MCP
// clients routinely omit it on discovery calls (tools/list, initialize).
// Rejecting those with -32600 broke interop and spammed the logs for no
// security gain — auth and pricing still gate every call. Tolerate an
// absent version; only reject a version that is present and wrong.
if (msg.jsonrpc != null && msg.jsonrpc !== '2.0') {
throw rpcError(-32600, 'invalid Request');
}
const method = msg.method;
if (method === 'initialize') return ok(id, await onInitialize(msg.params, auth));
if (method === 'ping') return ok(id, {});
if (method === 'notifications/initialized') return null;
if (method === 'tools/list')
return ok(id, {
tools: (await listForRequest(POLICY_SERVER, TOOL_CATALOG, auth, req)).map((t) => {
const price = priceFor(t.name);
if (!price) return t;
// USE-13: priced tools also surface a Bazaar discovery
// extension so MCP clients reading tools/list see the same
// catalog metadata facilitators index via
// /discovery/resources. The extension carries the canonical
// shape (transport, inputSchema, example) clients need to
// pay-and-call without re-reading the tool description.
const discovery = declareMcpDiscovery({
toolName: t.name,
description: t.description,
transport: 'streamable-http',
inputSchema: t.inputSchema,
});
return {
...t,
pricing: {
amount_usdc: price.amount_usdc,
currency: 'USDC',
description: price.description,
scheme: 'pump-agent-payments',
prep_endpoint: '/api/pump/accept-payment-prep',
confirm_endpoint: '/api/pump/accept-payment-confirm',
recipient_mint: resolveBillingMint(),
},
extensions: { bazaar: discovery },
};
}),
});
if (method === 'tools/call')
return ok(id, await onToolCall(msg.params, auth, started, req));
if (typeof method === 'string' && method.startsWith('resources/')) {
const result = await handleResourceMethod('mcp', method, msg.params, auth, req);
if (result !== undefined) return ok(id, result);
}
if (typeof method === 'string' && method.startsWith('prompts/')) {
const result = handlePromptMethod('mcp', TOOL_CATALOG, method, msg.params);
if (result !== undefined) return ok(id, result);
}
if (method === 'logging/setLevel') return ok(id, {});
throw rpcError(-32601, `method not found: ${method}`);
} catch (err) {
log.warn('rpc_error', { method: msg.method, code: err.code, message: err.message });
if (isNotification) return null;
return {
jsonrpc: '2.0',
id,
error: {
code: err.code || -32603,
message: err.message || 'internal error',
data: err.data,
},
};
}
}
function summarize(args) {
const o = {};
for (const [k, v] of Object.entries(args || {})) {
o[k] = typeof v === 'string' && v.length > 64 ? v.slice(0, 64) + '…' : v;
}
return o;
}
async function onInitialize(_params, _auth) {
return {
protocolVersion: PROTOCOL_VERSION,
serverInfo: SERVER_INFO,
capabilities: {
tools: { listChanged: false },
resources: RESOURCE_CAPABILITIES,
prompts: PROMPT_CAPABILITIES,
logging: {},
},
instructions: [
'Render 3D avatars stored on three.ws as <model-viewer> HTML artifacts.',
"Use list_my_avatars to see the user's avatars and render_avatar to get embeddable viewer HTML.",
'Public avatars can be discovered via search_public_avatars.',
'Give an agent persistent memory: remember stores a memory for an agent you own, recall retrieves the most relevant memories for a query, and forget deletes one.',
'Live account views are published as three:// resources (three://me, three://agents, three://agents/{id}/wallet and more); read_resource returns the same data for clients without a resource reader.',
'Guided prompts (get-started, create-agent, trade, review-costs and others) walk a user through a flow tool by tool.',
].join(' '),
};
}
async function onToolCall(params, auth, started, req) {
const { name, arguments: rawArgs = {} } = params || {};
// Own-property lookup only: a name like "__proto__" or "constructor" would
// otherwise resolve an inherited Object member and slip past the !tool guard.
const tool = typeof name === 'string' && Object.hasOwn(TOOLS, name) ? TOOLS[name] : null;
if (!tool) throw rpcError(-32602, `unknown tool: ${name}`);
// Tool policy (api/_mcp/policy.js): refuse a tool this session has not
// enabled, and a financial one without its confirm flag and fresh preview.
// The policy sees an untouched copy of what the caller sent; Ajv below fills
// defaults into the object the handler gets.
const sentArgs = { ...rawArgs };
const gate = await gateCall(POLICY_SERVER, name, sentArgs, auth, req, declaredArgs(CATALOG_BY_NAME.get(name)));
if (!gate.ok) return gate.result;
const args = gate.args === sentArgs ? rawArgs : gate.args;
if (!toolScopeSatisfied(tool, auth, name)) {
throw rpcError(-32002, `insufficient scope, requires ${tool.scope}`);
}
// Defense-in-depth: validate args against the tool's inputSchema before
// hitting the handler. Ajv mutates `args` to fill defaults + coerce types,
// matching what the handlers used to expect from informal argv shaping
// (`args.limit || 25`). When validation fails we surface the first error
// as an `invalid params` (-32602) — same code MCP clients already handle.
if (tool.validate && !tool.validate(args)) {
const first = tool.validate.errors?.[0];
const detail = first
? `${first.instancePath || '(root)'} ${first.message || 'invalid'}`
: 'invalid arguments';
throw rpcError(-32602, `invalid params for ${name}: ${detail}`);
}
// Payment gate for priced tools called by anonymous x402 principals.
//
// An x402 principal reaches here only after the HTTP layer verified an
// X-PAYMENT against this tool's per-tool price (auth.x402Paid). That single
// pay-per-call payment satisfies the charge — we do NOT additionally demand a
// pump-agent-payments subscription, which would double-bill a caller who just
// paid. The subscription path stays as an ALTERNATIVE for x402 principals who
// did not pay per-call (auth.x402Paid falsy): if they hold an active
// pump-agent-payments window for this tool we honor it, otherwise we 402 with
// the subscription challenge. This keeps advertised price == charged price.
const price = priceFor(name);
if (price && auth.source === 'x402' && !auth.x402Paid) {
const billingMint = resolveBillingMint();
const payerWallet = args.payer_wallet || auth.payer || null;
if (billingMint && payerWallet) {
const sub = await findActiveSubscription({
mint: billingMint,
network: process.env.PUMP_DEFAULT_NETWORK || 'mainnet',
payerWallet,
toolName: name,
// Only a subscription that paid at least this tool's advertised
// price counts — a confirmed-but-underpaid invoice must not unlock it.
minAmountAtomics: x402AmountForTool(name) || '0',
});
if (!sub) {
throw rpcError(-32402, 'payment required for this tool', {
scheme: 'pump-agent-payments',
tool: name,
amount_usdc: price.amount_usdc,
recipient_mint: billingMint,
prep_endpoint: '/api/pump/accept-payment-prep',
hint: 'POST a confirmed acceptPayment whose end_time > now() and tool_name matches this tool, then retry.',
});
}
auth.subscription = sub;
} else if (billingMint) {
// A price is advertised and billing is configured, but the caller gave
// no wallet to match a subscription against and did not pay per-call.
throw rpcError(-32402, 'payment required for this tool', {
scheme: 'pump-agent-payments',
tool: name,
amount_usdc: price.amount_usdc,
recipient_mint: billingMint,
prep_endpoint: '/api/pump/accept-payment-prep',
});
}
}
// Credit plans and trials (api/_lib/mcp-credits.js): debit before the call,
// refund below if it fails. Throws -32402 when a plan holder has nothing left.
const meter = await beginMeter({ auth, tool: name, args, rpcError });
try {
const result = await tool.handler(args, auth, req);
recordEvent({
userId: auth.userId,
apiKeyId: auth.apiKeyId,
clientId: auth.clientId,
kind: 'tool_call',
tool: name,
latencyMs: Date.now() - started,
meta: { args_summary: summarize(args) },
});
if (result?.isError) await refundMeter(meter);
return await finishMeter(
meter,
await finishCall(POLICY_SERVER, name, sentArgs, auth, result, gate.preview),
args,
);
} catch (err) {
await refundMeter(meter);
recordEvent({
userId: auth.userId,
apiKeyId: auth.apiKeyId,
clientId: auth.clientId,
kind: 'tool_call',
tool: name,
status: 'error',
latencyMs: Date.now() - started,
meta: { error: err.message },
});
// Only re-throw intentional JSON-RPC errors (integer codes); string codes are
// postgres SQL states (e.g. '42P01') — sanitize those rather than leaking them.
if (err.code && typeof err.code === 'number') throw err;
// Framework convention: tool errors go in result.isError, not rpc error.
// Shared sanitizer suppresses pg/driver internals + internal hostnames,
// logs full detail to stderr with a log id, and passes safe
// handler-authored messages through unchanged.
const { message } = sanitizeToolError(err, { tool: name, server: 'mcp', log });
return await finishMeter(meter, {
content: [{ type: 'text', text: `Error: ${message}` }],
isError: true,
});
}
}