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
docs(mcp): write every guided prompt out as its ordered tool calls, held to the live catalogs by a test
nirholas563529648fa4
diff --git a/docs/mcp.md b/docs/mcp.mdindex a8967c7fe..c64ac98a7 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -1071,7 +1071,7 @@ Each server offers short guided workflows through `prompts/list` and `prompts/ge| `embed-avatar` | `agentId` | mcp | Paste-ready `<agent-3d>` embed code and a preview || `generate-3d` | `prompt` | mcp-3d | Sharpen the prompt, generate, poll, optionally rig, save to your library |-`prompts/list` on a server is the authoritative list for that server; `/.well-known/mcp.json` and each `server*.json` manifest carry the same lists.+`prompts/list` on a server is the authoritative list for that server; `/.well-known/mcp.json` and each `server*.json` manifest carry the same lists. Every prompt is written out step by step, as the exact tool and resource calls it drives, under [Use cases](#use-cases).### Worked example: get a prompt@@ -1086,6 +1086,257 @@ Every prompt that can move funds ends with the same rules: show the recipient, a---+## Use cases++Each guided prompt above, written out as the calls an agent makes, in order. Read a use case top to bottom and you have the workflow: which tool or resource to call, what to show the user, and where the user has to say yes. Resources (`three://...` URIs) are read with `resources/read`, or with the `read_resource` tool on clients without a resource UI. Steps marked **Spends money.** move funds or charge the user; every one of them waits for an explicit yes after showing the amount, the token, the chain and the recipient.++Some prompts run differently depending on the server, because each server publishes a different tool set; those use cases list each server separately. `tests/mcp-use-cases-doc.test.js` renders every prompt against every server's live `tools/list` and fails when a tool named here is gone, when a prompt starts calling a tool this section does not name, or when a prompt has no use case here.++### Get started (`get-started`)++Goal: orient a new user on what the server does, their account and agents, and the best first thing to try.++On `mcp`, `mcp-agent` and `mcp-3d`:++1. `getting_started`: summarize in three lines what this server can do.+2. `read_resource` on `three://me`: confirm the user is signed in; if not, explain OAuth or an API key from [Dashboard, API keys](https://three.ws/dashboard/api-keys) and stop.+3. `read_resource` on `three://agents`: list the user's agents by name with their Solana address.+4. Suggest the single best next guided prompt from the ones this server lists.++On `mcp-bazaar`:++1. `getting_started`: summarize in three lines what this server can do.+2. `read_resource` on `three://me`: confirm the user is signed in.+3. Suggest the best next guided prompt: hiring an agent, the marketplace, or x402 services.++### Create an agent (`create-agent`)++Goal: create a new agent with a name, persona and brain model, then give it a body.++On `mcp`:++1. `read_resource` on `three://models`: confirm the chosen model is available, or recommend one free and one paid model with prices.+2. `identity_check` with the name and description: catch a look-alike of an existing public agent before creating.+3. Show the name, persona and model, and wait for the go-ahead.+4. `create_agent`: creates the agent with a custodial Solana wallet. Moves no funds.+5. `read_resource` on `three://agents/{agentId}`: show the new agent's page URL and Solana address.+6. `list_my_avatars`, then `attach_avatar_to_agent` with the avatar the user picks.+7. Next: fund the wallet with the Set up an agent wallet use case on `mcp-agent`, or embed the agent on a site.++### Set up an agent wallet (`setup-wallet`)++Goal: provision, review and fund an agent's Solana wallet, and get notified of transfers.++On `mcp-agent`:++1. `read_resource` on `three://agents/{agentId}/wallet`: is there a wallet yet?+2. `provision_wallet` with the agent id on mainnet, only if the address is null. Creates a wallet, moves no funds.+3. `wallet_status`: address, SOL and USDC balances, spending caps.+4. Walk through the guard settings (daily and per-transaction USD limits, withdraw allowlist, freeze switch), changed on the agent's wallet page.+5. **Spends money.** The user funds the wallet by sending SOL or USDC on Solana to the address from their own wallet. The agent never sends funds from here.+6. `resources/subscribe` on `three://agents/{agentId}/wallet`: notified after every transfer in or out.++### Research and trade a token (`trade`)++Goal: research a Solana token, check the agent's balance and limits, then trade it with explicit confirmation.++On `mcp`:++1. `token_snapshot` with the mint: price, liquidity, market cap and holders.+2. `pumpfun_token_intel` with the mint: creator history and risk flags.+3. `oracle_coin` with the mint: conviction score and its reasons.+4. `read_resource` on `three://agents/{agentId}/wallet`: balance, trade limits (per-trade SOL, daily budget, max slippage) and freeze state.+5. Summarize the risks and the case for and against in five lines.+6. **Spends money.** Swap execution is not enabled on this server yet, so the user quotes and confirms the swap on the agent's wallet page (`/agents/{agentId}/wallet#trade`). The prompt switches to quoting and executing in MCP once those tools ship.++### Launch a token (`launch-token`)++Goal: launch a token from an agent, with the name, symbol and cost confirmed first.++On `mcp`:++1. `read_resource` on `three://launches`: what this account launched before; flag a repeated name or symbol.+2. `pumpfun_recent_graduations`: what recently graduated launches have in common.+3. `read_resource` on `three://agents/{agentId}/wallet`: enough SOL for the launch fee?+4. Show the name, symbol, description, image, launching wallet and cost, and wait for a yes.+5. **Spends money.** Launching from MCP is not enabled yet: the user reviews and signs the launch on [/launch](https://three.ws/launch). Then `read_resource` on `three://launches` to confirm it landed.++### Hire an agent for a task (`hire-agent`)++Goal: find an agent or paid service that does the task, compare prices, and hire it with a confirmed, capped spend.++On `mcp-agent` (pays from the agent wallet):++1. `find_services` with the task as the query: the three best matches with price and network, Solana first.+2. `wallet_status`: the balance and spending caps cover the price.+3. Show the service, resource URL, exact price and paying wallet, and wait for a yes.+4. **Spends money.** `pay_and_call` with that resource URL and the maximum price set to the quote, so it refuses to pay more.+5. Show the result and the payment receipt.++On `mcp`:++1. `read_resource` on `three://marketplace`: agents and services that fit the task, with price, free-trial uses and completion stats.+2. `call_agent` with the chosen agent and a clear brief.+3. To pay a priced service from a wallet, continue on `mcp-agent` (above).++On `mcp-bazaar`:++1. `search_services` with the task as the query: the best matches, Solana first.+2. `get_service` on the pick: exact price, networks and input schema.+3. To pay and call it, continue on `mcp-agent` (above).++### Sell a skill (`sell-a-skill`)++Goal: price one of an agent's capabilities and publish it as a paid service other agents can call.++On `mcp-agent`:++1. `read_resource` on `three://agents/{agentId}`: its skills and any prices already set.+2. `read_resource` on `three://marketplace`: what comparable skills and services charge.+3. `read_resource` on `three://agents/{agentId}/wallet`: which wallet receives the revenue.+4. Agree on the name, description, USDC price per call, the https endpoint that does the work, and the network (Solana by default).+5. `monetize_endpoint` with the agent id and those values. Publishing moves no funds; buyers pay per call.+6. Show the listing URL and how buyers call it.++### Review costs (`review-costs`)++Goal: break down an agent's model, tool and credit spend this month and find the biggest saving.++On `mcp`:++1. `read_resource` on `three://agents/{agentId}/usage`: this month's LLM calls, tokens and cost per model, tool calls per tool, credit balance.+2. `read_resource` on `three://models`: current prices per million tokens.+3. `read_resource` on `three://me`: the daily MCP quota and what is left today.+4. A short table (model, calls, tokens, cost) and the one change that saves the most, with its estimated monthly saving.+5. If credits are low, point to [/credits](https://three.ws/credits).++### Set up automations (`setup-automations`)++Goal: put an agent on autopilot with conviction watches, copy trading and standing wallet intents, simulated first.++On `mcp`:++1. `read_resource` on `three://agents/{agentId}/intents` and `three://agents/{agentId}/orders`: what is already running.+2. `read_resource` on `three://agents/{agentId}/wallet`: balance, trade limits and freeze state.+3. `oracle_watch_status`, then `oracle_arm_watch` in simulate mode, which only logs what it would buy.+4. **Spends money.** Switching the watch to live mode buys with real SOL from the agent wallet: show the per-trade cap and daily budget and wait for a yes first.+5. `trader_leaderboard` to pick a leader, then `copy_subscribe` with a per-trade cap and daily budget. Non-custodial: it creates intents the user acts on from the copy dashboard.+6. Standing wallet intents are created and confirmed on the agent's wallet page.+7. List every automation now active and how to switch each one off.++### Set up dollar-cost averaging (`setup-dca`)++Goal: plan a recurring buy, check the wallet, and start it with a confirmed permission.++On `mcp`:++1. `read_resource` on `three://agents/{agentId}/dca`: strategies already running and how their last executions went.+2. `read_resource` on `three://agents/{agentId}/wallet`: balance and limits.+3. `token_snapshot` on the token to accumulate: liquidity and volatility.+4. Propose an amount per buy and a period, and show the total committed over three months.+5. **Spends money.** The user signs the spending permission on [/recurring](https://three.ws/recurring). Then `read_resource` on `three://agents/{agentId}/dca` to confirm it is active.++On `mcp-agent`:++1. `read_resource` on `three://agents/{agentId}/dca`: strategies already running.+2. `read_resource` on `three://agents/{agentId}/wallet`: balance and limits.+3. Propose an amount per buy and a period, and show the total committed over three months.+4. **Spends money.** The user signs the spending permission on [/recurring](https://three.ws/recurring), then the plan is read back to confirm it is active.++### Explore the marketplace (`explore-marketplace`)++Goal: browse paid agent skills and services with prices, free trials and track records.++On `mcp`:++1. `read_resource` on `three://marketplace`.+2. Group the skills by what they do: the three best per group with price, pricing type and free-trial uses.+3. Agent-to-agent services by completion count and rating, best first, plus any trials the user still holds.+4. `call_agent` with a short test request to try one.++On `mcp-agent` and `mcp-bazaar`:++1. `read_resource` on `three://marketplace`.+2. Group the skills by what they do: the three best per group with price, pricing type and free-trial uses.+3. Agent-to-agent services by completion count and rating, best first, plus any trials the user still holds.+4. To hire one, continue with the Hire an agent use case.++### Explore x402 services (`explore-x402`)++Goal: find paid x402 services for a capability, compare prices and networks, and see exactly how to pay.++On `mcp-agent`:++1. `find_services` with the capability as the query: the best matches with price and network, Solana first.+2. Show the pick with its exact price and wait for a yes.+3. **Spends money.** `pay_and_call` with its resource URL and the maximum price set to the quote.++On `mcp-bazaar`:++1. `search_services` with the capability as the query (or `browse_services` with no query): the best matches, Solana first.+2. `get_service` on the pick: exact price, networks, recipient and input schema.+3. To pay and call it, continue on `mcp-agent`.++On `mcp`:++1. `read_resource` on `three://x402/services`: services matching the capability, Solana first, with price and facilitator.+2. To pay and call one, continue on `mcp-agent`.++### Earn yield (`earn-yield`)++Goal: put an agent's idle funds to work in lending, with markets compared first.++On `mcp`:++1. `read_resource` on `three://agents/{agentId}/wallet`: what is idle.+2. `crypto_data` for pool APYs for the assets held, Solana first, plus [/yields](https://three.ws/yields) for the full explorer.+3. Summarize the two best options and their risks. Lending is not enabled on MCP yet, so no funds move here; once lending tools ship, the prompt adds a quoted, confirmed deposit.++### Trade perpetuals (`perps`)++Goal: research a perpetual futures setup before any position.++On `mcp`:++1. `read_resource` on `three://agents/{agentId}/wallet`: collateral and limits.+2. `crypto_data` for spot price and recent volatility, and `token_snapshot` for Solana tokens.+3. Summarize the setup, the liquidation risk at 2x and 5x, and what would invalidate it. Perpetuals are not enabled on MCP yet, so no position opens here; once they ship, the prompt adds a previewed, confirmed order.++### Prediction markets (`predictions`)++Goal: research a prediction-market question and estimate a probability.++On `mcp`:++1. `read_resource` on `three://agents/{agentId}/wallet`: balance and limits.+2. `crypto_data` for the prices and data behind the question, then a probability estimate with reasoning.+3. No position is placed here; once prediction-market tools ship, the prompt adds a priced, confirmed position.++### Embed an agent on a website (`embed-avatar`)++Goal: put an agent's live 3D avatar on any site with paste-ready code.++On `mcp`:++1. `read_resource` on `three://agents/{agentId}`: does it have an avatar? If not, `list_my_avatars` and `attach_avatar_to_agent`.+2. `get_embed_code` with the agent id, at the size and autorotate setting the user wants.+3. `render_avatar` to preview it in the chat.+4. The snippet in one code block, where to paste it, and [/embed-doctor](https://three.ws/embed-doctor) to check it once live.++### Generate a 3D model (`generate-3d`)++Goal: turn a text prompt into a textured 3D model, optionally rigged, saved to the user's library.++On `mcp-3d`:++1. `direct_prompt` with the idea: a sharpened, single-subject prompt.+2. **Spends money.** `text_to_3d` with the prompt, after telling the user the tier's price. Paid per call in USDC over x402 by tier; run operator-funded on a signed-in account.+3. `generation_status` with the job id until it returns a GLB and an inline viewer.+4. **Spends money.** `auto_rig_model` if it is a character, so it can be animated. Priced per call over x402; operator-funded on a signed-in account.+5. `save_avatar` with the GLB URL and a name, then the view link and `read_resource` on `three://assets/{id}` for the saved asset.++---+## Rate limits| Scope | Limit |diff --git a/tests/mcp-use-cases-doc.test.js b/tests/mcp-use-cases-doc.test.jsnew file mode 100644index 000000000..7cb758c40--- /dev/null+++ b/tests/mcp-use-cases-doc.test.js@@ -0,0 +1,199 @@+// The "Use cases" section of docs/mcp.md writes every guided prompt+// (api/_mcp/prompts.js) out as the ordered tool and resource calls it drives.+// This suite holds that section to the live catalogs so it cannot drift:+// - every prompt has a use case, and every server that offers a prompt is+// covered by one of its "On `server`:" blocks;+// - every tool a block names is published by that server's tools/list, and+// every three:// resource it names is served there;+// - a block names exactly the tools the prompt renders on that server, so a+// prompt that starts calling a new tool forces the doc to follow;+// - a step that calls a destructive (fund-moving) tool is marked+// "Spends money.".+//+// Inside the numbered steps, backticks hold only tool names (snake_case),+// three:// resource URIs, and other literals with no snake_case shape (MCP+// method names, page paths), so the parser below can read them unambiguously.++import { readFileSync } from 'node:fs';++import { describe, it, expect } from 'vitest';++const { PROMPTS, promptsFor, renderPrompt } = await import('../api/_mcp/prompts.js');+const { matchResource } = await import('../api/_mcp/resources.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 SERVERS = { mcp: mainCatalog, 'mcp-agent': agentCatalog, 'mcp-3d': studioCatalog, 'mcp-bazaar': bazaarCatalog };++const DOC = readFileSync(new URL('../docs/mcp.md', import.meta.url), 'utf8');++const SPEND_MARK = '**Spends money.**';+const TOOL_RE = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/;++/** The text of the `## Use cases` section, up to the next top-level heading. */+function useCasesSection(doc) {+ const start = doc.indexOf('\n## Use cases\n');+ if (start === -1) return null;+ const rest = doc.slice(start + 1);+ const end = rest.indexOf('\n## ', 3);+ return end === -1 ? rest : rest.slice(0, end);+}++/**+ * Parse the section into use cases:+ * [{ prompt, blocks: [{ servers: [..], steps: [{ text, tools, resources, spends }] }] }]+ */+function parseUseCases(section) {+ const cases = [];+ for (const chunk of section.split(/\n### /).slice(1)) {+ const heading = chunk.split('\n', 1)[0];+ const prompt = heading.match(/\(`([a-z0-9-]+)`\)\s*$/)?.[1] ?? null;+ const blocks = [];+ let block = null;+ for (const line of chunk.split('\n').slice(1)) {+ const on = line.match(/^On ((?:`[a-z0-9-]+`(?:, | and )?)+)(?: \([^)]*\))?:$/);+ if (on) {+ block = { servers: [...on[1].matchAll(/`([a-z0-9-]+)`/g)].map((m) => m[1]), steps: [] };+ blocks.push(block);+ continue;+ }+ const step = line.match(/^\d+\. (.*)$/);+ if (step && block) {+ const ticks = [...step[1].matchAll(/`([^`]+)`/g)].map((m) => m[1]);+ block.steps.push({+ text: step[1],+ tools: ticks.filter((t) => TOOL_RE.test(t)),+ resources: ticks.filter((t) => t.startsWith('three://')),+ spends: step[1].startsWith(SPEND_MARK),+ });+ }+ }+ cases.push({ heading, prompt, blocks });+ }+ return cases;+}++/** Sample arguments: every argument, or required ones only. */+function sampleArgs(prompt, { optional }) {+ const args = {};+ for (const a of prompt.arguments) {+ if (!a.required && !optional) continue;+ args[a.name] = a.name === 'agentId' ? '{agentId}' : a.name === 'token' ? 'THREEsynthetic1111' : `sample ${a.name}`;+ }+ return args;+}++/** Every tool and resource a prompt can name on a server, across its argument shapes. */+function renderedCalls(server, prompt) {+ const catalog = SERVERS[server];+ const tools = new Set();+ const resources = new Set();+ for (const optional of [true, false]) {+ const out = renderPrompt(server, catalog, prompt.name, sampleArgs(prompt, { optional }));+ out.tools.forEach((t) => tools.add(t));+ out.resources.forEach((r) => resources.add(r));+ }+ return { tools, resources };+}++/**+ * Check the parsed use cases against the live catalogs. Returns a list of+ * human-readable problems; empty means the section matches the code.+ */+function auditUseCases(cases, servers = SERVERS) {+ const problems = [];+ const byPrompt = new Map(cases.map((c) => [c.prompt, c]));+ for (const c of cases) {+ if (!c.prompt) problems.push(`use case "${c.heading}" does not name its prompt as (\`name\`)`);+ else if (!PROMPTS.some((p) => p.name === c.prompt)) problems.push(`use case names unknown prompt ${c.prompt}`);+ }+ for (const prompt of PROMPTS) {+ const c = byPrompt.get(prompt.name);+ if (!c) {+ problems.push(`prompt ${prompt.name} has no use case`);+ continue;+ }+ const offeredOn = Object.entries(servers)+ .filter(([s, catalog]) => promptsFor(s, catalog).some((p) => p.name === prompt.name))+ .map(([s]) => s);+ const documentedOn = new Set(c.blocks.flatMap((b) => b.servers));+ for (const s of offeredOn) {+ if (!documentedOn.has(s)) problems.push(`${prompt.name}: offered on ${s} but no "On \`${s}\`:" block`);+ }+ for (const block of c.blocks) {+ if (!block.steps.length) problems.push(`${prompt.name}: block for ${block.servers.join(', ')} has no steps`);+ const named = new Set(block.steps.flatMap((st) => st.tools));+ const namedResources = new Set(block.steps.flatMap((st) => st.resources));+ for (const server of block.servers) {+ const catalog = servers[server];+ if (!catalog) {+ problems.push(`${prompt.name}: unknown server ${server}`);+ continue;+ }+ const byName = new Map(catalog.map((t) => [t.name, t]));+ for (const tool of named) {+ if (!byName.has(tool)) problems.push(`${prompt.name} on ${server}: names tool ${tool}, which ${server} does not publish`);+ }+ for (const uri of namedResources) {+ if (!matchResource(server, uri)) problems.push(`${prompt.name} on ${server}: names resource ${uri}, which ${server} does not serve`);+ }+ if (!offeredOn.includes(server)) {+ problems.push(`${prompt.name}: documented on ${server}, which does not offer it`);+ continue;+ }+ const rendered = renderedCalls(server, prompt);+ for (const tool of rendered.tools) {+ if (!named.has(tool)) problems.push(`${prompt.name} on ${server}: the prompt calls ${tool}, which the use case does not name`);+ }+ for (const tool of named) {+ if (!rendered.tools.has(tool)) problems.push(`${prompt.name} on ${server}: the use case names ${tool}, which the prompt never calls`);+ }+ for (const uri of rendered.resources) {+ if (!namedResources.has(uri)) problems.push(`${prompt.name} on ${server}: the prompt reads ${uri}, which the use case does not name`);+ }+ for (const step of block.steps) {+ for (const tool of step.tools) {+ if (byName.get(tool)?.annotations?.destructiveHint === true && !step.spends) {+ problems.push(`${prompt.name} on ${server}: step calling ${tool} moves funds but is not marked ${SPEND_MARK}`);+ }+ }+ }+ }+ }+ }+ return problems;+}++const section = useCasesSection(DOC);++describe('docs/mcp.md use cases', () => {+ it('has a Use cases section', () => {+ expect(section).toBeTruthy();+ });++ const cases = parseUseCases(section || '');++ it('covers every guided prompt, in prompt-catalog order', () => {+ expect(cases.map((c) => c.prompt)).toEqual(PROMPTS.map((p) => p.name));+ });++ it('names only live tools and resources, and exactly the ones each prompt calls', () => {+ expect(auditUseCases(cases)).toEqual([]);+ });++ it('marks at least one spending step, and every spending step says what moves', () => {+ const spends = cases.flatMap((c) => c.blocks.flatMap((b) => b.steps.filter((s) => s.spends)));+ expect(spends.length).toBeGreaterThan(0);+ for (const s of spends) expect(s.text.length).toBeGreaterThan(SPEND_MARK.length + 20);+ });++ it('fails when a tool the section names disappears from its server', () => {+ // The drift this suite exists for: drop pay_and_call from mcp-agent and the+ // audit must name it, not pass silently.+ const without = { ...SERVERS, 'mcp-agent': agentCatalog.filter((t) => t.name !== 'pay_and_call') };+ const problems = auditUseCases(cases, without);+ expect(problems.some((p) => p.includes('pay_and_call'))).toBe(true);+ });+});