@gripforgeai/mcp 0.1.10 → 0.1.12

package/dist/studio-tools-tools.js

@@ -0,0 +1,106 @@
+import { z } from 'zod/v4';
+/**
+ * Les outils MCP des outils chaînés (studios → outils → étapes), enregistrés par le MCP hébergé
+ * (`apps/web/src/lib/mcp-server.ts`) et par le client npm (`server.ts`).
+ *
+ * Même contrat que la library : tout passe par `/api/v1/tools*`, ouvert aux membres du workspace de
+ * la clé (lecture pour tous, lancer et corriger pour ceux qui écrivent dans le casier). Quand une
+ * chaîne s'arrête, la réponse porte l'étape, la phrase qui dit quoi
+ * faire et l'URL où le faire — on ne décrit pas le problème, on donne l'endroit où le régler.
+ */
+export const STUDIO_TOOLS_TOOL_NAMES = ['gripforge_studios', 'gripforge_tool_run', 'gripforge_tool_runs', 'gripforge_mesh_passport'];
+export function registerStudioToolsTools(register, options, schema = z) {
+    const libId = schema.string().regex(/^lib_[A-Za-z0-9_-]{8,64}$/);
+    const ws = schema.string().max(100).optional().describe('Workspace id (defaults to the key’s workspace).');
+    const shapes = {
+        studios: { item_id: libId.optional().describe('A locker item: the answer says which tools are possible on it right now.'), workspace_id: ws },
+        run: {
+            tool: schema.string().min(1).max(40).describe('Tool id from gripforge_studios (passport, rig, mannequin).'),
+            item_id: libId.optional().describe('Locker item the chain works on. mannequin without item = the adult canon.'),
+            step: schema.string().max(40).optional().describe('Replay ONE step (the one you just corrected) instead of the whole chain.'),
+            force: schema.boolean().optional().describe('Recompute fresh blocks too. Default: fresh blocks are skipped.'),
+            workspace_id: ws,
+        },
+        runs: {
+            item_id: libId.optional(),
+            tool: schema.string().max(40).optional(),
+            limit: schema.number().int().min(1).max(100).optional(),
+            workspace_id: ws,
+        },
+        passport: {
+            item_id: libId,
+            manual: schema.record(schema.string(), schema.unknown()).optional().describe('Partial PassportManual to MERGE (e.g. {"orientation":{"up":[0,1,0],"front":[0,0,1],"toCanonical":[0,0,0,1],"confidence":1,"source":"manual"}}). Omit to read.'),
+            clear: schema.string().max(60).optional().describe('Remove one correction (orientation, joints.elbow.L, fits.helm) or "*" for all.'),
+            workspace_id: ws,
+        },
+    };
+    async function call(method, path, args, body, signal) {
+        const key = options.getApiKey();
+        if (!key)
+            return { isError: true, content: [{ type: 'text', text: 'GripForge API key required.' }] };
+        const ws = typeof args.workspace_id === 'string' ? args.workspace_id : null;
+        try {
+            const response = await fetch(options.apiUrl.replace(/\/$/, '') + path, {
+                method,
+                headers: { 'content-type': 'application/json', 'x-gripforge-client': 'mcp', 'x-api-key': key, ...(ws ? { 'x-workspace-id': ws } : {}) },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                signal: AbortSignal.any([AbortSignal.timeout(300_000), ...(signal ? [signal] : [])]),
+            });
+            const data = await response.json().catch(() => ({ error: `HTTP ${response.status}` }));
+            return { ...(!response.ok ? { isError: true } : {}), structuredContent: data, content: [{ type: 'text', text: JSON.stringify(data) }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: 'text', text: error instanceof Error ? error.message : 'GripForge tools request failed.' }] };
+        }
+    }
+    const q = (o) => {
+        const p = new URLSearchParams();
+        for (const [k, v] of Object.entries(o))
+            if (v !== undefined && v !== null && v !== '')
+                p.set(k, String(v));
+        const s = p.toString();
+        return s ? `?${s}` : '';
+    };
+    const tools = [
+        {
+            name: 'gripforge_studios', title: 'Studios · tools map', readOnly: true, shape: shapes.studios,
+            description: 'The map of GripForge studios and their chained tools (steps, kind code/ai/tool/analysis, manual equivalent of each step). Call it BEFORE guessing a tool name. With item_id, `available` says what is possible on that item now.',
+            run: (a, s) => call('GET', `/api/v1/tools${q({ item: a.item_id })}`, a, undefined, s),
+        },
+        {
+            name: 'gripforge_tool_run', title: 'Studios · run a chained tool', readOnly: false, shape: shapes.run,
+            description: 'Run a chained tool server-side (computation happens in the GripForge compute service). Returns the step-by-step run. status "needs-manual" = the chain stopped on purpose: read manual_hint, fix it (gripforge_mesh_passport) or send the user to `url`, then replay with step=<that step>. mannequin with an item = chain passport → rig → mannequin, a new locker item.',
+            run: (a, s) => call('POST', '/api/v1/tools/run', a, { tool: a.tool, id: a.item_id ?? null, step: a.step ?? null, force: a.force === true, source: 'mcp' }, s),
+        },
+        {
+            name: 'gripforge_tool_runs', title: 'Studios · run history', readOnly: true, shape: shapes.runs,
+            description: 'The shared history of chained-tool runs (web page and agents alike), newest first: which tool, on which item, each step, where it stopped and the URL to resume.',
+            run: (a, s) => call('GET', `/api/v1/tools/runs${q({ item: a.item_id, tool: a.tool, limit: a.limit })}`, a, undefined, s),
+        },
+        {
+            name: 'gripforge_mesh_passport', title: 'Studios · mesh passport', readOnly: false, shape: shapes.passport,
+            description: 'Read or correct the passport of a locker mesh (size, orientation, reference skeleton, colliders). `manual` merges a human correction (it always wins and survives regeneration); `clear` removes one. Measurements themselves come from gripforge_tool_run tool=passport.',
+            run: (a, s) => {
+                const path = `/api/v1/tools/passport/${a.item_id}`;
+                if (typeof a.clear === 'string')
+                    return call('DELETE', `${path}${a.clear === '*' ? '' : q({ field: a.clear })}`, a, undefined, s);
+                if (a.manual)
+                    return call('PUT', path, a, { manual: a.manual }, s);
+                return call('GET', path, a, undefined, s);
+            },
+        },
+    ];
+    for (const tool of tools) {
+        register(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.shape,
+            annotations: { readOnlyHint: tool.readOnly, destructiveHint: false, idempotentHint: tool.readOnly, openWorldHint: false },
+        }, async (args, extra) => {
+            const parsed = schema.object(tool.shape).strict().safeParse(args);
+            if (!parsed.success)
+                return { isError: true, content: [{ type: 'text', text: parsed.error.message }] };
+            return tool.run(parsed.data, extra?.signal);
+        });
+    }
+}

