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
// `knock_send`: get one message through to a person.
//
// This tool deliberately CANNOT spend. A free door is sent immediately, because
// nothing moves. A priced door returns the exact recipient, amount, token and
// chain, plus the endpoint, and stops: paying is an act that belongs to the
// wallet the human controls, not to an MCP server holding a key in an env var.
// The agent shows those facts, the human approves, and the payment happens in
// their own x402 client (@three-ws/knock, or any other).
import { z } from 'zod';
import { apiRequest } from '../lib/api.js';
export const def = {
name: 'knock_send',
title: 'Knock on a door',
annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
description:
'Send exactly one message to a person through their three.ws door. The message lands in their inbox ' +
'AND their 3D companion walks on screen wherever they are on the site and delivers it out loud, ' +
'naming you and what you paid. On a FREE door this sends immediately. On a PRICED door this tool ' +
'does not pay and cannot pay: it returns `payment_required` together with the recipient, the amount, ' +
'the token, the chain and the endpoint, so a human can approve the spend and pay from their own ' +
'wallet (npx @three-ws/knock, or any x402 client). Pass `request_id` to make retries safe: the same ' +
'id never knocks, or charges, twice. Refusals (shut door, daily cap, message too long) happen before ' +
'any payment, so a rejected knock is never a paid one. Use this when you have one message for a specific ' +
'person; call knock_quote first on a priced door so the human approves the live price.',
inputSchema: {
to: z.string().min(1).max(40).describe('Recipient username, with or without the @.'),
from: z.string().min(1).max(64).describe('Who is knocking. Shown to them and spoken out loud.'),
message: z.string().min(8).max(2000).describe('The message. Shown in full, never read aloud.'),
subject: z.string().max(120).optional().describe('One line their companion says out loud. Make it the reason you are knocking.'),
url: z.string().max(400).optional().describe('An http(s) link about you.'),
request_id: z.string().max(80).optional().describe('Idempotency key. A retry returns the first knock instead of knocking twice.'),
},
async handler({ to, from, message, subject, url, request_id: requestId }) {
const handle = String(to).replace(/^@+/, '');
const { door } = await apiRequest('/api/knock/door', { query: { handle } });
if (!door.free) {
return {
ok: false,
error: 'payment_required',
message: `${door.display_name} charges ${door.price} to be reached. This server does not hold a wallet, so a human has to approve and pay.`,
confirm: {
recipient: `${door.display_name} (@${door.handle})`,
amount: door.price,
token: door.currency,
chains: door.networks,
endpoint: door.endpoint,
settles_to: 'the recipient directly, not to three.ws',
},
how_to_pay: `npx @three-ws/knock send ${door.handle} "<message>" --from "${from}" --payer ./payer.mjs`,
};
}
const body = {
to: handle,
from,
message,
sender_kind: 'agent',
...(subject ? { subject } : {}),
...(url ? { url } : {}),
...(requestId ? { request_id: requestId } : {}),
};
const data = await apiRequest('/api/knock/send', { method: 'POST', body });
return {
ok: true,
knock_id: data.knock_id,
delivered_to: data.delivered_to,
duplicate: data.duplicate,
paid: data.paid,
receipt_url: data.receipt_url,
next: 'Poll receipt_url with knock_receipt to see whether they replied.',
};
},
};