@gripforgeai/mcp 0.1.10 → 0.1.12

package/dist/scene-tools.js

@@ -1,15 +1,28 @@
 import { z } from 'zod/v4';
+import { LOOK_DESCRIPTION, LOOK_VALUES } from './look.js';
 /** UI and agents call the same scene commands, access checks and revision store. */
 export function registerSceneTools(register, options, schema = z) {
     const identifier = schema.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,159}$/);
     const record = schema.record(schema.string(), schema.unknown());
     const revision = schema.number().int().positive();
+    const imageRef = schema.object({ assetId: identifier, revisionId: identifier, fileRole: identifier.optional() });
+    const mapWizard = schema.object({
+        style: schema.enum(['realistic', 'stylized', 'lowpoly', 'handpainted']).optional().describe('Legacy wording kept in the intent; it does not change the rendering. Use look.'),
+        look: schema.enum(LOOK_VALUES).optional().describe(`${LOOK_DESCRIPTION} Map: the theme gives the biome, the look the materials (LevelSpec.look).`),
+        world: schema.enum(['open_world', 'closed_arena', 'dungeon', 'linear', 'battle_map']).optional(),
+        terrain: schema.enum(['auto', 'plains', 'desert_canyon', 'forest', 'snow', 'island', 'volcanic']).optional(),
+        size: schema.enum(['small', 'medium', 'large']).optional(),
+        dimensions: schema.object({ width: schema.number().min(100).max(5000), depth: schema.number().min(100).max(5000) }).optional().describe('Explicit ground footprint in metres. Overrides size presets and world multipliers. Example: {width:500,depth:500}. Four-team maps require a square.'),
+        boundary: schema.enum(['fixed', 'infinite']).optional(), spawn: schema.enum(['single', 'teams']).optional(),
+        teams: schema.union([schema.literal(2), schema.literal(4)]).optional(),
+        boss: schema.boolean().optional(), safeZone: schema.boolean().optional(), extraction: schema.boolean().optional(),
+    }).passthrough();
     const workspace = { workspace_id: schema.string().max(100).optional().describe('Workspace authorized by the current key. Returned scene links open this workspace.') };
     async function call(path, args, method, signal) {
         const key = options.getApiKey();
         if (!key)
             return { isError: true, content: [{ type: 'text', text: 'GripForge API key required.' }] };
-        const { workspace_id, id: _id, version: _version, include_preview, ...body } = args;
+        const { workspace_id, id: _id, version: _version, include_preview, preview_view, ...body } = args;
         try {
             const response = await fetch(`${options.apiUrl.replace(/\/$/, '')}/api/v1/${path}`, {
                 method, headers: { 'content-type': 'application/json', 'x-api-key': key, 'x-gripforge-client': 'mcp', ...(typeof workspace_id === 'string' ? { 'x-workspace-id': workspace_id } : {}) },
@@ -23,16 +36,47 @@ export function registerSceneTools(register, options, schema = z) {
                 if (result && typeof result === 'object' && typeof result.studio_url === 'string')
                     result.studio_url = new URL(String(result.studio_url), options.apiUrl).href;
             const content = [{ type: 'text', text: JSON.stringify(data) }];
-            const preview = data.result?.preview_url;
-            if (response.ok && include_preview === true && typeof preview === 'string' && preview.startsWith('/api/v1/generation-jobs/')) {
-                const image = await fetch(new URL(preview, options.apiUrl), { headers: { 'x-api-key': key, ...(typeof workspace_id === 'string' ? { 'x-workspace-id': workspace_id } : {}) }, signal: AbortSignal.any([AbortSignal.timeout(30_000), ...(signal ? [signal] : [])]) });
-                if (!image.ok || !image.headers.get('content-type')?.startsWith('image/png'))
-                    throw Error('The job preview could not be read. The completed job remains available.');
-                const bytes = await image.arrayBuffer();
-                if (bytes.byteLength > 12 * 1024 * 1024)
-                    throw Error('Preview exceeds the image budget.');
-                content.push({ type: 'image', mimeType: 'image/png', data: Buffer.from(bytes).toString('base64') });
+            const result = data.result;
+            if (response.ok && include_preview === true) {
+                let previews = Array.isArray(result?.concept_views) ? result.concept_views.slice(0, 4) : result?.preview_url ? [{ view: 'overview', label: 'Preview', preview_url: result.preview_url }] : [];
+                if (typeof preview_view === 'string') {
+                    previews = previews.filter(view => view.view === preview_view);
+                    if (!previews.length)
+                        throw Error('This preview view is not available yet. The job remains available.');
+                }
+                const images = await Promise.all(previews.map(async (preview) => {
+                    const path = preview.preview_url ?? ('image_url' in preview ? preview.image_url : undefined);
+                    if (typeof path !== 'string' || !/^\/api\/v1\/(?:generation-jobs|scene-assets)\//.test(path))
+                        throw Error('Invalid job preview URL.');
+                    const image = await fetch(new URL(path, options.apiUrl), { headers: { 'x-api-key': key, ...(typeof workspace_id === 'string' ? { 'x-workspace-id': workspace_id } : {}) }, signal: AbortSignal.any([AbortSignal.timeout(30_000), ...(signal ? [signal] : [])]) });
+                    if (!image.ok || !image.headers.get('content-type')?.startsWith('image/png'))
+                        throw Error('The job preview could not be read. The completed job remains available.');
+                    const bytes = await image.arrayBuffer();
+                    if (bytes.byteLength > 12 * 1024 * 1024)
+                        throw Error('Preview exceeds the image budget.');
+                    return { label: preview.label ?? preview.view.replaceAll('_', ' '), data: Buffer.from(bytes).toString('base64') };
+                }));
+                for (const image of images) {
+                    if (images.length > 1)
+                        content.push({ type: 'text', text: image.label });
+                    content.push({ type: 'image', mimeType: 'image/png', data: image.data });
+                }
             }
+            for (const result of [data, data.result, job?.result])
+                if (result && typeof result === 'object') {
+                    const row = result;
+                    for (const key of ['studio_url', 'review_url', 'file_url', 'source_url', 'concept_url', 'status_url'])
+                        if (typeof row[key] === 'string' && row[key].startsWith('/'))
+                            row[key] = new URL(row[key], options.apiUrl).href;
+                    if (Array.isArray(row.concept_views))
+                        for (const view of row.concept_views)
+                            if (view && typeof view === 'object') {
+                                for (const key of ['image_url', 'preview_url', 'studio_url'])
+                                    if (typeof view[key] === 'string' && view[key].startsWith('/'))
+                                        view[key] = new URL(view[key], options.apiUrl).href;
+                            }
+                }
+            content[0] = { type: 'text', text: JSON.stringify(data) };
             return { ...(!response.ok ? { isError: true } : {}), structuredContent: data, content };
         }
         catch (error) {
@@ -40,6 +84,15 @@ export function registerSceneTools(register, options, schema = z) {
         }
     }
     const tool = (name, title, description, inputSchema, readOnly, callback) => register(name, { title, description, inputSchema: { ...inputSchema, ...workspace }, annotations: { readOnlyHint: readOnly, destructiveHint: false, idempotentHint: readOnly, openWorldHint: false } }, callback);
+    tool('gripforge_vehicle_doors', 'Open or close vehicle doors in the Studio', 'Save an independent door pose on one prepared vehicle instance in a saved scene. doors maps Door_FL/FR/RL/RR to 0 (closed)..1 (open). Unspecified doors retain their state; null clears the manual pose. Requires exact expectedRevision and named hinges/portable clips from prepare_vehicle. Pauses the global animation for manual control. Preserves the source asset, transforms, other instances and validated versions. Returns the actual Studio link. No generation charge.', { id: identifier, expectedRevision: revision, nodeId: identifier, doors: schema.record(schema.string().regex(/^Door_[FR][LR]$/), schema.number().min(0).max(1)).nullable() }, false, (args, extra) => call(`scenes/${args.id}/vehicle-doors`, args, 'POST', extra?.signal));
+    tool('gripforge_prepare_vehicle', 'Prepare segmented vehicle hinges in Blender', 'Durable Blender preparation of an owned static segmented GLB. Map each Door_FL/FR/RL/RR or Wheel_FL/FR/RL/RR to exact mesh node names from the segmentation report. Keeps geometry placement, UVs and PBR; normalizes +Z forward/metres using yaw and length; adds hinge origins, seat/entry sockets and portable GLB open/close/preview clips. Optional hinge coordinates are in normalized vehicle metres. thickness adds an inward door shell, not a full cabin. Optional cuts provide strictly convex door outlines [forwardZ,heightY] and depth [near,far] measured from the centre on that side, in normalized metres. cuts[].meshes restricts each cut to exact exterior/glazing meshes so seats and dashboard cannot be cut. removeMeshes discards explicitly named obsolete trim in the work copy only. Optional clearanceDepthM clears scoped inner walls behind the door skin; trim adds measured body frames, seals and moulded cards below cardTopY. framePoints follows outline in normalized [x,y,z]. Optional trim.fitToSurface projects frames, seals and the inner card onto only the explicitly selected opaque door skin, preserving the supplied outline. attachments adds scoped [min,max] [x,y,z] volumes for mirrors extending beyond the door profile. Blender cuts those explicit profiles while interpolating UVs. Does not infer outlines or guarantee clearance. Returns job_id, new private work GLB, Blender source and animated Studio review link. 0 credits; storage applies. Inspect before replacement.', { source: imageRef, parts: schema.record(schema.string(), schema.array(schema.string().min(1).max(160)).min(1).max(64)).optional(), cuts: schema.array(schema.object({ role: schema.enum(['Door_FL', 'Door_FR', 'Door_RL', 'Door_RR']), outline: schema.array(schema.tuple([schema.number(), schema.number()])).min(3).max(12), depth: schema.tuple([schema.number(), schema.number()]), meshes: schema.array(schema.string().min(1).max(160)).min(1).max(128).optional(), clearanceDepthM: schema.number().min(0).max(3).optional(), attachments: schema.array(schema.object({ bounds: schema.tuple([schema.tuple([schema.number(), schema.number(), schema.number()]), schema.tuple([schema.number(), schema.number(), schema.number()])]), meshes: schema.array(schema.string().min(1).max(160)).min(1).max(128) })).max(4).optional(), trim: schema.object({ framePoints: schema.array(schema.tuple([schema.number(), schema.number(), schema.number()])).min(3).max(12), frameRadiusM: schema.number().min(.003).max(.04).optional(), sealRadiusM: schema.number().min(.002).max(.02).optional(), cardTopY: schema.number().optional(), cardInsetM: schema.number().min(.01).max(.12).optional(), fitToSurface: schema.boolean().optional(), cardColor: schema.tuple([schema.number().min(0).max(1), schema.number().min(0).max(1), schema.number().min(0).max(1)]).optional() }).optional() })).max(4).optional(), removeMeshes: schema.array(schema.string().min(1).max(160)).max(128).optional(), yaw: schema.number().min(-180).max(180).optional(), length: schema.number().min(2.8).max(7).optional(), openAngle: schema.number().min(20).max(85).optional(), thickness: schema.number().min(0).max(.04).optional(), hinges: schema.record(schema.string(), schema.tuple([schema.number(), schema.number(), schema.number()])).optional(), idempotency_key: schema.string().min(8).max(160).optional() }, false, (args, extra) => call('vehicles/prepare', args, 'POST', extra?.signal));
+    tool('gripforge_vehicle_schema', 'Modular vehicle manufacturing contract', 'Read the concept-first vehicle recipe, canonical parts, hinge convention, limits, quotes and revision workflow.', {}, true, (args, extra) => call('vehicles', args, 'GET', extra?.signal));
+    tool('gripforge_generate_vehicle', 'Generate a vehicle from reviewed multi-view references', 'Read vehicle_schema first. Recommended recipe.workflow=body_wheels follows concept → references (five wheel-less body views + wheel) → geometry (stop/review) → topology (stop/review) → build (PBR + wheel + rig). Each geometry review uses scene_review with the returned assetRef and must be approved before the next paid step. Rigging preserves UVs and corner normals, GLB/FBX/Blend and measured Chaos setup. Top view is review-only. parts.body.geometry accepts unfinished Hunyuan/Blender GLB; parts.body.topology pins the reviewed reduced GLB; parts.<role>.source reuses finished meshes. Legacy modular_doors remains available for articulated doors. stage=plan quotes each stage without spending; paid stages require its budget. Durable job; poll generation_read. Work draft, real-render review and target-engine driving test required; no automatic publication/replacement.', { stage: schema.enum(['plan', 'concept', 'references', 'geometry', 'topology', 'build']).default('plan'), recipe: record, budget: schema.object({ usd: schema.number().nonnegative().optional(), credits: schema.number().int().nonnegative().optional() }).optional(), idempotency_key: schema.string().min(8).max(160).optional() }, false, (args, extra) => call('vehicles', args, 'POST', extra?.signal));
+    tool('gripforge_vehicle_segment', 'Separate an existing vehicle with Tripo', 'Quote then queue one durable Tripo v2 semantic segmentation of an owned immutable GLB, including Meshy or Blender sources. stage=plan is free; stage=build requires quoted budget. 40 Tripo provider credits, distinct from the GripForge quote. Returns job_id; inspect parts and texture preservation in generation_read. No automatic completion, retexture, articulation, publication or replacement. A segmented output still needs hinge preparation.', { stage: schema.enum(['plan', 'build']).default('plan'), source: imageRef, granularity: schema.enum(['simple', 'balanced', 'detailed']).optional(), budget: schema.object({ usd: schema.number().nonnegative().optional(), credits: schema.number().int().nonnegative().optional() }).optional(), idempotency_key: schema.string().min(8).max(160).optional() }, false, (args, extra) => call('vehicles/segment', args, 'POST', extra?.signal));
+    tool('gripforge_map_import_unreal_schema', 'Unreal to Studio import contract', 'Read the native export → binary upload → persistent map import workflow, limits and explicit conversion caveats. Native extraction requires the local MCP and an installed Unreal editor. Hosted MCP/API consume the resulting portable SceneDocument; they cannot read your local .umap/.uasset files.', {}, true, (args, extra) => call('maps/import/unreal', args, 'GET', extra?.signal));
+    tool('gripforge_map_import_unreal', 'Import a portable Unreal scene', 'Queue a persistent import of schema gripforge.unreal-studio-import.v1. Upload files via local gripforge_map_unreal_upload_local or POST /api/v1/maps/import/unreal/assets first. document is a common SceneDocument with workspace-owned immutable assets, separate props, static foliage patches and editable terrain. source={engine:unreal,level:/Game/...,sha256,warnings:[]}. Returns job_id; poll generation_read for studio_url. Always a NEW private work scene; no overwrite, automatic validation or Community publication. 0 credits; storage quota applies.', { schema: schema.literal('gripforge.unreal-studio-import.v1'), document: record, source: schema.object({ engine: schema.literal('unreal'), level: schema.string().regex(/^\/Game(?:\/[\w-]+)+$/), sha256: schema.string().regex(/^[a-f0-9]{64}$/), warnings: schema.array(schema.string().max(2000)).max(100) }), idempotency_key: schema.string().min(8).max(160).optional() }, false, (args, extra) => call('maps/import/unreal', args, 'POST', extra?.signal));
+    tool('gripforge_flexible_weapon_schema', 'Flexible weapon manufacturing recipes', 'Read the bounded recipe and concept-first workflow for Meshy + Blender flexible weapons, costs, pinned component reuse and source animation requirements.', {}, true, (args, extra) => call('flexible-weapons', args, 'GET', extra?.signal));
+    tool('gripforge_generate_flexible_weapon', 'Generate an articulated flexible weapon', 'Persistent concept → isolated handle/segment references → Meshy PBR components → FlexibleChain XPBD → Blender assembly/rig → actual GripForge renderer review. Read flexible_weapon_schema first. recipe stage=concept returns an image before 3D; build can reuse that concept and owned pinned components. Up to 12 existing source clips or sampled motions; character choreography is not generated by this tool. Returns job_id immediately; poll generation_read for weapon GLB, Blender source, physics reports, separate character/weapon review scene and Studio links. Max 23 credits when all art is new; reused components are free. Cancel/retry retains successful provider and fabrication steps. Always private work: no automatic replacement, promotion or Community publication.', { recipe: record, idempotency_key: schema.string().min(8).max(160).optional() }, false, (args, extra) => call('flexible-weapons', args, 'POST', extra?.signal));
     tool('gripforge_flexible_chain_schema', 'Flexible chain recipes and examples', 'Read the bounded recipe schema for the shared FlexibleChain solver. Presets: whip, rope, tail. Input can follow an exact named mount in a pinned GLB animation or sampled world-space motion. Includes units, collision capsules, limits and a runnable example.', {}, true, (args, extra) => call('flexible-chain', args, 'GET', extra?.signal));
     tool('gripforge_flexible_chain', 'Simulate and bake a flexible chain', 'Queue a persistent 240 Hz XPBD simulation using GripForge Scene Engine. Read flexible_chain_schema first. recipe version=1: preset whip|rope|tail, duration<=10s, fps=30|60, physics {length,segments,damping,bendCompliance,gravity,radius,floor,iterations}; choose motion [{time,position,direction,capsules}] OR source {asset:{assetId,revisionId},clip,mount_node,offset,axis,colliders}. Source assets are immutable and workspace-scoped. Returns a job ID; poll generation_read for a new draft skinned-chain GLB, sampled joints, recipe, physics metrics and Character Studio link. This is a neutral physics preview, not a Meshy weapon redesign or automatic rebind of the source weapon. No runtime world collision or seamless loop guarantee. Cancel/retry keeps completed steps. Does not replace or visually validate an existing asset. 0 credits; storage quota applies.', { recipe: record, idempotency_key: schema.string().min(8).max(160).optional() }, false, (args, extra) => call('flexible-chain', args, 'POST', extra?.signal));
     tool('gripforge_armor_generate', 'Generate a modular armor kit', 'Queue a durable armor-kit job: one shared concept, isolated Imagine references, Meshy PBR models, bounded Blender interior preparation and paired GLB exports, then actual GripForge wearer review. Types: helmet, chest, belt, pauldron, bracer, glove, thigh, greave, boot, upperarm, gorget, tasset, undersuit. coverage=full adds a durable anatomical decomposition of the concept, rejects missing planned roles before mesh generation and records per-instance coverage fits. A piece count alone never proves body coverage. The optional undersuit is a locally manufactured adaptive textile which retains each wearer’s skin weights. Meshy pieces cost 11 credits per canonical type; the textile has no image/mesh charge. A new concept costs 1 credit; mirrors are included. concept_item must be an owned Library image. source_kit + explicit pieces regenerates only those types into a NEW work kit and pins unchanged pieces. Closing the call/page does not cancel. Poll gripforge_generation_read. Success is a work version, never automatic visual approval. The result includes a Grip Studio link, review scene, concepts, source models and Blender source.', {
@@ -52,19 +105,32 @@ export function registerSceneTools(register, options, schema = z) {
     tool('gripforge_armor_read', 'Read a modular armor kit', 'Read an owned kit manifest, semantic slots and immutable piece revisions. Equipment and instances remain independent. Returns the Grip Studio link. To correct selected types, call gripforge_armor_generate with source_kit and pieces.', { id: identifier }, true, (args, extra) => call(`armor-kits/${args.id}`, args, 'GET', extra?.signal));
     tool('gripforge_armor_repair', 'Repair unfinished armor pieces', 'Fork a failed/cancelled armor job into a new work kit. Preserve completed pieces and the exact shared concept; recreate only unfinished types by default. Optional pieces chooses types explicitly. Use prompt for targeted corrections. Original checkpoints and artifacts remain intact. Costs 11 credits per regenerated canonical type (plus a concept credit only if none survived). Use generation_retry instead for a transient provider or worker error to reuse the exact same steps without another charge.', { source_job: identifier, prompt: schema.string().min(3).max(2000).optional(), pieces: schema.array(schema.enum(['helmet', 'chest', 'belt', 'pauldron', 'bracer', 'glove', 'thigh', 'greave', 'boot', 'upperarm', 'gorget', 'tasset', 'undersuit'])).min(1).max(13).optional(), idempotency_key: schema.string().min(8).max(160).optional() }, false, (args, extra) => call('armor-kits', args, 'POST', extra?.signal));
     tool('gripforge_map_import', 'Migrate a saved terrain map', 'Queue a one-time materialization of an owned legacy terrain map into the shared Scene Engine. Preserve the saved spec, seed, resolution, family replacements, placed assets and removed props. Completed jobs return a canonical Studio link; source edits during migration cause a conflict rather than data loss.', { id: identifier }, false, (args, extra) => call('generation-jobs/map/import', { ...args, legacyMapId: args.id }, 'POST', extra?.signal));
-    tool('gripforge_map_generate', 'Generate an editable map', 'Queue persistent map generation into the common Scene Engine. wizard: style realistic|stylized|lowpoly|handpainted; world open_world|closed_arena|dungeon|linear|battle_map; terrain plains|desert_canyon|forest|snow|island|volcanic; size small|medium|large; boundary fixed|infinite (open edge, finite terrain); spawn single|teams; teams 2|4. Result contains independent terrain, regions, paths, spawn zones and asset instances. Work is not automatically validated. Poll generation_read.', { prompt: schema.string().min(3).max(4000), wizard: record, seed: schema.number().int().optional(), idempotency_key: schema.string().min(8).max(160).optional() }, false, (args, extra) => call('generation-jobs/map', args, 'POST', extra?.signal));
+    tool('gripforge_map_schema', 'Map concept and generation workflow', 'Read the concept-first map workflow, immutable image reference format, costs and an example. Concepts, map work scenes and external engine delivery are separate steps.', {}, true, (args, extra) => call('generation-jobs/map', args, 'GET', extra?.signal));
+    tool('gripforge_map_generate', 'Create map concept views or an editable map', 'Queue a persistent map job. stage=concept creates a private master overview plus optional views and stops. views: overview,top_down,entrance,objective. All additional views are conditioned on the SAME pinned master; they are illustrations, not exact 3D renders. reference is an environment screenshot for a NEW layout. To add views to an existing concept, pass source_concept instead; the master is kept unchanged and is free. One credit per new image (full new 4-view set = 4); default is overview only. Poll generation_read with include_preview=true to see the views. After the user selects the concept, submit stage=build with the returned concept and a new idempotency key. Build costs 1 credit and is the default for existing callers; legacy concept_item accepts a Library image ID, while concept pins its exact version. wizard: look stylized|painted|toon|anime|realistic|lowpoly|pixel (rendering, separate from style; omit for the theme default); style realistic|stylized|lowpoly|handpainted (legacy wording); world open_world|closed_arena|dungeon|linear|battle_map; terrain auto|plains|desert_canyon|forest|snow|island|volcanic; size small|medium|large; boundary fixed|infinite (open edge, finite terrain); spawn single|teams; teams 2|4; boss,safeZone,extraction booleans. sources selects catalog/workspace/community props. Build uses the common Scene Engine with independent terrain, regions, paths, zones and asset instances. Cancel/retry keeps successful images and billing. No automatic visual validation, promotion or Unreal import.', {
+        prompt: schema.string().min(3).max(4000), wizard: mapWizard, stage: schema.enum(['concept', 'build']).optional(),
+        reference: imageRef.optional().describe('Pinned source-environment screenshot for stage=concept only. Upload to Library and pin first.'),
+        source_concept: imageRef.optional().describe('Existing immutable master to add views to, stage=concept only. Mutually exclusive with reference; never regenerate this master.'),
+        views: schema.array(schema.enum(['overview', 'top_down', 'entrance', 'objective'])).min(1).max(4).optional().describe('Unique requested views, stage=concept only. The master overview is always included; omitting views keeps overview only.'),
+        concept: imageRef.optional().describe('Exact chosen concept revision for stage=build. Mutually exclusive with concept_item.'),
+        concept_item: identifier.optional().describe('Legacy Library concept image ID. Prefer an immutable concept reference.'),
+        structure: record.optional().describe('Optional explicit gripforge.map-structures.v1 plan for stage=build: terraces with polygon/elevation and separate ramp/bridge connections. Read gripforge_map_schema for the contract. Preserves canyon voids; validates bridge clearance, endpoints and slopes. Uses durable per-piece assets and the common SceneDocument. Dimensions must match wizard.dimensions. Solo maps only; result is a structural work version requiring visual review.'),
+        sources: schema.array(schema.enum(['catalog', 'workspace', 'community'])).min(1).max(3).optional(),
+        seed: schema.number().int().min(-2147483647).max(2147483647).optional(), idempotency_key: schema.string().min(8).max(160).optional(),
+    }, false, (args, extra) => call('generation-jobs/map', args, 'POST', extra?.signal));
     tool('gripforge_scene_modify', 'Modify a selection with AI', 'Queue a scoped edit of saved scene nodes or a region. The server derives the allowed scope and preserves locks, gameplay zones, outside geometry and the last validated revision. Blender may fabricate missing assets. The result is a proposal requiring explicit application, never a silently replaced map.', { id: identifier, expectedRevision: revision, nodeIds: schema.array(identifier).min(1).max(100), prompt: schema.string().min(3).max(4000), blendDistance: schema.number().positive().max(1000).optional(), idempotency_key: schema.string().min(8).max(160).optional() }, false, (args, extra) => call(`scenes/${args.id}/modify`, args, 'POST', extra?.signal));
     tool('gripforge_scene_proposals', 'List proposed scene edits', 'List persistent proposals and their base revision, status and descriptions.', { id: identifier }, true, (args, extra) => call(`scenes/${args.id}/proposals`, args, 'GET', extra?.signal));
     tool('gripforge_scene_proposal_read', 'Read a proposed scene edit', 'Read the original scene, proposed document and scoped commands. Use the Studio link to inspect actual rendering before applying.', { id: identifier, proposal: identifier }, true, (args, extra) => call(`scenes/${args.id}/proposals/${args.proposal}`, args, 'GET', extra?.signal));
     tool('gripforge_scene_proposal_apply', 'Apply a reviewed proposal to work', 'Explicitly accept or discard a proposal after inspecting it. Accept requires expectedRevision to match the exact base and current work revision. Atomic: concurrent changes or discard abort the save. Creates work, never promotes validated.', { id: identifier, proposal: identifier, action: schema.enum(['accept', 'discard']), expectedRevision: revision.optional() }, false, (args, extra) => call(`scenes/${args.id}/proposals/${args.proposal}`, args, 'POST', extra?.signal));
     tool('gripforge_scene_schema', 'Shared scene engine format', 'Start here. Read the shared scene model, kinds, commands, limits and an editable example. Assets are immutable revisions; placed objects are independent instances. Scene saves create work revisions, never automatic visual approval.', {}, true, (args, extra) => call('scenes/schema', args, 'GET', extra?.signal));
+    tool('gripforge_scene_realism', 'Shared materials, automotive lighting and post-processing', 'Apply reusable architectural surface profiles and GTAO to a saved work scene. Read gripforge_scene_schema.realism first. assignments [{nodeId,material:"*" or a named slot,surface:{preset:preserve|brick|stone|metal|glass,detail:0..1,weathering:0..1,regions:[]}}]; surface:null removes only this local profile. Optional glass regions use explicit normalized mesh-local min/max bounds and interior parallax settings. Never guess masks from colours. ambientOcclusion {enabled,radius:0.02..3 metres,intensity:0..1,quality:low|medium|high}, or null to remove. Preserves transforms, source PBR maps, other instances and validated revisions. Returns Studio link for visual comparison. Optional quality {preset:performance|balanced|quality,resolutionScale:0.5..1,sharpness:0..0.5}, or null to restore the original presentation. Quality supports viewport resolution up to a bounded 4K budget. Optional automotive {look:studio|daylight,quality,lengthM,depthOfField:false,focusDistanceM} explicitly applies a whole-scene look: HDR strip reflections, contact AO, quality and restrained post-processing. Studio replaces an existing HDRI; daylight keeps it. Optional colorGrading/depthOfField overrides or null. DOF is perspective/capture only, disabled with volumetric passes. No generation charge, DLSS or automatic approval.', { id: identifier, expectedRevision: revision, assignments: schema.array(schema.object({ nodeId: identifier, material: schema.string().min(1).max(256).optional(), surface: record.nullable() })).max(100).optional(), ambientOcclusion: schema.object({ enabled: schema.boolean(), radius: schema.number().min(.02).max(3), intensity: schema.number().min(0).max(1), quality: schema.enum(['low', 'medium', 'high']) }).nullable().optional(), quality: schema.object({ preset: schema.enum(['performance', 'balanced', 'quality']), resolutionScale: schema.number().min(.5).max(1).optional(), sharpness: schema.number().min(0).max(.5).optional() }).nullable().optional(), automotive: schema.object({ look: schema.enum(['studio', 'daylight']).optional(), quality: schema.enum(['performance', 'balanced', 'quality']).optional(), lengthM: schema.number().min(1).max(25).optional(), ground: schema.boolean().optional(), depthOfField: schema.boolean().optional(), focusDistanceM: schema.number().min(.1).max(1000).optional() }).optional(), colorGrading: schema.object({ contrast: schema.number().min(.5).max(1.5), saturation: schema.number().min(0).max(1.5), temperature: schema.number().min(-1).max(1) }).nullable().optional(), depthOfField: schema.object({ enabled: schema.boolean(), focusDistanceM: schema.number().min(.1).max(1000), aperture: schema.number().min(0).max(.01), maxBlur: schema.number().min(0).max(.02) }).nullable().optional() }, false, (args, extra) => call(`scenes/${args.id}/realism`, args, 'POST', extra?.signal));
+    tool('gripforge_scene_optimize', 'Prepare a scene for fast browser loading', 'Queue resumable browser texture variants for a saved scene. Preserve original GLBs, geometry, transforms, PBR, animations and Library heads. Color textures up to 1024px, data maps up to 512px and terrain color up to 4096px; WebP encoding. Saves a new work revision only if expectedRevision still matches. Does not promote validated. Poll generation_read for byte savings and studio_url. 0 credits; storage quota applies. New Unreal imports do this automatically.', { id: identifier, expectedRevision: revision, idempotency_key: schema.string().min(8).max(160).optional() }, false, (args, extra) => call(`scenes/${args.id}/optimize`, args, 'POST', extra?.signal));
     tool('gripforge_scene_list', 'List workspace scenes', 'List scenes, work/validated revision pointers and links in the authenticated workspace.', {}, true, (args, extra) => call('scenes', args, 'GET', extra?.signal));
     tool('gripforge_scene_read', 'Read scene source', 'Read the editable SceneDocument at work, validated, or a numbered revision. Keep work_revision for optimistic writes. Validated can be absent.', { id: identifier, version: schema.union([schema.enum(['work', 'validated']), schema.number().int().positive()]).optional() }, true, (args, extra) => call(`scenes/${encodeURIComponent(String(args.id))}?version=${args.version ?? 'work'}`, args, 'GET', extra?.signal));
     tool('gripforge_scene_create', 'Create a workspace scene', 'Create a draft scene. Pin Library assets first and use returned assetId/revisionId references. The response contains a GripForge Studio link. Exporting a VFX definition must not include this test scene.', { document: record }, false, (args, extra) => call('scenes', args, 'POST', extra?.signal));
     tool('gripforge_scene_write', 'Save scene work revision', 'Save a complete SceneDocument. expectedRevision must equal the latest work revision. A 409 is a real conflict: reread before changing it. Does not change the validated revision or source Library assets.', { id: identifier, document: record, expectedRevision: schema.number().int().positive() }, false, (args, extra) => call(`scenes/${encodeURIComponent(String(args.id))}`, args, 'PUT', extra?.signal));
     tool('gripforge_scene_patch', 'Edit selected scene instances', 'Apply insert/remove/transform/replace/update commands atomically. Environment updates can configure shared 3D cloud layers (density, altitude, wind, colour and quality); see gripforge_scene_schema. Replace preserves id, transform, role, materials and attachments, and rejects incompatible named slots. Locked objects cannot be changed. Scope constrains regional edits; read the schema first.', { id: identifier, baseRevision: schema.number().int().positive(), commands: schema.array(record).min(1).max(20000), scope: record.optional() }, false, (args, extra) => call(`scenes/${encodeURIComponent(String(args.id))}`, args, 'PATCH', extra?.signal));
     tool('gripforge_scene_versions', 'Scene versions and visual reviews', 'Read work/current pointers, immutable revision history and trusted visual review evidence. A rejected or unavailable review does not change the validated version.', { id: identifier }, true, (args, extra) => call(`scenes/${args.id}/versions`, args, 'GET', extra?.signal));
-    tool('gripforge_scene_review', 'Request an actual GripForge visual review', 'Queue a persistent render and independent visual review of the exact saved work revision. Poll generation_read. This does not promote or replace the validated version.', { id: identifier, expectedRevision: schema.number().int().positive(), prompt: schema.string().max(4000).optional(), idempotency_key: schema.string().min(8).max(160).optional() }, false, (args, extra) => call(`scenes/${args.id}/review`, args, 'POST', extra?.signal));
+    tool('gripforge_scene_review', 'Request an actual GripForge visual review', 'Queue a persistent render and independent visual review of the exact saved work revision. Poll generation_read. Optional assetRef records the review on the exact isolated asset revision as well; required for vehicle geometry/topology gates. This does not promote or replace the validated version.', { id: identifier, expectedRevision: schema.number().int().positive(), assetRef: imageRef.optional(), prompt: schema.string().max(4000).optional(), idempotency_key: schema.string().min(8).max(160).optional() }, false, (args, extra) => call(`scenes/${args.id}/review`, args, 'POST', extra?.signal));
     tool('gripforge_scene_promote', 'Set the visually approved scene version', 'Explicitly promote the latest work revision only if its trusted visual review matches the exact content, dependencies and current renderer. expectedCurrent must match the existing validated pointer or null. No client-supplied approval report is accepted.', { id: identifier, revision: schema.number().int().positive(), expectedCurrent: schema.number().int().positive().nullable() }, false, (args, extra) => call(`scenes/${args.id}/promote`, args, 'POST', extra?.signal));
     tool('gripforge_scene_asset_pin', 'Pin an immutable Library revision', 'Archive the owned Library resource bytes and metadata for use in scenes. Returns assetId/revisionId, capabilities, material/animation names and sockets. Repeating for identical content reuses the archive; it consumes workspace storage only once. Prefers the validated version for insertion; choose version=work to test the draft. Does not approve the asset visually.', { assetId: identifier, version: schema.enum(['current', 'work']).default('current') }, false, (args, extra) => call('scene-assets', args, 'POST', extra?.signal));
     tool('gripforge_scene_asset_versions', 'Read asset version and review', 'Read immutable asset work/current pointers and the trusted review of work. Does not create a version.', { assetId: identifier }, true, (args, extra) => call(`scene-assets/${args.assetId}/versions`, args, 'GET', extra?.signal));
@@ -72,7 +138,7 @@ export function registerSceneTools(register, options, schema = z) {
     tool('gripforge_scene_asset_promote', 'Set the visually approved asset version', 'Promote only when the exact work revision has a matching trusted review for the current renderer. Existing scene instances keep their pinned revision.', { assetId: identifier, revisionId: identifier, expectedCurrent: identifier.nullable() }, false, (args, extra) => call(`scene-assets/${args.assetId}/${args.revisionId}/promote`, args, 'POST', extra?.signal));
     tool('gripforge_fps_animation', 'Manufacture first-person weapon animations', 'Queue a persistent Blender job for paired FPS arms and an articulated pistol: idle, draw, fire, tactical reload and empty reload. Recipe: {version:1,preset:"pistol",name:"Pistol FPS",tempo:1}; tempo 0.7–1.3. Returns job_id immediately; poll gripforge_generation_read for the private Library asset, .blend source, event markers and Character Studio FPS link. Generated variants are work revisions, never automatically validated. Use gripforge_generation_cancel/retry; completed steps survive closing the page.', { recipe: record, idempotency_key: schema.string().min(8).max(160).optional() }, false, (args, extra) => call('fps-animations', args, 'POST', extra?.signal));
     tool('gripforge_generation_list', 'List persistent generation jobs', 'List workspace jobs. Jobs and completed steps survive closing the studio or restarting the web server and worker.', {}, true, (args, extra) => call('generation-jobs', args, 'GET', extra?.signal));
-    tool('gripforge_generation_read', 'Read generation progress and result', 'Poll a job returned by a generation tool. Includes durable steps, progress, failure/retry state and the resulting work revision with a Studio link. include_preview returns an actual rendered VFX image when available. Success does not mean visual approval or promotion.', { id: identifier, include_preview: schema.boolean().optional() }, true, (args, extra) => call(`generation-jobs/${args.id}`, args, 'GET', extra?.signal));
+    tool('gripforge_generation_read', 'Read generation progress and result', 'Poll a job returned by a generation tool. Includes durable steps, progress, failure/retry state and the resulting work revision with a Studio link. include_preview returns saved map/building concept images (at most 4). Set preview_view to return one chosen view. Concepts are generated illustrations, not verified 3D renders. Success does not mean visual approval or promotion.', { id: identifier, include_preview: schema.boolean().optional(), preview_view: schema.enum(['overview', 'top_down', 'entrance', 'objective', 'front_right', 'front_left', 'rear_right', 'rear_left']).optional() }, true, (args, extra) => call(`generation-jobs/${args.id}`, args, 'GET', extra?.signal));
     tool('gripforge_generation_cancel', 'Cancel generation', 'Request worker cancellation while retaining completed steps and artifacts. Closing a page alone does not cancel a job.', { id: identifier }, false, (args, extra) => call(`generation-jobs/${args.id}`, { ...args, action: 'cancel' }, 'POST', extra?.signal));
     tool('gripforge_generation_retry', 'Retry interrupted generation', 'Retry a failed or cancelled job, reusing completed steps. An unconfirmed interrupted provider call may be executed again when explicitly retried.', { id: identifier }, false, (args, extra) => call(`generation-jobs/${args.id}`, { ...args, action: 'retry' }, 'POST', extra?.signal));
     tool('gripforge_blender_fabricate', 'Fabricate editable assets with Blender', 'Queue a bounded Blender recipe, never arbitrary Python. Saves GLB and .blend in the workspace as an unvalidated work version with a shared Scene Studio link. Read gripforge_scene_schema for recipe fields. Supports original primitive/custom meshes, PBR colors and keyed transforms. Poll gripforge_generation_read; final visual approval must use GripForge rendering, not Blender screenshots.', { recipe: record, idempotency_key: schema.string().min(8).max(160).optional() }, false, (args, extra) => call('generation-jobs/blender', args, 'POST', extra?.signal));

package/dist/server-tools.js

@@ -112,7 +112,7 @@ export function registerServerTools(register, options, schema = z) {
     }, { readOnly: false }, (args, extra) => api('servers', args, 'POST', extra?.signal));
     tool('gripforge_server_deploy', 'Deploy a game server', 'Create a Docker instance for this server and start it. Local demo uses a real container (python heartbeat unless a custom image is set). Mutating.', { id: serverId }, { readOnly: false }, (args, extra) => api(`servers/${encodeURIComponent(String(args.id))}/deploy`, args, 'POST', extra?.signal));
     tool('gripforge_server_start', 'Start a game server', 'Start the existing instance. Mutating.', { id: serverId }, { readOnly: false }, (args, extra) => api(`servers/${encodeURIComponent(String(args.id))}/start`, args, 'POST', extra?.signal));
-    tool('gripforge_server_stop', 'Stop a game server', 'Stop the running instance. Mutating.', { id: serverId }, { readOnly: false }, (args, extra) => api(`servers/${encodeURIComponent(String(args.id))}/stop`, args, 'POST', extra?.signal));
+    tool('gripforge_server_stop', 'Stop a game server', 'Stop the running instance. Mutating.', { id: serverId }, { readOnly: false, destructive: true }, (args, extra) => api(`servers/${encodeURIComponent(String(args.id))}/stop`, args, 'POST', extra?.signal));
     tool('gripforge_server_restart', 'Restart a game server', 'Restart the running instance. Mutating.', { id: serverId }, { readOnly: false }, (args, extra) => api(`servers/${encodeURIComponent(String(args.id))}/restart`, args, 'POST', extra?.signal));
     tool('gripforge_server_scale', 'Scale max players', 'Update desired max players. Does not resize cloud hardware (Docker provider has no node pool). Mutating.', { id: serverId, maxPlayers: schema.number().int().min(1).max(200) }, { readOnly: false }, (args, extra) => api(`servers/${encodeURIComponent(String(args.id))}/scale`, args, 'POST', extra?.signal));
     tool('gripforge_server_delete', 'Delete a game server', 'HIGH IMPACT. Stops the instance and deletes the server. Requires confirm=true. Owner only.', { id: serverId, confirm: schema.literal(true).describe('Must be true. Production-destructive.') }, { readOnly: false, destructive: true }, (args, extra) => api(`servers/${encodeURIComponent(String(args.id))}`, args, 'DELETE', extra?.signal, { confirm: true }));
@@ -127,7 +127,7 @@ export function registerServerTools(register, options, schema = z) {
     tool('gripforge_build_rollback', 'Rollback a build', 'Not implemented. Returns 501. Mutating / production-sensitive.', { id: buildId }, { readOnly: false, destructive: true }, (args, extra) => api(`game-builds/${encodeURIComponent(String(args.id))}/rollback`, args, 'POST', extra?.signal));
     tool('gripforge_players_list', 'List connected players', 'Sessions reported by the Unity SDK. Empty until the SDK calls player.joined.', { id: serverId }, { readOnly: true }, (args, extra) => api(`servers/${encodeURIComponent(String(args.id))}/players`, args, 'GET', extra?.signal));
     tool('gripforge_player_get', 'Get a player session', 'Read one player session on a server.', { id: serverId, player_id: playerId }, { readOnly: true }, (args, extra) => api(`servers/${encodeURIComponent(String(args.id))}/players/${encodeURIComponent(String(args.player_id))}`, args, 'GET', extra?.signal));
-    tool('gripforge_player_kick', 'Kick a player', 'Requires the Unity SDK. Currently returns 501. Mutating.', { id: serverId, player_id: playerId }, { readOnly: false }, (args, extra) => api(`servers/${encodeURIComponent(String(args.id))}/players/${encodeURIComponent(String(args.player_id))}/kick`, args, 'POST', extra?.signal));
+    tool('gripforge_player_kick', 'Kick a player', 'Requires the Unity SDK. Currently returns 501. Mutating.', { id: serverId, player_id: playerId }, { readOnly: false, destructive: true }, (args, extra) => api(`servers/${encodeURIComponent(String(args.id))}/players/${encodeURIComponent(String(args.player_id))}/kick`, args, 'POST', extra?.signal));
     tool('gripforge_player_ban', 'Ban a player', 'HIGH IMPACT. Requires the Unity SDK. Currently returns 501. Owner only.', { id: serverId, player_id: playerId }, { readOnly: false, destructive: true }, (args, extra) => api(`servers/${encodeURIComponent(String(args.id))}/players/${encodeURIComponent(String(args.player_id))}/ban`, args, 'POST', extra?.signal));
     tool('gripforge_game_broadcast', 'Broadcast to a match', 'Requires the Unity SDK. Currently returns 501. Never runs a shell on the host.', { id: serverId, message: schema.string().max(500).optional() }, { readOnly: false }, (args, extra) => api(`servers/${encodeURIComponent(String(args.id))}/broadcast`, args, 'POST', extra?.signal));
     tool('gripforge_world_list', 'List worlds', 'Worlds stored for the workspace or a server’s project. Empty until worlds are implemented.', { id: serverId.optional() }, { readOnly: true }, (args, extra) => args.id
@@ -139,5 +139,5 @@ export function registerServerTools(register, options, schema = z) {
     tool('gripforge_match_list', 'List matches', 'Matches recorded for a server (SDK or API).', { id: serverId }, { readOnly: true }, (args, extra) => api(`servers/${encodeURIComponent(String(args.id))}/matches`, args, 'GET', extra?.signal));
     tool('gripforge_match_get', 'Get a match', 'Read one match record.', { id: serverId, match_id: matchId }, { readOnly: true }, (args, extra) => api(`servers/${encodeURIComponent(String(args.id))}/matches/${encodeURIComponent(String(args.match_id))}`, args, 'GET', extra?.signal));
     tool('gripforge_match_create', 'Create a match record', 'Records match.started. Does not spawn a new process. Mutating.', { id: serverId, map: schema.string().max(120).optional() }, { readOnly: false }, (args, extra) => api(`servers/${encodeURIComponent(String(args.id))}/matches`, args, 'POST', extra?.signal));
-    tool('gripforge_match_stop', 'Stop a match', 'Marks the match ended. Mutating.', { id: serverId, match_id: matchId }, { readOnly: false }, (args, extra) => api(`servers/${encodeURIComponent(String(args.id))}/matches/${encodeURIComponent(String(args.match_id))}`, args, 'POST', extra?.signal));
+    tool('gripforge_match_stop', 'Stop a match', 'Marks the match ended. Mutating.', { id: serverId, match_id: matchId }, { readOnly: false, destructive: true }, (args, extra) => api(`servers/${encodeURIComponent(String(args.id))}/matches/${encodeURIComponent(String(args.match_id))}`, args, 'POST', extra?.signal));
 }

package/dist/server.js

@@ -16,7 +16,22 @@ import { registerVfxProjectTools } from './vfx-project-tools.js';
 import { registerSceneTools } from './scene-tools.js';
 import { registerServerTools } from './server-tools.js';
 import { registerGameKitTools } from './gamekit-tools.js';
+import { registerJoystickTools } from './joystick-tools.js';
+import { registerAbilityTools } from './ability-tools.js';
+import { registerAssetProductionTools } from './asset-production-tools.js';
+import { registerCreatureRigTools } from './creature-rig-tools.js';
+import { registerWeaponMotionTools } from './weapon-motion-tools.js';
+import { registerShieldVfxTools } from './shield-vfx-tools.js';
+import { registerProjectileTools } from './projectile-tools.js';
+import { registerArchitectureTools } from './architecture-tools.js';
+import { registerGameConceptTools } from './game-concept-tools.js';
+import { registerMotionTools } from './motion-tools.js';
+import { registerHeroAbilityTools } from './hero-ability-tools.js';
+import { registerGameCreationTools } from './game-creation-tools.js';
 import { registerGameKitLocalTools } from './gamekit-deliver-local.js';
+import { registerMapUnrealLocalTools } from './map-unreal-local.js';
+import { registerMapUnrealImportLocalTools } from './map-unreal-import-local.js';
+import { registerMapUnrealExportLocalTools } from './map-unreal-export-local.js';
 const API_URL = process.env.GRIPFORGE_API_URL ?? 'https://gripforge.ai';
 const API_KEY = process.env.GRIPFORGE_API_KEY;
 const MCP_SELF = '0.1.9';
@@ -27,6 +42,21 @@ registerSceneTools(server.registerTool.bind(server), { apiUrl: API_URL, getApiKe
 registerServerTools(server.registerTool.bind(server), { apiUrl: API_URL, getApiKey: () => API_KEY });
 registerGameKitTools(server.registerTool.bind(server), { apiUrl: API_URL, getApiKey: () => API_KEY });
 registerGameKitLocalTools(server.registerTool.bind(server), { apiUrl: API_URL, getApiKey: () => API_KEY, userAgent: `gripforge-mcp/${MCP_SELF}` });
+registerMapUnrealLocalTools(server.registerTool.bind(server));
+registerMapUnrealImportLocalTools(server.registerTool.bind(server));
+registerMapUnrealExportLocalTools(server.registerTool.bind(server), { apiUrl: API_URL, getApiKey: () => API_KEY });
+registerJoystickTools(server.registerTool.bind(server));
+registerAbilityTools(server.registerTool.bind(server), { apiUrl: API_URL, getApiKey: () => API_KEY });
+registerCreatureRigTools(server.registerTool.bind(server), { apiUrl: API_URL, getApiKey: () => API_KEY });
+registerWeaponMotionTools(server.registerTool.bind(server), { apiUrl: API_URL, getApiKey: () => API_KEY });
+registerShieldVfxTools(server.registerTool.bind(server), { apiUrl: API_URL, getApiKey: () => API_KEY });
+registerProjectileTools(server.registerTool.bind(server), { apiUrl: API_URL, getApiKey: () => API_KEY });
+registerArchitectureTools(server.registerTool.bind(server), { apiUrl: API_URL, getApiKey: () => API_KEY });
+registerGameConceptTools(server.registerTool.bind(server), { apiUrl: API_URL, getApiKey: () => API_KEY });
+registerMotionTools(server.registerTool.bind(server), { apiUrl: API_URL, getApiKey: () => API_KEY });
+registerHeroAbilityTools(server.registerTool.bind(server), { apiUrl: API_URL, getApiKey: () => API_KEY });
+registerGameCreationTools(server.registerTool.bind(server), { apiUrl: API_URL, getApiKey: () => API_KEY });
+registerAssetProductionTools(server.registerTool.bind(server), { apiUrl: API_URL, getApiKey: () => API_KEY });
 const err = (text) => ({ content: [{ type: 'text', text }], isError: true });
 server.tool('gripforge_attach', 'Attach a prop (sword, shield, gun, staff/scythe…) onto a rigged character. ' +
     'Finds the hand bone across naming schemes, scales to body height, seats the grip, ' +
@@ -37,7 +67,9 @@ server.tool('gripforge_attach', 'Attach a prop (sword, shield, gun, staff/scythe
     'GripForge puts that point in the palm and skips all grip heuristics. ' +
     'Hand closing: rigs WITH finger bones get bind.gripPose rotations (applied by the snippets); ' +
     'rigs WITHOUT finger bones (mitten hands) need export_glb: true + out_dir to receive ' +
-    'attached.glb with the fist baked in — the JSON bind alone cannot close a mitten hand.', {
+    'attached.glb with the fist baked in — the JSON bind alone cannot close a mitten hand. ' +
+    'Attachment confidence is not visual validation. Inspect bind.review and preview the exported GLB ' +
+    'in the target renderer at idle and during attacks; do not call a needs_review result validated.', {
     character_path: z.string().optional().describe('Absolute path to the rigged character (.glb .gltf .fbx .obj)'),
     prop_path: z.string().optional().describe('Absolute path to the prop mesh'),
     character_id: z.string().optional().describe('Library id of a character (lib_…)'),
@@ -218,7 +250,8 @@ server.tool('gripforge_attach', 'Attach a prop (sword, shield, gun, staff/scythe
                     JSON.stringify({ bind: data.bind, confidence: data.confidence, exports: exportsObj, wrote, glbFile, library }, null, 2) +
                     (credits ? `\ncredits: ${credits.remaining}/${credits.limit} remaining (${credits.plan})` : '') +
                     (glbNotes.length ? `\nglb notes:\n- ${glbNotes.join('\n- ')}` : '') +
-                    mittenHint,
+                    mittenHint +
+                    '\nVisual review required: verify palm contact, wrist continuity and weapon/body clearance in the target renderer. Bone parenting alone does not validate the grip.',
             },
         ],
     };
@@ -450,6 +483,7 @@ server.tool('gripforge_generate_character', 'CREATE a Mixamo T-pose auto-rigged
     'Without an image, this is text-to-3D only. ' +
     'If the look may already be in the locker, call gripforge_style_kit FIRST. ' +
     'For knives/guns use gripforge_generate_weapon. Costs 10 credits. Returns job_id immediately; poll gripforge_generation_read. Closing this call does not cancel it.', {
+    idempotency_key: z.string().regex(/^[a-zA-Z0-9_.:-]{8,160}$/).optional().describe('Stable asset request key; reuse after an uncertain response.'),
     prompt: z.string().min(3).max(600).describe('Description. "Devil May Cry like enemy" → tagged devil-may-cry, kind=enemy.'),
     provider: z.enum(['tripo', 'meshy']).optional().describe('Default tripo. Forced meshy when concept_item / path / file_url is set.'),
     name: z.string().max(160).optional().describe('Library item name (default: the prompt)'),
@@ -460,7 +494,7 @@ server.tool('gripforge_generate_character', 'CREATE a Mixamo T-pose auto-rigged
     path: z.string().optional().describe('Absolute path to a local concept or T-pose image (PNG/JPG/WebP). Image-to-3D.'),
     file_url: z.string().optional().describe('https URL of a concept or T-pose image. Image-to-3D.'),
     out_dir: z.string().optional().describe('After the job completes, gripforge_library_pull into this folder.'),
-}, async ({ prompt, provider, name, kind, polycount, underwear, concept_item, path, file_url, out_dir }) => {
+}, async ({ idempotency_key, prompt, provider, name, kind, polycount, underwear, concept_item, path, file_url, out_dir }) => {
     if (!API_KEY)
         return err('GRIPFORGE_API_KEY missing.');
     let image_base64;
@@ -488,6 +522,7 @@ server.tool('gripforge_generate_character', 'CREATE a Mixamo T-pose auto-rigged
         method: 'POST',
         headers: { ...apiHeaders(), 'content-type': 'application/json' },
         body: JSON.stringify({
+            idempotency_key,
             prompt,
             provider: image_base64 || concept_item ? 'meshy' : provider,
             name,
@@ -517,19 +552,21 @@ server.tool('gripforge_generate_character', 'CREATE a Mixamo T-pose auto-rigged
 server.tool('gripforge_generate_weapon', 'CREATE a game-ready weapon GLB (knife, gun, sword) and save it to Library as kind=weapon. ' +
     'Default Meshy, no T-pose, no rig. polycount default 4000. style=melee|gun for attach. 10 credits. ' +
     'Do NOT write one-off Meshy scripts.', {
+    idempotency_key: z.string().regex(/^[a-zA-Z0-9_.:-]{8,160}$/).optional().describe('Stable asset request key; reuse after an uncertain response.'),
     prompt: z.string().min(3).max(600).describe('e.g. CS2 default CT combat knife, silver blade, black grip'),
     name: z.string().max(160).optional(),
     polycount: z.number().optional().describe('Target triangles (default 4000)'),
     style: z.enum(['melee', 'gun', 'shield', 'staff']).optional().describe('Grip style for attach (inferred if omitted)'),
     provider: z.enum(['meshy', 'tripo']).optional().describe('Default meshy'),
     out_dir: z.string().optional().describe('After the durable job completes, use gripforge_library_pull with this out_dir.'),
-}, async ({ prompt, name, polycount, style, provider, out_dir }) => {
+}, async ({ idempotency_key, prompt, name, polycount, style, provider, out_dir }) => {
     if (!API_KEY)
         return err('GRIPFORGE_API_KEY missing.');
     const res = await fetch(`${API_URL}/api/v1/generate-character`, {
         method: 'POST',
         headers: { ...apiHeaders(), 'content-type': 'application/json' },
         body: JSON.stringify({
+            idempotency_key,
             prompt,
             name,
             kind: 'weapon',
@@ -554,24 +591,32 @@ server.tool('gripforge_generate_weapon', 'CREATE a game-ready weapon GLB (knife,
     }
     return { content: [{ type: 'text', text: JSON.stringify({ ...data, wrote, ...(out_dir && !wrote.length ? { next: 'Poll gripforge_generation_read, then gripforge_library_pull with the completed asset id and this out_dir.', requested_out_dir: out_dir } : {}) }, null, 2) }] };
 });
-server.tool('gripforge_generate_prop', 'CREATE a game-ready prop GLB (kart, crate, banana, barrier…) and save it to Library as kind=prop. Default Meshy, no T-pose, no rig. polycount default 4000. 10 credits. Returns a durable job_id; poll gripforge_generation_read.', {
+server.tool('gripforge_generate_prop', 'CREATE a game-ready prop GLB (kart, crate, banana, barrier…) and save it to Library as kind=prop. Default Meshy, no T-pose, no rig. polycount default 4000. Quoted against the shared subscription, or 10 GripForge credits if it cannot cover the complete operation. Returns a durable job_id; poll gripforge_generation_read.', {
+    idempotency_key: z.string().regex(/^[a-zA-Z0-9_.:-]{8,160}$/).optional().describe('Stable asset request key; reuse after an uncertain response.'),
     prompt: z.string().min(3).max(600).describe('e.g. compact orange open-cockpit racing kart, isolated'),
     name: z.string().max(160).optional(),
     polycount: z.number().optional().describe('Target triangles (default 4000)'),
     provider: z.enum(['meshy', 'tripo']).optional().describe('Default meshy'),
+    concept_item: z.string().min(1).max(160).optional().describe('Owned concept image in this workspace; forces Meshy image-to-3D.'),
+    concept_items: z.array(z.string().min(1).max(160)).min(2).max(4).optional().describe('2–4 distinct owned views of the SAME prop for Meshy multi-image-to-3D. Do not combine with concept_item. Geometry standard/2k only.'),
+    meshQuality: z.object({ geometry: z.enum(['standard', '2k', '4k']), texture: z.enum(['2k', '4k', '8k']) }).optional().describe('Meshy geometry and PBR texture quality. Requested texture resolution is retained through optimization.'),
+    optimize: z.boolean().optional().describe('Default true; false retains the provider mesh for close-up review.'),
     out_dir: z.string().optional().describe('After the durable job completes, use gripforge_library_pull with this out_dir.'),
-}, async ({ prompt, name, polycount, provider, out_dir }) => {
+    subtype: z.enum(['vehicle', 'none']).optional().describe('vehicle: made as the Vehicles prop sub-kind — no grip style, nose on +Z, the four wheels split with hub pivots so it drives. Then finished like a game car: paint, glass, chrome, grille and lamp materials, smoothed body, modelled wheels. Detected from the prompt (car, truck, van, kart…) when omitted; none opts out.'),
+}, async ({ idempotency_key, prompt, name, polycount, provider, concept_item, concept_items, meshQuality, optimize, out_dir, subtype }) => {
     if (!API_KEY)
         return err('GRIPFORGE_API_KEY missing.');
     const res = await fetch(`${API_URL}/api/v1/generate-character`, {
         method: 'POST',
         headers: { ...apiHeaders(), 'content-type': 'application/json' },
         body: JSON.stringify({
+            idempotency_key,
             prompt,
             name,
             kind: 'prop',
+            subtype,
             polycount: polycount ?? 4000,
-            provider: provider ?? 'meshy',
+            provider: provider ?? 'meshy', concept_item, concept_items, meshQuality, optimize,
         }),
     });
     const data = (await res.json().catch(() => ({})));
@@ -829,11 +874,13 @@ server.tool('gripforge_concept_correct', 'Turn a character concept image into a
         return err(String(data.error ?? res.status));
     return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
 });
-server.tool('gripforge_library_list', 'List the GripForge Library locker (characters, enemies, weapons, props, textures, HUD, buttons, binds). Filter by kind and/or game style.', {
+server.tool('gripforge_library_list', 'List the GripForge Library locker (characters, enemies, weapons, props, textures, HUD, buttons, binds). Filter by kind and/or game style. Every item carries `rank` {score/100, grade A–D, reasons}: fitness for a GripForge game; sort=rank lists the best fit first.', {
     kind: KIND.optional().describe('Filter by kind'),
     q: z.string().optional().describe('Search name/filename'),
     style: z.string().optional().describe('Game look (devil-may-cry, dmc, genshin)'),
-}, async ({ kind, q, style }) => {
+    sort: z.enum(['newest', 'rank']).optional().describe('newest (default) or rank: best fit first'),
+    target: z.enum(['mobile', 'desktop']).optional().describe('Platform for the rank budgets. Defaults to mobile.'),
+}, async ({ kind, q, style, sort, target }) => {
     if (!API_KEY)
         return err('GRIPFORGE_API_KEY missing.');
     const qs = new URLSearchParams();
@@ -843,12 +890,34 @@ server.tool('gripforge_library_list', 'List the GripForge Library locker (charac
         qs.set('q', q);
     if (style)
         qs.set('style', style);
+    if (sort === 'rank')
+        qs.set('sort', 'rank');
+    if (target)
+        qs.set('target', target);
     const res = await fetch(`${API_URL}/api/v1/library?${qs}`, { headers: apiHeaders() });
     const data = await res.json().catch(() => ({}));
     if (!res.ok)
         return err(String(data.error ?? res.status));
     return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
 });
+server.tool('gripforge_library_optimize', 'Derive a lighter version of a static model (prop, weapon, equipment, vehicle) for a target: decimated to `triangles`, textures bounded to `texture` px, saved as a NEW Library item linked to its master (meta.lod_of). The master is never changed — generate high once, derive mobile/desktop versions. Wheel pivots and nodes are kept. 0 credits.', {
+    id: z.string().describe('Library id of the master model (lib_…)'),
+    triangles: z.number().int().min(500).max(200000).describe('Target triangles, e.g. 12000 for a mobile car, 40000 desktop'),
+    texture: z.union([z.literal(512), z.literal(1024), z.literal(2048), z.literal(4096)]).optional().describe('Max texture size in px (default 2048)'),
+    name: z.string().max(160).optional(),
+}, async ({ id, triangles, texture, name }) => {
+    if (!API_KEY)
+        return err('GRIPFORGE_API_KEY missing.');
+    const res = await fetch(`${API_URL}/api/v1/library/${encodeURIComponent(id)}/optimize`, {
+        method: 'POST',
+        headers: { ...apiHeaders(), 'content-type': 'application/json' },
+        body: JSON.stringify({ triangles, texture, name }),
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok)
+        return err(String(data.error ?? res.status));
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
 server.tool('gripforge_library_get', 'Get one Library item (metadata + signed file URL).', { id: z.string().describe('Library id (lib_…)') }, async ({ id }) => {
     if (!API_KEY)
         return err('GRIPFORGE_API_KEY missing.');
@@ -1110,7 +1179,7 @@ server.tool('gripforge_audio_kit', 'Search locker + Community SFX by description
         hits,
         wrote: [],
         hint: wanted
-            ? 'Pick by description/use. Locker ids: gripforge_library_pull. Community ids: clone first (1 credit), then pull.'
+            ? 'Pick by description/use. Locker ids: gripforge_library_pull. Community ids: clone first (free unless the creator sets a price in credits), then pull.'
             : 'Pass prompt to filter. Descriptions are on each hit.',
     };
     if (out_dir) {
@@ -1343,16 +1412,73 @@ server.tool('gripforge_hitbox', 'Body capsules + weapons[] (one per gf_prop_ wra
         return err(String(data.error ?? res.status));
     return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
 });
-server.tool('gripforge_vehicle_wheels', 'Split the 4 wheels out of a fused kart/car GLB so they can spin: Wheel_FL/FR/RL/RR nodes, hub pivots, extras gf_wheel {radius, axle, spin}. Geometric cut (cylinder + plane, seam invariant under rotation, capped). Run gripforge_vehicle_orient first. 0 credits. apply=false → analysis only.', {
+server.tool('gripforge_vehicle_wheels', 'Split the 4 wheels out of a fused kart/car GLB so they can spin: Wheel_FL/FR/RL/RR nodes, hub pivots, extras gf_wheel {radius, radiusMeters, axle, spin}. Geometric cut (cylinder + plane, seam invariant under rotation, capped). normalize=true also puts the nose on +Z, the real size in metres and the wheels on y = 0 (works on a vehicle already split). 0 credits. apply=false → analysis only.', {
     id: z.string().describe('Library id of the vehicle GLB (lib_…)'),
     apply: z.boolean().optional().describe('default true — rewrite the Library file with the split wheels'),
-}, async ({ id, apply }) => {
+    normalize: z.boolean().optional().describe('nose on +Z, metres, wheels on the ground'),
+    reverse: z.boolean().optional().describe('the nose came out backwards: turn the vehicle 180° (with normalize)'),
+    length_m: z.number().min(0.5).max(25).optional().describe('bumper-to-bumper length in metres; default: typical for the vehicle named (car 4.4, SUV 4.7, pickup 5.8, van 5.5, kart 1.8…)'),
+}, async ({ id, apply, normalize, length_m, reverse }) => {
     if (!API_KEY)
         return err('GRIPFORGE_API_KEY missing.');
     const res = await fetch(`${API_URL}/api/v1/vehicle-wheels`, {
         method: 'POST',
         headers: { ...apiHeaders(), 'content-type': 'application/json' },
-        body: JSON.stringify({ id, apply }),
+        body: JSON.stringify({ id, apply, normalize, length_m, reverse }),
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok)
+        return err(String(data.error ?? res.status));
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+server.tool('gripforge_vehicle_finish', 'Repair generated automotive surfaces. Preferred: source (immutable static GLB with Body/Wheel_* groups) + repair recipe queues a persistent Blender job; guided glazing/panel regions, paint cleanup, coloured caliper extraction, measured replacement panels/curves with PBR and fitted boundaries, optional rebuilt wheels and rigid wheel rig. features.marks adds surface-fitted pinned PNG logos, relief badges and mesh lettering; wheel markings follow their wheel, named authored marks are replaced in the new work copy. For grilles or trim on a reconstructed recess, set curves.fitSurface.panel to its non-structural panel name to follow the final part. Returns a NEW private work version with GLB/Blend/optional FBX and GripForge review link. Does not promote or overwrite the source. Regions use +Y up/+Z forward metres, bounded displacement; region-only glass stays opaque, authored transmissive panes need an authored cabin. Poll/cancel/retry generation-jobs. 0 provider credits. Legacy id without repair uses one-time material/wheel finish and rewrites its Library file.', {
+    id: z.string().optional().describe('Library id; with repair pins source, without repair uses legacy finish'),
+    source: z.object({ assetId: z.string(), revisionId: z.string(), fileRole: z.string().optional() }).optional().describe('Pinned static source, instead of id'),
+    repair: z.object({
+        regions: z.array(z.object({ name: z.string(), bounds: z.tuple([z.tuple([z.number(), z.number(), z.number()]), z.tuple([z.number(), z.number(), z.number()])]), select: z.enum(['neutral', 'paint', 'all']), surface: z.enum(['glass', 'paint']), fitAxis: z.enum(['x', 'y', 'z']), maxOffsetM: z.number().min(0).max(.05).optional() })).max(16),
+        denoise: z.object({ iterations: z.number().int().min(1).max(80).optional(), maxOffsetM: z.number().min(0).max(.05).optional(), normalIterations: z.number().int().min(0).max(30).optional() }).optional().describe('Bounded Body smoothing across UV seams; pins open boundaries, retains UVs and wheel/caliper transforms; review small details'),
+        cleanPaint: z.boolean().optional(), paintColor: z.tuple([z.number(), z.number(), z.number()]).optional(),
+        calipers: z.object({ color: z.tuple([z.number(), z.number(), z.number()]), tolerance: z.number().min(.05).max(.4).optional() }).optional(),
+        features: z.object({
+            replaceBody: z.boolean().optional().describe('Explicitly replace coachwork in a new work copy using structural panels; preserve wheels and Body calipers.'),
+            panels: z.array(z.object({
+                name: z.string(), points: z.array(z.array(z.tuple([z.number(), z.number(), z.number()])).min(2).max(12)).min(2).max(12),
+                structural: z.boolean().optional().describe('New coachwork shell, required with replaceBody; cannot fit or clip the discarded source.'),
+                normal: z.tuple([z.number(), z.number(), z.number()]).optional(),
+                segmentsU: z.number().int().min(4).max(96).optional(), segmentsV: z.number().int().min(4).max(96).optional(),
+                mirrorX: z.boolean().optional(), material: z.object({ color: z.tuple([z.number(), z.number(), z.number()]).optional(), metallic: z.number().min(0).max(1).optional(), roughness: z.number().min(.02).max(1).optional(), coat: z.number().min(0).max(1).optional(), transmission: z.number().min(0).max(1).optional(), ior: z.number().min(1).max(2.5).optional(), emission: z.number().min(0).max(10).optional() }).optional(),
+                replace: z.object({ axis: z.enum(['x', 'y', 'z']), depthM: z.number().min(.001).max(.5).optional() }).optional(),
+                fitBoundary: z.object({ axis: z.enum(['x', 'y', 'z']), direction: z.union([z.literal(1), z.literal(-1)]).optional(), offsetM: z.number().min(0).max(.01).optional(), fullSurface: z.boolean().optional() }).optional(), sealRadiusM: z.number().min(.0005).max(.03).optional(),
+            })).max(32).optional(),
+            curves: z.array(z.object({
+                name: z.string(), points: z.array(z.tuple([z.number(), z.number(), z.number()])).min(2).max(128),
+                fitSurface: z.object({ axis: z.enum(['x', 'y', 'z']), direction: z.union([z.literal(1), z.literal(-1)]).optional(), offsetM: z.number().min(0).max(.01).optional(), panel: z.string().trim().min(1).max(80).optional() }).optional(),
+                radiusM: z.number().min(.0005).max(.08).optional(), closed: z.boolean().optional(), mirrorX: z.boolean().optional(),
+                material: z.object({ color: z.tuple([z.number(), z.number(), z.number()]).optional(), metallic: z.number().min(0).max(1).optional(), roughness: z.number().min(.02).max(1).optional(), coat: z.number().min(0).max(1).optional(), transmission: z.number().min(0).max(1).optional(), ior: z.number().min(1).max(2.5).optional(), emission: z.number().min(0).max(10).optional() }).optional(),
+            })).max(256).optional(),
+            marks: z.array(z.object({
+                name: z.string().min(1).max(80), kind: z.enum(['decal', 'badge', 'text']), target: z.enum(['Body', 'Wheel_FL', 'Wheel_FR', 'Wheel_RL', 'Wheel_RR']).optional(),
+                receiver: z.string().trim().min(1).max(120).optional(), position: z.tuple([z.number(), z.number(), z.number()]), normal: z.tuple([z.number(), z.number(), z.number()]), up: z.tuple([z.number(), z.number(), z.number()]),
+                widthM: z.number().min(.005).max(.8), heightM: z.number().min(.005).max(.8), offsetM: z.number().min(.0002).max(.01).optional(), depthM: z.number().min(0).max(.01).optional(), maxDistanceM: z.number().min(.001).max(.12).optional(), segments: z.number().int().min(4).max(32).optional(), mirrorX: z.boolean().optional(),
+                outline: z.array(z.tuple([z.number().min(-.5).max(.5), z.number().min(-.5).max(.5)])).min(3).max(64).optional(),
+                artwork: z.object({ assetId: z.string(), revisionId: z.string(), fileRole: z.string().optional() }).optional(), text: z.string().min(1).max(48).optional(),
+                material: z.object({ color: z.tuple([z.number(), z.number(), z.number()]).optional(), metallic: z.number().min(0).max(1).optional(), roughness: z.number().min(.02).max(1).optional(), coat: z.number().min(0).max(1).optional(), transmission: z.number().min(0).max(1).optional(), ior: z.number().min(1).max(2.5).optional(), emission: z.number().min(0).max(10).optional() }).optional(),
+            })).max(32).optional().describe('Surface-fitted logos and relief: decals require pinned PNG artwork; badges add thickness and a convex outline; text makes mesh lettering. Explicit normal/up frame; target wheel marks spin with that wheel. Optional receiver scopes fitting to a mesh in the target. PNGs <=1 MiB/2048px, max 16 distinct sources. No URLs or local paths.'),
+        }).optional().describe('Measured panels, curves, badges and decals; explicit PBR, clipping, symmetry, 250k vertex budget.'),
+        rig: z.object({ wheelRadius: z.number(), wheelWidth: z.number() }).optional(),
+        wheelRebuild: z.object({ radiusM: z.number().min(.1).max(1.5), widthM: z.number().min(.05).max(.8), spokes: z.number().int().min(3).max(12).optional(), segments: z.number().int().min(24).max(128).optional(), trackM: z.number().min(.3).max(6).optional() }).optional().describe('Replace generated wheel meshes with measured tyres, dished spokes and brake rotors. Optional trackM adjusts axle track and matching explicit Body calipers together; omitted preserves wheel pivots.'),
+    }).optional().describe('Guided surface repair; never edits the source'),
+    name: z.string().optional(), idempotency_key: z.string().min(8).max(160).optional(),
+    smooth: z.number().int().min(0).max(60).optional().describe('body smoothing passes (default 15, 0 = none)'),
+    wheels: z.boolean().optional().describe('false keeps the generated wheels'),
+    segments: z.number().int().min(12).max(128).optional().describe('wheel roundness: 64 default, 24 for mobile'),
+}, async (args) => {
+    if (!API_KEY)
+        return err('GRIPFORGE_API_KEY missing.');
+    const res = await fetch(`${API_URL}/api/v1/vehicle-finish`, {
+        method: 'POST',
+        headers: { ...apiHeaders(), 'content-type': 'application/json' },
+        body: JSON.stringify(args),
     });
     const data = await res.json().catch(() => ({}));
     if (!res.ok)

package/dist/shield-vfx-tools.js

@@ -0,0 +1,29 @@
+import { z } from 'zod/v4';
+const styles = ['fire', 'water', 'water-petal', 'blood', 'cat', 'cosmic', 'cyber', 'cyber-grid', 'holy', 'ice', 'ink', 'light', 'lightning', 'poison', 'rock', 'void', 'wind'];
+export const SHIELD_VFX_TOOL_NAMES = ['gripforge_shield_vfx', 'gripforge_shield_export'];
+export function registerShieldVfxTools(register, options, s = z) {
+    const config = s.object({ version: s.literal(1).optional(), style: s.enum(styles).optional(), radius: s.number().min(.15).max(5).optional(), stretch: s.tuple([s.number().min(.25).max(2), s.number().min(.25).max(2), s.number().min(.25).max(2)]).optional(), color: s.string().regex(/^#[a-f\d]{6}$/i).optional(), accent: s.string().regex(/^#[a-f\d]{6}$/i).optional(), intensity: s.number().min(.1).max(3).optional(), opacity: s.number().min(0).max(1).optional(), speed: s.number().min(.1).max(4).optional(), seed: s.number().int().min(0).max(65535).optional(), quality: s.enum(['low', 'high']).optional() }).strict();
+    const common = { workspace_id: s.string().max(100).optional(), config: config.optional() };
+    const definitions = [{ name: SHIELD_VFX_TOOL_NAMES[0], shape: { ...common, save: s.boolean().optional(), idempotency_key: s.string().min(8).max(160).optional() }, description: 'ADMIN ONLY. Create an original editable 3D elemental shield using the shared shield-vfx module: 17 styles, radius/stretch, colours, intensity, quality and seed. Same shaders used in Studio and native exports. save=true by default queues persistent rendering/review/workspace save; poll generation_read for Studio URL. save=false returns an unsaved project. No commercial reference assets, collision or damage. Recipe compilation needs no AI; saving uses the normal VFX review pipeline. Work is not visually validated automatically.' },
+        { name: SHIELD_VFX_TOOL_NAMES[1], shape: { ...common, engine: s.enum(['threejs', 'godot', 'unity', 'unreal']) }, description: 'ADMIN ONLY. Compile a shield recipe into reusable native source files for Three.js, Godot 4, Unity or Unreal 5, using the same geometry and shader functions. Returns files keyed by relative path plus install instructions. Write ALL files into a dedicated directory; never overwrite an existing modified package without checking. Includes enable/hit/shatter runtime; no mannequin or preview environment. Native builds require target-engine verification; source export is not visual certification.' }];
+    for (const d of definitions)
+        register(d.name, { title: d.name, description: d.description, inputSchema: d.shape, annotations: { readOnlyHint: d.name.endsWith('export'), destructiveHint: false, idempotentHint: d.name.endsWith('export'), 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 r = await fetch(options.apiUrl.replace(/\/$/, '') + '/api/v1/vfx/shields', { method: 'POST', headers: { 'content-type': 'application/json', 'x-api-key': key, ...(workspace_id ? { 'x-workspace-id': String(workspace_id) } : {}) }, body: JSON.stringify({ ...body, action: d.name.endsWith('export') ? 'export' : body.save === false ? 'preview' : 'create' }), signal: AbortSignal.any([AbortSignal.timeout(90000), ...(extra?.signal ? [extra.signal] : [])]) });
+                const data = await r.json();
+                if (data.studio_url?.startsWith('/'))
+                    data.studio_url = new URL(data.studio_url, options.apiUrl).href;
+                return { ...(!r.ok ? { isError: true } : {}), structuredContent: data, content: [{ type: 'text', text: JSON.stringify(data) }] };
+            }
+            catch (e) {
+                return { isError: true, content: [{ type: 'text', text: e.message }] };
+            }
+        });
+}