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.

14.3 KB
Raw Blame
import { describe, it, expect } from 'vitest';

// The five hosted remote MCP servers. Each catalog is the exact tools/list
// payload: the shared dispatcher (api/_lib/mcp-dispatch.js) returns it
// verbatim, and the main /api/mcp dispatcher spreads each entry before adding
// pricing — so asserting on TOOL_CATALOG asserts on the wire response.
import { TOOL_CATALOG as mainCatalog } from '../api/_mcp/catalog.js';
import { TOOL_CATALOG as studioCatalog } from '../api/_mcp3d/catalog.js';
import { TOOL_CATALOG as agentCatalog } from '../api/_mcpagent/catalog.js';
import { TOOL_CATALOG as ibmCatalog } from '../api/_mcpibm/catalog.js';
import { TOOL_CATALOG as bazaarCatalog } from '../api/_mcpbazaar/catalog.js';
import { POLICY } from '../packages/mcp-policy/src/table.js';

// [label, catalog, @three-ws/mcp-policy server id]
const CATALOGS = [
	['three.ws main (/api/mcp)', mainCatalog, 'three.ws'],
	['3D Studio (/api/mcp-3d)', studioCatalog, 'threews-3d-studio'],
	['Agent (/api/agent-mcp)', agentCatalog, 'threews-agent'],
	['IBM Granite (/api/ibm-mcp)', ibmCatalog, 'ibm-x402-mcp-remote'],
	['x402 Bazaar (/api/bazaar-mcp)', bazaarCatalog, 'threews-x402-bazaar'],
];

// 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.
//
// 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
//   delete_agent        - cancels an agent's runs and erases its memories and
//                         action log; gated on confirm_delete
//   automation_delete   - removes an automation (or the wallet rule or alert
//                         rule behind it); 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
//   alert_rule_delete   - removes an alert rule and its delivery history for good
//
// Spends or moves funds (irreversible transfer, or an on-chain transaction):
//   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
//   domain_register     - buys a web domain from the user's credits, one year
//   paired_launch, uniswap_launch - launches a coin and its opening buy on
//                         Robinhood Chain
//   paired_claim_fees   - signs and broadcasts the fee-collection transaction
//                         on Robinhood Chain
//   automation_trigger  - fires an automation now, and a swap or transfer
//                         automation spends SOL from the agent 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
//   perps_order_execute, perps_collateral_deposit, perps_collateral_withdraw,
//   perps_order_cancel, perps_flatten - trade perpetual futures or move USDC
//                         collateral
//   limit_order_create, stop_order_create, trailing_order_create,
//   ladder_order_create, oco_order_create, dca_create - arm a standing order
//                         or recurring buy that spends from the agent wallet
//                         once its trigger fires
//   sniper_activate     - arms a launch sniper that spends SOL from the
//                         agent's wallet on every launch that passes its filters
//   agent_mail_create, agent_mail_send, agent_mail_reply - send mail that
//                         can carry a payment
//   agent_send          - sends funds from the agent wallet
//   agent_buy_confirm   - confirms and executes a marketplace purchase
//   swap_execute        - executes a quoted token swap
//
// 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. 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', 'delete_custom_skill', 'delete_agent', 'automation_delete',
	'agent_card_reveal', 'agent_card_cancel',
	'pay_and_call', 'persona_tip', 'persona_send',
	'agent_card_create', 'agent_card_withdraw',
	'domain_register', 'paired_launch', 'uniswap_launch', 'paired_claim_fees', 'automation_trigger',
	'create_marketplace_listing', 'delist_marketplace_listing', 'place_bid', 'buy_now',
	'accept_marketplace_bid', 'withdraw_marketplace_bid',
	'predictions_open', 'predictions_close', 'predictions_redeem',
	'sniper_activate', 'alert_rule_delete',
	'perps_order_execute', 'perps_collateral_deposit', 'perps_collateral_withdraw', 'perps_order_cancel', 'perps_flatten',
	'limit_order_create', 'stop_order_create', 'trailing_order_create', 'ladder_order_create', 'oco_order_create', 'dca_create',
	'home_activate', 'home_call',
	'agent_mail_create', 'agent_mail_send', 'agent_mail_reply',
	'agent_send', 'agent_buy_confirm',
	'swap_execute',
	// Named commerce tools (order 521, api/_mcpagent/named-services-tools.js):
	// each pays a fixed three.ws x402 service from the agent wallet, gated on
	// its own <name>_quote preview (the quote tools themselves stay read-only
	// and are not in this set).
	'weather_forecast', 'weather_go_no_go', 'carbon_now', 'carbon_best_window',
	'domain_rdap_check', 'domain_rdap_check_bulk', 'research_search', 'research_paper', 'research_bibliography',
	'book_search', 'book_read', 'news_wire_search', 'news_wire_poll',
	'transit_plan', 'transit_delays', 'places_search', 'places_detail',
]);

