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.

feat(mcp): let an agent ask whether a re-exported model is still safe to ship

nirholas910a21660d2d
diff --git a/api/_lib/rate-limit.js b/api/_lib/rate-limit.js
index afe1c8db0..0a1ecc81d 100644
--- a/api/_lib/rate-limit.js
+++ b/api/_lib/rate-limit.js
@@ -873,6 +873,10 @@ export const limits = {
getLimiter('mcp:inspect', { limit: 30, window: '1 m', critical: true }).limit(key),
mcpOptimize: (key) =>
getLimiter('mcp:optimize', { limit: 10, window: '1 m', critical: true }).limit(key),
+ // Diffing fetches and fully parses TWO models per call, so it costs roughly
+ // double an inspect and gets half the budget.
+ mcpDiff: (key) =>
+ getLimiter('mcp:diff', { limit: 15, window: '1 m', critical: true }).limit(key),
// 3D Studio MCP. Generation submits a real GPU job on Replicate (text→image
// and/or image→3D reconstruction) that costs real money, so it gets a hard
// hourly ceiling per principal. Status polling is cheap and frequent.
diff --git a/api/_mcp/tools/models.js b/api/_mcp/tools/models.js
index ec350812f..3f7b2859b 100644
--- a/api/_mcp/tools/models.js
+++ b/api/_mcp/tools/models.js
@@ -1,6 +1,7 @@
import { limits } from '../../_lib/rate-limit.js';
import { fetchModel, FetchModelError } from '../../_lib/fetch-model.js';
import { inspectModel, suggestOptimizations } from '../../_lib/model-inspect.js';
+import { describeModel, diffDescriptions, formatText } from '@three-ws/glb-diff';
import { validateBytes } from 'gltf-validator';
function rpcError(code, message, data) {
@@ -198,4 +199,48 @@ export const toolDefs = [
};
},
},
+ {
+ name: 'diff_models',
+ title: 'Diff two glTF/GLB models',
+ annotations: INSPECTION_ANNOTATIONS,
+ description:
+ 'Compare two remote GLB or glTF models and return what changed: geometry, hierarchy, materials, textures, skeletons, and animation clips, each classified as added, removed, renamed, moved, or modified, with renames detected by content hash rather than by name. Every change carries a severity (none, cosmetic, minor, major, breaking) so an agent can decide whether an optimized, rigged, or re-exported model is still safe to ship. Breaking means something a consumer references by name is gone: a clip, a joint, a mesh.',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ before: {
+ type: 'string',
+ format: 'uri',
+ description: 'Public https URL of the baseline .glb or .gltf file.',
+ },
+ after: {
+ type: 'string',
+ format: 'uri',
+ description: 'Public https URL of the candidate .glb or .gltf file.',
+ },
+ },
+ required: ['before', 'after'],
+ additionalProperties: false,
+ },
+ async handler(args, auth) {
+ const rl = await limits.mcpDiff(auth.userId || auth.rateKey);
+ if (!rl.success)
+ throw rpcError(-32000, 'rate_limited', {
+ retry_after: Math.ceil((rl.reset - Date.now()) / 1000),
+ });
+ // Sequential, so a caller who passed one bad URL learns which one
+ // without the server having spent a second full download first.
+ const a = await safeFetchModel(args.before);
+ const b = await safeFetchModel(args.after);
+ const [beforeDesc, afterDesc] = await Promise.all([
+ describeModel(a.bytes, { name: a.filename }),
+ describeModel(b.bytes, { name: b.filename }),
+ ]);
+ const changeset = diffDescriptions(beforeDesc, afterDesc);
+ return {
+ content: [{ type: 'text', text: formatText(changeset, { color: false }) }],
+ structuredContent: { before: a.url, after: b.url, ...changeset },
+ };
+ },
+ },
];
diff --git a/tests/fixtures/mcp-golden-tools.json b/tests/fixtures/mcp-golden-tools.json
index 3d119c828..2f1448b63 100644
--- a/tests/fixtures/mcp-golden-tools.json
+++ b/tests/fixtures/mcp-golden-tools.json
@@ -18,7 +18,7 @@
},
{
"name": "persona_say",
- "title": "Speak a reply through a persona — lip-sync + emotion + gesture",
+ "title": "Speak a reply through a persona \u2014 lip-sync + emotion + gesture",
"descHead": "dynamic",
"descHash": "dynamic",
"annotations": "ref:SAY_ANNOTATIONS",
@@ -398,6 +398,14 @@
}
],
"api/_mcp/tools/models.js": [
+ {
+ "name": "diff_models",
+ "title": "Diff two glTF/GLB models",
+ "descHead": "Compare two remote GLB or glTF models and return what changed: geometry,",
+ "descHash": "7258f23cf52e",
+ "annotations": "ref:INSPECTION_ANNOTATIONS",
+ "schemaHash": "449d45d54027"
+ },
{
"name": "inspect_model",
"title": "Inspect glTF/GLB model",
@@ -640,7 +648,7 @@
"api/_mcp3d/tools/persona-identity.js": [
{
"name": "persona_identity",
- "title": "Read a persona's on-chain identity — wallet, reputation, holdings",
+ "title": "Read a persona's on-chain identity \u2014 wallet, reputation, holdings",
"descHead": "dynamic",
"descHash": "dynamic",
"annotations": "ref:READ_ANNOTATIONS",
@@ -726,7 +734,7 @@
{
"name": "create_agent_persona",
"title": "Mint a persistent, living agent persona from a rigged GLB",
- "descHead": "Turn a generated GLB into a NAMED, persistent agent body — a \"persona\" t",
+ "descHead": "Turn a generated GLB into a NAMED, persistent agent body \u2014 a \"persona\" t",
"descHash": "716809d092b0",
"annotations": "ref:PERSONA_CREATE_ANNOTATIONS",
"schemaHash": "7d650a9be810"
@@ -763,7 +771,7 @@
{
"name": "get_agent_persona",
"title": "Reload a persisted persona by id (continuity across sessions)",
- "descHead": "Bring back a previously minted persona by its persona_id — the SAME body",
+ "descHead": "Bring back a previously minted persona by its persona_id \u2014 the SAME body",
"descHash": "04388b6c47b0",
"annotations": "ref:PERSONA_READ_ANNOTATIONS",
"schemaHash": "b8451da964a3"
@@ -778,7 +786,7 @@
},
{
"name": "persona_say",
- "title": "Speak a reply through a persona — lip-sync + emotion + gesture",
+ "title": "Speak a reply through a persona \u2014 lip-sync + emotion + gesture",
"descHead": "Make a persona PERFORM a reply: the body lip-syncs the text and shows th",
"descHash": "7ce7c147f8f6",
"annotations": "ref:PERSONA_SAY_ANNOTATIONS",
@@ -800,7 +808,7 @@
{
"name": "preview_3d",
"title": "Preview any GLB as an interactive 3D artifact",
- "descHead": "Render any public GLB URL as an inline <model-viewer> HTML artifact — or",
+ "descHead": "Render any public GLB URL as an inline <model-viewer> HTML artifact \u2014 or",
"descHash": "ed4b123a6d3e",
"annotations": {
"readOnlyHint": true,
@@ -1030,7 +1038,7 @@
{
"name": "get_feed_events",
"title": "Site-wide activity feed",
- "descHead": "The site-wide activity ticker — recent things that just happened across ",
+ "descHead": "The site-wide activity ticker \u2014 recent things that just happened across ",
"descHash": "2bdbb0bc0a3a",
"annotations": {
"readOnlyHint": true,
@@ -1058,7 +1066,7 @@
{
"name": "get_tier_info",
"title": "$THREE holder tier ladder",
- "descHead": "The $THREE holder tier ladder — the membership bands a wallet earns pure",
+ "descHead": "The $THREE holder tier ladder \u2014 the membership bands a wallet earns pure",
"descHash": "81281cff2892",
"annotations": {
"readOnlyHint": true,
@@ -1243,7 +1251,7 @@
{
"name": "agora_board",
"title": "Browse the Agora job board",
- "descHead": "Browse the live Agora job board — the work an agent can claim and earn $",
+ "descHead": "Browse the live Agora job board \u2014 the work an agent can claim and earn $",
"descHash": "5dbb1bdad754",
"annotations": {
"readOnlyHint": true,
@@ -1257,7 +1265,7 @@
{
"name": "agora_citizens",
"title": "List Agora citizens",
- "descHead": "List the citizens of Agora — the population of the agent + human economy",
+ "descHead": "List the citizens of Agora \u2014 the population of the agent + human economy",
"descHash": "9c8f5bf601b4",
"annotations": {
"readOnlyHint": true,
@@ -1271,7 +1279,7 @@
{
"name": "agora_claim_task",
"title": "Claim an open Agora task (on-chain)",
- "descHead": "CLAIM an open job from the Agora board — a REAL on-chain AgenC claim sig",
+ "descHead": "CLAIM an open job from the Agora board \u2014 a REAL on-chain AgenC claim sig",
"descHash": "0bb79da5c125",
"annotations": {
"readOnlyHint": false,
@@ -1285,7 +1293,7 @@
{
"name": "agora_complete_task",
"title": "Complete an Agora task with a proof (on-chain)",
- "descHead": "COMPLETE a task you claimed and GET PAID — a REAL on-chain AgenC complet",
+ "descHead": "COMPLETE a task you claimed and GET PAID \u2014 a REAL on-chain AgenC complet",
"descHash": "35535d8835f8",
"annotations": {
"readOnlyHint": false,
@@ -1299,7 +1307,7 @@
{
"name": "agora_passport",
"title": "Get one Agora citizen passport",
- "descHead": "Fetch one citizen's living passport — the full record of a participant i",
+ "descHead": "Fetch one citizen's living passport \u2014 the full record of a participant i",
"descHash": "5427f717ba36",
"annotations": {
"readOnlyHint": true,
@@ -1327,7 +1335,7 @@
{
"name": "agora_professions",
"title": "List Agora professions (the capability bit map)",
- "descHead": "List Agora's professions — the labor market's type system over AgenC's u",
+ "descHead": "List Agora's professions \u2014 the labor market's type system over AgenC's u",
"descHash": "65a97e8f01a0",
"annotations": {
"readOnlyHint": true,
@@ -1341,7 +1349,7 @@
{
"name": "agora_pulse",
"title": "Read the Agora economy pulse",
- "descHead": "Read the Agora economy ticker — a live snapshot of the agent + human eco",
+ "descHead": "Read the Agora economy ticker \u2014 a live snapshot of the agent + human eco",
"descHash": "7b1f7e64a4a2",
"annotations": {
"readOnlyHint": true,
@@ -1355,7 +1363,7 @@
{
"name": "agora_register",
"title": "Register as an Agora citizen (on-chain)",
- "descHead": "JOIN AGORA as a citizen — a REAL on-chain AgenC registration signed by Y",
+ "descHead": "JOIN AGORA as a citizen \u2014 a REAL on-chain AgenC registration signed by Y",
"descHash": "97f5aaecd553",
"annotations": {
"readOnlyHint": false,
@@ -1797,7 +1805,7 @@
{
"name": "pump_buy",
"title": "Buy a Solana token via Jupiter (direct or Jito-bundled)",
- "descHead": "Swap SOL → target mint via Jupiter aggregator. Direct mode = one tx sign",
+ "descHead": "Swap SOL \u2192 target mint via Jupiter aggregator. Direct mode = one tx sign",
"descHash": "2a5ec65bb978",
"annotations": {
"readOnlyHint": false,
@@ -2222,7 +2230,7 @@
{
"name": "get_executions",
"title": "List copy executions (intent inbox)",
- "descHead": "List the authenticated account's copy executions — the sized, guard-chec",
+ "descHead": "List the authenticated account's copy executions \u2014 the sized, guard-chec",
"descHash": "cbe66041c82b",
"annotations": {
"readOnlyHint": true,
@@ -2334,7 +2342,7 @@
{
"name": "smart_money_coin",
"title": "Smart-money score for a coin",
- "descHead": "Assess a coin by WHO is net-buying it right now. Returns a 0–100 smart_m",
+ "descHead": "Assess a coin by WHO is net-buying it right now. Returns a 0\u2013100 smart_m",
"descHash": "e779edb0c8bf",
"annotations": {
"readOnlyHint": true,
@@ -2475,7 +2483,7 @@
{
"name": "browse_skills",
"title": "Browse the skills catalog",
- "descHead": "Search and page the public three.ws skills catalog — reusable tools and ",
+ "descHead": "Search and page the public three.ws skills catalog \u2014 reusable tools and ",
"descHash": "cc6bca95f4db",
"annotations": {
"readOnlyHint": true,
@@ -2671,7 +2679,7 @@
"packages/portfolio-mcp/src/tools/portfolio-summary.js": [
{
"name": "get_portfolio_summary",
- "title": "My agents’ live portfolio (holdings + USD value)",
+ "title": "My agents\u2019 live portfolio (holdings + USD value)",
"descHead": "dynamic",
"descHash": "dynamic",
"annotations": {
@@ -2729,7 +2737,7 @@
{
"name": "append_agent_action",
"title": "Append a signed action to the provenance ledger",
- "descHead": "Record an action in an agent's append-only provenance ledger — the perma",
+ "descHead": "Record an action in an agent's append-only provenance ledger \u2014 the perma",
"descHash": "094f7fe192ca",
"annotations": {
"readOnlyHint": false,
@@ -2772,7 +2780,7 @@
{
"name": "build_world",
"title": "Build a complete 3D world from one sentence (no browser needed)",
- "descHead": "One sentence → a fully forged, exported 3D world, entirely server-side: ",
+ "descHead": "One sentence \u2192 a fully forged, exported 3D world, entirely server-side: ",
"descHash": "0216a43f7396",
"annotations": {
"readOnlyHint": false,
@@ -2943,7 +2951,7 @@
"packages/three-token-mcp/src/tools/three-price.js": [
{
"name": "three_price",
- "title": "Live $THREE price (Jupiter) + USD→$THREE quote",
+ "title": "Live $THREE price (Jupiter) + USD\u2192$THREE quote",
"descHead": "Return the live USD price of $THREE (Jupiter primary, Birdeye fallback).",
"descHash": "b589970ff915",
"annotations": {
@@ -3057,7 +3065,7 @@
{
"name": "vanity_open",
"title": "List claimable open bounties for workers",
- "descHead": "List the open, unexpired bounties a grinding worker can race to claim — ",
+ "descHead": "List the open, unexpired bounties a grinding worker can race to claim \u2014 ",
"descHash": "45f3acbc46ae",
"annotations": {
"readOnlyHint": true,
@@ -3155,7 +3163,7 @@
{
"name": "inspect_endpoint",
"title": "Inspect an x402 endpoint (price + requirements, no payment)",
- "descHead": "Fetch an x402 endpoint and return its 402 payment requirements — every a",
+ "descHead": "Fetch an x402 endpoint and return its 402 payment requirements \u2014 every a",
"descHash": "278c58d6e1c4",
"annotations": {
"readOnlyHint": true,