Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
index 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.mjs
index 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.mjs
new file mode 100644
index 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.md
index 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 --a
1. `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.js
new file mode 100644
index 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'));
+});