package/dist/unreal-export-package.js

@@ -0,0 +1,212 @@
+import { createHash } from 'node:crypto';
+import { readFile, writeFile, rename, stat, realpath } from 'node:fs/promises';
+import { resolve, sep } from 'node:path';
+import { inflateSync, deflateSync } from 'node:zlib';
+export const sha256 = (b) => createHash('sha256').update(b).digest('hex');
+export async function atomicJson(file, value) { const tmp = file + '.' + process.pid + '.tmp'; await writeFile(tmp, JSON.stringify(value)); await rename(tmp, file); }
+export async function readJson(file) { if ((await stat(file)).size > 64 * 1024 * 1024)
+    throw Error('Manifest exceeds 64 MB.'); return JSON.parse(await readFile(file, 'utf8')); }
+export async function exportFile(dir, file) {
+    const root = await realpath(dir), path = await realpath(resolve(root, file));
+    if (!path.startsWith(root + sep))
+        throw Error('Export file escapes its job directory.');
+    return path;
+}
+const signature = Buffer.from('89504e470d0a1a0a', 'hex');
+function crc32(data) { let crc = 0xffffffff; for (const byte of data) {
+    crc ^= byte;
+    for (let i = 0; i < 8; i++)
+        crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
+} return (crc ^ 0xffffffff) >>> 0; }
+/** Native RGBA8 data, without gamma conversion (height is packed in RG). */
+export function decodeExportPng(bytes) {
+    if (!bytes.subarray(0, 8).equals(signature))
+        throw Error('Invalid PNG signature.');
+    let width = 0, height = 0, channels = 0, ended = false;
+    const parts = [];
+    for (let at = 8; at + 12 <= bytes.length;) {
+        const length = bytes.readUInt32BE(at), end = at + length + 12;
+        if (end > bytes.length)
+            throw Error('Truncated PNG.');
+        const type = bytes.toString('ascii', at + 4, at + 8), data = bytes.subarray(at + 8, end - 4);
+        if (crc32(bytes.subarray(at + 4, end - 4)) !== bytes.readUInt32BE(end - 4))
+            throw Error('PNG checksum mismatch.');
+        if (type === 'IHDR') {
+            if (width || length !== 13 || data[8] !== 8 || ![2, 6].includes(data[9]) || data[10] || data[11] || data[12])
+                throw Error('Expected non-interlaced RGB/RGBA8 PNG.');
+            width = data.readUInt32BE(0);
+            height = data.readUInt32BE(4);
+            channels = data[9] === 6 ? 4 : 3;
+            if (!width || !height || width > 8192 || height > 8192)
+                throw Error('PNG dimensions exceed export budget.');
+        }
+        else if (type === 'IDAT')
+            parts.push(data);
+        else if (type === 'IEND') {
+            ended = true;
+            break;
+        }
+        at = end;
+    }
+    if (!width || !ended)
+        throw Error('Incomplete PNG.');
+    const stride = width * channels, expected = (stride + 1) * height, raw = inflateSync(Buffer.concat(parts), { maxOutputLength: expected });
+    if (raw.length !== expected)
+        throw Error('Invalid PNG data length.');
+    const pixels = Buffer.alloc(stride * height);
+    for (let y = 0; y < height; y++) {
+        const filter = raw[y * (stride + 1)];
+        if (filter > 4)
+            throw Error('Invalid PNG filter.');
+        for (let x = 0; x < stride; x++) {
+            const at = y * stride + x, a = x >= channels ? pixels[at - channels] : 0, b = y ? pixels[at - stride] : 0, c = y && x >= channels ? pixels[at - stride - channels] : 0;
+            const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+            pixels[at] = raw[y * (stride + 1) + x + 1] + (filter === 0 ? 0 : filter === 1 ? a : filter === 2 ? b : filter === 3 ? Math.floor((a + b) / 2) : pa <= pb && pa <= pc ? a : pb <= pc ? b : c);
+        }
+    }
+    return { width, height, channels, pixels };
+}
+export function encodeExportPng(width, height, pixels, channels = 4) {
+    const chunk = (name, data) => { const out = Buffer.alloc(data.length + 12); out.writeUInt32BE(data.length); out.write(name, 4); data.copy(out, 8); out.writeUInt32BE(crc32(out.subarray(4, out.length - 4)), out.length - 4); return out; };
+    const header = Buffer.alloc(13);
+    header.writeUInt32BE(width);
+    header.writeUInt32BE(height, 4);
+    header[8] = 8;
+    header[9] = channels === 4 ? 6 : 2;
+    const stride = width * channels, scan = Buffer.alloc(height * (stride + 1));
+    for (let y = 0; y < height; y++)
+        pixels.copy(scan, y * (stride + 1) + 1, y * stride, (y + 1) * stride);
+    return Buffer.concat([signature, chunk('IHDR', header), chunk('IDAT', deflateSync(scan)), chunk('IEND', Buffer.alloc(0))]);
+}
+const vec = (x = 0, y = 0, z = 0) => ({ x, y, z });
+const identity = () => ({ translation: vec(), rotation: { ...vec(), w: 1 }, scale: vec(1, 1, 1) });
+const base = (id, name = id) => ({ id, name, parentId: null, transform: identity(), visible: true, locked: false });
+const round = (n) => Math.round(n * 1e6) / 1e6;
+const refFor = (file) => ({ assetId: 'ue_' + file.sha256.slice(0, 24), revisionId: 'rev_' + file.sha256.slice(0, 24) });
+export function decodeUnrealTerrain(t, bytes, resolution, visibility) {
+    const png = decodeExportPng(bytes), mask = visibility ? decodeExportPng(visibility) : undefined;
+    if (png.width !== t.width || png.height !== t.height || mask && (mask.width !== t.width || mask.height !== t.height))
+        throw Error('Landscape grid does not match its PNG.');
+    const spanX = t.width - 1, spanZ = t.height - 1, longest = Math.max(spanX, spanZ), sx = Math.max(1, Math.round((resolution - 1) * spanX / longest)), sz = Math.max(1, Math.round((resolution - 1) * spanZ / longest));
+    const q = t.component_quads, occupied = new Set(t.components.map(([x, y]) => x + ':' + y));
+    const present = (x, z) => occupied.has((Math.floor((t.base[0] + Math.min(spanX - .00001, Math.max(0, x))) / q) * q) + ':' + (Math.floor((t.base[1] + Math.min(spanZ - .00001, Math.max(0, z))) / q) * q));
+    const hidden = (x, z) => mask ? mask.pixels[(Math.round(z) * mask.width + Math.round(x)) * mask.channels] >= 128 : false;
+    const sample = (x, z) => { const at = (Math.min(t.height - 1, Math.max(0, z)) * t.width + Math.min(t.width - 1, Math.max(0, x))) * png.channels; return (png.pixels[at] * 256 + png.pixels[at + 1] - 32768) / 128 * t.scale[2] * .01; };
+    const heights = [], holes = [];
+    for (let z = 0; z <= sz; z++)
+        for (let x = 0; x <= sx; x++) {
+            const px = x / sx * spanX, pz = z / sz * spanZ, ix = Math.floor(px), iz = Math.floor(pz), u = px - ix, v = pz - iz;
+            const a = sample(ix, iz) * (1 - u) + sample(ix + 1, iz) * u, b = sample(ix, iz + 1) * (1 - u) + sample(ix + 1, iz + 1) * u;
+            heights.push(present(px, pz) ? Math.round((a * (1 - v) + b * v) * 1000) / 1000 : 0);
+        }
+    for (let z = 0; z < sz; z++)
+        for (let x = 0; x < sx; x++) {
+            let hole = false;
+            // Every source sample overlapped by this quad is checked, so small painted holes survive downsampling.
+            for (let j = Math.floor(z / sz * spanZ); j <= Math.ceil((z + 1) / sz * spanZ) && !hole; j++)
+                for (let i = Math.floor(x / sx * spanX); i <= Math.ceil((x + 1) / sx * spanX); i++)
+                    if (!present(i, j) || hidden(i, j)) {
+                        hole = true;
+                        break;
+                    }
+            holes.push(hole ? 1 : 0);
+        }
+    return { size: [spanX * t.scale[0] * .01, spanZ * t.scale[1] * .01], segments: [sx, sz], heights, holes,
+        center: vec((t.origin[0] + (t.base[0] + spanX / 2) * t.scale[0]) * .01, t.origin[2] * .01, (t.origin[1] + (t.base[1] + spanZ / 2) * t.scale[1]) * .01) };
+}
+export async function buildUnrealStudioPackage(directory) {
+    const dir = await realpath(directory), manifest = await readJson(resolve(dir, 'native.json')), request = await readJson(resolve(dir, 'request.json'));
+    if (manifest.schema !== 'gripforge.unreal-export.v1' || manifest.status !== 'exported-awaiting-gripforge-review' || sha256(await readFile(resolve(dir, 'request.json'))) !== manifest.request_hash)
+        throw Error('Native export must finish successfully before assembly.');
+    const assets = [], nodes = [], assetRefs = new Map();
+    async function addFile(file, name, kind, mime) {
+        const path = await exportFile(dir, file.file), bytes = await readFile(path);
+        if (bytes.length > 128 * 1024 * 1024 || bytes.length !== file.bytes || sha256(bytes) !== file.sha256)
+            throw Error('Changed or oversized export: ' + file.file);
+        const ref = refFor(file);
+        if (!assets.some(a => a.sha256 === file.sha256))
+            assets.push({ ...file, ...ref, name, kind, mime });
+        return ref;
+    }
+    for (const [key, file] of Object.entries(manifest.assets))
+        assetRefs.set(key, await addFile(file, file.name, 'prop', 'model/gltf-binary'));
+    nodes.push({ ...base('props', 'Props & buildings'), type: 'group' }, { ...base('vegetation', 'Vegetation'), type: 'group' }, { ...base('terrain', 'Terrain'), type: 'group' });
+    const batches = new Map();
+    let zeroScaleInstances = 0;
+    for (const instance of manifest.instances) {
+        const asset = assetRefs.get(instance.asset);
+        if (!asset)
+            throw Error('Missing exported mesh: ' + instance.asset);
+        const t = instance.transform, p = t.translation, q = t.rotation, s = t.scale;
+        // Unreal foliage retains removed placements as zero-scale tombstones. They have no visible geometry.
+        if ([s.x, s.y, s.z].every(n => n === 0)) {
+            zeroScaleInstances++;
+            continue;
+        }
+        const row = [p.x, p.y, p.z, q.x, q.y, q.z, q.w, s.x, s.y, s.z].map(round);
+        if (!row.every(Number.isFinite) || Math.abs(Math.hypot(q.x, q.y, q.z, q.w) - 1) > .001 || [s.x, s.y, s.z].some(n => Math.abs(n) < .00001))
+            throw Error('Invalid native transform: ' + instance.id);
+        if (instance.batch && [s.x, s.y, s.z].every(n => n > 0)) {
+            const cx = Math.floor(p.x / 64), cz = Math.floor(p.z / 64), prefix = instance.asset + ':' + cx + ':' + cz;
+            let part = 0, key = prefix;
+            while ((batches.get(key)?.instanceBatch.ids.length ?? 0) >= 4096)
+                key = prefix + ':' + (++part);
+            if (!batches.has(key)) {
+                const b = { ...base('batch_' + sha256(key).slice(0, 24), instance.name.slice(0, 110) + ` [${cx},${cz}]`), type: 'asset', parentId: 'vegetation', asset, role: 'vegetation', materials: {}, parameters: { source: 'unreal-instancing' }, instanceBatch: { ids: [], transforms: [] } };
+                batches.set(key, b);
+                nodes.push(b);
+            }
+            const b = batches.get(key);
+            b.instanceBatch.ids.push(instance.id);
+            b.instanceBatch.transforms.push(row);
+        }
+        else
+            nodes.push({ ...base(instance.id, instance.name), type: 'asset', parentId: instance.batch ? 'vegetation' : 'props', asset, role: 'prop', transform: t, materials: {}, parameters: { unrealSource: instance.source } });
+    }
+    let overview;
+    for (const t of manifest.terrains) {
+        await addFile(t.heightmap, t.id + ' source height', 'texture', 'image/png');
+        if (t.visibility)
+            await addFile(t.visibility, t.id + ' source holes', 'texture', 'image/png');
+        const terrain = decodeUnrealTerrain(t, await readFile(await exportFile(dir, t.heightmap.file)), request.terrain_resolution ?? 513, t.visibility ? await readFile(await exportFile(dir, t.visibility.file)) : undefined);
+        let albedo = t.albedo;
+        if (Math.abs(terrain.size[0] - terrain.size[1]) > .001) {
+            const source = decodeExportPng(await readFile(await exportFile(dir, albedo.file)));
+            const w = Math.max(1, Math.round(source.width * terrain.size[0] / (t.albedo_span_cm * .01))), h = Math.max(1, Math.round(source.height * terrain.size[1] / (t.albedo_span_cm * .01))), data = Buffer.alloc(w * h * source.channels);
+            if (w > source.width || h > source.height)
+                throw Error('Invalid Landscape albedo extent.');
+            const ox = Math.floor((source.width - w) / 2), oy = Math.floor((source.height - h) / 2);
+            for (let y = 0; y < h; y++)
+                source.pixels.copy(data, y * w * source.channels, ((y + oy) * source.width + ox) * source.channels, ((y + oy) * source.width + ox + w) * source.channels);
+            const bytes = encodeExportPng(w, h, data, source.channels), file = t.id + '-albedo-cropped.png';
+            await writeFile(resolve(dir, file), bytes);
+            albedo = { file, bytes: bytes.length, sha256: sha256(bytes) };
+        }
+        const map = await addFile(albedo, t.id + ' albedo', 'texture', 'image/png');
+        nodes.push({ ...base('terrain_' + sha256(t.id).slice(0, 24), t.id), type: 'terrain', parentId: 'terrain', transform: { ...identity(), translation: terrain.center }, size: terrain.size, segments: terrain.segments, heights: terrain.heights, holes: terrain.holes, layers: [], material: { color: '#ffffff', roughness: 1, metalness: 0, map } });
+        overview ??= terrain;
+    }
+    const placements = manifest.instances;
+    if (!overview && placements.length) {
+        const axes = ['x', 'y', 'z'], min = axes.map(k => Math.min(...placements.map(p => p.transform.translation[k]))), max = axes.map(k => Math.max(...placements.map(p => p.transform.translation[k])));
+        overview = { center: vec(...min.map((v, i) => (v + max[i]) / 2)), size: [Math.max(10, max[0] - min[0]), Math.max(10, max[2] - min[2])] };
+    }
+    if (!overview)
+        throw Error('Nothing portable was found in the selected map.');
+    const center = overview.center, span = Math.max(...overview.size), sun = manifest.environment.sun ?? [1, 2, 1];
+    nodes.push({ ...base('environment', 'Environment (portable approximation)'), type: 'environment', preset: 'outdoor', background: '#9dc4e1', intensity: .8, exposure: 1, rotation: 0, fog: null, sky: { mode: 'physical', sun: vec(...sun), turbidity: 3, rayleigh: 1.5, intensity: .8 } });
+    nodes.push({ ...base('camera_overview', 'Overview'), type: 'camera', projection: 'perspective', transform: { ...identity(), translation: vec(center.x + span * .55, center.y + span * .7, center.z + span * .65) }, target: center, fov: 55, near: .1, far: Math.max(3000, span * 6), zoom: 1 });
+    for (const [i, c] of manifest.cameras.entries())
+        nodes.push({ ...base('camera_native_' + i, c.name.slice(0, 160)), type: 'camera', projection: 'perspective', transform: { ...identity(), translation: vec(...c.position) }, target: vec(...c.target), fov: Math.min(175, Math.max(1, c.fov)), near: .1, far: Math.max(3000, span * 6), zoom: 1 });
+    const warnings = [...manifest.warnings, 'Repeated foliage is editable by spatial patch. Member IDs and transforms are retained; per-blade gizmos are not implemented.', 'Portable environment lighting is an approximation; compare against Unreal before validation.'];
+    if (zeroScaleInstances)
+        warnings.push(`${zeroScaleInstances} zero-scale native placements have no visible geometry and were omitted; their original transforms remain in native.json.`);
+    const document = { schemaVersion: 1, id: 'unreal_' + manifest.request_hash.slice(0, 24), workspaceId: 'local-preview', name: manifest.project + ' — ' + manifest.source_level.split('/').pop(), purpose: 'map', revision: 0, nodes, activeCameraId: 'camera_overview', metadata: { unrealSource: { level: manifest.source_level, sha256: manifest.source_sha256, omitted: manifest.omitted }, lifecycle: 'work', warnings } };
+    const input = { schema: 'gripforge.unreal-studio-import.v1', source: { engine: 'unreal', level: manifest.source_level, sha256: manifest.source_sha256, warnings }, document };
+    if (nodes.length > 20000 || Buffer.byteLength(JSON.stringify(input)) > 16 * 1024 * 1024)
+        throw Error('Portable scene exceeds the Studio budget; export smaller regions.');
+    await atomicJson(resolve(dir, 'scene.json'), document);
+    const portable = { schema: 'gripforge.scene-package.v1', scene: 'scene.json', sceneHash: sha256(JSON.stringify(document)), assets, cameras: ['camera_overview', ...nodes.filter(n => n.id.startsWith('camera_native_')).map(n => n.id)], source: input.source, instanceCount: manifest.instances.length - zeroScaleInstances, zeroScaleInstances, nodeCount: nodes.length, lifecycle: 'work' };
+    await atomicJson(resolve(dir, 'manifest.json'), portable);
+    return { directory: dir, input, manifest: portable };
+}

