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
feat(knock): publish the door as an SDK and an MCP server
nirholasc368777124ac
diff --git a/packages/knock-mcp/LICENSE b/packages/knock-mcp/LICENSEnew file mode 100644index 000000000..dff21b7f4--- /dev/null+++ b/packages/knock-mcp/LICENSE@@ -0,0 +1,20 @@+Copyright 2026 nirholas++All rights reserved.++This software is proprietary and may not be used, copied, modified, distributed,+translated, or made available to any third party without the express written+permission of the copyright owner.++No rights are granted by implication, estoppel, or otherwise. Use of this+software is subject to the terms of a separate license agreement with the+copyright owner.++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 COPYRIGHT OWNER 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.diff --git a/packages/knock-sdk/LICENSE b/packages/knock-sdk/LICENSEnew file mode 100644index 000000000..dff21b7f4--- /dev/null+++ b/packages/knock-sdk/LICENSE@@ -0,0 +1,20 @@+Copyright 2026 nirholas++All rights reserved.++This software is proprietary and may not be used, copied, modified, distributed,+translated, or made available to any third party without the express written+permission of the copyright owner.++No rights are granted by implication, estoppel, or otherwise. Use of this+software is subject to the terms of a separate license agreement with the+copyright owner.++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 COPYRIGHT OWNER 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.diff --git a/packages/knock-sdk/src/index.js b/packages/knock-sdk/src/index.jsnew file mode 100644index 000000000..c6e8eed89--- /dev/null+++ b/packages/knock-sdk/src/index.js@@ -0,0 +1,215 @@+// @three-ws/knock: reach a real person, and pay their price to do it.+//+// Every three.ws account can publish a priced door at three.ws/knock/<handle>.+// Paying its price buys exactly one message through to that person: it lands in+// their inbox and their 3D companion walks on screen and says who you are and+// what you paid. The USDC settles directly to them.+//+// This module is transport-honest and wallet-agnostic:+//+// quote(handle) what a door costs, and which lane it uses. No payment.+// knock(opts) send one. Free doors need nothing but fetch. Priced doors+// need an x402-capable fetch you supply, so this package+// never touches your keys and never picks your chain for you.+// receipt(url) read what became of a knock you sent. No account needed.+//+// Bring any x402 client: pass its paying fetch as `fetchWithPayment` and a+// priced door settles without this package ever seeing a key. A runnable+// example lives in the README.++export const DEFAULT_ORIGIN = 'https://three.ws';++export class KnockError extends Error {+ constructor(message, { code = 'knock_error', status = 0, data = null } = {}) {+ super(message);+ this.name = 'KnockError';+ this.code = code;+ this.status = status;+ this.data = data;+ }+}++function normalizeHandle(raw) {+ const handle = String(raw ?? '').trim().replace(/^@+/, '').toLowerCase();+ if (!/^[a-z0-9._-]{1,40}$/.test(handle)) {+ throw new KnockError(`"${raw}" is not a usable handle`, { code: 'bad_handle' });+ }+ return handle;+}++async function asJson(res) {+ const text = await res.text();+ let data = null;+ if (text) {+ try {+ data = JSON.parse(text);+ } catch {+ data = null;+ }+ }+ if (!res.ok) {+ throw new KnockError(data?.error_description || data?.message || `request failed (${res.status})`, {+ code: data?.error || 'http_error',+ status: res.status,+ data,+ });+ }+ return data;+}++/**+ * What a door costs and how to pay it. Pure read, no payment, no account.+ *+ * @param {string} handle+ * @param {{origin?: string, fetch?: typeof fetch}} [opts]+ * @returns {Promise<{handle:string, display_name:string, free:boolean, price:string,+ * price_atomics:string, currency:string, networks:string[], max_chars:number,+ * headline:string|null, greeting:string|null, endpoint:string, protocol:'http'|'x402'}>}+ */+export async function quote(handle, { origin = DEFAULT_ORIGIN, fetch: f = fetch } = {}) {+ const clean = normalizeHandle(handle);+ const res = await f(`${origin}/api/knock/door?handle=${encodeURIComponent(clean)}`, {+ headers: { accept: 'application/json' },+ });+ const data = await asJson(res);+ return data.door;+}++/**+ * Every door that is open and listed, cheapest first.+ * @returns {Promise<Array<{handle:string, display_name:string, price:string, price_atomics:string, headline:string|null, replies:number}>>}+ */+export async function directory({ origin = DEFAULT_ORIGIN, limit = 60, fetch: f = fetch } = {}) {+ const res = await f(`${origin}/api/knock/directory?limit=${limit}`, {+ headers: { accept: 'application/json' },+ });+ return (await asJson(res)).doors;+}++/**+ * Knock on someone's door.+ *+ * A free door needs nothing. A priced door needs `fetchWithPayment`: any+ * fetch-compatible function that answers a 402 by paying and retrying, which+ * is exactly what every x402 client exports. This package deliberately does+ * not sign anything itself, so your keys, your chain and your spending limits+ * stay in the client you already trust.+ *+ * `maxPriceAtomics` is a hard ceiling checked against the door's live price+ * BEFORE any payment is attempted. Set it whenever an agent knocks unattended:+ * a door owner can raise their price between your quote and your call.+ *+ * @param {object} opts+ * @param {string} opts.to recipient handle+ * @param {string} opts.from who is knocking, shown and spoken+ * @param {string} opts.message the message body, never read aloud+ * @param {string} [opts.subject] one line the companion says out loud+ * @param {string} [opts.url] an http(s) link about you+ * @param {'agent'|'human'|'unknown'} [opts.senderKind='agent']+ * @param {string} [opts.requestId] idempotency key; a retry returns the first knock+ * @param {string|number|bigint} [opts.maxPriceAtomics] refuse above this price+ * @param {(url:string, init:object) => Promise<Response>} [opts.fetchWithPayment]+ * @param {string} [opts.origin]+ * @returns {Promise<{ok:true, knock_id:string, delivered_to:string, paid:string,+ * receipt_url:string, duplicate:boolean, announced?:boolean, importance?:number}>}+ */+export async function knock({+ to,+ from,+ message,+ subject,+ url,+ senderKind = 'agent',+ requestId,+ maxPriceAtomics,+ fetchWithPayment,+ origin = DEFAULT_ORIGIN,+ fetch: f = fetch,+} = {}) {+ const handle = normalizeHandle(to);+ if (!from?.trim()) throw new KnockError('`from` is required: tell them who is knocking', { code: 'missing_sender' });+ if (!message?.trim()) throw new KnockError('`message` is required', { code: 'missing_message' });++ const door = await quote(handle, { origin, fetch: f });+ if (message.length > door.max_chars) {+ throw new KnockError(`this door accepts up to ${door.max_chars} characters`, { code: 'message_too_long' });+ }+ if (maxPriceAtomics !== undefined && BigInt(door.price_atomics) > BigInt(maxPriceAtomics)) {+ throw new KnockError(+ `${door.display_name} charges ${door.price}, above the ${formatUsdc(maxPriceAtomics)} ceiling you set`,+ { code: 'over_budget', data: { price_atomics: door.price_atomics } },+ );+ }++ const body = {+ from: from.trim(),+ message: message.trim(),+ sender_kind: senderKind,+ ...(subject ? { subject: String(subject).trim() } : {}),+ ...(url ? { url: String(url).trim() } : {}),+ ...(requestId ? { request_id: String(requestId) } : {}),+ };++ if (door.free) {+ const res = await f(`${origin}/api/knock/send`, {+ method: 'POST',+ headers: { 'content-type': 'application/json', accept: 'application/json' },+ body: JSON.stringify({ to: handle, ...body }),+ });+ return asJson(res);+ }++ if (typeof fetchWithPayment !== 'function') {+ throw new KnockError(+ `${door.display_name} charges ${door.price} to be reached. Pass \`fetchWithPayment\`: any x402 client's ` ++ 'paying fetch (for example wrapFetchWithPayment(fetch, wallet) from x402-fetch). ' ++ `The endpoint is ${door.endpoint}.`,+ { code: 'payment_required', data: { door } },+ );+ }++ const res = await fetchWithPayment(door.endpoint, {+ method: 'POST',+ headers: { 'content-type': 'application/json', accept: 'application/json' },+ body: JSON.stringify(body),+ });+ return asJson(res);+}++/**+ * What became of a knock you sent. Takes the `receipt_url` the knock returned.+ * Needs no account: the URL carries its own proof.+ *+ * @returns {Promise<{id:string, status:'pending'|'read'|'replied'|'dismissed',+ * reply:string|null, seen:boolean, amount:string, created_at:string}>}+ */+export async function receipt(receiptUrl, { fetch: f = fetch } = {}) {+ const res = await f(String(receiptUrl), { headers: { accept: 'application/json' } });+ return (await asJson(res)).knock;+}++/** Render USDC atomic units as a price string, the same way the API does. */+export function formatUsdc(atomics) {+ const value = BigInt(atomics ?? 0);+ const whole = value / 1000000n;+ const frac = (value % 1000000n).toString().padStart(6, '0').replace(/0+$/, '');+ const cents = frac.length <= 2 ? frac.padEnd(2, '0') : frac;+ return `$${whole.toString()}.${cents}`;+}++/**+ * The confirmation an unattended agent should show a human before it spends.+ * Returns the recipient, the amount, the token and the chain as plain strings,+ * so a CLI, a chat agent, or a UI can all print the same thing. Nothing here+ * pays: it exists so the decision to pay is always a deliberate one.+ */+export function confirmationFor(door) {+ return {+ recipient: `${door.display_name} (@${door.handle})`,+ amount: door.price,+ token: door.currency || 'USDC',+ chains: door.networks?.length ? door.networks : ['solana'],+ endpoint: door.endpoint,+ note: door.free ? 'This door is free. Nothing will be spent.' : 'The payment settles directly to the recipient.',+ };+}