3D engine that AI agents drive
Serve one valid call per hard tool under scene_capabilities examples
Nguyen Xuan Anf4825eadf926
diff --git a/changes/657.md b/changes/657.mdnew file mode 100644index 00000000..edd8e614--- /dev/null+++ b/changes/657.md@@ -0,0 +1 @@+- `scene_capabilities` topic `examples` (and `examples.<tool>`) serves one valid call each for `scene_create`, `scene_apply`, `scene_create_asset` and `scene_render_submit`, with no growth of any tool schema (#657)diff --git a/docs/mcp.md b/docs/mcp.mdindex e5a5a9b0..f1087398 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -122,7 +122,7 @@ Inspect or export the recipe before retrying. Context loss still permits recipe| Tool | Arguments | Result || --- | --- | --- |-| `scene_capabilities` | `topic` (optional) | A short index of topics; with a topic, its limits and fields (`motion`, `environment`, `materialFields`, `meshEdit`, `meshEdit.<op>`, `physics`, `jobs` and more) |+| `scene_capabilities` | `topic` (optional) | A short index of topics; with a topic, its limits and fields (`motion`, `environment`, `materialFields`, `meshEdit`, `meshEdit.<op>`, `physics`, `jobs`, `examples` and more; `examples.<tool>` is a complete call for `scene_create`, `scene_apply`, `scene_create_asset` or `scene_render_submit`) || `scene_create` | `recipe` | Session ID, revision, inspection, and render status || `scene_asset_catalog` | None | Configured catalog and content-bound GLB, image, `.hdr` (kind `environment`) and `.cube` (kind `look`) IDs; an ID goes in `environment.hdri` or `environment.look`, see [agent-look](agent-look.md#catalog-hdris-and-looks) || `scene_create_asset` | `recipe` using `67js.asset` | Imported scene ID, revision, inspection and render status |diff --git a/scripts/capabilities-topics.mjs b/scripts/capabilities-topics.mjsindex 7b2fb5e2..667cc8b0 100644--- a/scripts/capabilities-topics.mjs+++ b/scripts/capabilities-topics.mjs@@ -3,6 +3,7 @@// (motion, environment, meshEdit, ...). A union such as meshEdit takes a branch: meshEdit.bevel.import * as z from 'zod/v4';import { outlineSchema, unionBranches } from './schema-outline.mjs';+import { AGENT_TOOL_EXAMPLES } from './tool-examples.mjs';const RUNTIME_SECTIONS = ['sceneLimits', 'preview', 'review', 'assets', 'jobs', 'unsupported'];const SUMMARY_LENGTH = 110;@@ -25,6 +26,7 @@ function sceneTopics(scene) {if (isScalar(value)) flags[name] = value;else topics.set(name, value);}+ topics.set('examples', AGENT_TOOL_EXAMPLES);topics.set(FLAGS_TOPIC, flags);return topics;}@@ -91,7 +93,7 @@ export function answerCapabilities(capabilities, topic, outlineSources) {return {format: capabilities.scene.format, schemaVersion: capabilities.scene.schemaVersion,phase: capabilities.phase, availableIn: capabilities.availableIn,- how: 'Call scene_capabilities with topic set to a name below. Tools list common fields; schemas names the full field list of a recipe part (meshEdit and meshStack also take <name>.<op>, geometries takes geometries.<type>).',+ how: 'Call scene_capabilities with topic set to a name below. Tools list common fields; schemas names the full field list of a recipe part (meshEdit and meshStack also take <name>.<op>, geometries takes geometries.<type>). examples.<tool> is one complete call.',topics: names,};}@@ -109,5 +111,8 @@ export function answerCapabilities(capabilities, topic, outlineSources) {}const answeredTopic = [name, branchName].filter(Boolean).join('.');if (source) return { topic: answeredTopic, ...(notes === undefined ? {} : { notes }), fields: outlineAnswer(name, branchName, source) };+ // A dotted name picks one entry of a plain topic: examples.scene_apply.+ const entry = notes !== null && typeof notes === 'object' && branchName !== undefined && Object.hasOwn(notes, branchName);+ if (entry) return { topic: answeredTopic, value: notes[branchName] };return { topic: answeredTopic, value: notes ?? runtime };}diff --git a/scripts/tool-examples.mjs b/scripts/tool-examples.mjsnew file mode 100644index 00000000..d8942bc4--- /dev/null+++ b/scripts/tool-examples.mjs@@ -0,0 +1,41 @@+/**+ * One complete, valid call for each of the four hardest tools. scene_capabilities serves them from the MCP server (not the scene bundle) under the topic+ * `examples`, so the tool schemas stay small: they are read on every turn and this text only when asked for.+ * A test sends every example through the tool's own input schema and the scene it targets.+ */+export const AGENT_TOOL_EXAMPLES = Object.freeze({+ scene_create: Object.freeze({+ recipe: {+ format: '67js.scene', schemaVersion: 1,+ geometries: [{ id: 'cube', type: 'box', bevel: 0 }],+ materials: [{ id: 'wood', color: [0.55, 0.36, 0.2], roughness: 0.8 }, { id: 'stone', color: [0.5, 0.5, 0.52] }],+ nodes: [+ { id: 'floor', geometry: 'cube', material: 'stone', translation: [0, -0.05, 0], scale: [8, 0.1, 8] },+ { id: 'crate', geometry: 'cube', material: 'wood', translation: [0, 0.5, 0] },+ ],+ camera: { eye: [3, 2, 4], target: [0, 0.5, 0], fov: 45 },+ },+ }),+ scene_apply: Object.freeze({+ expectedRevision: 0,+ operations: [+ { type: 'set-node', id: 'crate', translation: [1, 0.5, 0] },+ { type: 'set-material', id: 'wood', color: [0.7, 0.2, 0.1], roughness: 0.5 },+ { type: 'add-node', node: { id: 'crate2', geometry: 'cube', material: 'wood', translation: [-1.2, 0.5, 0], scale: [1, 0.6, 1] } },+ { type: 'set-camera', eye: [4, 3, 5], target: [0, 0.5, 0] },+ ],+ }),+ scene_create_asset: Object.freeze({+ recipe: {+ format: '67js.asset', schemaVersion: 1,+ assetId: '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',+ camera: { eye: [2, 1.5, 3], target: [0, 0.8, 0], fov: 40 },+ root: { rotation: [0, 0.7071, 0, 0.7071] },+ },+ }),+ scene_render_submit: Object.freeze({+ expectedRevision: 1,+ settings: { kind: 'image', width: 1280, height: 720 },+ }),+ notes: 'sessionId stays out: the active scene is used. expectedRevision is the revision the last call returned. scene_create_asset takes assetId from scene_asset_catalog. Use topic examples.<tool> for one.',+});diff --git a/skills/build-67js-scene/SKILL.md b/skills/build-67js-scene/SKILL.mdindex daa37c18..e9e0657a 100644--- a/skills/build-67js-scene/SKILL.md+++ b/skills/build-67js-scene/SKILL.md@@ -14,7 +14,7 @@ Start the server with `npx --package @codepawlhq/67js 67js-mcp --backend gpu --a1. `scene_capabilities`: with no arguments it returns a short index of features, limits and topic names. Pass`topic` for the field list of one feature (`environment`, `materialFields`, `geometries`, `meshEdit.bevel`,- `motion`). Tool schemas list only common fields, so read the topic before a feature you have not used.+ `motion`) or `examples.scene_apply` for a complete call of a hard tool. Tool schemas list only common fields, so read the topic before a feature you have not used.2. `scene_create` with a `recipe`: `{ "format": "67js.scene", "schemaVersion": 1, "geometries": [], "materials": [], "nodes": [] }`plus optional `camera`, `environment`, `effects`, `shadow`, `motion`, `bake`, `timeline`.3. `scene_inspect`: node IDs, bounds, `diagnostics`, current `revision`.diff --git a/tests/tool-input-examples.test.js b/tests/tool-input-examples.test.jsnew file mode 100644index 00000000..468132c0--- /dev/null+++ b/tests/tool-input-examples.test.js@@ -0,0 +1,54 @@+import './support/load-agent-scene-modules.mjs';+import test from 'node:test';+import assert from 'node:assert/strict';+import Ajv2020 from 'ajv/dist/2020.js';+import { Client } from '@modelcontextprotocol/client';+import { InMemoryTransport } from '@modelcontextprotocol/server';+import { createAgentMcpServer } from '../scripts/mcp-server.mjs';+import { createAgentScene, AGENT_SCENE_CAPABILITIES } from '../src/agent-scene.js';+import { AGENT_TOOL_EXAMPLES } from '../scripts/tool-examples.mjs';++const EXAMPLE_TOOLS = ['scene_create', 'scene_apply', 'scene_create_asset', 'scene_render_submit'];++async function connect(context) {+ const runtime = { async close() {}, async capabilities() { return { scene: AGENT_SCENE_CAPABILITIES, phase: 'idle', availableIn: 'test' }; } };+ const server = createAgentMcpServer(runtime);+ const client = new Client({ name: '67js-examples-test', version: '1' });+ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();+ await server.connect(serverTransport);+ await client.connect(clientTransport);+ context.after(async () => {+ await client.close();+ await server.close();+ });+ return client;+}++test('every tool example passes the input schema its tool advertises', async context => {+ const client = await connect(context);+ const { tools } = await client.listTools();+ const validator = new Ajv2020({ strict: false });+ for (const toolName of EXAMPLE_TOOLS) {+ const tool = tools.find(candidate => candidate.name === toolName);+ const validate = validator.compile(tool.inputSchema);+ assert.ok(validate(AGENT_TOOL_EXAMPLES[toolName]), `${toolName}: ${JSON.stringify(validate.errors)}`);+ }+});++test('the scene_create and scene_apply examples build and edit a real scene', () => {+ const scene = createAgentScene(AGENT_TOOL_EXAMPLES.scene_create.recipe);+ const { expectedRevision, operations } = AGENT_TOOL_EXAMPLES.scene_apply;+ assert.equal(scene.revision, expectedRevision);+ scene.apply(operations, { expectedRevision });+ assert.equal(scene.revision, expectedRevision + 1);+});++test('scene_capabilities serves the examples whole and one tool at a time', async context => {+ const client = await connect(context);+ const call = async topic => JSON.parse((await client.callTool({ name: 'scene_capabilities', arguments: topic ? { topic } : {} })).content[0].text);+ assert.deepEqual((await call('examples')).value.scene_apply, AGENT_TOOL_EXAMPLES.scene_apply);+ const single = await call('examples.scene_render_submit');+ assert.equal(single.topic, 'examples.scene_render_submit');+ assert.deepEqual(single.value, AGENT_TOOL_EXAMPLES.scene_render_submit);+ assert.ok((await call()).topics.scene.includes('examples'));+});