package/dist/vfx-project-tools.js

@@ -2,6 +2,7 @@
 // mcp-handler requires v4 field schemas for raw shapes. zod 3.25 ships v4
 // alongside v3, so existing stdio tools can retain their current v3 schemas.
 import { z } from 'zod/v4';
+import { LOOK_DESCRIPTION, LOOK_VALUES } from './look.js';
 // The hosted SDK uses a newer Zod v4 serializer than the npm SDK. Inject its
 // matching factory so schemas remain compatible with each host's serializer.
 export function registerVfxProjectTools(register, options, schema = z) {
@@ -44,5 +45,5 @@ export function registerVfxProjectTools(register, options, schema = z) {
     tool('gripforge_vfx_project_render', 'Render actual VFX frames for inspection', 'Queue a durable render of an owned id OR an unsaved project at 1–4 timestamps. Returns job_id immediately. Poll gripforge_generation_read with include_preview for the actual rendered image, coverage, clipping and shader diagnostics. Uses the shared GripForge SceneViewport. Saves preview evidence only, no project revision. Requires workspace write access because the job and preview consume storage. Render timings are not browser FPS.', { idempotency_key: schema.string().min(8).max(160).optional(), id: id.optional(), project: project.optional(), times }, false, (args, extra) => api('/render', args, 'POST', extra?.signal));
     tool('gripforge_vfx_project_review', 'Review an existing work revision', 'Queue a fresh GripForge capture and independent visual review without writing another source revision. Poll gripforge_generation_read; inspect its preview, then explicitly promote if approved.', { id, expected_revision: schema.number().int().positive(), idempotency_key: schema.string().min(8).max(160).optional() }, false, (args, extra) => api(`/${args.id}/review`, args, 'POST', extra?.signal));
     tool('gripforge_vfx_project_promote', 'Set the visually approved VFX version', 'Explicitly promote work after a trusted positive review matching this source, dependencies and renderer. expectedCurrent is the existing validated revision, or null.', { id, revision: schema.number().int().positive(), expectedCurrent: schema.number().int().positive().nullable() }, false, (args, extra) => api(`/${args.id}/promote`, args, 'POST', extra?.signal));
-    tool('gripforge_vfx_project_generate', 'Create, render and refine a custom VFX', 'Text/image -> durable generation job -> original geometry/shaders -> actual GripForge rendering -> visual critique/correction -> workspace work revision. Returns immediately with job_id, status_url and studio_url. Poll gripforge_generation_read, then open its source_url to inspect the saved source and review. Closing the request does not cancel the job. Completed steps survive worker restart. Pass id + expected_revision to refine; image_id must belong to this workspace. A visually rejected candidate never replaces the validated version.', { idempotency_key: schema.string().min(8).max(160).optional(), prompt: schema.string().max(2000).optional(), visual_style: schema.enum(['realistic', 'stylized', 'anime', 'lowpoly']).optional(), image_mode: schema.enum(['spatial', 'animated-artwork']).optional().describe('Default spatial: build a 3D effect. animated-artwork explicitly opts into a flat animated illustration.'), image_id: id.optional(), image_data: schema.string().max(12 * 1024 * 1024).optional(), id: id.optional(), expected_revision: schema.number().int().positive().optional() }, false, (args, extra) => api('/generate', args, 'POST', extra?.signal), true);
+    tool('gripforge_vfx_project_generate', 'Create, render and refine a custom VFX', 'Text/image -> durable generation job -> original geometry/shaders -> actual GripForge rendering -> visual critique/correction -> workspace work revision. Returns immediately with job_id, status_url and studio_url. Poll gripforge_generation_read, then open its source_url to inspect the saved source and review. Closing the request does not cancel the job. Completed steps survive worker restart. Pass id + expected_revision to refine; image_id must belong to this workspace. A visually rejected candidate never replaces the validated version.', { idempotency_key: schema.string().min(8).max(160).optional(), prompt: schema.string().max(2000).optional(), visual_style: schema.enum(LOOK_VALUES).optional().describe('Rendering look of the effect (same vocabulary as look). Default stylized.'), look: schema.enum(LOOK_VALUES).optional().describe(LOOK_DESCRIPTION), image_mode: schema.enum(['spatial', 'animated-artwork']).optional().describe('Default spatial: build a 3D effect. animated-artwork explicitly opts into a flat animated illustration.'), image_id: id.optional(), image_data: schema.string().max(12 * 1024 * 1024).optional(), id: id.optional(), expected_revision: schema.number().int().positive().optional() }, false, (args, extra) => api('/generate', args, 'POST', extra?.signal), true);
 }

package/dist/weapon-motion-tools.js

@@ -0,0 +1,34 @@
+import { z } from 'zod/v4';
+export const WEAPON_MOTION_TOOL_NAMES = ['gripforge_weapon_profile', 'gripforge_weapon_motion', 'gripforge_weapon_motion_review'];
+export function registerWeaponMotionTools(register, options, s = z) {
+    const v = s.tuple([s.number(), s.number(), s.number()]);
+    const common = { source_id: s.string().regex(/^lib_[A-Za-z0-9_-]{8,64}$/), workspace_id: s.string().max(100).optional() };
+    const profile = { ...common, family: s.enum(['axe', 'sword', 'hammer', 'staff']).optional().describe('Required on the first call. Never infer axe vs sword from geometry alone.'), hand: s.enum(['left', 'right']).optional(), hands: s.union([s.literal(1), s.literal(2)]).optional(), weaponNode: s.string().max(150).optional(), primaryAnchor: v.optional(), secondaryAnchor: v.optional().describe('Required for two hands; weapon-node local coordinates.'), handleAxis: v.optional(), edgeAxis: v.optional() };
+    const generate = { ...profile, slots: s.array(s.enum(['idle', 'walk', 'run', 'attack1', 'attack2', 'attack3', 'hit', 'death', 'dodge', 'block', 'jump_start', 'jump_loop', 'jump_land'])).min(1).max(13).optional(), name: s.string().max(150).optional(), idempotency_key: s.string().regex(/^[a-zA-Z0-9_.:-]{8,160}$/).optional() };
+    const definitions = [
+        { name: WEAPON_MOTION_TOOL_NAMES[0], action: 'profile', shape: profile, description: 'Measure an owned armed GLB instance and return its editable weapon/motion profile: explicit family, holding hand, dimensions, grip anchors, handle and cutting-edge axes. Use gripforge_attach first. Default axes are +Y handle and +Z edge; inspect/correct them. Does not mutate the Library source or certify the initial seating.' },
+        { name: WEAPON_MOTION_TOOL_NAMES[1], action: 'generate', shape: generate, description: 'Queue a persistent weapon-aware motion draft from an owned armed GLB. Axe/hammer get distinct procedural cleave, backhand and overhead attacks; sword uses the explicit UAL sword pack. Staff attacks fail with compatible_motion_missing; no silent sword fallback. Holds Grip finger poses, supports a second-hand anchor with IK. Poll gripforge_generation_read, cancel/retry with generation tools. Returns a NEW work asset and Character Studio URL; never replaces the game/source or visually validates a result. 0 generation credits.' },
+        { name: WEAPON_MOTION_TOOL_NAMES[2], action: 'review', shape: common, description: 'Independently sample the saved weapon-motion GLB at 60 Hz: grip drift, finger pose, wrist rotation, joint discontinuities, second-hand reach and torso overlaps. Reports technicalPassed separately from visualStatus=not_reviewed. Inspect idle, wind-up, impact, recovery and locomotion in GripForge before using the draft. No promotion or mutation.' },
+    ];
+    for (const d of definitions)
+        register(d.name, { title: d.name, description: d.description, inputSchema: d.shape, annotations: { readOnlyHint: d.action !== 'generate', destructiveHint: false, idempotentHint: d.action !== 'generate', openWorldHint: false } }, async (args, extra) => {
+            const key = options.getApiKey();
+            if (!key)
+                return { isError: true, content: [{ type: 'text', text: 'GripForge API key required.' }] };
+            const parsed = s.object(d.shape).strict().safeParse(args);
+            if (!parsed.success)
+                return { isError: true, content: [{ type: 'text', text: parsed.error.message }] };
+            const { workspace_id, ...body } = parsed.data;
+            try {
+                const response = await fetch(options.apiUrl.replace(/\/$/, '') + '/api/v1/weapon-motion', { method: 'POST', headers: { 'content-type': 'application/json', 'x-api-key': key, ...(workspace_id ? { 'x-workspace-id': workspace_id } : {}) }, body: JSON.stringify({ action: d.action, ...body }), signal: AbortSignal.any([AbortSignal.timeout(150000), ...(extra?.signal ? [extra.signal] : [])]) });
+                const data = await response.json();
+                for (const k of ['studio_url', 'status_url'])
+                    if (typeof data[k] === 'string' && data[k].startsWith('/'))
+                        data[k] = new URL(data[k], options.apiUrl).href;
+                return { ...(!response.ok ? { isError: true } : {}), structuredContent: data, content: [{ type: 'text', text: JSON.stringify(data) }] };
+            }
+            catch (error) {
+                return { isError: true, content: [{ type: 'text', text: error instanceof Error ? error.message : 'Weapon motion request failed.' }] };
+            }
+        });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gripforgeai/mcp",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "The tools your AI needs to make your games. Turn prompts into production-ready game assets — animated characters with their weapons attached, seamless textures, terrain, VFX, HUDs — and playable game kits Unity, Godot, Unreal or Three.js can load.",
   "license": "MIT",
   "type": "module",
@@ -9,6 +9,11 @@
   },
   "files": [
     "dist",
+    "runtime/unreal-scene-import.py",
+    "runtime/unreal-scene-export.py",
+    "runtime/unreal-scene-upload.mjs",
+    "runtime/unreal_scene_math.py",
+    "runtime/unreal_spawn_review.py",
     "README.md"
   ],
   "scripts": {