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
// Remote clients: MCP clients whose configuration lives in someone else's
// cloud. Grok Bot runs on xAI's machines and keeps its connectors there, so
// there is no file on this machine to write. `setup` does everything else:
// picks the server, gets the credential the auth mode needs (a free install
// token, or a connector key that can never spend), prints the connector form's
// exact fields, copies the URL, and proves the public URL answers from outside.
//
// What to connect comes from the live directory (/.well-known/mcp.json): its
// `clients` block names each client's recommended server and install endpoint,
// and a deployment that predates the block falls back to the client's
// preferred paths among the servers the directory lists.
import os from 'node:os';
import { requestJson, request, ApiError, VERSION } from './http.js';
import { listTools, PROTOCOL_VERSION } from './mcp-http.js';
import { readStore, updateStore } from './store.js';
import { bearerFor } from './oauth.js';
import { whoami } from './auth.js';
import { systemEnv } from './paths.js';
/** none: anonymous. install: anonymous with a free install token. key: a connector API key. oauth: sign in from the client. */
export const AUTH_MODES = ['none', 'install', 'key', 'oauth'];
export const AUTH_LABELS = {
none: 'None',
install: 'None',
key: 'API key',
oauth: 'OAuth 2.1',
};
// A connector key is held unattended by a cloud agent, so it must never carry
// a scope that moves funds (api/_lib/spend-scope.js).
const SPEND_SCOPES = ['wallet:write', 'services:write'];
const CONNECTOR_MARKER = 'connector';
// The query parameter that makes a studio surface answer anonymous callers 401
// so a connector set to OAuth 2.1 starts sign-in (api/_mcp-studio/handler.js).
const SIGN_IN_PARAM = 'auth';
/** The directory's `clients` entry for a remote client, or null. */
export function directoryEntry(client, directory) {
const entry = directory?.clients?.[client.directoryKey];
return entry && typeof entry === 'object' ? entry : null;
}
function pathOf(url) {
try {
return new URL(url).pathname;
} catch {
return null;
}
}
/**
* The server a remote client is pointed at when the person names none: the
* directory's recommendation, else the first of the client's preferred paths
* the directory lists, else the first server that needs no account.
*/
export function recommendedServer(client, directory, servers) {
const entry = directoryEntry(client, directory);
const byPath = (p) => servers.find((s) => s.path === p);
return (entry?.server && byPath(pathOf(entry.server))) || client.preferredPaths.map(byPath).find(Boolean) || servers.find((s) => s.keyless) || servers[0] || null;
}
/** The auth modes a server supports as a connector. */
export function modesFor(server) {
if (server.auth === 'none') return ['none', 'install'];
if (server.keyless) return ['none', 'install', 'key', 'oauth'];
return ['key', 'oauth'];
}
/** The default mode for a server: the directory's, when it applies, else the first supported one. */
export function defaultMode(client, directory, server) {
const entry = directoryEntry(client, directory);
const fromDirectory = { none: 'none', 'api-key': 'key', oauth: 'oauth' }[entry?.auth];
const supported = modesFor(server);
if (fromDirectory && pathOf(entry.server) === server.path && supported.includes(fromDirectory)) return fromDirectory;
return supported[0];
}
export function parseMode(value) {
const v = String(value || '').trim().toLowerCase();
const alias = { 'api-key': 'key', apikey: 'key', token: 'install', anonymous: 'none' }[v] || v;
if (!AUTH_MODES.includes(alias)) throw new ApiError(`unknown --auth "${value}". Use one of: ${AUTH_MODES.join(', ')}`);
return alias;
}
/** The install endpoint: the directory's, rebased onto this origin, else the platform default. */
export function installEndpoint(client, directory, origin) {
const alt = directoryEntry(client, directory)?.alternatives?.find?.((a) => a?.install);
const p = alt ? pathOf(alt.install) : null;
return `${origin}${p || '/api/mcp-studio/install'}`;
}
/**
* The connector URL carrying a free install token for `server`. A token this
* machine already minted for the origin is reused, so running setup again
* prints the same URL and the connector keeps its budget.
*/
export async function installUrl({ client, directory, server, origin, env = systemEnv() }) {
const pick = (urls) => Object.values(urls || {}).find((u) => pathOf(u) === server.path) || null;
const saved = readStore(env).install_tokens?.[origin];
if (saved && pick(saved.connector_urls)) return { url: pick(saved.connector_urls), reused: true };
let minted;
try {
minted = await requestJson(installEndpoint(client, directory, origin), { method: 'POST' });
} catch (err) {
if (err.status === 404) throw new ApiError(`${origin} cannot mint install tokens yet; connect with --auth none, or try again after it updates`, { status: 404 });
throw err;
}
const url = pick(minted?.connector_urls) || (pathOf(minted?.connector_url) === server.path ? minted.connector_url : null);
if (!url) throw new ApiError(`${server.path} does not take install tokens; use --auth none, key or oauth`);
updateStore((s) => {
s.install_tokens = { ...(s.install_tokens || {}), [origin]: { token: minted.token, connector_urls: minted.connector_urls || { [server.path]: url }, created_at: minted.created_at || null } };
return s;
}, env);
return { url, reused: false, limits: minted.limits || null };
}
function scopeList(scope) {
return String(scope || '').split(/\s+/).filter(Boolean);
}
/** Why a key must not be handed to an unattended connector, or null when it may. */
export function connectorKeyProblem(scope) {
const spend = scopeList(scope).filter((s) => SPEND_SCOPES.includes(s));
if (spend.length) return `this key carries ${spend.join(' and ')}, which moves funds; a cloud agent holds a connector key unattended. Make one with "For an AI agent" at /dashboard/api, or let setup mint one`;
return null;
}
/** Check a key someone brought: it must verify and must not be able to spend. */
export async function checkConnectorKey({ origin, key }) {
let me;
try {
me = await whoami(origin, key);
} catch (err) {
if (err.status === 401) throw new ApiError('three.ws does not recognize that key; it may be revoked or expired', { status: 401 });
throw err;
}
const scope = me.credential?.scope || '';
const problem = connectorKeyProblem(scope);
if (problem) throw new ApiError(problem);
return { key, scope, connector: scopeList(scope).includes(CONNECTOR_MARKER), reused: true };
}
/**
* A connector key for the signed-in account: the one this machine minted
* before when it still verifies, else a new one from the `connector` preset,
* which reads, generates and edits agent data and never spends.
*/
export async function connectorKey({ origin, label, env = systemEnv() }) {
const saved = readStore(env).connector_keys?.[origin];
if (saved?.key) {
try {
return await checkConnectorKey({ origin, key: saved.key });
} catch (err) {
if (err.status !== 401) throw err;
}
}
const bearer = await bearerFor(env, { origin });
if (!bearer) throw new ApiError('sign in first so setup can mint a connector key: `npx three-ws login`, or pass --connector-key sk_live_...');
const res = await requestJson(`${origin}/api/api-keys`, {
method: 'POST',
headers: { authorization: `Bearer ${bearer}` },
// The preset fixes the scopes server side. `scope` names the marker too,
// so a deployment that predates the preset refuses the request with 400
// instead of minting a standard key in its place.
json: { name: `${label} (three-ws CLI on ${os.hostname()})`.slice(0, 80), preset: CONNECTOR_MARKER, scope: `avatars:read ${CONNECTOR_MARKER}` },
}).catch((err) => {
if (err.status === 400) throw new ApiError(`${origin} cannot mint connector keys from the CLI yet. Make one at ${origin}/dashboard/api ("For an AI agent") and pass it with --connector-key`, { status: 400 });
throw err;
});
const minted = res.data;
if (!scopeList(minted.scope).includes(CONNECTOR_MARKER) || connectorKeyProblem(minted.scope)) {
throw new ApiError(`the key ${origin} minted is not a connector key (scope: ${minted.scope}); revoke ${minted.prefix} at ${origin}/dashboard/api`);
}
updateStore((s) => {
s.connector_keys = { ...(s.connector_keys || {}), [origin]: { key: minted.token, prefix: minted.prefix, key_id: minted.id, scope: minted.scope } };
return s;
}, env);
return { key: minted.token, scope: minted.scope, connector: true, reused: false };
}
/** The URL the connector form takes for this server and mode. */
export function connectorUrl(server, mode, { install = null } = {}) {
if (mode === 'install') return install;
if (mode === 'oauth' && server.keyless) {
const u = new URL(server.url);
u.searchParams.set(SIGN_IN_PARAM, 'oauth');
return u.toString();
}
return server.url;
}
/** The fields the client's connector form asks for, in its order. */
export function connectorFields({ client, server, mode, url, key = null }) {
const fields = [
['Name', server.slug],
['Transport', client.transport],
['Server URL', url],
['Authentication', AUTH_LABELS[mode]],
];
if (mode === 'key') fields.push(['Header', 'Authorization'], ['Value', `Bearer ${key}`]);
if (mode === 'oauth') fields.push(['Client ID', 'leave empty: the connector registers itself']);
return fields;
}
/** The sentence to paste into the client's chat instead of filling the form. A key never goes in chat. */
export function sayLine({ server, mode, url }) {
if (mode === 'key') return null;
return `Add a custom MCP server called ${server.slug} at ${url}${mode === 'oauth' ? ' with OAuth authentication' : ''}`;
}
const PRIVATE_HOST = /^(localhost|.*\.localhost|.*\.local|.*\.internal|127\.\d+\.\d+\.\d+|10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(1[6-9]|2\d|3[01])\.\d+\.\d+|169\.254\.\d+\.\d+|0\.0\.0\.0|\[?::1\]?|\[?f[cd][0-9a-f]{2}:.*)$/i;
/** True when a cloud client can reach the URL: https on a public host name. */
export function isPublicUrl(url) {
try {
const u = new URL(url);
return u.protocol === 'https:' && !PRIVATE_HOST.test(u.hostname);
} catch {
return false;
}
}
async function oauthChecks(url) {
const checks = [];
const res = await request(url, {
method: 'POST',
headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream', 'mcp-protocol-version': PROTOCOL_VERSION },
json: { jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: 'three-ws-cli', version: VERSION } } },
});
await res.text();
const challenge = res.headers.get('www-authenticate') || '';
const metadata = /resource_metadata="([^"]+)"/.exec(challenge)?.[1] || null;
const asks = res.status === 401 && Boolean(metadata);
checks.push({ id: 'oauth-challenge', label: 'asks an anonymous client to sign in', ok: asks, detail: asks ? `401, ${new URL(metadata).pathname}` : `answered ${res.status}${challenge ? '' : ' with no www-authenticate'}` });
if (!asks) return checks;
try {
const doc = await requestJson(metadata);
const servers = Array.isArray(doc?.authorization_servers) ? doc.authorization_servers : [];
checks.push({ id: 'oauth-metadata', label: 'publishes its authorization server', ok: servers.length > 0, detail: servers[0] || 'no authorization_servers' });
} catch (err) {
checks.push({ id: 'oauth-metadata', label: 'publishes its authorization server', ok: false, detail: err.message });
}
return checks;
}
/**
* The live check, made from this machine exactly as the cloud client will
* call: the public URL, the connector's own credential, a real initialize and
* tools/list. Never throws; each check carries its own result.
*/
export async function verifyConnector({ url, mode, key = null }) {
const checks = [];
const reachable = isPublicUrl(url);
checks.push({ id: 'public', label: 'public https URL a cloud agent can reach', ok: reachable, detail: reachable ? new URL(url).host : `${new URL(url).host} is not reachable from the internet; use the public deployment` });
try {
const { tools, serverInfo } = await listTools(url, { bearer: mode === 'key' ? key : null });
const name = serverInfo?.name ? ` from ${serverInfo.name}${serverInfo.version ? ` ${serverInfo.version}` : ''}` : '';
if (mode === 'oauth') {
// A client only starts OAuth on a 401, so a URL that serves anonymous
// callers would leave the connector signed out forever.
checks.push({ id: 'oauth-challenge', label: 'asks an anonymous client to sign in', ok: false, detail: `answered anonymously with ${tools.length} tools, so sign-in never starts` });
} else {
checks.push({ id: 'tools', label: 'initialize + tools/list', ok: tools.length > 0, detail: `${tools.length} tools${name}`, tools: tools.length });
}
} catch (err) {
if (mode === 'oauth' && err.status === 401) checks.push(...(await oauthChecks(url).catch((e) => [{ id: 'oauth-challenge', label: 'asks an anonymous client to sign in', ok: false, detail: e.message }])));
else checks.push({ id: 'tools', label: 'initialize + tools/list', ok: false, detail: err.message });
}
return checks;
}