Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Publish the MCP environment schema once, in scene_create (part of #447)

Nguyen Xuan An7ef9d29a84a1
diff --git a/changes/447-environment-schema-once.md b/changes/447-environment-schema-once.md
new file mode 100644
index 00000000..16fe6f4a
--- /dev/null
+++ b/changes/447-environment-schema-once.md
@@ -0,0 +1 @@
+- MCP: `scene_apply` (`set-environment`) and `scene_create_asset` no longer repeat the whole environment schema; they name `recipe.environment` in `scene_create` and the server still checks every field. The tool schemas are about 15 KB smaller, and the environment field descriptions shortened in #444 are back.
diff --git a/changes/447-environment-schema-once.size.md b/changes/447-environment-schema-once.size.md
new file mode 100644
index 00000000..02ec4d31
--- /dev/null
+++ b/changes/447-environment-schema-once.size.md
@@ -0,0 +1 @@
+- tool:scene_create: +594 bytes for the environment field descriptions #444 had to shorten (shadows follow the key light, the reflection-probe note, the four new fields); the same change removes two copies of the environment schema from scene_apply and scene_create_asset, so the tool total drops by 15,146 bytes
diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjs
index 63377deb..2655691c 100644
--- a/scripts/mcp-server.mjs
+++ b/scripts/mcp-server.mjs
@@ -171,14 +171,14 @@ const volumeFog = z.strictObject({
shadowAmbient: unit.optional(),
});
const affects = z.array(z.string()).optional();
-const lines = z.record(z.string(), z.unknown()).describe('Line art JSON; see scene_capabilities lineArt. null clears.');
+const lines = z.record(z.string(), z.unknown()).describe('Outlines, toon light and polylines as plain JSON; fields and limits in scene_capabilities lineArt. null clears.');
const environment = z.strictObject({
world: z.boolean().optional().describe('Draw the sky and apply surface fog.'),
ground: z.boolean().optional().describe('false: no automatic floor.'),
- setup: z.enum(LIGHTING_SETUP_NAMES).optional().describe('Named lighting; resets key, fill, ambient.'),
- environmentIntensity: bounded(0, 100).optional().describe('Scales environment light.'),
- environmentRotation: bounded(-100, 100).optional().describe('Radians about vertical.'),
- lightDirection: boundedVector(-1e6, 1e6).optional().describe('Toward the key light.'),
+ setup: z.enum(LIGHTING_SETUP_NAMES).optional().describe('Named lighting; resets key, fill and ambient fields. Default daylight.'),
+ environmentIntensity: bounded(0, 100).optional().describe('Scales the setup environment light and its reflections.'),
+ environmentRotation: bounded(-100, 100).optional().describe('Turns the setup environment around the vertical axis, in radians.'),
+ lightDirection: boundedVector(-1e6, 1e6).optional().describe('Direction toward the key light; shadows follow.'),
keyColor: boundedVector(0, 1000).optional(),
keyIntensity: bounded(0, 100).optional(),
fillIntensity: bounded(0, 100).optional(),
@@ -192,12 +192,12 @@ const environment = z.strictObject({
intensity: bounded(0, 1e5).optional(),
radius: bounded(0.001, 1e6).optional(),
range: z.union([z.literal(0), bounded(0.001, 1e6)]).optional(),
- castShadow: z.boolean().optional().describe('6 atlas tiles.'),
+ castShadow: z.boolean().optional().describe('Casts a shadow; 6 atlas tiles.'),
affects,
- })).max(8).optional().describe('Replaces the list; [] clears. Candela.'),
+ })).max(8).optional().describe('Replaces the list; [] clears. Intensity in candela.'),
spotLights: z.array(z.strictObject({
position: boundedVector(-1e6, 1e6),
- direction: boundedVector(-1e6, 1e6).describe('Nonzero cone direction.'),
+ direction: boundedVector(-1e6, 1e6).describe('Nonzero direction the cone points along.'),
angle: bounded(0.01, Math.PI / 2 - 0.01).optional().describe('Outer half angle, radians; default pi/4.'),
penumbra: unit.optional().describe('Soft edge, 0 hard; default 0.15.'),
color: color.optional(),
@@ -209,8 +209,8 @@ const environment = z.strictObject({
})).max(8).optional().describe('Replaces the list; [] clears.'),
areaLights: z.array(z.strictObject({
position: boundedVector(-1e6, 1e6).describe('Center of the rectangle.'),
- direction: boundedVector(-1e6, 1e6).describe('Facing direction; one side emits.'),
- up: boundedVector(-1e6, 1e6).optional().describe('Height axis; default up.'),
+ direction: boundedVector(-1e6, 1e6).describe('Direction the rectangle faces; emits that side only.'),
+ up: boundedVector(-1e6, 1e6).optional().describe('Height axis direction; default world up.'),
width: bounded(0.001, 1e4),
height: bounded(0.001, 1e4),
color: color.optional(),
@@ -222,14 +222,20 @@ const environment = z.strictObject({
fogColor: color.optional(),
fogDensity: bounded(0, 10).optional(),
volumeFog: volumeFog.optional().describe('Directional scattering; needs HDR.'),
- liquid: liquidOptics.optional().describe('For liquid or foam materials.'),
+ liquid: liquidOptics.optional().describe('Optics for materials tagged liquid or foam.'),
lines: lines.nullable().optional(),
- objectReflections: z.boolean().optional(),
- resolveCoplanar: z.union([z.literal('offset'), z.literal(false)]).optional(),
- viewTransform: z.enum(VIEW_TRANSFORM_NAMES).optional(),
- look: z.enum(LOOK_NAMES).nullable().optional(),
- wind: z.strictObject({ strength: bounded(0, 4).optional(), direction: bounded(-360, 360).optional().describe('Degrees; 0 is +x, 90 is +z.') }).optional().describe('Foliage and grass sway; strength default 0.3.'),
+ objectReflections: z.boolean().optional().describe("false turns off reflection probes on smooth metal parts."),
+ resolveCoplanar: z.union([z.literal('offset'), z.literal(false)]).optional().describe("'offset' biases the smaller part of each coplanar pair at draw time; false clears."),
+ viewTransform: z.enum(VIEW_TRANSFORM_NAMES).optional().describe('Display transform, for example agx to compare with Blender.'),
+ look: z.enum(LOOK_NAMES).nullable().optional().describe('Named look preset; null clears.'),
+ wind: z.strictObject({ strength: bounded(0, 4).optional(), direction: bounded(-360, 360).optional().describe('Degrees: 0 toward +x, 90 toward +z.') }).optional().describe('Sway of foliage and grass materials; strength defaults to 0.3.'),
});
+// The full environment schema is published once, in scene_create. A JSON Schema $ref can not point from one tool's
+// inputSchema into another's, so scene_apply and scene_create_asset publish a plain object that names it and still
+// check every field against the same schema here, with the same error paths.
+const environmentReference = z.record(z.string(), z.unknown())
+ .describe('Same fields as recipe.environment in scene_create.')
+ .pipe(environment);
const effects = z.strictObject({
exposure: bounded(0.01, 16).optional(),
saturation: bounded(0, 2).optional(),
@@ -587,7 +593,7 @@ const assetRecipe = z.strictObject({
schemaVersion: z.literal(1),
assetId: z.string().regex(/^[a-f0-9]{64}$/).describe('SHA-256 asset ID from scene_asset_catalog.'),
camera: z.strictObject(cameraFields).optional(),
- environment: environment.optional(),
+ environment: environmentReference.optional(),
effects: effects.optional(),
shadow: shadow.optional(),
root: z.strictObject({
@@ -621,7 +627,7 @@ const otherOperations = [
z.strictObject({ type: z.literal('set-particles'), particles: z.record(z.string(), z.unknown()).nullable() }),
z.strictObject({ type: z.literal('set-bake'), bake: z.record(z.string(), z.unknown()).nullable() }),
z.strictObject({ type: z.literal('set-post-passes'), postPasses: z.array(z.record(z.string(), z.unknown())).nullable() }),
- z.strictObject({ type: z.literal('set-environment'), environment }),
+ z.strictObject({ type: z.literal('set-environment'), environment: environmentReference }),
z.strictObject({ type: z.literal('set-effects'), effects }),
z.strictObject({ type: z.literal('set-shadow'), shadow }),
z.strictObject({ type: z.literal('set-root'), translation: vector3.optional(), rotation: quaternion.optional(), scale: z.tuple([positive, positive, positive]).optional() }),
diff --git a/tests/mcp-environment-schema.test.js b/tests/mcp-environment-schema.test.js
index 579d4781..2cea1aa5 100644
--- a/tests/mcp-environment-schema.test.js
+++ b/tests/mcp-environment-schema.test.js
@@ -36,20 +36,58 @@ function findSetEnvironmentSchema(node) {
return null;
}
-async function mcpEnvironmentFields() {
+async function withMcpClient(use) {
const server = createAgentMcpServer({ async close() {} });
const client = new Client({ name: '67js-environment-schema-test', version: '1' });
const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
await server.connect(serverTransport);
await client.connect(clientTransport);
- const { tools } = await client.listTools();
- await client.close();
- await server.close();
- const schema = findSetEnvironmentSchema(tools.find(tool => tool.name === 'scene_apply').inputSchema);
- assert.ok(schema, 'scene_apply no longer lists a set-environment operation');
- return Object.keys(schema.properties);
+ try {
+ return await use(client);
+ } finally {
+ await client.close();
+ await server.close();
+ }
+}
+
+async function listedTools() {
+ return withMcpClient(async client => (await client.listTools()).tools);
+}
+
+function toolSchema(tools, name) {
+ return tools.find(tool => tool.name === name).inputSchema;
+}
+
+// scene_create publishes the one full environment schema; the other tools name it.
+async function mcpEnvironmentFields() {
+ const environment = toolSchema(await listedTools(), 'scene_create').properties.recipe.properties.environment;
+ assert.ok(environment?.properties, 'scene_create no longer publishes recipe.environment');
+ return Object.keys(environment.properties);
}
+test('scene_apply and scene_create_asset point to the environment schema in scene_create instead of repeating it', async () => {
+ const tools = await listedTools();
+ const references = [
+ findSetEnvironmentSchema(toolSchema(tools, 'scene_apply')),
+ toolSchema(tools, 'scene_create_asset').properties.recipe.properties.environment,
+ ];
+ for (const reference of references) {
+ assert.equal(reference.properties, undefined);
+ assert.match(reference.description, /recipe.environment in scene_create/);
+ }
+});
+
+test('the server still checks every environment field of scene_apply and scene_create_asset', async () => {
+ await withMcpClient(async client => {
+ const apply = await client.callTool({ name: 'scene_apply', arguments: { expectedRevision: 0, operations: [{ type: 'set-environment', environment: { skyTop: 'blue', bogus: 1 } }] } });
+ const asset = await client.callTool({ name: 'scene_create_asset', arguments: { recipe: { format: '67js.asset', schemaVersion: 1, assetId: 'a'.repeat(64), environment: { world: 'yes' } } } });
+ for (const result of [apply, asset]) assert.equal(result.isError, true);
+ assert.match(apply.content[0].text, /bogus/);
+ assert.match(apply.content[0].text, /skyTop/);
+ assert.match(asset.content[0].text, /world/);
+ });
+});
+
test('the MCP environment schema lists exactly the fields the backend allows', async () => {
const backend = (await backendEnvironmentFields()).sort();
assert.deepEqual((await mcpEnvironmentFields()).sort(), backend);