// Destructive tools the policy deliberately leaves in the write tier (on by
// default, no confirm flag). paired_claim_fees collects fees into the agent's
// own wallet, so nothing leaves the owner's control. automation_trigger gates
// its own spend: an agent_prompt or notify fire moves nothing, and a swap or
// transfer fire refuses connector keys, needs wallet:write, and needs
// confirm_spend after the tool has shown recipient, amount, asset and chain.
// Every other destructive tool must be financial tier: off until the session
// enables it, and refused without its confirm flag.
const DESTRUCTIVE_WRITE_TIER = new Set(['paired_claim_fees', 'automation_trigger']);

// Internal/spec-only fields that must never leak into the tools/list wire
// payload.
const FORBIDDEN_WIRE_FIELDS = ['handler', 'scope', 'example', 'output'];

describe.each(CATALOGS)('%s: tools/list catalog', (label, catalog, serverId) => {
	it('is a non-empty array', () => {
		expect(Array.isArray(catalog)).toBe(true);
		expect(catalog.length).toBeGreaterThan(0);
	});

	it('tool names are unique', () => {
		const names = catalog.map((t) => t.name);
		expect(new Set(names).size).toBe(names.length);
	});

	it('every tool has a name, a human title, and a description', () => {
		for (const tool of catalog) {
			expect(typeof tool.name, `${label}: name`).toBe('string');
			expect(tool.name.length).toBeGreaterThan(0);
			expect(typeof tool.title, `${tool.name}: title`).toBe('string');
			expect(tool.title.length, `${tool.name}: title`).toBeGreaterThan(0);
			expect(typeof tool.description, `${tool.name}: description`).toBe('string');
		}
	});

	it('every tool carries complete, explicit boolean annotations', () => {
		for (const tool of catalog) {
			const a = tool.annotations;
			expect(a, `${tool.name}: annotations`).toBeTypeOf('object');
			for (const hint of [
				'readOnlyHint',
				'destructiveHint',
				'idempotentHint',
				'openWorldHint',
			]) {
				expect(typeof a[hint], `${tool.name}: ${hint}`).toBe('boolean');
			}
		}
	});

	it('only the pinned destructive tools advertise destructiveHint: true', () => {
		for (const tool of catalog) {
			const a = tool.annotations;
			if (DESTRUCTIVE_TOOLS.has(tool.name)) {
				expect(a.destructiveHint, `${tool.name}: destructiveHint`).toBe(true);
				expect(a.readOnlyHint, `${tool.name}: readOnlyHint`).toBe(false);
			} else {
				expect(a.destructiveHint, `${tool.name}: destructiveHint`).toBe(false);
			}
			// A read-only tool can never be destructive.
			if (a.readOnlyHint) {
				expect(a.destructiveHint, `${tool.name}: read-only yet destructive`).toBe(false);
			}
		}
	});

	it('gates every destructive tool behind the financial policy tier', () => {
		const rows = POLICY[serverId];
		for (const tool of catalog) {
			if (tool.annotations?.destructiveHint !== true || DESTRUCTIVE_WRITE_TIER.has(tool.name)) continue;
			const row = rows[tool.name];
			expect(row?.tier, `${tool.name}: policy tier`).toBe('financial');
			expect(row?.confirmFlag, `${tool.name}: confirm flag`).toMatch(/^confirm_/);
		}
	});

	it('serves the preview tool every financial tool is gated on', () => {
		// The policy refuses a financial tool without a fresh id from its preview
		// tool, so a preview this server does not serve leaves the tool
		// uncallable (pay_and_call once named a pay_quote nobody registered).
		const names = new Set(catalog.map((t) => t.name));
		for (const [name, row] of Object.entries(POLICY[serverId])) {
			if (!names.has(name) || !row.previewTool) continue;
			expect(names.has(row.previewTool), `${name} needs ${row.previewTool}`).toBe(true);
		}
	});

	it('never asks for a preview id under a name the policy does not check', () => {
		// The policy injects its id argument into each gated schema at list time,
		// named after the preview tool (quote_id for a *quote* tool, preview_id
		// otherwise). A schema that declares the OTHER name makes clients send an
		// id the policy ignores (paired_launch once required preview_id while the
		// policy checked quote_id, so it was uncallable as documented).
		const byName = new Map(catalog.map((t) => [t.name, t]));
		for (const [name, row] of Object.entries(POLICY[serverId])) {
			const tool = byName.get(name);
			if (!tool || !row.previewTool) continue;
			const other = /quote/.test(row.previewTool) ? 'preview_id' : 'quote_id';
			expect(Object.keys(tool.inputSchema?.properties || {}), `${name} declares ${other}`).not.toContain(other);
		}
	});

	it('never leaks internal fields onto the wire', () => {
		for (const tool of catalog) {
			for (const field of FORBIDDEN_WIRE_FIELDS) {
				expect(tool[field], `${tool.name}: ${field}`).toBeUndefined();
			}
		}
	});
});

