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.

fix(mcp): serve the free asset catalog to keyless MCP clients and stop promising it on /api/mcp

nirholasb9f1dc920553
diff --git a/.agents/skills/find-3d-assets/SKILL.md b/.agents/skills/find-3d-assets/SKILL.md
index c83084ff3..a8bc902ce 100644
--- a/.agents/skills/find-3d-assets/SKILL.md
+++ b/.agents/skills/find-3d-assets/SKILL.md
@@ -1,6 +1,6 @@
---
name: find-3d-assets
-description: Search 3,492 ready-made 3D assets on three.ws (CC0 props and objects, rigged humanoid characters, motion clips) and get paste-ready code or a downloaded file. Use when you or the user need a 3D model, prop, object, character, or animation for a scene, site, game, or app ("I need a 3D chair", "find a rigged character", "is there a wave animation", "add a lamp model to my page"). Free: no account, no API key, no payment. Check here BEFORE generating a model from scratch.
+description: Search thousands of ready-made 3D assets on three.ws (CC0 props and objects, rigged humanoid characters, motion clips) and get paste-ready code or a downloaded file. Use when you or the user need a 3D model, prop, object, character, or animation for a scene, site, game, or app ("I need a 3D chair", "find a rigged character", "is there a wave animation", "add a lamp model to my page"). Free: no account, no API key, no payment. Check here BEFORE generating a model from scratch.
when_to_use: Something needs a 3D asset and a ready-made one would do. If the catalog has no match, fall through to generate-3d-model (props) or create-3d-avatar (characters). To put an asset you already have on a page, use embed-three-ws-avatar.
license: MIT
metadata:
@@ -13,11 +13,14 @@ metadata:
three.ws publishes three asset libraries and joins them into one searchable catalog:
-| Kind | What it is | How many |
-| --- | --- | --- |
-| `object` | CC0 props and objects (furniture, lighting, tools, electronics, decor) staged as web GLB | 511 |
-| `character` | Ready-made rigged humanoids, animation-ready out of the box | 107 |
-| `animation` | Retargetable motion clips as `THREE.AnimationClip` JSON | 2,874 |
+| Kind | What it is |
+| --- | --- |
+| `object` | CC0 props and objects (furniture, lighting, tools, electronics, decor) staged as web GLB |
+| `character` | Ready-made rigged humanoids, animation-ready out of the box |
+| `animation` | Retargetable motion clips as `THREE.AnimationClip` JSON (the largest library, in the thousands) |
+
+The libraries grow, so do not quote a count from memory: every search response carries the live
+per-kind totals in `facets.kinds`, and `total` is the size of the whole catalog.
Everything here is **free and public**: no account, no API key, no payment, no rate card.
@@ -35,7 +38,7 @@ different answers and the user should know which they got.
## The fastest path: MCP tools
-If the three.ws MCP server is connected, three free tools cover the whole flow:
+If a three.ws MCP server is connected, three free tools cover the whole flow:
| Tool | Use |
| --- | --- |
@@ -48,12 +51,19 @@ search_catalog { "q": "wooden chair", "kind": "object", "limit": 5 }
get_item_source { "id": "object:painted_wooden_chair_01" }
```
-Not connected? Add it:
+Not connected? Add the keyless studio server. It needs no account and also carries the
+free generation tools the catalog falls through to:
```json
-{ "mcpServers": { "three-ws": { "type": "http", "url": "https://three.ws/api/mcp" } } }
+{ "mcpServers": { "three-ws-studio": { "type": "http", "url": "https://three.ws/api/mcp-studio" } } }
```
+The main server, `https://three.ws/api/mcp`, lists the same three tools, but an MCP client
+that adds it is asked to sign in to a three.ws account as soon as it connects, because most
+of that server's tools act on an account. Add it when the user already has one or wants their
+own library; for the catalog alone, the studio server is the no-account path. Plain HTTP
+(below) also needs no account.
+
## Without MCP: the HTTP endpoint
```bash
diff --git a/STRUCTURE.md b/STRUCTURE.md
index d31643608..3f23ec5ca 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -26,7 +26,7 @@ bottom.
| Prompt library (`/prompts`) | Source [data/prompt-library.json](data/prompt-library.json), builder [scripts/build-prompt-library.mjs](scripts/build-prompt-library.mjs) → `public/prompts.json` + `public/prompts.txt`, page [pages/prompts.html](pages/prompts.html) `→ /prompts` + [src/prompt-library/](src/prompt-library) (page.js, page.css) | Live | Prompts written to be copied out and pasted into someone else's assistant, grouped by what they build (3D models and rigged avatars, site embeds, the x402 economy, platform integrations) and by what they need first (nothing at all, the free MCP server, the skills pack, a funded wallet). Every prompt names a real endpoint or tool, says what to do when a job comes back pending, and says what to hand back; the ones that can spend money are written so the assistant stops and shows the amount and the recipient first. Each card copies to the clipboard or opens straight in claude.ai with the text already in the box, and the whole library is fetchable as `/prompts.json` or `/prompts.txt` so an agent can read it without scraping. The builder validates the data on every build (unique kebab-case ids, known category and setup, balanced `<placeholder>` brackets, internal links that resolve to routes in [data/pages.json](data/pages.json)) and `npm run check:prompt-library` holds the published copies in sync inside `npm run gate`. Docs: [docs/prompts.md](docs/prompts.md) `→ /docs/prompts`. Tests: [tests/prompt-library.test.js](tests/prompt-library.test.js) |
| React avatar creator | [avatar-sdk/](avatar-sdk) `→ /react` `/creator` | Published as `@three-ws/avatar` | Same package, React subpath |
| Avatar CLI (manifests in the build pipeline) | [packages/avatar-cli/](packages/avatar-cli), landing [pages/avatar-cli.html](pages/avatar-cli.html) `→ /avatar-cli`, styles [public/avatar-cli.css](public/avatar-cli.css), page runtime [src/avatar-cli-page.js](src/avatar-cli-page.js) | Published as `@three-ws/avatar-cli` | The terminal half of the avatar story, and the half that makes an avatar auditable. Four commands over one file: `init` scaffolds a schema-valid manifest from a wallet plus a mesh (reading the GLB once to compute its SHA-256 and size, so the document cannot disagree with the bytes it was built from), `validate` checks it against [packages/avatar-schema/](packages/avatar-schema) and exits non-zero so it works as a build gate, `hash` prints a bare digest that composes in a shell, and `preview` emits a resolver URL, an `<agent-3d>` snippet paired with the loader that registers it, and a zero-install iframe. Offline and deterministic throughout: no account, no API key, no network call, which is what makes it safe in a release script. `preview` warns instead of printing a dead snippet when `mesh.uri` is still a local `file://` path. The landing page proves the emitted markup by rendering it live rather than screenshotting it. Docs: [docs/avatar-cli.md](docs/avatar-cli.md) `→ /docs/avatar-cli`, tutorial [docs/tutorials/ship-an-avatar-manifest.md](docs/tutorials/ship-an-avatar-manifest.md). Tests: [packages/avatar-cli/test/](packages/avatar-cli/test) |
-| Asset catalog (one search over every ready-made asset) | join + ranking [api/_lib/asset-catalog.js](api/_lib/asset-catalog.js), code generation [api/_lib/asset-snippets.js](api/_lib/asset-snippets.js), REST [api/catalog.js](api/catalog.js) `→ /api/catalog`, MCP tools [api/_mcp/tools/library.js](api/_mcp/tools/library.js), CLI [packages/assets-cli/](packages/assets-cli) | Published as `@three-ws/assets` | The CC0 prop library, the ready-made character library and the motion-clip library joined into one ranked catalog (3,492 items) that also hands back paste-ready source: the `<model-viewer>` tag the browse grids render with, `<agent-3d>` pinned to the exact published version plus its SRI hash, plain three.js, or React. Reachable three ways off one implementation: `GET /api/catalog`, the free MCP tools `search_catalog` / `get_catalog_item` / `get_item_source` (on the dispatcher's public allowlist, so no OAuth and no x402), and `npx @three-ws/assets add <id>`, which downloads the asset into the caller's project and rewrites the snippet to the local path. Every word of a query must match, with a labelled partial-match fallback so a phrase never dead-ends. Docs: [docs/mcp.md](docs/mcp.md) `→ /docs/mcp`, [docs/api-reference.md](docs/api-reference.md). Tests: [tests/api/mcp-asset-catalog.test.js](tests/api/mcp-asset-catalog.test.js), [tests/api/catalog-endpoint.test.js](tests/api/catalog-endpoint.test.js), [packages/assets-cli/test/](packages/assets-cli/test) |
+| Asset catalog (one search over every ready-made asset) | join + ranking [api/_lib/asset-catalog.js](api/_lib/asset-catalog.js), code generation [api/_lib/asset-snippets.js](api/_lib/asset-snippets.js), REST [api/catalog.js](api/catalog.js) `→ /api/catalog`, MCP tools [api/_mcp/tools/library.js](api/_mcp/tools/library.js), CLI [packages/assets-cli/](packages/assets-cli) | Published as `@three-ws/assets` | The CC0 prop library, the ready-made character library and the motion-clip library joined into one ranked catalog (thousands of items; the live count is `total` on `GET /api/catalog`) that also hands back paste-ready source: the `<model-viewer>` tag the browse grids render with, `<agent-3d>` pinned to the exact published version plus its SRI hash, plain three.js, or React. Reachable three ways off one implementation: `GET /api/catalog`, the free MCP tools `search_catalog` / `get_catalog_item` / `get_item_source` (on `/api/mcp`'s public allowlist, so a plain JSON-RPC call needs no OAuth and no x402, though an MCP client connecting there is sent through sign-in on `initialize`; the keyless `/api/mcp-studio` serves the same three to a client with no account via [api/_mcp-studio/catalog-tools.js](api/_mcp-studio/catalog-tools.js)), and `npx @three-ws/assets add <id>`, which downloads the asset into the caller's project and rewrites the snippet to the local path. Every word of a query must match, with a labelled partial-match fallback so a phrase never dead-ends. Docs: [docs/mcp.md](docs/mcp.md) `→ /docs/mcp`, [docs/api-reference.md](docs/api-reference.md). Tests: [tests/api/mcp-asset-catalog.test.js](tests/api/mcp-asset-catalog.test.js), [tests/api/catalog-endpoint.test.js](tests/api/catalog-endpoint.test.js), [packages/assets-cli/test/](packages/assets-cli/test) |
| MCP resources and guided prompts | registry and readers [api/_mcp/resources.js](api/_mcp/resources.js), prompts [api/_mcp/prompts.js](api/_mcp/prompts.js), `read_resource` tools [api/_mcp/tools/resources.js](api/_mcp/tools/resources.js) and [api/_mcp3d/tools/resources.js](api/_mcp3d/tools/resources.js), `create_agent` in [api/_mcp/tools/agents.js](api/_mcp/tools/agents.js) over the shared creation path [api/_lib/agent-create.js](api/_lib/agent-create.js), subscriptions table [api/_lib/migrations/20260922120000_mcp_resource_subscriptions.sql](api/_lib/migrations/20260922120000_mcp_resource_subscriptions.sql), manifest generator [scripts/build-mcp-surfaces.mjs](scripts/build-mcp-surfaces.mjs) | Live on `/api/mcp`, `/api/mcp-agent`, `/api/mcp-3d`, `/api/mcp-bazaar` | Live read-only `three://` views of the caller's account (agents, each agent's Solana wallet with balances, limits and freeze state, usage, chat, runs, orders, DCA, intents, wallets, launches) plus the public marketplace, model catalog, x402 catalog and 3D assets, each as JSON or markdown and each also reachable through the `read_resource` tool. `resources/subscribe` stores a fingerprint per client and the authenticated GET event stream emits `notifications/resources/updated` when it moves; a wallet moves when its latest signature changes. Seventeen guided prompts render against each server's live tools/list, so a server only offers flows whose tools it publishes, and venue flows switch to their executing tools once those ship. `npm run audit:mcp-surfaces` keeps `server*.json` and `/.well-known/mcp.json` in step with the code. Docs: [docs/mcp.md](docs/mcp.md) `→ /docs/mcp`. Tests: [tests/mcp-resources.test.js](tests/mcp-resources.test.js), [tests/mcp-prompts.test.js](tests/mcp-prompts.test.js) |
| Terminal avatar (any avatar or agent body, live in a terminal) | [packages/tty-avatar/](packages/tty-avatar) | Published as `@three-ws/tty-avatar` | `npx @three-ws/tty-avatar <avatar id>` draws the avatar in colour at 24 fps in any terminal: a software rasterizer ([packages/tty-avatar/src/raster.js](packages/tty-avatar/src/raster.js), z-buffered scanline fill, key + fill + rim lighting) over a subpixel grid that three encoders turn into truecolor half-blocks, braille, or plain ASCII ([packages/tty-avatar/src/encode.js](packages/tty-avatar/src/encode.js)). Sources: a `.glb` path, a URL, an avatar id (`/api/avatars/:id`), `agent:<id>` (the agent's bound body via `/api/agents/:id`), or a three.ws page URL. Moods are procedural whole-body motion ([packages/tty-avatar/src/moods.js](packages/tty-avatar/src/moods.js)), so a rigless prop animates too, and they cross-fade. The point of it: `install-hooks --write` merges nine Claude Code hooks whose command is a bare `cat > ~/.three-ws/tty-avatar/event.json` (zero startup cost per tool call), the viewer polls that file and maps each payload to a mood and a caption ([packages/tty-avatar/src/state.js](packages/tty-avatar/src/state.js)), so the avatar thinks, works, errors, asks and celebrates in step with the agent. Every avatar and agent page's Embed tab prints the command ([src/avatar-page.js](src/avatar-page.js)). Docs: [docs/tty-avatar.md](docs/tty-avatar.md) `→ /docs/tty-avatar`. Tests: [packages/tty-avatar/test/](packages/tty-avatar/test) (builds a real GLB in memory and exercises loader, rasterizer, encoders, moods, state bridge, hook installer and CLI) |
| Model Diff (what changed between two GLBs) | [pages/diff.html](pages/diff.html) `→ /diff` + page runtime [src/model-diff.js](src/model-diff.js), 3D stage [src/model-diff-stage.js](src/model-diff-stage.js), styles [public/model-diff.css](public/model-diff.css), engine [packages/glb-diff/](packages/glb-diff), free API [api/3d/diff.js](api/3d/diff.js) `→ /api/3d/diff` (catalog entry [api/_lib/3d-catalog/diff.js](api/_lib/3d-catalog/diff.js)), MCP tool `diff_models` in [api/_mcp/tools/models.js](api/_mcp/tools/models.js) | Live | The check that catches the most expensive silent failure in an asset pipeline: a checksum flags every re-export, and cannot tell a lossless recompression from a rig that quietly lost three finger joints. Objects are paired in three passes the way git pairs renamed files (name, then content hash, then similarity), so an exporter that renumbers `Mesh.001` reads as a rename rather than a rewrite, and a node that kept its name but changed parent reads as a move. Vertex data is hashed at a 1e-4 quantum with normals, UVs and **skin weights** included, so a Draco round trip registers as nothing and a re-skin registers as a change. Every difference carries a severity (`none` to `breaking`), where breaking means something a consumer addresses by name is gone: a clip, a joint, a mesh. One engine, four surfaces, so a CI verdict can never disagree with the page: the browser page (drop two files, nothing uploaded; overlay / wipe / side-by-side in 3D, clicking a row frames that node), the free keyless API (`?a=&b=`, `format=markdown` for a pull-request comment), the `glb-diff` CLI (`--fail-on breaking`, exit 2 reserved for "could not run"), and the MCP tool. Docs: [docs/model-diff.md](docs/model-diff.md) `→ /docs/model-diff`. Tests: [packages/glb-diff/tests/glb-diff.test.js](packages/glb-diff/tests/glb-diff.test.js), [tests/model-diff-api.test.js](tests/model-diff-api.test.js) |
diff --git a/api/_mcp-studio/catalog-tools.js b/api/_mcp-studio/catalog-tools.js
new file mode 100644
index 000000000..6672f0c29
--- /dev/null
+++ b/api/_mcp-studio/catalog-tools.js
@@ -0,0 +1,53 @@
+// three.ws 3D Studio (free): the asset catalog tools.
+//
+// search_catalog, get_catalog_item and get_item_source are free public reads of
+// the published CC0 props, rigged characters and motion clips. The main server
+// at /api/mcp also lists them, but an MCP client that connects there is sent
+// through OAuth sign-in on initialize, because most of that server's tools act on
+// an account. This keyless server is where a client with no account reaches the
+// catalog, so "check the catalog before you generate" holds on the server the
+// generation tools live on.
+//
+// The definitions are the main server's own (api/_mcp/tools/library.js): one
+// implementation, two transports, identical answers. Each tool is named here
+// explicitly because scripts/build-openai-skills-bundle.mjs reads the tool names
+// this directory declares to decide which skills the studio can serve.
+
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+import { toolDefs as libraryTools } from '../_mcp/tools/library.js';
+
+// The studio's contract carries no payment vocabulary at all (tests/mcp-studio.test.js
+// holds every studio tool to that), so the main server's "no account or payment"
+// lead-in is restated as what it means here.
+const MAIN_SERVER_LEAD = /^FREE, no account or payment\. /;
+
+function libraryTool(name) {
+ const def = libraryTools.find((d) => d.name === name);
+ if (!def) throw new Error(`api/_mcp/tools/library.js no longer defines ${name}`);
+ return { ...def, description: def.description.replace(MAIN_SERVER_LEAD, 'Free, no account needed. ') };
+}
+
+const DEFS = [
+ {
+ ...libraryTool('search_catalog'),
+ name: 'search_catalog',
+ },
+ {
+ ...libraryTool('get_catalog_item'),
+ name: 'get_catalog_item',
+ },
+ {
+ ...libraryTool('get_item_source'),
+ name: 'get_item_source',
+ },
+];
+
+export const CATALOG_TOOL_CATALOG = DEFS.map(({ handler: _h, ...schema }) => schema);
+
+const ajv = new Ajv({ allErrors: true, useDefaults: true, coerceTypes: true, strict: false });
+addFormats(ajv);
+
+export const CATALOG_TOOLS = Object.fromEntries(
+ DEFS.map(({ name, handler, inputSchema }) => [name, { handler, validate: ajv.compile(inputSchema) }]),
+);
diff --git a/api/_mcp-studio/dispatch.js b/api/_mcp-studio/dispatch.js
index 420544321..198f17db5 100644
--- a/api/_mcp-studio/dispatch.js
+++ b/api/_mcp-studio/dispatch.js
@@ -11,6 +11,7 @@ import { recordEvent, logger } from '../_lib/usage.js';
import { sanitizeToolError } from '../_lib/mcp-error-sanitize.js';
import { TOOL_CATALOG, TOOLS } from './tools.js';
import { PERSONA_TOOL_CATALOG, PERSONA_TOOLS } from './persona-tools.js';
+import { CATALOG_TOOL_CATALOG, CATALOG_TOOLS } from './catalog-tools.js';
import { finishCall, gateCall, listForRequest } from '../_mcp/policy.js';
// The @three-ws/mcp-policy server id for the free studio.
@@ -52,6 +53,12 @@ const CHATGPT_INSTRUCTIONS = [
// response's own trip back through ChatGPT.
export const CHATGPT_CALL_BUDGET_MS = 40_000;
+const CATALOG_INSTRUCTIONS = [
+ 'Before generating a prop, character or animation, search_catalog(q) checks the thousands of ready-made CC0 props,',
+ 'rigged characters and motion clips three.ws already publishes; get_item_source(id) returns paste-ready code for a',
+ 'match. Say whether you used an existing asset or generated a new one.',
+];
+
const PERSONA_INSTRUCTIONS = [
'To give the assistant a LIVING body: create_agent_persona(glb_url, name) saves a rigged model as a named,',
'persistent persona and returns a persona_id; persona_say(persona_id, text) makes that body lip-sync the reply and',
@@ -62,7 +69,9 @@ const PERSONA_INSTRUCTIONS = [
// Two surfaces share this dispatcher, each advertising a consistent set of
// tools, widgets and model instructions.
// full /api/mcp-studio: every tool and both widgets, for Claude, the
-// examples, and any MCP host that renders the inline living body.
+// examples, and any MCP host that renders the inline living body,
+// plus the free asset catalog tools (./catalog-tools.js), the only
+// place a keyless MCP client can reach them.
// chatgpt /api/mcp-chatgpt: the eight tools in ./tools.js and the
// model-viewer widget only. The persona widget frames the hosted
// embodiment page, which requires frameDomains, and OpenAI's app
@@ -77,10 +86,10 @@ const PERSONA_INSTRUCTIONS = [
const SURFACES = {
full: {
server: 'mcp-studio',
- catalog: [...TOOL_CATALOG, ...PERSONA_TOOL_CATALOG],
- tools: { ...TOOLS, ...PERSONA_TOOLS },
+ catalog: [...TOOL_CATALOG, ...CATALOG_TOOL_CATALOG, ...PERSONA_TOOL_CATALOG],
+ tools: { ...TOOLS, ...CATALOG_TOOLS, ...PERSONA_TOOLS },
personas: true,
- instructions: [...BASE_INSTRUCTIONS, ...PERSONA_INSTRUCTIONS].join(' '),
+ instructions: [...BASE_INSTRUCTIONS, ...CATALOG_INSTRUCTIONS, ...PERSONA_INSTRUCTIONS].join(' '),
},
chatgpt: {
server: 'mcp-chatgpt',
diff --git a/blog/three-ws-on-anthropic-mcp-registry.html b/blog/three-ws-on-anthropic-mcp-registry.html
index f095d2524..eeebd42e3 100644
--- a/blog/three-ws-on-anthropic-mcp-registry.html
+++ b/blog/three-ws-on-anthropic-mcp-registry.html
@@ -69,7 +69,8 @@
<h2>What the MCP listing unlocks</h2>
<p>The Model Context Protocol Registry is Anthropic's official index of remote tool servers that AI assistants can call. Being listed here means Claude — and any other MCP-compatible agent — can natively discover and invoke the three.ws toolkit without any custom configuration from the developer.</p>
- <p>What that means in practice: drop <code>https://three.ws/api/mcp</code> as a remote server into Claude Desktop, Cursor, or any MCP client, and you instantly have access to the full three.ws 3D agent toolkit. Create a 3D avatar, give it an on-chain identity, wire it to an LLM brain, and embed it anywhere — all driven by natural language through the same tools Claude already knows how to call.</p>
+ <p>What that means in practice: drop <code>https://three.ws/api/mcp</code> as a remote server into Claude Desktop, Cursor, or any MCP client, sign in with your three.ws account when the client asks, and you have the full three.ws 3D agent toolkit. Create a 3D avatar, give it an on-chain identity, wire it to an LLM brain, and embed it anywhere, all driven by natural language through the same tools Claude already knows how to call.</p>
+ <p>The sign-in comes first because most of those tools act on your own avatars, agents, and wallet, so the client is asked to authorize as soon as it connects. To try three.ws with no account at all, add <code>https://three.ws/api/mcp-studio</code> instead. It never asks you to sign in, and it serves free text-to-3D and image-to-3D generation, rigged avatars, and a search of the ready-made asset catalog (CC0 props, rigged characters, and motion clips) with paste-ready code for each. See the <a href="/docs/mcp-studio">studio server docs</a>.</p>
<h2>What the three.ws MCP server exposes</h2>
<ul>
diff --git a/data/changelog.json b/data/changelog.json
index 71e02ded4..1a697dcd3 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,13 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-10-01",
+ "title": "Search the 3D asset catalog from any AI client without an account",
+ "summary": "Our docs said an AI client could connect to the main three.ws MCP server and search the ready-made asset catalog with no account, but adding that server makes the client ask you to sign in straight away, because most of its tools work on your own avatars and agents. The free studio server, three.ws/api/mcp-studio, now carries the same three catalog tools (search, item details and paste-ready code), so an AI client with no account can check the thousands of ready-made props, characters and motion clips before it generates anything. The docs, the find-3d-assets skill and the registry post now say which server to add, and the asset counts no longer go stale.",
+ "tags": ["fix", "docs"],
+ "link": "/docs/mcp-studio"
+ },
{
"date": "2026-10-01",
"title": "Trending and the agent directory show only real agents",
diff --git a/docs/agent-skills.md b/docs/agent-skills.md
index fe03e35dc..34720678b 100644
--- a/docs/agent-skills.md
+++ b/docs/agent-skills.md
@@ -137,11 +137,10 @@ instructions scoped to the plugin's purpose.
references one the endpoint does not serve. When run online it first checks that
the live endpoint and this checkout agree on the tool surface, and fails if they
do not, because that disagreement means production is running different code.
-`find-3d-assets` is excluded today on the first rule: its `search_catalog` /
-`get_catalog_item` / `get_item_source` tools live on the full MCP server, not on
-the hosted studio endpoint, and inside ChatGPT there is no shell to reach the
-skill's `curl` fallback. Ship those three on mcp-studio and the skill rejoins the
-bundle with no edit to the builder.
+`find-3d-assets` was excluded on this rule until its `search_catalog` /
+`get_catalog_item` / `get_item_source` tools shipped on the studio endpoint
+([`api/_mcp-studio/catalog-tools.js`](../api/_mcp-studio/catalog-tools.js)); it is
+in the bundle now, with no edit to the builder.
Published Markdown follows the repo's dash rule; the canonical files under
`.agents/skills/` are never rewritten.
@@ -180,8 +179,8 @@ schema, and failure envelope, so the model does not have to guess.
The platform's signature set, safe to reuse anywhere:
-- **`find-3d-assets`**: search the 3,492 ready-made assets three.ws already
- publishes (511 CC0 props, 107 rigged characters, 2,874 motion clips) and get
+- **`find-3d-assets`**: search the thousands of ready-made assets three.ws already
+ publishes (CC0 props, rigged characters, and the motion-clip library) and get
paste-ready code or a downloaded file. Free, and the one to try FIRST: an
existing asset is instant where a generation is GPU minutes. Reachable three
ways off one catalog (the `search_catalog` / `get_catalog_item` /
diff --git a/docs/mcp-studio.md b/docs/mcp-studio.md
index c5987c03e..f665054b1 100644
--- a/docs/mcp-studio.md
+++ b/docs/mcp-studio.md
@@ -29,10 +29,10 @@ generation quota:
| URL | Serves | Use it for |
|---|---|---|
-| `https://three.ws/api/mcp-studio` | all eleven tools, both widgets | any MCP host, including a ChatGPT developer-mode connector |
+| `https://three.ws/api/mcp-studio` | all fourteen tools (the 3D tools, the asset catalog, the persona tools), both widgets | any MCP host, including a ChatGPT developer-mode connector |
| `https://three.ws/api/mcp-chatgpt` | the eight 3D tools and the model viewer | the ChatGPT plugin directory listing |
-The ChatGPT surface leaves out the three persona tools because their widget
+The ChatGPT surface leaves out the three catalog tools, which keeps that listing's reviewed tool set unchanged, and the three persona tools, because their widget
frames the hosted embodiment page, which needs `frameDomains`. OpenAI's app
guidelines reserve frame domains for embedding an essential third-party
experience and say those apps "are often not approved for broad distribution";
@@ -76,16 +76,18 @@ launcher, living avatars, link unfurls) is documented end to end in
## Tools
-`tools/list` returns exactly **eleven** tools, and they split four ways:
+`tools/list` returns exactly **fourteen** tools, and they split five ways:
- **Six generation tools** (`forge_free`, `text_to_avatar`, `mesh_forge`,
`rig_mesh`, `forge_avatar`, `refine_model`), in the table below.
- **One collector**, `check_job`, also in the table below.
- **One inspector**, `look_at_model`, also in the table below.
+- **Three asset catalog reads** (`search_catalog`, `get_catalog_item`,
+ `get_item_source`), in **Ready-made assets** below.
- **Three persona/embodiment tools** (`create_agent_persona`,
`get_agent_persona`, `persona_say`), in the **Embodiment** section further down.
-All eleven are free and keyless.
+All fourteen are free and keyless.
The six generation tools run operator-funded on the platform's own generation
pipeline. Annotations: `readOnlyHint:false`, `destructiveHint:false`,
@@ -112,6 +114,25 @@ quota as the six generators.
| `check_job` | Check a pending 3D generation and collect it | `job_id` | GLB model, or an updated pending state |
| `look_at_model` | Look at a 3D model | `glb_url`, `views?` (up to 6 of `front`, `three-quarter`, `side`, `back`, `top`, `bottom`; default three-quarter, front, side, back), `size?` (128 to 1024 px, default 512) | rendered frames as images, plus geometry stats (triangles, materials, textures) and a plain reading of them |
+### Ready-made assets (`search_catalog`, `get_catalog_item`, `get_item_source`)
+
+Before generating anything, check whether three.ws already publishes it. These
+three read-only tools search the same catalog as the main server's tools of the
+same names ([`api/_mcp/tools/library.js`](../api/_mcp/tools/library.js), served
+here by [`api/_mcp-studio/catalog-tools.js`](../api/_mcp-studio/catalog-tools.js)):
+the CC0 prop library, the ready-made rigged characters and the motion-clip library.
+`search_catalog` takes `q`, `kind`, `category`, `tag`, `limit` and `offset`;
+`get_catalog_item` and `get_item_source` take the `id` it returns, and
+`get_item_source` hands back paste-ready code (the `<agent-3d>` tag pinned to a
+release and its integrity hash, `<model-viewer>`, three.js or React). Schemas and
+example responses are in [docs/mcp.md](./mcp.md#search_catalog).
+
+They are here because this is the server an MCP client can use with no account.
+The main server at `https://three.ws/api/mcp` lists the same three tools, but a
+protocol client that connects there is sent through three.ws sign-in first,
+because most of that server's tools act on an account. The catalog tools never
+count against the generation quota.
+
### Quality tiers
`forge_free` takes an optional `tier` of `draft`, `standard`, or `high`.
diff --git a/docs/mcp.md b/docs/mcp.md
index 339b10390..a139a0865 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -179,6 +179,8 @@ GET /.well-known/oauth-protected-resource
On a `401`, the `WWW-Authenticate` header points clients at the protected-resource metadata URL so they can begin the flow.
+This is also why an MCP client asks you to sign in as soon as you add `https://three.ws/api/mcp`, even if you only meant to use the free tools: the `401` arrives on `initialize`, before any tool is chosen. A client with no account belongs on `https://three.ws/api/mcp-studio`, which never challenges and serves the free 3D generation and asset catalog tools.
+
### API key (server-to-server)
For scripts, CI, and server agents, generate a key at **[/dashboard/api](https://three.ws/dashboard/api)** and pass it as a bearer token:
@@ -240,16 +242,17 @@ Send `POST /api/mcp` with valid JSON-RPC 2.0 messages and a bearer token. The se
All tools return `{ content: [{ type, text }], structuredContent: {...} }`. On error, `isError: true` is set and `content[0].text` contains the message.
-`search_catalog`, `get_catalog_item`, and `get_item_source` are free and need no account, API key, or payment: start there. The tools below them are the core avatar, validation, minting, and market-data set. The server registers more beyond this page (memory `remember`/`recall`/`forget`, `register_agent`, oracle and pump.fun intel reads, trader analytics, copy-trading); call `tools/list` for the complete live catalog with schemas.
+`search_catalog`, `get_catalog_item`, and `get_item_source` are free and need no API key or payment: start there. How you reach them without an account depends on the client. A plain JSON-RPC `tools/call` to `https://three.ws/api/mcp` (curl, `fetch`, any script that does not speak the MCP transport) is served anonymously. An MCP client that connects to `/api/mcp` is a different case: the server answers its `initialize` with `401` so the client starts three.ws sign-in (see [Authentication](#authentication)), because most tools on this server act on an account. To use the catalog from an MCP client with no account, connect it to the free studio server, `https://three.ws/api/mcp-studio`, which serves the same three tools keyless ([docs/mcp-studio.md](./mcp-studio.md)). The tools below them are the core avatar, validation, minting, and market-data set. The server registers more beyond this page (memory `remember`/`recall`/`forget`, `register_agent`, oracle and pump.fun intel reads, trader analytics, copy-trading); call `tools/list` for the complete live catalog with schemas.
---
### `search_catalog`
-Search every ready-made asset three.ws publishes in one call: 511 CC0 props, 107 rigged
-characters, and 2,874 retargetable motion clips (live counts come back in `facets.kinds`).
+Search every ready-made asset three.ws publishes in one call: the CC0 prop library, the
+rigged character library, and thousands of retargetable motion clips. The libraries grow, so
+read the live counts from `facets.kinds` in any response rather than trusting a number here.
-**Free. No account, no API key, no x402 payment.** Discovery works before you connect.
+**Free. No API key, no x402 payment.** No account either: call it as plain JSON-RPC here, or from an MCP client on the keyless `https://three.ws/api/mcp-studio`.
```json
{
diff --git a/packages/assets-cli/README.md b/packages/assets-cli/README.md
index 406d687e9..260aa8212 100644
--- a/packages/assets-cli/README.md
+++ b/packages/assets-cli/README.md
@@ -5,7 +5,8 @@ and put it in your project, with the code that renders it.
Free and public. No account, no API key, no payment, nothing to sign up for. The catalog it
searches is the platform's published CC0 object library, ready-made character library, and
-motion-clip library: **3,492 assets** as of September 2026.
+motion-clip library: thousands of assets and growing. `GET https://three.ws/api/catalog?limit=1`
+returns the live count as `total`.
```bash
npx @three-ws/assets search wooden chair --kind object
@@ -158,13 +159,16 @@ Or talk to the endpoint directly: `GET https://three.ws/api/catalog?q=desk+lamp&
## The same catalog from an AI client
Every three.ws MCP client gets the same data through three free tools, `search_catalog`,
-`get_catalog_item`, and `get_item_source`. Add the server and ask for a chair in plain
-language:
+`get_catalog_item`, and `get_item_source`. Add the keyless studio server, which needs no
+account, and ask for a chair in plain language:
```json
-{ "mcpServers": { "three-ws": { "type": "http", "url": "https://three.ws/api/mcp" } } }
+{ "mcpServers": { "three-ws-studio": { "type": "http", "url": "https://three.ws/api/mcp-studio" } } }
```
+The main server at `https://three.ws/api/mcp` lists the same tools, but an MCP client that
+adds it is asked to sign in to a three.ws account first.
+
See [docs/mcp.md](https://three.ws/docs/mcp) for the tool schemas.
## License
diff --git a/packages/mcp-policy/src/table.js b/packages/mcp-policy/src/table.js
index 0ab2c6e9c..d1577eebc 100644
--- a/packages/mcp-policy/src/table.js
+++ b/packages/mcp-policy/src/table.js
@@ -236,6 +236,9 @@ export const POLICY = {
refine_model: w('assets'),
check_job: w('assets'),
look_at_model: r('assets'),
+ search_catalog: r('assets'),
+ get_catalog_item: r('assets'),
+ get_item_source: r('assets'),
create_agent_persona: w('agents'),
get_agent_persona: r('agents'),
persona_say: w('agents'),
diff --git a/public/.well-known/mcp.json b/public/.well-known/mcp.json
index a4a731d98..44ec75266 100644
--- a/public/.well-known/mcp.json
+++ b/public/.well-known/mcp.json
@@ -74,7 +74,7 @@
"endpoint": "https://three.ws/api/mcp-studio",
"transport": "streamable-http",
"auth": "none",
- "description": "Free text-to-3D, image-to-3D, rigged avatars, and persistent talking personas. No account, no payment.",
+ "description": "Free text-to-3D, image-to-3D, rigged avatars, persistent talking personas, and a search of the ready-made asset catalog. No account, no payment.",
"documentation": "https://three.ws/docs/mcp-studio"
},
{
diff --git a/public/skills/3d-studio/README.md b/public/skills/3d-studio/README.md
index 880235733..2d011d10d 100644
--- a/public/skills/3d-studio/README.md
+++ b/public/skills/3d-studio/README.md
@@ -9,6 +9,7 @@ https://three.ws/api/mcp-studio.
| --- | --- |
| [`create-3d-avatar`](create-3d-avatar/SKILL.md) | Turn a text prompt (or reference image) into a rigged, animation-ready 3D avatar (GLB). |
| [`embed-three-ws-avatar`](embed-three-ws-avatar/SKILL.md) | Embed a live, animated three.ws 3D avatar in any website with the &lt;agent-3d&gt; web component. |
+| [`find-3d-assets`](find-3d-assets/SKILL.md) | Search thousands of ready-made 3D assets on three.ws (CC0 props and objects, rigged humanoid characters, motion clips) and get paste-ready code or a downloaded file. |
| [`generate-3d-model`](generate-3d-model/SKILL.md) | Turn a text prompt into a downloadable, textured 3D model (GLB). |
| [`rig-a-model`](rig-a-model/SKILL.md) | Auto-rig a static 3D GLB model into an animation-ready one. |
diff --git a/public/skills/3d-studio/find-3d-assets/SKILL.md b/public/skills/3d-studio/find-3d-assets/SKILL.md
new file mode 100644
index 000000000..a8bc902ce
--- /dev/null
+++ b/public/skills/3d-studio/find-3d-assets/SKILL.md
@@ -0,0 +1,151 @@
+---
+name: find-3d-assets
+description: Search thousands of ready-made 3D assets on three.ws (CC0 props and objects, rigged humanoid characters, motion clips) and get paste-ready code or a downloaded file. Use when you or the user need a 3D model, prop, object, character, or animation for a scene, site, game, or app ("I need a 3D chair", "find a rigged character", "is there a wave animation", "add a lamp model to my page"). Free: no account, no API key, no payment. Check here BEFORE generating a model from scratch.
+when_to_use: Something needs a 3D asset and a ready-made one would do. If the catalog has no match, fall through to generate-3d-model (props) or create-3d-avatar (characters). To put an asset you already have on a page, use embed-three-ws-avatar.
+license: MIT
+metadata:
+ category: 3d/creative
+ cross-platform-safe: true
+ pack: three-ws-skills
+---
+
+# Find a ready-made 3D asset
+
+three.ws publishes three asset libraries and joins them into one searchable catalog:
+
+| Kind | What it is |
+| --- | --- |
+| `object` | CC0 props and objects (furniture, lighting, tools, electronics, decor) staged as web GLB |
+| `character` | Ready-made rigged humanoids, animation-ready out of the box |
+| `animation` | Retargetable motion clips as `THREE.AnimationClip` JSON (the largest library, in the thousands) |
+
+The libraries grow, so do not quote a count from memory: every search response carries the live
+per-kind totals in `facets.kinds`, and `total` is the size of the whole catalog.
+
+Everything here is **free and public**: no account, no API key, no payment, no rate card.
+
+## Check the catalog before you generate
+
+Generating a model takes GPU minutes and returns something nobody has reviewed. The catalog
+returns a finished, textured asset instantly. So the order is:
+
+1. Search the catalog. If something fits, use it. Done.
+2. Nothing fits, and it is a **prop or object**? Use `generate-3d-model`.
+3. Nothing fits, and it is a **character**? Use `create-3d-avatar`.
+
+Say which one you did. "I found an existing CC0 chair" and "I generated a chair" are
+different answers and the user should know which they got.
+
+## The fastest path: MCP tools
+
+If a three.ws MCP server is connected, three free tools cover the whole flow:
+
+| Tool | Use |
+| --- | --- |
+| `search_catalog` | Find assets by text, `kind`, `category`, or `tag` |
+| `get_catalog_item` | One item in full, with links and related items |
+| `get_item_source` | Paste-ready code for one item |
+
+```
+search_catalog { "q": "wooden chair", "kind": "object", "limit": 5 }
+get_item_source { "id": "object:painted_wooden_chair_01" }
+```
+
+Not connected? Add the keyless studio server. It needs no account and also carries the
+free generation tools the catalog falls through to:
+
+```json
+{ "mcpServers": { "three-ws-studio": { "type": "http", "url": "https://three.ws/api/mcp-studio" } } }
+```
+
+The main server, `https://three.ws/api/mcp`, lists the same three tools, but an MCP client
+that adds it is asked to sign in to a three.ws account as soon as it connects, because most
+of that server's tools act on an account. Add it when the user already has one or wants their
+own library; for the catalog alone, the studio server is the no-account path. Plain HTTP
+(below) also needs no account.
+
+## Without MCP: the HTTP endpoint
+
+```bash
+curl -s 'https://three.ws/api/catalog?q=industrial+lamp&kind=object&limit=5'
+curl -s 'https://three.ws/api/catalog?id=object:painted_wooden_chair_01'
+```
+
+The search form returns `items[]` with `id`, `title`, `tags`, `license`, `url` (the CDN GLB or
+clip JSON), `thumb`, and `facets` you can use to narrow the next query. The `id` form adds
+`links`, `related`, and `snippets` for every framework that applies.
+
+Search semantics worth knowing: **every word must match** something, which keeps a two-word
+query precise. If nothing matches all of them, the response comes back with `relaxed: true`
+and the partial matches, best first. Check that flag before telling a user you found an exact
+match.
+
+## Putting it in a project: the CLI
+
+```bash
+npx @three-ws/assets search wooden chair --kind object
+npx @three-ws/assets add object:painted_wooden_chair_01
+```
+
+`add` downloads the GLB into `public/three-ws/` (or `three-ws-assets/` when the project has no
+`public/` directory) and prints the snippet **already rewritten to the local path**, so the
+host site does not depend on the three.ws CDN staying up.
+
+It is safe to re-run: identical bytes report as already up to date, and a file edited after it
+was added is never overwritten without `--force`.
+
+Useful flags: `--dir <path>`, `--framework <f>`, `--thumb`, `--json`.
+
+## Which framework to emit
+
+`get_item_source` (and `show`/`add` in the CLI) default to the right one per kind. Override
+with `framework` only when the project dictates it.
+
+| Framework | Emits | Default for |
+| --- | --- | --- |
+| `model-viewer` | The `<model-viewer>` tag, build, and integrity hash the three.ws browse grids render with | props |
+| `agent-3d` | The `<agent-3d>` web component, pinned to the exact published version with its SRI hash | rigged characters |
+| `three` | Plain three.js: `GLTFLoader` for a model, `THREE.AnimationClip.parse` for a clip | motion clips |
+| `react` | The same as a React component, or a hook for a clip | React projects |
+| `all` | Every applicable variant in one response | when you are choosing |
+
+The `agent-3d` snippet is never pinned to `latest`, because `latest` can change under the
+reader with no action on their side. Keep the version and the `integrity` attribute intact
+when you paste it.
+
+## Worked example
+
+User: *"put a chair on the landing page"*
+
+```
+search_catalog { "q": "wooden chair", "kind": "object", "limit": 3 }
+```
+
+```
+10 matches for "wooden chair" (showing 3 from offset 0):
+- `object:painted_wooden_chair_01` | Painted Wooden Chair 01 | CC0 | chair, wood, painted
+- `object:painted_wooden_chair_02` | Painted Wooden Chair 02 | CC0 | old, wooden, vintage
+- `object:WoodenChair_01` | Wooden Chair 01 | CC0 | wood, prop, vintage
+```
+
+```
+get_item_source { "id": "object:painted_wooden_chair_01" }
+```
+
+Returns the `<model-viewer>` block to paste, the preview link, and the license (`CC0`). Paste
+it, tell the user which asset you used and that it is public domain, and link the preview so
+they can look at it before shipping.
+
+## Licensing
+
+Every `object` in the library is **CC0**: public domain, commercial use fine, no attribution
+required. Characters and clips carry their own `license` field, which travels with every
+response. Read it and pass it on; do not assume CC0 outside the object library.
+
+## Related skills
+
+- `generate-3d-model` when the catalog has no match for a prop.
+- `create-3d-avatar` when the catalog has no match for a character.
+- `embed-three-ws-avatar` for the full `<agent-3d>` embedding story, including moods,
+ animations, and driving the avatar from page code.
+- `rig-a-model` to add a skeleton to a static GLB you already have.
diff --git a/public/skills/3d-studio/three-ws-3d-skills.zip b/public/skills/3d-studio/three-ws-3d-skills.zip
index 072af7a58..8bc324b2a 100644
Binary files a/public/skills/3d-studio/three-ws-3d-skills.zip and b/public/skills/3d-studio/three-ws-3d-skills.zip differ
diff --git a/scripts/build-openai-skills-bundle.mjs b/scripts/build-openai-skills-bundle.mjs
index ed4d1d879..c1a9e878c 100644
--- a/scripts/build-openai-skills-bundle.mjs
+++ b/scripts/build-openai-skills-bundle.mjs
@@ -26,10 +26,9 @@
// 2. No dead paths. A skill is only true if its tools exist. This reads the
// tool names the studio endpoint actually declares and drops any skill
// referencing one that is missing, naming it in the report. find-3d-assets
-// is excluded today for exactly that reason: its catalog tools live on the
-// full MCP server, not on mcp-studio, and inside ChatGPT there is no shell,
-// so the skill's documented curl fallback cannot rescue it either. Ship
-// those tools on mcp-studio and the skill rejoins with no edit here.
+// was excluded for exactly that reason until its catalog tools shipped on
+// mcp-studio (api/_mcp-studio/catalog-tools.js); inside ChatGPT there is no
+// shell, so the skill's curl fallback could not have rescued it.
//
// 3. Determinism. Published output is tracked, so a rebuild that changes bytes
// for no reason would show up as a diff in everyone else's worktree. Staged
diff --git a/tests/mcp-studio.test.js b/tests/mcp-studio.test.js
index 3d1bc9693..2e0c6769a 100644
--- a/tests/mcp-studio.test.js
+++ b/tests/mcp-studio.test.js
@@ -2,6 +2,8 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { TOOL_CATALOG, TOOL_NAMES } from '../api/_mcp-studio/tools.js';
import { PERSONA_TOOL_CATALOG, PERSONA_TOOL_NAMES } from '../api/_mcp-studio/persona-tools.js';
+import { CATALOG_TOOL_CATALOG, CATALOG_TOOLS } from '../api/_mcp-studio/catalog-tools.js';
+import { toolDefs as LIBRARY_TOOLS } from '../api/_mcp/tools/library.js';
import { dispatch, toolCatalogFor } from '../api/_mcp-studio/dispatch.js';
import { COMPONENT_HTML, COMPONENT_URI, PERSONA_COMPONENT_URI, componentCsp } from '../api/_mcp-studio/component.js';
import { MODEL_VIEWER_CDN_ORIGIN } from '../api/_lib/model-viewer-cdn.js';
@@ -10,10 +12,13 @@ import { MODEL_VIEWER_CDN_ORIGIN } from '../api/_lib/model-viewer-cdn.js';
// model-viewer widget) + check_job (collects a pending generation) +
// look_at_model (renders frames of an existing model). PERSONA adds the three
// embodiment tools from api/_mcp-studio/persona-tools.js (which render the
-// living-body embed), for the eleven the connector advertises in total.
+// living-body embed). CATALOG adds the three free asset catalog reads
+// (api/_mcp-studio/catalog-tools.js) on the full surface only, for the fourteen
+// /api/mcp-studio advertises in total.
const ALLOWED = ['forge_free', 'text_to_avatar', 'mesh_forge', 'rig_mesh', 'forge_avatar', 'refine_model', 'check_job', 'look_at_model'];
const PERSONA = ['create_agent_persona', 'get_agent_persona', 'persona_say'];
-const ALL = [...ALLOWED, ...PERSONA];
+const CATALOG = ['search_catalog', 'get_catalog_item', 'get_item_source'];
+const ALL = [...ALLOWED, ...CATALOG, ...PERSONA];
// Anything that would signal a crypto / payment surface. The whole point of the
// free studio app is that NONE of this appears anywhere in its contract — the
@@ -127,7 +132,7 @@ describe('mcp-studio dispatch', () => {
expect(FORBIDDEN.test(JSON.stringify(r))).toBe(false);
});
- it('tools/list returns the generation + persona tools', async () => {
+ it('tools/list returns the generation, catalog and persona tools', async () => {
const r = await dispatch({ jsonrpc: '2.0', id: 2, method: 'tools/list' }, auth, mkReq());
expect(r.result.tools.map((t) => t.name).sort()).toEqual([...ALL].sort());
});
@@ -591,6 +596,42 @@ describe('mcp-studio dispatch', () => {
// The ChatGPT plugin surface (/api/mcp-chatgpt). It must never advertise a tool
// or widget that needs frameDomains, and a persona call on it must fail rather
// than succeed off-listing.
+// A keyless MCP client is sent through OAuth on /api/mcp, so this server is where
+// it reaches the asset catalog. The tools must be the main server's own (same
+// handler, same schema) and hold the studio's no-payment-vocabulary bar.
+describe('mcp-studio asset catalog tools', () => {
+ it('serves the main server catalog tools with their own handlers and schemas', () => {
+ expect(CATALOG_TOOL_CATALOG.map((t) => t.name)).toEqual(CATALOG);
+ for (const name of CATALOG) {
+ const lib = LIBRARY_TOOLS.find((d) => d.name === name);
+ const studio = CATALOG_TOOL_CATALOG.find((t) => t.name === name);
+ expect(CATALOG_TOOLS[name].handler).toBe(lib.handler);
+ expect(studio.inputSchema).toEqual(lib.inputSchema);
+ expect(studio.annotations.readOnlyHint).toBe(true);
+ expect(studio.description.startsWith('Free, no account needed.')).toBe(true);
+ }
+ });
+
+ it('carries no payment vocabulary', () => {
+ expect(FORBIDDEN.test(JSON.stringify(CATALOG_TOOL_CATALOG))).toBe(false);
+ });
+
+ it('rejects a call with no id before reaching the catalog', async () => {
+ const r = await dispatch(
+ { jsonrpc: '2.0', id: 30, method: 'tools/call', params: { name: 'get_item_source', arguments: {} } },
+ auth,
+ mkReq(),
+ );
+ expect(r.error.code).toBe(-32602);
+ expect(r.error.message).toMatch(/required property 'id'/);
+ });
+
+ it('tells the model to check the catalog before generating', async () => {
+ const r = await dispatch({ jsonrpc: '2.0', id: 31, method: 'initialize' }, auth, mkReq());
+ expect(r.result.instructions).toMatch(/search_catalog/);
+ });
+});
+
describe('mcp-studio chatgpt surface', () => {
const opts = { surface: 'chatgpt' };