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
test(mcp): pin the tools each server deliberately gained, and fix preview_macro's hints
nirholas4da09d565245
diff --git a/api/_mcpbazaar/discovery.js b/api/_mcpbazaar/discovery.jsindex 75d885668..0a3fa6acd 100644--- a/api/_mcpbazaar/discovery.js+++ b/api/_mcpbazaar/discovery.js@@ -16,7 +16,8 @@ export const RESOURCE_DESCRIPTION ='three.ws x402 Bazaar MCP: Streamable HTTP (MCP 2025-06-18) that discovers and prices paid ' +'agent services across the live x402 facilitator network: search_services (ranked search), ' +'browse_services (list what is payable), get_service (exact price, networks, recipient, input ' +- 'schema, and a ready pay link), and bazaar_service_details (live per-network price for cost ' ++ 'schema, and a ready pay link), read_resource (the same catalogs as three:// resources), and ' ++ 'bazaar_service_details (live per-network price for cost ' +'tracking). Connect with a three.ws account (OAuth) or pay per call in USDC on Base or Solana ' +'mainnet, no API key. Operated by three.ws.';@@ -75,7 +76,7 @@ function bazaarServerExtension() {params: {type: 'object',description:- 'For tools/call: { name, arguments }. Tool names: getting_started (free), search_services, browse_services, get_service, bazaar_service_details, see tools/list.',+ 'For tools/call: { name, arguments }. Tool names: getting_started (free), search_services, browse_services, get_service, bazaar_service_details, read_resource, see tools/list.',},},};diff --git a/docs/mcp-x402-bazaar.md b/docs/mcp-x402-bazaar.mdindex 0170fa1fc..08975f93b 100644--- a/docs/mcp-x402-bazaar.md+++ b/docs/mcp-x402-bazaar.md@@ -18,6 +18,7 @@ client. Registered with the MCP Registry as| `browse_services(type?, network?, max_price_usdc?, limit?)` | List services without a query — "what can I pay for?". || `get_service(resource_url, tool_name?)` | Full payment requirements (price, asset, network, recipient), input/output schema, and a ready pay link. || `bazaar_service_details(resource_url, tool_name?)` | Live price only: cheapest across networks plus a per-network breakdown. Built for price tracking on a schedule. |+| `read_resource(uri?, format?)` | Read a live three.ws resource by URI: `three://x402/services` (the x402 service catalog), `three://marketplace` (paid agent skills and services) and `three://me`. Omit `uri` to list every resource you can read; `format: "markdown"` renders it for reading. || `getting_started(section?)` | Free, no auth or payment. An overview of the server, its tools, and how to connect. Call this first. |`type` is `http` (paid HTTP APIs) or `mcp` (paid MCP tools). `network` is adiff --git a/packages/agora-mcp/README.md b/packages/agora-mcp/README.mdindex 346829633..365a81100 100644--- a/packages/agora-mcp/README.md+++ b/packages/agora-mcp/README.md@@ -91,12 +91,14 @@ agora_register agora_board agora_claim_task (you do it) agora_complete_task| `agora_citizens` | read | The population — each citizen's profession, status, on-chain identity, reputation, stake, earnings. Filterable. || `agora_passport` | read | One citizen reconciled against its **live on-chain** AgenC state + its full work history (with proofs you can verify).|| `agora_professions` | read | The capability bit map — each profession's stable bit and the real platform skill that backs it. |+| `agora_quote_register` | read | Preview `agora_register` before it signs: derived identity, whether it is already registered, the stake, the signing wallet and its balance. Returns a `quote_id`. |+| `agora_quote_task` | read | Preview `agora_post_task` before it escrows: the reward to lock, deadline, required capabilities, signing wallet and whether its balance covers the escrow. Returns a `quote_id`. || `agora_register` | **write** | Join as a citizen — a real on-chain AgenC registration with a capability bitmap + stake. Idempotent. || `agora_claim_task` | **write** | Claim an open task on-chain as your worker identity. || `agora_complete_task` | **write** | Submit a real 32-byte `proofHash` (+ deliverable) to release the escrow and earn. || `agora_post_task` | **write** | Escrow a bounty on the board — devnet native SOL, mainnet the **$THREE** mint (or an SPL mint you supply). |-The five read tools query live on-chain / projection data (the board, pulse, population, and a citizen's chain state all move between calls), so none are idempotent and none require a key. The four write tools each perform the **real** on-chain action and return the **tx signature** + an explorer link + the resulting on-chain state.+The five discovery tools query live on-chain / projection data (the board, pulse, population, and a citizen's chain state all move between calls), so none are idempotent and none require a key. The two quote tools sign nothing and move no funds: show the quote to the user, get a clear yes, then call the matching write tool with the same arguments, the returned `quote_id` and `confirm_spend: true`. The four write tools each perform the **real** on-chain action and return the **tx signature** + an explorer link + the resulting on-chain state.### Input parametersdiff --git a/packages/agora-mcp/test/registration.test.mjs b/packages/agora-mcp/test/registration.test.mjsindex 5c863768b..6d633b7f2 100644--- a/packages/agora-mcp/test/registration.test.mjs+++ b/packages/agora-mcp/test/registration.test.mjs@@ -15,7 +15,10 @@ import { TOOLS, buildServer } from '../src/index.js';const READ_TOOLS = ['agora_board', 'agora_pulse', 'agora_citizens', 'agora_passport', 'agora_professions'];const WRITE_TOOLS = ['agora_register', 'agora_claim_task', 'agora_complete_task', 'agora_post_task'];-const EXPECTED_NAMES = [...READ_TOOLS, ...WRITE_TOOLS];+// Spend previews: each one quotes its write tool (agora_register, agora_post_task)+// and returns the quote_id that tool requires alongside confirm_spend: true.+const QUOTE_TOOLS = ['agora_quote_register', 'agora_quote_task'];+const EXPECTED_NAMES = [...READ_TOOLS, ...QUOTE_TOOLS, ...WRITE_TOOLS];const byName = (name) => TOOLS.find((t) => t.name === name);@@ -50,6 +53,16 @@ test('read tools are read-only, live-data queries (openWorld, non-idempotent, no}});+test('quote tools are read-only previews of a live spend and never destructive', () => {+ for (const name of QUOTE_TOOLS) {+ const tool = byName(name);+ assert.equal(tool.annotations.readOnlyHint, true, `${name} signs nothing and moves no funds`);+ assert.equal(tool.annotations.openWorldHint, true, `${name} reads live chain state and balances`);+ assert.notEqual(tool.annotations.destructiveHint, true, `${name} is a preview, never destructive`);+ assert.match(tool.description, /confirm_spend: true/, `${name} must tell the model how to commit`);+ }+});+test('write tools are honestly NOT read-only and talk to the live chain', () => {for (const name of WRITE_TOOLS) {const tool = byName(name);diff --git a/packages/home-mcp/README.md b/packages/home-mcp/README.mdindex 1dd885a42..9a71adfc9 100644--- a/packages/home-mcp/README.md+++ b/packages/home-mcp/README.md@@ -3,8 +3,8 @@**Give any MCP assistant safe control of a real house.**An [MCP](https://modelcontextprotocol.io) server that connects straight to a-[Home Assistant](https://www.home-assistant.io) instance and hands your assistant five tools:-read the house, list what is in it, list the scenes the household already built, run one, and+[Home Assistant](https://www.home-assistant.io) instance and hands your assistant six tools:+read the house, list what is in it, list the scenes the household already built, preview which one a phrase would run, run one, andcall a service. Everything that opens the house goes through a physical-action gate, and overstdio that gate **refuses**. Read [The gate, over stdio](#the-gate-over-stdio) before you installthis: it is the part that decides whether your front door is safe.@@ -73,6 +73,7 @@ timing out into a shrug.| `list_entities` | read | The addressable entities, filtered by `domain`, `area` or `query`, each flagged `guarded` or not. || `list_macros` | read | Every scene and script the household already built. || `call_service` | write | One Home Assistant service call, through the gate. |+| `preview_macro` | read | The scene or script a phrase would resolve to, with confidence and a reason, and nothing runs. Show it to the person before `run_macro`. || `run_macro` | write | A phrase like "good night" resolved to this house's own scene, then run. `dry_run` to resolve only. |`home_overview` first, always: it gives the assistant the room names the household actually uses,diff --git a/packages/home-mcp/src/index.js b/packages/home-mcp/src/index.jsindex 0fe8bf779..7bf61f27f 100755--- a/packages/home-mcp/src/index.js+++ b/packages/home-mcp/src/index.js@@ -7,6 +7,7 @@// • list_entities: the addressable entities, filtered// • list_macros: the scenes and scripts the household already built// • call_service: act on the house, through the physical-action gate+// • preview_macro: which scene a phrase would run, without running it// • run_macro: "good night" to this house's own scene, then run it//// It writes NO device code. Zigbee, Z-Wave, Matter, Thread, BLE and the longdiff --git a/packages/home-mcp/src/tools/preview-macro.js b/packages/home-mcp/src/tools/preview-macro.jsindex 7c22daf4e..95bde8c97 100644--- a/packages/home-mcp/src/tools/preview-macro.js+++ b/packages/home-mcp/src/tools/preview-macro.js@@ -1,6 +1,7 @@// `preview_macro`: resolve a phrase to the scene or script run_macro would fire,// without firing it. This is run_macro's own dry run exposed as a read-only-// tool, so it stays callable while run_macro itself is off by default.+// tool, so a client that only grants read-only tools can still show the person+// what a phrase would do before anything moves in the house.import { z } from 'zod';@@ -9,11 +10,12 @@ import { def as runMacro } from './run-macro.js';export const def = {name: 'preview_macro',title: 'Preview which scene a phrase would run (nothing runs)',- annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },+ annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },description:'Resolve a phrase like "good night" to the scene or script this house would run, with the match confidence ' +- 'and a reason, and run NOTHING. A phrase with no match returns match:null. Show the match to the person, get ' +- 'a clear yes, then call run_macro with the same phrase, the returned preview_id and confirm_run: true.',+ 'and a reason, and run NOTHING. A phrase with no match returns match:null. Show the match to the person and, ' ++ 'once they agree, call run_macro with the same phrase. A macro that would open the house is still refused ' ++ 'there, because confirming a guarded action takes a person on the hosted three.ws surface.',inputSchema: {phrase: z.string().min(1).describe('What the person said, e.g. "good night".'),},diff --git a/packages/home-mcp/tests/registration.test.js b/packages/home-mcp/tests/registration.test.jsindex cb7337ab8..f700152f1 100644--- a/packages/home-mcp/tests/registration.test.js+++ b/packages/home-mcp/tests/registration.test.js@@ -18,6 +18,7 @@ const EXPECTED = {list_entities: { write: false },list_macros: { write: false },call_service: { write: true },+ preview_macro: { write: false },run_macro: { write: true },};diff --git a/tests/agora-mcp-tools.test.js b/tests/agora-mcp-tools.test.jsindex ae45002a8..7f28d0bba 100644--- a/tests/agora-mcp-tools.test.js+++ b/tests/agora-mcp-tools.test.js@@ -4,8 +4,9 @@* node:test suites (packages/agora-mcp/test/*.test.mjs) for the write-tool* early-reject paths; this suite complements them with:*- * 1. the tool-surface contract for ALL nine tools (name/title/description/- * inputSchema/handler + read-only vs write annotations), and+ * 1. the tool-surface contract for ALL eleven tools (name/title/description/+ * inputSchema/handler + read-only vs write annotations; the two+ * agora_quote_* tools are read-only spend previews), and* 2. the READ tools' real shaping/filtering logic, driven with `apiRequest`* mocked at the HTTP boundary (never a mock in shipped code) so profession /* minReward filtering, the additive bit-value derivation, and the passport@@ -28,14 +29,22 @@ import { def as passport } from '../packages/agora-mcp/src/tools/passport.js';import { def as pulse } from '../packages/agora-mcp/src/tools/pulse.js';import { def as citizens } from '../packages/agora-mcp/src/tools/citizens.js';-const READ_TOOLS = new Set(['agora_board', 'agora_pulse', 'agora_citizens', 'agora_passport', 'agora_professions']);+const READ_TOOLS = new Set([+ 'agora_board',+ 'agora_pulse',+ 'agora_citizens',+ 'agora_passport',+ 'agora_professions',+ 'agora_quote_register',+ 'agora_quote_task',+]);const WRITE_TOOLS = new Set(['agora_register', 'agora_claim_task', 'agora_complete_task', 'agora_post_task']);beforeEach(() => {vi.mocked(apiRequest).mockReset();});-describe('tool surface — all nine tools', () => {+describe('tool surface, all eleven tools', () => {it('exposes exactly the expected tool names', () => {const names = TOOLS.map((t) => t.name).sort();expect(names).toEqual(diff --git a/tests/api/mcp-bazaar-challenge.test.js b/tests/api/mcp-bazaar-challenge.test.jsindex d9310e5d3..2a41f0ce4 100644--- a/tests/api/mcp-bazaar-challenge.test.js+++ b/tests/api/mcp-bazaar-challenge.test.js@@ -145,6 +145,7 @@ describe('POST /api/mcp-bazaar: free discovery for plain clients', () => {'browse_services','get_service','bazaar_service_details',+ 'read_resource',]);});diff --git a/tests/api/mcp-bazaar.test.js b/tests/api/mcp-bazaar.test.jsindex 4e3d3bed5..dfa4ae6e4 100644--- a/tests/api/mcp-bazaar.test.js+++ b/tests/api/mcp-bazaar.test.js@@ -92,6 +92,7 @@ describe('x402 Bazaar MCP', () => {'browse_services','get_service','bazaar_service_details',+ 'read_resource',]);});diff --git a/tests/mcp-remote-annotations.test.js b/tests/mcp-remote-annotations.test.jsindex ec2980e0b..dc1631241 100644--- a/tests/mcp-remote-annotations.test.js+++ b/tests/mcp-remote-annotations.test.js@@ -19,30 +19,70 @@ const CATALOGS = [];// The ONLY tools across all five hosted servers allowed to advertise-// destructiveHint: true. Everything else must set it explicitly to false —+// destructiveHint: true. Everything else must set it explicitly to false:// the MCP spec defaults destructiveHint to TRUE when omitted, so an absent// hint silently marks a tool destructive.-// delete_avatar — permanently removes a user's avatar-// forget — deletes a stored agent memory-// pay_and_call — spends the user's USDC (irreversible transfer)-// persona_tip — spends a persona's own USDC (irreversible transfer)-// persona_send - spends a persona's own USDC (irreversible transfer)-// home_activate - runs a scene or script in a real house, which moves locks,-// covers and alarms in the physical world-// home_call - calls an arbitrary Home Assistant service, so it can unlock a-// door or open a garage+//+// The rule is the one scripts/audit-mcp-safety.mjs enforces from the handler+// side: a tool is destructive when it moves funds (an irreversible transfer+// is the definition of destructive), deletes something that cannot be+// regenerated, or reaches a physical actuator. Every money-moving tool here is+// also gated on a confirm flag plus a fresh preview_id, which is the+// confirmation table an MCP client must show before a yes.+//+// Deletes something that cannot be regenerated:+// delete_avatar - permanently removes a user's avatar+// forget - deletes a stored agent memory// delete_custom_skill - permanently removes a skill an owner may have written-// by hand; gated on confirm_delete+// by hand; gated on confirm_delete+// agent_card_reveal - returns a card secret once and deletes the stored+// encrypted copy+// agent_card_cancel - cancels a card; a paid card may not come back+//+// Spends or moves funds (irreversible transfer):+// pay_and_call - spends the user's USDC+// persona_tip - spends a persona's own USDC+// persona_send - spends a persona's own USDC+// agent_card_create - buys a gift or prepaid card from the agent wallet+// agent_card_withdraw - drains a prepaid card balance back to the wallet+// predictions_open - spends agent-wallet USDC on a prediction position+// predictions_close - sells a prediction position at market+// predictions_redeem - settles a resolved position on chain+//+// Commits or transfers a whole agent (marketplace, escrowed on Solana):+// create_marketplace_listing - a buy-now or an accepted bid then sells the+// agent without asking again, and include_history:+// false deletes its memories before the handover+// delist_marketplace_listing - takes the listing down and refunds every+// open bid out of escrow+// place_bid - locks the bidder's USDC in the listing's escrow+// buy_now - pays the buy-now price; custody rotates to the buyer+// accept_marketplace_bid - final: escrow pays out, the other bids refund,+// custody rotates to the buyer+// withdraw_marketplace_bid - cancels a bid and moves its escrow back+//+// Reaches a physical actuator:+// home_activate - runs a scene or script in a real house, which moves+// locks, covers and alarms in the physical world+// home_call - calls an arbitrary Home Assistant service, so it can+// unlock a door or open a garage//// The two home tools are the reason this list is not just about money. Marking// them non-destructive would tell every MCP client that opening someone's front// door is a safe, reversible call, which is exactly the claim Home Assistant's// own intent__HassTurnOff makes and exactly why this platform gates it. If a// future home tool is genuinely read-only it belongs outside this set; anything-// that reaches an actuator belongs inside it.+// that reaches an actuator belongs inside it. The previews and quotes that sit+// in front of each financial tool (agent_card_quote, preview_marketplace_action,+// predictions_*_preview) move nothing, so they stay outside it.const DESTRUCTIVE_TOOLS = new Set([- 'delete_avatar', 'forget', 'pay_and_call', 'persona_tip', 'persona_send',- 'home_activate', 'home_call', 'delete_custom_skill',+ 'delete_avatar', 'forget', 'delete_custom_skill', 'agent_card_reveal', 'agent_card_cancel',+ 'pay_and_call', 'persona_tip', 'persona_send',+ 'agent_card_create', 'agent_card_withdraw',+ 'predictions_open', 'predictions_close', 'predictions_redeem',+ 'create_marketplace_listing', 'delist_marketplace_listing', 'place_bid', 'buy_now',+ 'accept_marketplace_bid', 'withdraw_marketplace_bid',+ 'home_activate', 'home_call',]);// Internal/spec-only fields that must never leak into the tools/list wire@@ -111,7 +151,7 @@ describe.each(CATALOGS)('%s — tools/list catalog', (label, catalog) => {});describe('destructive set across all five servers', () => {- it('is exactly { delete_avatar, forget, pay_and_call, persona_tip, persona_send }', () => {+ it('is exactly the pinned set: deletes, fund movements and physical actuators', () => {const destructive = new Set();for (const [, catalog] of CATALOGS) {for (const tool of catalog) {diff --git a/tests/pump-alert-eval.test.js b/tests/pump-alert-eval.test.jsindex a7c3c09ae..c71338f3f 100644--- a/tests/pump-alert-eval.test.js+++ b/tests/pump-alert-eval.test.js@@ -13,6 +13,7 @@ import {deriveRuleLabel,MINT_TARGETED_KINDS,AGENT_TARGETED_KINDS,+ MARKET_TARGETED_KINDS,THRESHOLD_KINDS,} from '../api/_lib/pump-alert-eval.js';@@ -205,6 +206,7 @@ describe('kind classification constants', () => {it('partitions kinds correctly', () => {expect(MINT_TARGETED_KINDS).toEqual(['price_above', 'price_below', 'whale_buy']);expect(AGENT_TARGETED_KINDS).toEqual(['new_mint']);- expect(THRESHOLD_KINDS).toEqual(['price_above', 'price_below', 'whale_buy']);+ expect(MARKET_TARGETED_KINDS).toEqual(['market_price']);+ expect(THRESHOLD_KINDS).toEqual(['price_above', 'price_below', 'whale_buy', 'market_price']);});});