@gripforgeai/mcp 0.1.15 → 0.1.17

package/dist/gamekit-tools.js

@@ -1,5 +1,6 @@
 /** Modular Game Kits tools. Studio and MCP call the same Core HTTP API. */
 import { z } from 'zod/v4';
+import { LOOK_VALUES, LOOK_DESCRIPTION } from './look.js';
 export const GAMEKIT_TOOL_NAMES = [
     'gripforge_gamekit_search',
     'gripforge_gamekit_get',
@@ -12,16 +13,46 @@ export const GAMEKIT_TOOL_NAMES = [
     'gripforge_gamekit_deliver',
     'gripforge_game_capabilities',
     'gripforge_game_project',
+    'gripforge_game_art_direction',
+    'gripforge_game_asset_plan',
+    'gripforge_gamekit_creatures',
     'gripforge_game_engine',
     'gripforge_game_content',
     'gripforge_game_play_url',
     'gripforge_game_test',
+    'gripforge_game_audit',
     'gripforge_game_web_export',
     'gripforge_moba_roster',
     'gripforge_ability_vfx',
     'gripforge_moba_map',
     'gripforge_terrain_map_use',
 ];
+/**
+ * Where each tool stands in the making of a game, appended to its description: when to call it, and the audit it
+ * leads to. One table, so the journey reads the same from every tool — and one place to change it.
+ */
+export const TOOL_JOURNEY = {
+    gripforge_gamekit_search: 'Journey — first: find the preset of the genre. Its `done` says what a finished game of that genre has beyond the request, and gripforge_game_audit checks it at the end.',
+    gripforge_gamekit_installed: 'Journey — first on an existing project; gripforge_game_audit then says what stands between it and a finished game.',
+    gripforge_gamekit_install: 'Journey — while composing. A kit installed and left empty is not done (audio.core without a sound, ui.endscreen without an end condition): gripforge_game_audit names them.',
+    gripforge_gamekit_configure: 'Journey — while composing, and to fix what gripforge_game_audit reports (its defects carry the exact config to write).',
+    gripforge_game_capabilities: 'Journey — while composing; gripforge_game_audit includes this report, with the creatures, the controls, the playtest and the definition of done of the genre.',
+    gripforge_game_project: 'Journey — create, then bind a model to every creature slot (get carries the creatures report) and set the controls: action=controls applies the control scheme of the gameplay, a proposal to adapt. Before telling the user the game is done: gripforge_game_audit.',
+    gripforge_gamekit_creatures: 'Journey — right after creating or binding: no unit stays a capsule, every model gets its movement and action clips. gripforge_game_audit folds this report with the rest and applies the free steps with fix=true.',
+    gripforge_game_engine: 'Journey — the build order of the content; its last step is gripforge_game_audit, not "it loads".',
+    gripforge_game_content: 'Journey — the content of the game. Once written, gripforge_game_audit says what a finished game of the genre still lacks (a quest, a way to win and to lose, dialogues…).',
+    gripforge_game_test: 'Journey — after each change. A playtest that passes is not a finished game: gripforge_game_audit (playtest="run" runs this test) gives the verdict and everything the tester cannot see.',
+    gripforge_game_play_url: 'Journey — to look at the running game. Share it as finished only when gripforge_game_audit says complete; otherwise say what is left.',
+    gripforge_game_web_export: 'Journey — last. Run gripforge_game_audit first: export a game whose verdict is complete, or tell the user what is left.',
+    gripforge_gamekit_deliver: 'Journey — last. Run gripforge_game_audit first: deliver a game whose verdict is complete, or tell the user what is left.',
+    gripforge_moba_roster: 'Journey — a MOBA needs distinct heroes; then gripforge_game_audit for the minions, towers, jungle monsters and the rest of a finished MOBA.',
+    gripforge_ability_vfx: 'Journey — after the roster; gripforge_game_audit lists it among what a finished MOBA has.',
+};
+/** The tool's place in the journey, then its description (whose closing credit rule stays last). */
+function withJourney(name, description) {
+    const journey = TOOL_JOURNEY[name];
+    return journey ? `${journey} ${description}` : description;
+}
 const enc = (v) => encodeURIComponent(String(v));
 const HOSTED_DELIVERY_NOTE = 'This hosted endpoint cannot write into your project: write bundle.files following plan.actions in order, or use npx @gripforgeai/mcp with gripforge_gamekit_deliver_local { project_dir }, or the editor bridge.';
 export function registerGameKitTools(register, options, schema = z) {
@@ -43,7 +74,7 @@ export function registerGameKitTools(register, options, schema = z) {
         .record(schema.string(), schema.unknown())
         .optional()
         .describe('Kit config values, validated against the kit configSchema returned by gripforge_gamekit_get. Merged over the current config.');
-    async function api(path, args, method, signal, query) {
+    async function api(path, args, method, signal, query, timeoutMs = 120_000) {
         const key = options.getApiKey();
         if (!key)
             return { isError: true, content: [{ type: 'text', text: 'GripForge API key required.' }] };
@@ -66,7 +97,7 @@ export function registerGameKitTools(register, options, schema = z) {
                     ...(typeof workspace_id === 'string' ? { 'x-workspace-id': workspace_id } : {}),
                 },
                 ...(method === 'GET' || method === 'DELETE' ? {} : { body: JSON.stringify(body) }),
-                signal: AbortSignal.any([AbortSignal.timeout(120_000), ...(signal ? [signal] : [])]),
+                signal: AbortSignal.any([AbortSignal.timeout(timeoutMs), ...(signal ? [signal] : [])]),
             });
             const data = (await res.json());
             return {
@@ -82,7 +113,7 @@ export function registerGameKitTools(register, options, schema = z) {
     function tool(name, title, description, inputSchema, opts, callback) {
         register(name, {
             title,
-            description,
+            description: withJourney(name, description),
             inputSchema: { ...inputSchema, ...workspace },
             annotations: {
                 readOnlyHint: opts.readOnly,
@@ -251,18 +282,51 @@ export function registerGameKitTools(register, options, schema = z) {
     }, { readOnly: true }, (args, extra) => api(`gamekit-projects/${enc(args.project_id)}/capabilities`, args, 'GET', extra?.signal, {
         goal: typeof args.goal === 'string' ? args.goal : undefined,
     }));
-    tool('gripforge_game_project', 'List, create, read, bind, feed or delete Game Kit projects', 'Manage Game Kit projects (gkp_…): the container holding installed kits, their lockfile, asset bindings and data collections. action=list lists the workspace projects; create needs name and takes a preset (see gripforge_gamekit_search; adventure is the reference game of game.engine) or an explicit kits map — every new project gets game.engine first (the engine of the game: scenes, archetypes, scripts, life cycle; its answer carries the engine start pack { structure, scene, blocks, order, next, rules } and added, the kits installed for dependencies), then the default kits ui.menu (title / pause / options / load and save screen), input.remap (key remapping), settings.graphics (graphics options), ui.prompts (on-screen key prompts that follow remapping and the gamepad), ui.endscreen (end screen and credits), save.persistence (save slots, quick save, autosave), audio.core (game audio: mixer, music, effects, event → sound table), i18n.text (game texts in the player’s language: translation tables in the translations collection, ICU plurals) ui.theme (the design of every interface as kit config: colours, font, shapes, key glyphs; unset = built-in look) and input.virtualpad (the on-screen gamepad of touch screens, mode auto: shown on a touch screen without a gamepad, Touch controls tab), addedBy default: keep and configure them, leave one out ({ "ui.menu": false }) or remove it only if the user asks; get returns the full ProjectDetail (installed kits, bindings, capabilities, missing, playUrl); bind maps asset slots to Library items (lib_…, null to clear); data reads a collection or upserts / removes documents validated against the kits’ schemas (replace=true swaps the whole collection); delete needs confirm=true. Call this first to create or pick the project, then gripforge_gamekit_installed (existing project) or gripforge_gamekit_install. 0 credits.', {
-        action: schema.enum(['list', 'create', 'get', 'bind', 'data', 'delete']).describe('list | create | get | bind | data | delete.'),
-        project_id: projectId.optional().describe('Game Kit project id (gkp_…). Required for get, bind, data and delete.'),
+    tool('gripforge_game_art_direction', 'Read or update the shared art direction of a game', 'Store artistic intent on the existing Game Kit project (game.engine), separately from gameplay: look, world/theme, palette, proportions/materials/lighting notes and device budget. Read first, then set with expected_revision. Unspecified fields are preserved; null clears a field or the profile. Existing assets and rendering are not modified. Use this direction with map wizard.look, VFX look, asset prompts, lighting and UI tools, then inspect gripforge_game_asset_plan and actual-engine captures. 0 credits.', {
+        project_id: projectId,
+        action: schema.enum(['get', 'set']).describe('get reads the profile/revision; set applies a partial profile update.'),
+        expected_revision: schema.number().int().positive().optional().describe('set: revision returned by get; stale changes are refused.'),
+        art_direction: schema.object({
+            look: schema.enum(LOOK_VALUES).nullable().optional().describe(LOOK_DESCRIPTION),
+            theme: schema.string().max(120).nullable().optional(),
+            palette: schema.array(schema.string().regex(/^#[a-f\d]{6}$/i)).max(12).nullable().optional(),
+            notes: schema.string().max(1600).nullable().optional(),
+            device: schema.enum(['mobile', 'desktop']).nullable().optional(),
+        }).strict().nullable().optional().describe('set: shared project art direction patch. Null clears the profile or an individual field.'),
+    }, { readOnly: false }, (args, extra) => {
+        const path = `gamekit-projects/${enc(args.project_id)}/art-direction`;
+        if (args.action === 'get')
+            return api(path, args, 'GET', extra?.signal);
+        if (args.art_direction === undefined || args.expected_revision === undefined)
+            return Promise.resolve(fail('set needs art_direction and expected_revision from get.'));
+        return api(path, { workspace_id: args.workspace_id, artDirection: args.art_direction, expected_revision: args.expected_revision }, 'PATCH', extra?.signal);
+    });
+    tool('gripforge_game_asset_plan', 'Audit project asset roles or search compatible candidates', 'Read asset requirements from enabled Game Kits and game.engine archetypes. Without slot: report missing files/bindings, template defaults, metadata style/theme conflicts, unknown classifications and technical ranking concerns. With slot: search accessible Library/Community candidates for that role and the saved art direction; known visual conflicts are excluded. No purchase, generation or binding. Metadata checks do not replace visual/animation/gameplay review in the actual engine. 0 credits.', {
+        project_id: projectId,
+        slot: schema.string().max(160).optional().describe('Omit for the audit; pass a role id from the audit to search candidates.'),
+        q: schema.string().max(400).optional().describe('Optional candidate search terms for this slot.'),
+        source: schema.enum(['all', 'workspace', 'community']).optional().describe('Search scope; default all accessible assets.'),
+        limit: schema.number().int().min(1).max(48).optional().describe('Maximum candidates, default 12.'),
+    }, { readOnly: true }, (args, extra) => api(`gamekit-projects/${enc(args.project_id)}/assets`, args, 'GET', extra?.signal, {
+        slot: args.slot, q: args.q, source: args.source, limit: args.limit,
+    }));
+    tool('gripforge_game_project', 'List, create, read, bind, feed, set the controls of or delete Game Kit projects', 'Manage Game Kit projects (gkp_…): the container holding installed kits, their lockfile, asset bindings and data collections. action=list lists the workspace projects; create needs name and takes a preset (see gripforge_gamekit_search; adventure is the reference game of game.engine) or an explicit kits map — every new project gets game.engine first (the engine of the game: scenes, archetypes, scripts, life cycle; its answer carries the engine start pack { structure, scene, blocks, order, next, rules } and added, the kits installed for dependencies), then the default kits ui.menu (title / pause / options / load and save screen), input.remap (key remapping), settings.graphics (graphics options), ui.prompts (on-screen key prompts that follow remapping and the gamepad), ui.endscreen (end screen and credits), save.persistence (save slots, quick save, autosave), audio.core (game audio: mixer, music, effects, event → sound table), i18n.text (game texts in the player’s language: translation tables in the translations collection, ICU plurals) ui.theme (the design of every interface as kit config: colours, font, shapes, key glyphs; unset = built-in look) and input.virtualpad (the on-screen gamepad of touch screens, mode auto: shown on a touch screen without a gamepad, Touch controls tab), addedBy default: keep and configure them, leave one out ({ "ui.menu": false }) or remove it only if the user asks; get returns the full ProjectDetail (installed kits, bindings, capabilities, missing, playUrl); bind maps asset slots to Library items (lib_…, null to clear); data reads a collection or upserts / removes documents validated against the kits’ schemas (replace=true swaps the whole collection); controls reads or sets the controls: without scheme it returns the control schemes of the catalogue (fps, third_person, moba_click, top_down, platformer, fighting, vehicle, rts, point_click: movement by keys or by click, what the mouse is for, expected actions and keys, touch layout), the project scheme, the one its kits suggest, every action with its effective key and the keys two actions share in one mode (warnings with a proposed reassignment, never a refusal — also in get → report.controls); with scheme and dry_run=true it returns the diff of keys the scheme would write; with scheme alone it applies it (input.actions overrides marked source: scheme, the touch layout of input.virtualpad, the help bar of ui.prompts). A scheme is a starting proposal: a preset applies its own at creation (create takes controls to pick another one, or none), and any key stays changeable with gripforge_gamekit_configure input.actions { overrides: [{ action, keys, buttons?, disabled? }] } — the action of any kit; those entries always win over the scheme. delete needs confirm=true. Call this first to create or pick the project, then gripforge_gamekit_installed (existing project) or gripforge_gamekit_install. 0 credits.', {
+        action: schema.enum(['list', 'create', 'get', 'bind', 'data', 'controls', 'delete']).describe('list | create | get | bind | data | controls | delete.'),
+        project_id: projectId.optional().describe('Game Kit project id (gkp_…). Required for get, bind, data, controls and delete.'),
         name: schema.string().min(1).max(120).optional().describe('create: project name.'),
         preset: schema.string().max(80).optional().describe('create: preset id whose default kits are installed (gripforge_gamekit_search returns presets).'),
         kits: schema.record(schema.string(), schema.boolean()).optional().describe('create: explicit kit toggles { "vehicle.driveable": true, … } on top of the preset. Unchecking a required kit fails with toggle_requires. The default kits (ui.menu, input.remap, settings.graphics, ui.prompts, ui.endscreen, save.persistence, audio.core, i18n.text, ui.theme, input.virtualpad) are included unless set to false here — only when the user asked for it.'),
         target: schema.enum(['web', 'godot', 'unity', 'unreal']).optional().describe('create: pass the confirmed engine explicitly (Three.js=web). Ask the user to choose Unity / Godot / Unreal Engine / Three.js before creating if unknown. API default web is for compatibility, not an engine choice.'),
-        bindings: schema.record(schema.string(), schema.string().nullable()).optional().describe('bind: { slot: lib_… | null } — Library item per asset slot declared by the installed kits, null clears.'),
+        bindings: schema.record(schema.string(), schema.string().nullable()).optional().describe('bind: { slot: lib_… | null } — Library item per asset slot declared by the installed kits, null clears. A model bound to a creature slot gets its animations by itself as far as that is free (the answer carries the chain in creatures); see gripforge_gamekit_creatures.'),
         collection: schema.string().max(80).optional().describe('data: collection name declared by an installed kit (e.g. missions, npcs, zones).'),
         documents: schema.array(schema.record(schema.string(), schema.unknown())).max(500).optional().describe('data: documents to upsert (each with its id), validated against the kit schema.'),
         remove: schema.array(schema.string().max(120)).max(500).optional().describe('data: document ids to remove.'),
         replace: schema.boolean().optional().describe('data: true to replace the whole collection with documents.'),
+        scheme: schema.string().max(40).optional().describe('controls: the control scheme to show (dry_run) or apply — fps, third_person, moba_click, top_down, platformer, fighting, vehicle, rts, point_click. Omit to read the schemes and the project controls.'),
+        dry_run: schema.boolean().optional().describe('controls: true returns the diff of keys without writing.'),
+        force: schema.boolean().optional().describe('controls: also replace a touch layout or a help bar the game edited (kept by default).'),
+        reset: schema.boolean().optional().describe('controls: also drop the key overrides the game wrote itself (kept by default), so the game ends exactly on the scheme — what a game made before the schemes needs to move to one. Preview with dry_run.'),
+        controls: schema.string().max(40).optional().describe('create: control scheme applied at creation instead of the preset’s own (or of the one the kits suggest); none keeps the kits’ own keys.'),
         confirm: schema.boolean().optional().describe('delete: must be true. The project, its revisions and data are removed.'),
     }, { readOnly: false }, (args, extra) => {
         const action = String(args.action);
@@ -271,13 +335,14 @@ export function registerGameKitTools(register, options, schema = z) {
         if (action === 'create') {
             if (typeof args.name !== 'string' || !args.name.trim())
                 return Promise.resolve(fail('create needs name.'));
-            return api('gamekit-projects', body(args, 'bindings', 'collection', 'documents', 'remove', 'replace'), 'POST', extra?.signal);
+            return api('gamekit-projects', body(args, 'bindings', 'collection', 'documents', 'remove', 'replace', 'scheme', 'dry_run', 'force', 'reset'), 'POST', extra?.signal);
         }
         if (typeof args.project_id !== 'string')
             return Promise.resolve(fail(`${action} needs project_id (gkp_…).`));
         const project = enc(args.project_id);
+        // creatures=1: the answer carries ranked models for every creature slot that would draw a capsule.
         if (action === 'get')
-            return api(`gamekit-projects/${project}`, args, 'GET', extra?.signal);
+            return api(`gamekit-projects/${project}`, args, 'GET', extra?.signal, { creatures: 1 });
         if (action === 'bind') {
             if (!args.bindings || typeof args.bindings !== 'object')
                 return Promise.resolve(fail('bind needs bindings { slot: lib_… | null }.'));
@@ -291,6 +356,18 @@ export function registerGameKitTools(register, options, schema = z) {
                 return api(`gamekit-projects/${project}/data`, args, 'GET', extra?.signal, { collection: args.collection });
             return api(`gamekit-projects/${project}/data`, { workspace_id: args.workspace_id, collection: args.collection, upsert: args.documents, remove: args.remove, replace: args.replace }, 'PATCH', extra?.signal);
         }
+        if (action === 'controls') {
+            if (typeof args.scheme === 'string' && args.scheme) {
+                return api(`gamekit-projects/${project}/controls`, { workspace_id: args.workspace_id, scheme: args.scheme, dry_run: args.dry_run, force: args.force, reset: args.reset }, 'POST', extra?.signal);
+            }
+            return (async () => {
+                const [schemes, current] = await Promise.all([api('gamekits/control-schemes', args, 'GET', extra?.signal), api(`gamekit-projects/${project}/controls`, args, 'GET', extra?.signal)]);
+                if (current.isError)
+                    return current;
+                const data = { ...current.structuredContent, schemes: schemes.structuredContent?.schemes ?? [] };
+                return { structuredContent: data, content: [{ type: 'text', text: JSON.stringify(data) }] };
+            })();
+        }
         if (action === 'delete') {
             if (args.confirm !== true)
                 return Promise.resolve(fail('delete needs confirm=true.'));
@@ -298,6 +375,22 @@ export function registerGameKitTools(register, options, schema = z) {
         }
         return Promise.resolve(fail(`Unknown action ${action}.`));
     });
+    tool('gripforge_gamekit_creatures', 'Creatures of a project: a model and its animations for every unit', 'The living units of a Game Kit project (gkp_…) — player, heroes, enemies, bosses, minions, monsters, NPCs: the creature slots its kits declare. Two rules: NO creature ships as a capsule, and a model ships WITH its animations (movement AND action). action=report (default): every creature slot with its status (bound | fallback = a capsule in game), the model bound, the clips the slot plays (locomotion, action), the ones the model lacks, and its chain (steps: clone | rig | animate | more_clips, each done / running / proposed with its tool, free or its credits). action=propose: ranked Library models for each unbound slot — the workspace first, then the Community — with the reasons of the rank (source, slot and role words, game theme, size, rigged, animated, triangle budget). YOU judge: read the reasons, pick the model that fits the game (any monster beats a capsule), bind it with gripforge_game_project { action: "bind" }; nothing is final, rebind any time. A slot with no proposal at all carries defect creature_no_model: generate a model (paid — quote and ask first), never leave the capsule. action=animate: run the free steps of the chain now for the bound models (a free Community model is copied into the workspace and bound in place of the original; the standard clip pack is retargeted, 0 credits; wait=true waits for the result, else it runs in the background — read report again). action=fill: bind the best free proposal to every unbound creature slot, then animate (what the hosted creation does). Nothing here spends credits: the automatic rig, a priced Community asset and generated motions always come back as proposed steps for you to quote and ask about. Binding a model through gripforge_game_project already starts its chain. 0 credits.', {
+        project_id: projectId,
+        action: schema.enum(['report', 'propose', 'animate', 'fill']).optional().describe('report (default) | propose | animate | fill.'),
+        slot: schema.string().max(80).optional().describe('report / propose: only this creature slot (e.g. enemy_grunt, moba_hero_3).'),
+        slots: schema.array(schema.string().max(120)).max(64).optional().describe('animate: only these slots (slot or slot:variant). Default: every bound creature slot.'),
+        limit: schema.number().int().min(1).max(12).optional().describe('propose: models per slot (default 5).'),
+        wait: schema.boolean().optional().describe('animate / fill: wait for the retargets instead of running them in the background.'),
+        brief: schema.string().max(2000).optional().describe('fill: what the game is about, to rank the models (theme, mood).'),
+    }, { readOnly: false }, (args, extra) => {
+        const action = typeof args.action === 'string' ? args.action : 'report';
+        const path = `gamekit-projects/${enc(args.project_id)}/creatures`;
+        if (action === 'report' || action === 'propose') {
+            return api(path, args, 'GET', extra?.signal, { propose: action === 'propose' ? 1 : undefined, slot: typeof args.slot === 'string' ? args.slot : undefined, limit: typeof args.limit === 'number' ? args.limit : undefined });
+        }
+        return api(path, { workspace_id: args.workspace_id, action, slots: args.slots, wait: args.wait, brief: args.brief }, 'POST', extra?.signal);
+    });
     tool('gripforge_game_engine', 'The engine of a game: structure, bricks, report, next steps', 'Read game.engine of a Game Kit project (gkp_…) — a direction, never a gate. action=start (default): the start pack { version, active, structure { engine, kits, content counts, code }, scene, blocks digest, order (scene → playable → assets → archetypes → story → scripts → ui → validate → deliver → code), next [{ step, tool, args, why }], code (where game code goes per engine), rules } and the full content report. action=blocks: the brick catalogue computed from the manifests — entity kinds, archetype components (kit, schema, example), script verbs (conditions / actions with arguments and shorthand), script sugars (interact, enter, leave, scene, talked, quest, state, gives), quest step types, NPC behaviours, worlds, layers, events, variables; scope=catalog adds the bricks of kits not installed (install <kit>). action=report: { ok, errors, warnings, stats } — an error means that piece is left out of the game (the rest plays), a warning that it loads with something missing; each issue may carry a fix { tool, args }. action=next: the next steps only. A game with everything in code is valid: content first, kits second, code for the rest. 0 credits.', {
         project_id: projectId,
         action: schema.enum(['start', 'structure', 'blocks', 'report', 'next']).optional().describe('start (default) | structure | blocks | report | next.'),
@@ -367,6 +460,14 @@ export function registerGameKitTools(register, options, schema = z) {
         replay: schema.record(schema.string(), schema.unknown()).optional().describe('report.replay of an earlier run: plays the same inputs again (seed and budget come from it).'),
         lang: schema.enum(['en', 'fr']).optional().describe('Language of text (default en).'),
     }, { readOnly: true }, (args, extra) => api(`gamekit-projects/${enc(args.project_id)}/playtest`, body(args), 'POST', extra?.signal));
+    tool('gripforge_game_audit', 'Audit a game: what is left before it is finished', 'One report of everything that stands between a Game Kit project (gkp_…) and a FINISHED game of its genre — run it before telling the user a game is done, and again after each round of fixes. It aggregates, by severity (blocker / major / minor): creatures (slots drawn as a capsule, models without a skeleton, missing movement or action clips, the animation chain in progress), controls (no control scheme, the suggested one, keys shared by two actions in one mode, playable actions without a key), content (missing capabilities, required slots, the game.engine report), the last headless playtest (failures, warnings, the keys / models / animations probes, capabilities no probe covers) and completeness: what a finished game of the genre has beyond the literal request (MOBA: distinct heroes with Q/W/E/R, minions, towers, jungle monsters, shop, respawn; FPS: weapon, ammo, reload, crosshair, enemies; platformer: checkpoints, collectibles, end of level; racing: laps, ranking, AI opponents… and for every game a way to win AND to lose, title / pause / end screens, sound, a HUD, touch controls), checked against facts of the project, never a declaration. Each defect carries fix { tool, args, note, auto?, credits? }: call it as given. Returns { verdict: complete | playable_with_defects | incomplete, headline, genre, counts, defects, next (ordered calls), sections, text, play_url }. fix=true first applies what is free and safe (the best free Library model on each capsule — rebind at will —, the free standard clips, the suggested control scheme) and reports it in fixes. playtest="run" plays the game headless first (5–20 s); the default reads the last playtest and says when it is stale. Never refuses a write and never spends: paid fixes (a priced model, a rig, a generation) come back with their price to ask the user about. Aim for verdict complete; if you stop before, tell the user exactly what is left. 0 credits.', {
+        project_id: projectId,
+        fix: schema.boolean().optional().describe('true: apply the free and safe fixes first (free models on capsules, standard clips, suggested control scheme), then read. Nothing paid is ever done.'),
+        playtest: schema.enum(['last', 'run']).optional().describe('last (default): read the stored playtest of the project. run: play it headless now, then read.'),
+        brief: schema.string().max(2000).optional().describe('Free words about the game (theme, setting): they weigh in the model proposals.'),
+    }, { readOnly: false }, (args, extra) => (args.fix === true || args.playtest === 'run'
+        ? api(`gamekit-projects/${enc(args.project_id)}/audit`, body(args), 'POST', extra?.signal, undefined, 280_000)
+        : api(`gamekit-projects/${enc(args.project_id)}/audit`, { workspace_id: args.workspace_id }, 'GET', extra?.signal, { brief: typeof args.brief === 'string' ? args.brief : undefined })));
     tool('gripforge_moba_roster', 'Set the champions of a MOBA project', 'Turn champions into the playable roster of a moba project (preset "moba"). Pass the Library ids of 1 to 10 champions that carry an ability pack (the items made by gripforge_abilities_generate: rigged model + basic_attack and ability_q…r clips). Writes the moba_heroes and abilities collections (ids <hero>__ability_q), binds each champion to moba_hero_<n> and the player\'s champion (player, else the first) to player_character. Bots play the other champions. Returns the heroes with their attack and Q/W/E/R. Then gripforge_game_play_url to play. 0 credits.', {
         project_id: projectId,
         heroes: schema.array(schema.string()).min(1).max(10).describe('Library ids (lib_…) of champions with an ability pack, in roster order.'),

package/dist/scene-tools.js

@@ -123,6 +123,8 @@ export function registerSceneTools(register, options, schema = z) {
     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_apply_realism', 'Orchestrate scene realism', 'Plan or apply render.realism across shared PBR materials, immutable textures, surface shaders, lighting, post-processing, environment and skinned character rendering, with a bounded render quality and render.lod configuration suggestion. Defaults to mode=plan (no save); mode=apply writes one work revision atomically, preserving assets, transforms, animation and validated versions. Explicit nodeIds restrict instance assignments; lighting/post-processing are global. materials/characters rows use {nodeId,material:"*"|exactName,override:{roughness,metalness,map,normalMap,surface,...}}; pinned map references, null removes overrides. Characters require character/enemy/boss/fps-arms role. Does not fabricate missing detail, execute paid generation, add game LOD automatically, or approve realism visually. Request a real scene_review afterwards. WEB only; not DLSS.', { id: identifier, expectedRevision: revision, mode: schema.enum(['plan', 'apply']).default('plan'), quality: schema.enum(['performance', 'balanced', 'quality']).optional(), lighting: schema.enum(['preserve', 'daylight', 'golden_hour', 'overcast', 'night']).optional(), nodeIds: schema.array(identifier).min(1).max(100).optional(), materials: schema.array(schema.object({ nodeId: identifier, material: schema.string().min(1).max(256).optional(), override: record })).max(100).optional(), characters: schema.array(schema.object({ nodeId: identifier, material: schema.string().min(1).max(256).optional(), override: record })).max(100).optional(), environment: record.optional(), postProcess: record.optional() }, false, (args, extra) => call(`scenes/${args.id}/render-realism`, args, 'POST', extra?.signal));
+    tool('gripforge_realism_schema', 'Read realism orchestration contract', 'Read render.realism systems, modes, bounds and immutable-source workflow for an accessible scene.', { id: identifier }, true, (args, extra) => call(`scenes/${args.id}/render-realism`, args, 'GET', 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));
@@ -136,7 +138,9 @@ export function registerSceneTools(register, options, schema = z) {
     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));
     tool('gripforge_scene_asset_review', 'Review an immutable asset', 'Create a shared test scene and queue an independent review of real GripForge captures. Supports meshes, textures and effects. Never promotes automatically.', { assetId: identifier, revisionId: identifier, idempotency_key: schema.string().min(8).max(160).optional() }, false, (args, extra) => call(`scene-assets/${args.assetId}/${args.revisionId}/review`, args, 'POST', extra?.signal));
     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_fp_hands_schema', 'First-person hand manufacturing contract', 'Read the native FPS hand template, recipe defaults, limits and reuse workflow. Geometry is manufactured from an articulated FPS template, independently of full-body character generation.', {}, true, (args, extra) => call('fp-hands', args, 'GET', extra?.signal));
+    tool('gripforge_generate_fp_hands', 'Generate dedicated first-person hands', 'Manufacture a NEW fps-arms work asset using the native FPS template: curved hand surface refinement, fitted skinned long sleeves/cuff, optional tactical glove reinforcement and embedded PBR. recipe={version:1,name,quality:high|standard,gloves:tactical|light,sleeves:long|none,colors?:{fabric:#RRGGBB,sleeve:#RRGGBB,trim:#RRGGBB},source?:{assetId,revisionId,fileRole?}}. No source gives standalone hands with native finger rig, hand_item_r/l sockets and existing starting clips. Optional owned immutable native paired source keeps weapon, camera and animation tracks; source must contain FPS_Hands or FPS_Arms_Mesh, all ten native fingers, embedded GLB <=32 MiB. This is template geometry/garment manufacture, not prompt-to-new-anatomy or arbitrary rigging. Returns job_id; poll generation_read. Inspect fingers, seams and weapon/garment contact in the actual renderer before binding. No external provider charge; never auto-promotes or overwrites.', { recipe: record, idempotency_key: schema.string().min(8).max(160).optional() }, false, (args, extra) => call('fp-hands', args, 'POST', extra?.signal));
+    tool('gripforge_fps_animation', 'Author first-person weapon rigs and materials', 'Queue a persistent FPS work asset. Pistol recipe: {version:1,preset:"pistol",name:"Pistol FPS",tempo:1}, tempo 0.7–1.3; manufactures paired arms and articulated pistol clips plus .blend in Blender. Materials recipe: {version:1,preset:"materials",name:"Tactical gloves",source:{assetId,revisionId},node:"FPS_Hands",materials:{map:{assetId,revisionId},normalMap?:{assetId,revisionId},roughnessMap?:{assetId,revisionId},normalScale:0.35,roughness:1,metalness:0}}. Upload and pin owned textures first; they must match source UVs. Select one exact skinned node; other nodes, geometry, fingers and clips stay intact. Normal is OpenGL +Y; grayscale roughness reads G and requires metalness=0 (skin/fabric). Sources <=32 MB, images PNG/JPEG/WebP <=16 MB and 4096 pixels per side. Materials authors a reusable GLB variant, not new hand anatomy or a new .blend; no provider charge. Returns job_id: poll gripforge_generation_read for private Library ref, report and FPS Studio link. Never automatically validates or promotes. Cancel/retry supported; 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 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));

package/dist/server.js

@@ -32,6 +32,8 @@ 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';
+import { registerReverseTools } from './game-import-reverse.js';
+import { registerGameImportTools } from './game-import-tools.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';
@@ -45,6 +47,8 @@ registerGameKitLocalTools(server.registerTool.bind(server), { apiUrl: API_URL, g
 registerMapUnrealLocalTools(server.registerTool.bind(server));
 registerMapUnrealImportLocalTools(server.registerTool.bind(server));
 registerMapUnrealExportLocalTools(server.registerTool.bind(server), { apiUrl: API_URL, getApiKey: () => API_KEY });
+registerReverseTools(server.registerTool.bind(server));
+registerGameImportTools(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 });
@@ -1095,7 +1099,7 @@ server.tool('gripforge_hand_check', 'Verify that a rigged character\'s fingers f
         return err(String(data.error ?? res.statusText));
     return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
 });
-server.tool('gripforge_animate', 'Retarget the standard clip pack onto a Mixamo-named Library character/enemy/armed bind. Base slots (idle, walk, run, attack1-3, hit, death, dodge) + extras (taunt, stinger, knockback, block, jump_start/loop/land, idle_guns, shoot, reload, aim, crouch_idle, crouch_walk, knife). archetype remaps the base slots: sword (default), claws (zombie scratch), heavy (slow + heavy combo), brawler (punches), puppet (stiff walk + throws), operator (CS-style: knife/punch strikes). Opt-in slots fire_breath (mouth exhalation) and energy_cast (two-hand azure wave) use the Studio VFX character motions. Saves kind=animation. 0 credits.', {
+server.tool('gripforge_animate', 'Retarget the standard clip pack onto a Mixamo-named Library character/enemy/armed bind. In a Game Kit project gripforge_gamekit_creatures runs it for free on every bound creature, and gripforge_game_audit lists the models still lacking movement or action clips. Base slots (idle, walk, run, attack1-3, hit, death, dodge) + extras (taunt, stinger, knockback, block, jump_start/loop/land, idle_guns, shoot, reload, aim, crouch_idle, crouch_walk, knife). archetype remaps the base slots: sword (default), claws (zombie scratch), heavy (slow + heavy combo), brawler (punches), puppet (stiff walk + throws), operator (CS-style: knife/punch strikes). Opt-in slots fire_breath (mouth exhalation) and energy_cast (two-hand azure wave) use the Studio VFX character motions. Saves kind=animation. 0 credits.', {
     character_id: z.string().describe('Library character, enemy, or armed bind'),
     archetype: z.enum(['sword', 'claws', 'heavy', 'brawler', 'puppet', 'operator']).optional().describe('Movement/strike archetype — remaps the base slots (default sword); operator = CS-style (knife/punch strikes, guns via idle_guns/shoot/reload/aim, crouch_idle/crouch_walk)'),
     slots: z

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gripforgeai/mcp",
-  "version": "0.1.15",
-  "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.",
+  "version": "0.1.17",
+  "description": "The tools your AI needs to make your games. Turn prompts into production-ready game assets \u2014 animated characters with their weapons attached, seamless textures, terrain, VFX, HUDs \u2014 and playable game kits Unity, Godot, Unreal or Three.js can load.",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -14,7 +14,8 @@
     "runtime/unreal-scene-upload.mjs",
     "runtime/unreal_scene_math.py",
     "runtime/unreal_spawn_review.py",
-    "README.md"
+    "README.md",
+    "runtime/game-import-normalize.py"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json && node -e \"require('fs').chmodSync('dist/server.js', 0o755)\"",

package/runtime/game-import-normalize.py

@@ -0,0 +1,40 @@
+"""Blender manufacture worker. No source scripts, handlers or .blend files are loaded."""
+import bpy
+import json
+import sys
+from pathlib import Path
+
+plan = json.loads(Path(sys.argv[sys.argv.index('--') + 1]).read_text())
+source, output = plan['input'], plan['output']
+kind = Path(source).suffix.lower()
+bpy.ops.object.select_all(action='SELECT')
+bpy.ops.object.delete(use_global=False)
+if kind in ('.dds', '.tga'):
+    image = bpy.data.images.load(source, check_existing=False)
+    if not len(image.pixels):
+        raise ValueError('Image decoder returned no pixels')
+    image.pack()  # Resolve lazy pixels before changing the source filepath.
+    if not image.has_data:
+        raise ValueError('Image decoder returned no pixels')
+    image.filepath_raw = output
+    image.file_format = 'PNG'
+    image.save()
+else:
+    if kind == '.fbx':
+        bpy.ops.import_scene.fbx(filepath=source, use_image_search=False)
+    elif kind == '.obj':
+        bpy.ops.wm.obj_import(filepath=source)
+    else:
+        raise ValueError('Unsupported source format')
+    if not any(o.type == 'MESH' for o in bpy.context.scene.objects):
+        raise ValueError('No mesh imported')
+    # Pack only staged images. Missing textures remain an explicit conversion failure.
+    stage = Path(source).parent.resolve()
+    for image in bpy.data.images:
+        if image.source == 'FILE' and not image.packed_file:
+            path = Path(bpy.path.abspath(image.filepath)).resolve()
+            if not path.is_relative_to(stage) or not path.is_file():
+                raise ValueError('Missing or external material texture: ' + image.name)
+            image.pack()
+    bpy.ops.export_scene.gltf(filepath=output, export_format='GLB', export_animations=True)
+Path(plan['receipt']).write_text(json.dumps({'version': bpy.app.version_string}))