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
// Guided MCP prompts (api/_mcp/prompts.js): every prompt the spec requires is
// offered somewhere, and every prompt a server lists renders with every tool
// and resource it names actually published by that server's tools/list.
import { describe, it, expect } from 'vitest';
const { PROMPTS, promptsFor, renderPrompt, handlePromptMethod } = await import('../api/_mcp/prompts.js');
const { TOOL_CATALOG: mainCatalog } = await import('../api/_mcp/catalog.js');
const { TOOL_CATALOG: agentCatalog } = await import('../api/_mcpagent/catalog.js');
const { TOOL_CATALOG: studioCatalog } = await import('../api/_mcp3d/catalog.js');
const { TOOL_CATALOG: bazaarCatalog } = await import('../api/_mcpbazaar/catalog.js');
const { toolCatalogFor, dispatch: studioDispatch } = await import('../api/_mcp-studio/dispatch.js');
const { isAccountTool } = await import('../api/_mcp-studio/account-tools.js');
const SERVERS = { mcp: mainCatalog, 'mcp-agent': agentCatalog, 'mcp-3d': studioCatalog, 'mcp-bazaar': bazaarCatalog };
// The studio surfaces (x-grok order 031). /api/mcp-grok lists the account's
// agent tools on top of the studio for a signed-in caller, so it renders twice.
const freeStudio = toolCatalogFor('full');
const grokAnon = toolCatalogFor('grok');
const grokSignedIn = [...grokAnon, ...mainCatalog.filter((t) => isAccountTool(t.name))];
const AGENT_SURFACES = [
['mcp-studio', 'mcp-studio', freeStudio],
['mcp-grok', 'mcp-grok', grokAnon],
['mcp-grok signed in', 'mcp-grok', grokSignedIn],
];
const AGENT_PROMPTS = ['agent-get-started', 'daily-3d-brief', 'asset-pack', 'avatar-from-photo', 'agent-report'];
const GENERATION_PROMPTS = ['daily-3d-brief', 'asset-pack', 'avatar-from-photo'];
const REQUIRED = [
'get-started', 'create-agent', 'setup-wallet', 'trade', 'launch-token', 'hire-agent', 'sell-a-skill',
'review-costs', 'setup-automations', 'setup-dca', 'explore-marketplace', 'explore-x402', 'earn-yield',
'perps', 'predictions', 'embed-avatar', 'generate-3d',
];
// The repo bans the en dash and em dash (U+2013, U+2014) in all copy.
const BANNED_DASHES = new RegExp(`[${String.fromCharCode(0x2013, 0x2014)}]`);
const AGENT = '33333333-3333-4333-8333-333333333333';
function sampleArgs(prompt) {
return Object.fromEntries(
prompt.arguments.map((a) => [
a.name,
a.name === 'agentId' ? AGENT : a.name === 'token' ? 'THREEsynthetic1111' : a.name === 'image_url' ? 'https://three.ws/og.png' : `sample ${a.name}`,
]),
);
}
// Every backticked snake_case identifier in a rendered prompt is a tool name,
// a resource field or an argument; the ones that match a tool on ANY server
// must be tools on THIS server.
const ALL_TOOL_NAMES = new Set([...Object.values(SERVERS), grokSignedIn].flatMap((c) => c.map((t) => t.name)));
function backtickedTools(text) {
return [...text.matchAll(/`([a-z][a-z0-9]*(?:_[a-z0-9]+)+)`/g)].map((m) => m[1]).filter((n) => ALL_TOOL_NAMES.has(n));
}
describe('prompt catalog', () => {
it('defines every required prompt with unique names', () => {
const names = PROMPTS.map((p) => p.name);
expect(new Set(names).size).toBe(names.length);
for (const name of REQUIRED) expect(names, name).toContain(name);
});
it('offers every required prompt on at least one hosted server', () => {
const offered = new Set(Object.entries(SERVERS).flatMap(([s, c]) => promptsFor(s, c).map((p) => p.name)));
for (const name of REQUIRED) expect(offered, name).toContain(name);
});
it('offers get-started on every server', () => {
for (const [server, catalog] of Object.entries(SERVERS)) {
expect(promptsFor(server, catalog).map((p) => p.name), server).toContain('get-started');
}
});
});
describe('every listed prompt renders against its server', () => {
for (const [server, catalog] of Object.entries(SERVERS)) {
const toolNames = new Set(catalog.map((t) => t.name));
for (const prompt of promptsFor(server, catalog)) {
it(`${server} ${prompt.name}`, () => {
const out = renderPrompt(server, catalog, prompt.name, sampleArgs(prompt));
const text = out.messages[0].content.text;
expect(out.messages[0].role).toBe('user');
expect(text.length).toBeGreaterThan(80);
expect(out.tools.length).toBeGreaterThan(0);
for (const t of out.tools) expect(toolNames, `${prompt.name} names ${t}`).toContain(t);
for (const t of backtickedTools(text)) expect(toolNames, `${prompt.name} text names ${t}`).toContain(t);
expect(text).not.toMatch(BANNED_DASHES);
});
}
}
});
describe('agent prompts render against every surface that lists them', () => {
for (const [label, server, catalog] of AGENT_SURFACES) {
const toolNames = new Set(catalog.map((t) => t.name));
for (const prompt of promptsFor(server, catalog)) {
it(`${label} ${prompt.name}`, () => {
const out = renderPrompt(server, catalog, prompt.name, sampleArgs(prompt));
const text = out.messages[0].content.text;
expect(out.tools.length).toBeGreaterThan(0);
for (const t of out.tools) expect(toolNames, `${prompt.name} names ${t}`).toContain(t);
for (const t of backtickedTools(text)) expect(toolNames, `${prompt.name} text names ${t}`).toContain(t);
expect(text).not.toMatch(BANNED_DASHES);
});
}
}
});
describe('agent prompts for an unattended agent (x-grok order 031)', () => {
const names = (server, catalog) => promptsFor(server, catalog).map((p) => p.name);
it('lists them on the right surfaces', () => {
expect(names('mcp-studio', freeStudio)).toEqual(['agent-get-started', 'daily-3d-brief', 'asset-pack', 'avatar-from-photo']);
expect(names('mcp-grok', grokAnon)).toEqual(['agent-get-started', 'daily-3d-brief', 'asset-pack', 'avatar-from-photo']);
expect(names('mcp-grok', grokSignedIn)).toEqual(AGENT_PROMPTS);
// The core server holds the account tools and no free generation.
expect(names('mcp', mainCatalog)).toEqual(expect.arrayContaining(['agent-get-started', 'agent-report']));
for (const name of GENERATION_PROMPTS) expect(names('mcp', mainCatalog)).not.toContain(name);
});
it('keeps the human prompts off the studio surfaces', () => {
for (const [, server, catalog] of AGENT_SURFACES) {
for (const name of names(server, catalog)) expect(AGENT_PROMPTS, `${server} lists ${name}`).toContain(name);
}
});
it('keys every generation call with an idempotency_key', () => {
for (const name of GENERATION_PROMPTS) {
const def = PROMPTS.find((p) => p.name === name);
const text = renderPrompt('mcp-grok', grokAnon, name, sampleArgs(def)).messages[0].content.text;
const calls = [...text.matchAll(/`(forge_free|forge_avatar|refine_model|rig_mesh|mesh_forge|text_to_avatar)` with `(\{[^`]*\})`/g)];
expect(calls.length, name).toBeGreaterThan(0);
for (const [, tool, json] of calls) expect(JSON.parse(json), `${name} ${tool}`).toHaveProperty('idempotency_key');
}
});
it('spells out argument objects that validate against each tool schema', () => {
const byName = new Map(grokSignedIn.map((t) => [t.name, t]));
for (const name of AGENT_PROMPTS) {
const def = PROMPTS.find((p) => p.name === name);
const text = renderPrompt('mcp-grok', grokSignedIn, name, sampleArgs(def)).messages[0].content.text;
for (const [, tool, json] of text.matchAll(/`([a-z_]+)` with `(\{[^`]*\})`/g)) {
const props = byName.get(tool).inputSchema.properties;
for (const key of Object.keys(JSON.parse(json))) expect(props, `${name}: ${tool}.${key}`).toHaveProperty(key);
}
}
});
it('a renamed tool or argument breaks the render instead of shipping a dead call', () => {
const renamed = freeStudio.map((t) => (t.name === 'forge_free' ? { ...t, name: 'forge_model' } : t));
expect(names('mcp-studio', renamed)).not.toContain('daily-3d-brief');
expect(() => renderPrompt('mcp-studio', renamed, 'daily-3d-brief', {})).toThrow(expect.objectContaining({ code: -32602 }));
const noKey = freeStudio.map((t) => {
if (t.name !== 'forge_free') return t;
const { idempotency_key: _gone, ...properties } = t.inputSchema.properties;
return { ...t, inputSchema: { ...t.inputSchema, properties } };
});
expect(() => renderPrompt('mcp-studio', noKey, 'daily-3d-brief', {})).toThrow(/idempotency_key/);
});
it('daily-3d-brief picks a trending topic itself unless given one', () => {
const trending = renderPrompt('mcp-studio', freeStudio, 'daily-3d-brief', {}).messages[0].content.text;
expect(trending).toMatch(/most talked-about topic/);
const given = renderPrompt('mcp-studio', freeStudio, 'daily-3d-brief', { topic: 'the solar eclipse' }).messages[0].content.text;
expect(given).toContain('the solar eclipse');
expect(given).toContain('poster_png_url');
});
it('asset-pack clamps its count and searches before it generates', () => {
const text = renderPrompt('mcp-studio', freeStudio, 'asset-pack', { theme: 'retro arcade', count: '40' }).messages[0].content.text;
expect(text).toContain('a pack of 12 3D assets');
expect(text.indexOf('`search_catalog`')).toBeLessThan(text.indexOf('`forge_free`'));
});
it('avatar-from-photo returns a pose studio link', () => {
const text = renderPrompt('mcp-grok', grokAnon, 'avatar-from-photo', { image_url: 'https://three.ws/og.png' }).messages[0].content.text;
expect(text).toContain('https://three.ws/pose?src=');
expect(text).toContain('"image_url":"https://three.ws/og.png"');
});
});
describe('studio dispatcher prompts/*', () => {
const call = (surface, method, params = {}) => studioDispatch({ jsonrpc: '2.0', id: 1, method, params }, null, { headers: {} }, { surface });
it('serves the agent prompts on the free studio and none on ChatGPT', async () => {
const full = await call('full', 'prompts/list');
expect(full.result.prompts.map((p) => p.name)).toEqual(['agent-get-started', 'daily-3d-brief', 'asset-pack', 'avatar-from-photo']);
expect((await call('chatgpt', 'prompts/list')).result.prompts).toEqual([]);
expect((await call('full', 'initialize')).result.capabilities.prompts).toEqual({ listChanged: false });
expect((await call('chatgpt', 'initialize')).result.capabilities.prompts).toBeUndefined();
});
it('renders prompts/get and refuses a missing required argument', async () => {
const got = await call('full', 'prompts/get', { name: 'asset-pack', arguments: { theme: 'space station', count: '3' } });
expect(got.result.messages[0].content.text).toContain('a pack of 3 3D assets for the theme "space station"');
const missing = await call('full', 'prompts/get', { name: 'avatar-from-photo', arguments: {} });
expect(missing.error.code).toBe(-32602);
});
});
describe('venue prompts run on the tools that exist and hand signing to the page that owns it', () => {
it('trade researches with live tools and hands the swap to the wallet page', () => {
const out = renderPrompt('mcp', mainCatalog, 'trade', { agentId: AGENT, token: 'THREEsynthetic1111' });
expect(out.tools).toEqual(expect.arrayContaining(['token_snapshot', 'read_resource']));
expect(out.messages[0].content.text).toContain(`/agents/${AGENT}/wallet#trade`);
});
it('launch-token compares the live launch lanes and sends signing to /launch', () => {
const out = renderPrompt('mcp', mainCatalog, 'launch-token', { agentId: AGENT, name: 'Synthetic', symbol: 'SYN' });
expect(out.tools).toContain('launch_lanes');
expect(out.messages[0].content.text).toContain('https://three.ws/launch');
});
it('lending stays research-only and never names an execution tool', () => {
const out = renderPrompt('mcp', mainCatalog, 'earn-yield', { agentId: AGENT });
expect(out.tools).toEqual(expect.arrayContaining(['crypto_data', 'read_resource']));
expect(out.messages[0].content.text).toMatch(/do not move funds from here/i);
});
it('perps preview then execute with the confirm flag on mcp-agent, and point there from mcp', () => {
const out = renderPrompt('mcp-agent', agentCatalog, 'perps', { agentId: AGENT, market: 'SOL' });
expect(out.tools).toEqual(expect.arrayContaining(['perps_account', 'perps_markets', 'perps_order_preview', 'perps_order_execute']));
const text = out.messages[0].content.text;
expect(text).toContain('`confirm_trade: true`');
expect(text.indexOf('perps_order_preview')).toBeLessThan(text.indexOf('perps_order_execute'));
const main = renderPrompt('mcp', mainCatalog, 'perps', { agentId: AGENT });
expect(main.tools).toEqual(expect.arrayContaining(['crypto_data', 'read_resource']));
expect(main.messages[0].content.text).toContain('https://three.ws/api/mcp-agent');
expect(main.messages[0].content.text).not.toContain('perps_order_execute');
expect(main.messages[0].content.text).toMatch(/do not open positions from here/i);
});
it('predictions preview then place with the confirm flag on mcp-agent, and point there from mcp', () => {
const out = renderPrompt('mcp-agent', agentCatalog, 'predictions', { agentId: AGENT, topic: 'synthetic event' });
expect(out.tools).toEqual(expect.arrayContaining(['predictions_events', 'predictions_open_preview', 'predictions_open']));
expect(out.messages[0].content.text).toContain('`confirm_trade: true`');
const main = renderPrompt('mcp', mainCatalog, 'predictions', { agentId: AGENT }).messages[0].content.text;
expect(main).toContain('https://three.ws/api/mcp-agent');
expect(main).not.toContain('predictions_open');
});
});
describe('prompts/* methods', () => {
it('lists prompts with arguments', () => {
const out = handlePromptMethod('mcp-agent', agentCatalog, 'prompts/list', {});
const wallet = out.prompts.find((p) => p.name === 'setup-wallet');
expect(wallet.arguments).toEqual([{ name: 'agentId', description: expect.any(String), required: true }]);
});
it('rejects a missing required argument and an unknown prompt with -32602', () => {
expect(() => handlePromptMethod('mcp-agent', agentCatalog, 'prompts/get', { name: 'setup-wallet' })).toThrow(
expect.objectContaining({ code: -32602 }),
);
expect(() => handlePromptMethod('mcp-bazaar', bazaarCatalog, 'prompts/get', { name: 'create-agent', arguments: { name: 'x' } })).toThrow(
expect.objectContaining({ code: -32602 }),
);
});
it('ignores methods it does not own', () => {
expect(handlePromptMethod('mcp', mainCatalog, 'tools/list', {})).toBeUndefined();
});
});