Skip to content

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.

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.js
index 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.md
index 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 a
diff --git a/packages/agora-mcp/README.md b/packages/agora-mcp/README.md
index 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 parameters
diff --git a/packages/agora-mcp/test/registration.test.mjs b/packages/agora-mcp/test/registration.test.mjs
index 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.md
index 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, and
call a service. Everything that opens the house goes through a physical-action gate, and over
stdio that gate **refuses**. Read [The gate, over stdio](#the-gate-over-stdio) before you install
this: 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.js
index 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 long
diff --git a/packages/home-mcp/src/tools/preview-macro.js b/packages/home-mcp/src/tools/preview-macro.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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']);
});
});