describe('destructive set across all five servers', () => {
	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) {
				if (tool.annotations?.destructiveHint === true) destructive.add(tool.name);
			}
		}
		expect([...destructive].sort()).toEqual([...DESTRUCTIVE_TOOLS].sort());
	});
});

describe('free getting-started entry points', () => {
	const EXPECTED = {
		readOnlyHint: true,
		destructiveHint: false,
		idempotentHint: true,
		openWorldHint: false,
	};

	it.each([
		['three.ws main', mainCatalog, 'getting_started'],
		['3D Studio', studioCatalog, 'getting_started'],
		['Agent', agentCatalog, 'getting_started'],
		['x402 Bazaar', bazaarCatalog, 'getting_started'],
		['IBM Granite', ibmCatalog, 'ibm_granite_getting_started'],
	])('%s lists a read-only, idempotent, closed-world overview tool', (label, catalog, name) => {
		const tool = catalog.find((t) => t.name === name);
		expect(tool, `${label}: ${name}`).toBeDefined();
		expect(tool.annotations).toEqual(EXPECTED);
	});
});

describe('IBM Granite catalog mirrors packages/ibm-x402-mcp annotations', () => {
	// Generative inference: read-only, open-world, NOT idempotent (same input
	// can yield different output). Embeddings are deterministic for a model.
	const GENERATIVE = {
		readOnlyHint: true,
		destructiveHint: false,
		idempotentHint: false,
		openWorldHint: true,
	};
	const DETERMINISTIC = { ...GENERATIVE, idempotentHint: true };

	it.each([
		['ibm_granite_chat', GENERATIVE],
		['ibm_granite_code', GENERATIVE],
		['ibm_granite_analyze', GENERATIVE],
		['ibm_granite_forecast', GENERATIVE],
		['ibm_granite_embed', DETERMINISTIC],
	])('%s matches the npm package semantics', (name, expected) => {
		const tool = ibmCatalog.find((t) => t.name === name);
		expect(tool).toBeDefined();
		expect(tool.annotations).toEqual(expected);
	});
});