@gripforgeai/mcp 0.1.16 → 0.1.18

package/dist/architecture-tools.js

@@ -1,15 +1,26 @@
 import { z } from 'zod/v4';
 import { LOOK_DESCRIPTION, LOOK_VALUES } from './look.js';
-export const ARCHITECTURE_TOOL_NAMES = ['gripforge_architecture_schema', 'gripforge_generate_building', 'gripforge_generate_district', 'gripforge_environment_module'];
+export const ARCHITECTURE_TOOL_NAMES = ['gripforge_architecture_schema', 'gripforge_generate_building', 'gripforge_generate_district', 'gripforge_environment_module', 'gripforge_urban_building'];
 /** Hosted and local MCP share the same recipe and durable server workflow. */
 export function registerArchitectureTools(register, options, schema = z) {
     const identifier = schema.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,159}$/);
     const ref = schema.object({ assetId: identifier, revisionId: identifier, fileRole: identifier.optional() }).strict();
+    const point = schema.tuple([schema.number().min(-150).max(150), schema.number().min(-150).max(150), schema.number().min(-150).max(150)]);
+    const finishMaterial = { id: schema.string().regex(/^[a-zA-Z0-9_-]{1,48}$/), color: schema.string().regex(/^#[0-9a-f]{6}$/i), roughness: schema.number().min(.05).max(1).optional(), metalness: schema.number().min(0).max(1).optional() };
+    const finish = schema.object({ version: schema.literal(1),
+        remove: schema.array(schema.object({ center: point, size: schema.tuple([schema.number().min(.001).max(100), schema.number().min(.001).max(100), schema.number().min(.001).max(100)]), rotation: schema.tuple([schema.number().min(-Math.PI * 2).max(Math.PI * 2), schema.number().min(-Math.PI * 2).max(Math.PI * 2), schema.number().min(-Math.PI * 2).max(Math.PI * 2)]).optional() }).strict()).max(64),
+        parts: schema.array(schema.discriminatedUnion('kind', [
+            schema.object({ kind: schema.literal('shutter'), ...finishMaterial, origin: point, yaw: schema.number().min(-Math.PI * 2).max(Math.PI * 2).optional(), width: schema.number().min(.2).max(15), height: schema.number().min(.1).max(12), slatHeight: schema.number().min(.035).max(.3).optional() }).strict(),
+            schema.object({ kind: schema.literal('railing'), ...finishMaterial, points: schema.array(point).min(2).max(16), height: schema.number().min(.1).max(12), postSpacing: schema.number().min(.2).max(3).optional(), barSpacing: schema.number().min(.05).max(.5).optional(), postRadius: schema.number().min(.015).max(.1).optional(), barRadius: schema.number().min(.006).max(.05).optional(), railRadius: schema.number().min(.01).max(.08).optional() }).strict(),
+        ])).min(1).max(32),
+    }).strict().describe('Free deterministic repair of an owned source + delivery. All coordinates are Y-up metres AFTER the returned importTransform. Explicit oriented removal boxes (rotation XYZ radians), regular shutters (+Z outward, yaw radians) and railing paths (feet, vertical posts, supports slopes). Measure and review regions first. Applied AFTER each LOD simplification to keep thin parts straight. Textures outside cuts stay byte-identical; removed surfaces are not capped. Triangle targets remain soft. No AI auto-segmentation or collision repair.');
     const building = schema.object({
         id: schema.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,47}$/).optional(),
         name: schema.string().min(1).max(100).optional(), prompt: schema.string().min(3).max(300),
         style: schema.enum(['realistic', 'stylized', 'lowpoly', 'handpainted']).optional(),
         look: schema.enum(LOOK_VALUES).optional().describe(`${LOOK_DESCRIPTION} Fills style when style is omitted; toon, anime and pixel add their phrase to the prompt.`),
+        provider: schema.enum(['meshy', 'tripo']).optional().describe('3D provider pinned to this recipe, Meshy by default. Tripo v3.1 requires one reviewed concept (no multiview yet) and uses v3.5 PBR textures. No automatic paid provider fallback.'),
+        tripoQuality: schema.object({ geometry: schema.enum(['standard', 'detailed']).optional(), texture: schema.enum(['standard', 'detailed', 'extreme']).optional() }).strict().optional().describe('Tripo-only quality; default detailed geometry and detailed textures. extreme requests 8K. Read the separate provider quote. Exclusive with Meshy meshQuality and source.'),
         use: schema.enum(['residential', 'retail', 'office', 'industrial', 'mixed']).optional(),
         floors: schema.number().int().min(1).max(30).optional(),
         dimensions: schema.object({ width: schema.number().min(3).max(100).optional(), depth: schema.number().min(3).max(100).optional(), height: schema.number().min(3).max(150).optional() }).strict().optional().describe('Maximum footprint and height in metres. Uniform fit preserves proportions; actual dimensions are returned.'),
@@ -18,7 +29,9 @@ export function registerArchitectureTools(register, options, schema = z) {
         concept: ref.optional().describe('Owned PNG/JPEG/WebP revision for Meshy image-to-3D. At most 12 MiB. Mutually exclusive with source.'),
         concepts: schema.array(ref).min(1).max(4).optional().describe('Coherent views of ONE building, front first, for Meshy multi-image-to-3D. Exclusive with concept/source. Review coherence before building.'),
         meshQuality: schema.object({ geometry: schema.enum(['standard', '2k', '4k']).optional(), texture: schema.enum(['2k', '4k', '8k']).optional() }).strict().optional().describe('Meshy 7.1 quality. Defaults standard geometry and 2K PBR. Multi-image supports standard/2k geometry only. Texture resolution is preserved during optimization. Read the updated quote.'),
+        delivery: schema.object({ lods: schema.array(schema.object({ triangles: schema.number().int().min(1000).max(200000), textureSize: schema.union([schema.literal(1024), schema.literal(2048), schema.literal(4096), schema.literal(8192)]), maxError: schema.number().min(0).max(.02).optional(), lockBorder: schema.boolean().optional() }).strict()).min(1).max(3) }).strict().optional().describe('Preserve an immutable full-detail source without provider remeshing, then prepare 1–3 independent LOD GLBs. Highest detail first, decreasing triangles and texture sizes. Default maxError=.001, lockBorder=true prioritizes detail and may exceed targets. For distant levels, explicitly allow e.g. maxError=.005/.01 and lockBorder=false after review. Shared metric fit and preserved PBR. No normal rebake, runtime LOD switching or inferred collision. Also works with source at no provider cost.'),
         source: ref.optional().describe('Reuse an owned static GLB revision instead of paying for this building. The source is never modified.'),
+        finish: finish.optional(),
     }).strict();
     const material = schema.record(schema.string(), schema.unknown()).describe('SceneMaterialOverride: color, roughness, metalness, map/normalMap/roughnessMap/metalnessMap as owned immutable SceneAssetRef, repeat:[u,v]. Validated by the shared Scene Engine.');
     const district = schema.object({
@@ -42,18 +55,19 @@ export function registerArchitectureTools(register, options, schema = z) {
         palette: schema.object({ stone: schema.string().regex(/^#[0-9a-f]{6}$/i).optional(), recess: schema.string().regex(/^#[0-9a-f]{6}$/i).optional(), trim: schema.string().regex(/^#[0-9a-f]{6}$/i).optional(), water: schema.string().regex(/^#[0-9a-f]{6}$/i).optional() }).strict().optional(),
     }).strict();
     const definitions = [
-        { name: ARCHITECTURE_TOOL_NAMES[0], kind: 'schema', shape: {}, title: 'Architecture · schema', description: 'Read the reusable Meshy building and district contract, example, limits and plan → build workflow. Separate immutable Library assets, scene instances and shared SceneDocument. No paid generation.' },
+        { name: ARCHITECTURE_TOOL_NAMES[4], kind: 'urban', title: 'Manufacture a reusable urban building', description: 'Free, deterministic parametric architecture. plan validates a metric recipe; build queues a durable common-compute job and returns job_id to poll with gripforge_generation_read. Real window reveals, balconies, shopfronts, rooftop HVAC, photographic PBR and optional arid shutters/canopies/water tanks. Private immutable GLB plus recipe/report; reuse via Library bindings or scene instances. Nominal width/depth exclude protrusions: use returned actual bounds and preserve proportions. A solid envelope with storefront depth, not traversable interiors, a complete city or an AI replacement for gripforge_generate_building. Review in the actual game. 0 credits.', shape: { stage: schema.enum(['plan', 'build']).optional(), workspace_id: schema.string().max(100).optional(), idempotency_key: shared.idempotency_key, recipe: schema.object({ name: schema.string().min(1).max(100), style: schema.enum(['brick', 'balconies', 'limestone', 'loft', 'workshop', 'office', 'stucco']), width: schema.number().min(6).max(30).optional(), depth: schema.number().min(6).max(30).optional(), floors: schema.number().int().min(1).max(20).optional(), seed: schema.number().int().min(0).max(2147483646).optional(), shop: schema.number().int().min(0).max(7).optional(), climate: schema.enum(['temperate', 'arid']).optional(), palette: schema.object({ facade: schema.string().regex(/^#[a-fA-F0-9]{6}$/).optional(), stone: schema.string().regex(/^#[a-fA-F0-9]{6}$/).optional(), trim: schema.string().regex(/^#[a-fA-F0-9]{6}$/).optional(), roof: schema.string().regex(/^#[a-fA-F0-9]{6}$/).optional() }).strict().optional() }).strict() } },
+        { name: ARCHITECTURE_TOOL_NAMES[0], kind: 'schema', shape: {}, title: 'Architecture · schema', description: 'Read the reusable Meshy/Tripo building and district contract, example, limits and plan → build workflow. Separate immutable Library assets, scene instances and shared SceneDocument. No paid generation.' },
         { name: ARCHITECTURE_TOOL_NAMES[1], kind: 'building', shape: { ...shared, recipe: building,
                 stage: schema.enum(['plan', 'concept', 'build']).optional().describe('plan is free: exact prompts and separate image/3D quotes. concept creates reviewable workspace images. First review artistic scene, then isolated views of the SAME building, then build 3D from chosen isolated references.'),
                 concept_provider: schema.enum(['openai', 'xai']).optional().describe('Default openai (GPT Image 2.5 Sunburst, high quality). xai explicitly selects Imagine. Provider is pinned in the durable job; never silently falls back. Read the provider-specific concept_quote.'),
-                concept_presentation: schema.enum(['scene', 'isolated']).optional().describe('Default scene: artistic concept in its neighbourhood preserving the user atmosphere and lighting. isolated: technical views of the SAME building for Meshy. Keep rich architectural detail in both.'),
+                concept_presentation: schema.enum(['scene', 'isolated']).optional().describe('Default scene: artistic concept in its neighbourhood preserving the user atmosphere and lighting. isolated: technical views of the SAME building for 3D reconstruction. Keep rich architectural detail in both.'),
                 concept_reference: ref.optional().describe('Owned artistic reference to EDIT into new scene/isolated views. Distinct from recipe.concept, which reuses an existing front view without generation. Exclusive with recipe.concept/concepts/source and stage=build.'),
-                concept_views: schema.array(schema.enum(['front_right', 'front_left', 'rear_right', 'rear_left'])).min(1).max(4).optional().describe('Unique views starting with front_right. Default one view for scene, three for isolated. Alternate views edit the SAME master. recipe.concept reuses an existing master; concept_reference guides a NEW master.'),
-            }, title: 'Generate a building', description: 'Reusable plan → artistic concept → isolated reference views → review → Meshy build workflow. Generate 1–4 coherent images through OpenAI (1536×1024 high quality, default) or Imagine (2K), saved as private Library drafts; alternate views reference one master. Separate explicit budgets for concepts and 3D. Accepts text, owned single/multiple concept views or an owned static GLB. Meshy PBR/geometry quality, bounded geometry and uniform metric fit. Durable jobs return workspace links; poll generation_read, cancel/retry preserves finished steps. Review images before building and the real Studio render before publishing. No guaranteed interiors, collisions or LODs. Never substitutes procedural geometry or automatically replaces a game asset.' },
-        { name: ARCHITECTURE_TOOL_NAMES[2], kind: 'district', shape: { ...shared, recipe: district }, title: 'Generate a district', description: 'Plan then build a straight-street district from 1–8 distinct Meshy buildings, each manufactured once and reused as separate editable instances. Includes road, pavements, spawn, daylight and camera in the shared Map SceneDocument. Optional owned PBR road/pavement maps; otherwise simple solid surfaces. Plan returns layout, provider-credit count and account quote without spending. Build requires a budget and returns a persistent job, then Map Studio link. Private work version requiring visual review; no automatic Community publication or game replacement.' },
+                concept_views: schema.array(schema.enum(['front_right', 'front_left', 'rear_right', 'rear_left'])).min(1).max(4).optional().describe('Unique views starting with front_right. Default one view for scene or Tripo, three for isolated Meshy. Tripo requires one view. Alternate views edit the SAME master. recipe.concept reuses an existing master; concept_reference guides a NEW master.'),
+            }, title: 'Generate a building', description: 'Reusable plan → artistic concept → isolated reference views → review → Meshy or explicitly selected Tripo build workflow. Generate 1–4 images through OpenAI or Imagine; alternate views reference one master but must be checked for actually different viewpoints. If edits repeat the front, use one good concept instead of a false multiview set. Separate explicit budgets for concepts and 3D. Accepts text, owned concept views or a static GLB. Optional delivery preserves the source master and prepares reusable LOD GLBs with PBR and a common metric fit. Durable jobs return workspace links; poll generation_read, cancel/retry preserves finished steps. Review the actual render before publishing. No guaranteed interiors, collisions or runtime LOD switching; no automatic game replacement.' },
+        { name: ARCHITECTURE_TOOL_NAMES[2], kind: 'district', shape: { ...shared, recipe: district }, title: 'Generate a district', description: 'Plan then build a straight-street district from 1–8 distinct Meshy/Tripo buildings, each manufactured once and reused as separate editable instances. Includes road, pavements, spawn, daylight and camera in the shared Map SceneDocument. Optional owned PBR road/pavement maps; otherwise simple solid surfaces. Plan returns layout, provider-credit count and account quote without spending. Build requires a budget and returns a persistent job, then Map Studio link. Private work version requiring visual review; no automatic Community publication or game replacement.' },
         { name: ARCHITECTURE_TOOL_NAMES[3], kind: 'module', shape: { stage: schema.enum(['inspect', 'build']).optional(), recipe: moduleRecipe, name: schema.string().min(1).max(100).optional(), workspace_id: schema.string().max(100).optional() }, title: 'Create a reusable environment module', description: 'Free parametric 3D masonry, independent of any game: pillar, arch, fountain, stairs, wall, pavement, rock, cliff, ruin, bridge, watchtower, shrine or a stone guardian. inspect (default) returns real generated bounds, triangle count, metric recipe and assembly sockets. build saves a private textured GLB in the Library, with bevelled geometry, baked vertex shading and named stone/recess/trim/water materials. Dimensions are nominal metres; bounds report actual moulding overhang. Ground origin, stairs ascend toward -Z, <=23 cm risers; top/bottom sockets support assembly. Seed and palette are repeatable. Does not place assets, generate arbitrary AI models, publish, or guarantee navigation/collisions in a target game. 0 credits.' },
     ];
-    for (const tool of definitions)
+    for (const tool of definitions.sort((a, b) => ARCHITECTURE_TOOL_NAMES.indexOf(a.name) - ARCHITECTURE_TOOL_NAMES.indexOf(b.name)))
         register(tool.name, { title: tool.title, description: tool.description, inputSchema: tool.shape,
             annotations: { readOnlyHint: tool.kind === 'schema', destructiveHint: false, idempotentHint: tool.kind === 'schema', openWorldHint: tool.kind !== 'schema' } }, async (args, extra) => {
             const parsed = schema.object(tool.shape).strict().safeParse(args);
@@ -64,10 +78,10 @@ export function registerArchitectureTools(register, options, schema = z) {
                 return { isError: true, content: [{ type: 'text', text: 'GripForge API key required.' }] };
             const { workspace_id, ...body } = parsed.data;
             try {
-                const response = await fetch(options.apiUrl.replace(/\/$/, '') + (tool.kind === 'module' ? '/api/v1/environment-modules' : '/api/v1/architecture'), {
+                const response = await fetch(options.apiUrl.replace(/\/$/, '') + (tool.kind === 'module' ? '/api/v1/environment-modules' : tool.kind === 'urban' ? '/api/v1/urban-buildings' : '/api/v1/architecture'), {
                     method: tool.kind === 'schema' ? 'GET' : 'POST',
                     headers: { 'content-type': 'application/json', 'x-gripforge-client': 'mcp', ...(key ? { 'x-api-key': key } : {}), ...(typeof workspace_id === 'string' ? { 'x-workspace-id': workspace_id } : {}) },
-                    ...(tool.kind === 'schema' ? {} : { body: JSON.stringify(tool.kind === 'module' ? body : { ...body, kind: tool.kind }) }),
+                    ...(tool.kind === 'schema' ? {} : { body: JSON.stringify(['module', 'urban'].includes(tool.kind) ? body : { ...body, kind: tool.kind }) }),
                     signal: AbortSignal.any([AbortSignal.timeout(60_000), ...(extra?.signal ? [extra.signal] : [])]),
                 });
                 const data = await response.json();

package/dist/game-import-agent.js

@@ -0,0 +1,457 @@
+import { constants } from 'node:fs';
+import { readdir, mkdir, readFile, writeFile, rename, realpath, stat, open, access, unlink } from 'node:fs/promises';
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { createHash, randomBytes } from 'node:crypto';
+import { homedir } from 'node:os';
+import { normalizedPath } from './game-import-normalize.js';
+const MAX_FILES = 20000, MAX_BYTES = 256 * 1024 * 1024, MAX_JSON = 8 * 1024 * 1024;
+const OMIT = new Set(['.git', '.svn', 'node_modules', '.env', '.aws', '.ssh', 'Library', 'Temp', 'Logs', 'obj', '.DS_Store']);
+export const importHome = () => process.env.GRIPFORGE_GAME_IMPORT_HOME || join(homedir(), '.gripforge', 'game-imports');
+export function jobDirectory(id) {
+    if (!/^gi_[a-f0-9]{24}$/.test(id))
+        throw Error('Invalid import id');
+    return join(importHome(), id);
+}
+export async function loadImportJob(id) { return JSON.parse(await readFile(join(jobDirectory(id), 'job.json'), 'utf8')); }
+export async function saveImportJob(job) {
+    const dir = jobDirectory(job.id);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    job.updatedAt = new Date().toISOString();
+    const tmp = join(dir, `job.${process.pid}.tmp`);
+    await writeFile(tmp, JSON.stringify(job, null, 2), { mode: 0o600 });
+    await rename(tmp, join(dir, 'job.json'));
+    if (job.report) {
+        const report = join(dir, `report.${process.pid}.tmp`);
+        await writeFile(report, JSON.stringify(job.report, null, 2), { mode: 0o600 });
+        await rename(report, join(dir, 'report.json'));
+    }
+}
+export async function newImportJob(path) {
+    if (!isAbsolute(path))
+        throw Error('Use an absolute local directory path');
+    const root = await realpath(path);
+    if (!(await stat(root)).isDirectory())
+        throw Error('Source must be a directory');
+    if (root === sep || root === homedir())
+        throw Error('Select the game/project directory, not the whole computer');
+    const job = { schema: 'gripforge.game-import-job.v1', id: `gi_${randomBytes(12).toString('hex')}`, root, phase: 'analyze', status: 'queued', createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(), completed: 0, total: 0, receipts: {}, errors: {} };
+    await saveImportJob(job);
+    return job;
+}
+export async function confinedFile(root, path) {
+    if (!path || isAbsolute(path) || path.split(/[\\/]/).includes('..'))
+        throw Error('Unsafe source reference');
+    const requested = resolve(root, path), actual = await realpath(requested);
+    if (actual !== requested || !actual.startsWith(root + sep))
+        throw Error('Symlink or external source reference rejected');
+    const info = await stat(actual);
+    if (!info.isFile() || info.size > MAX_BYTES)
+        throw Error('File unavailable or exceeds 256 MiB');
+    return actual;
+}
+async function readSource(root, path) {
+    const file = await confinedFile(root, path), handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+    try {
+        const s = await handle.stat();
+        if (s.size > MAX_BYTES)
+            throw Error('File exceeds 256 MiB');
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+}
+const digest = (data) => createHash('sha256').update(data).digest('hex');
+const media = new Set(['.png', '.jpg', '.jpeg', '.webp', '.wav', '.ogg', '.mp3']);
+const structured = new Set(['.prefab', '.unity', '.mat', '.asset', '.anim', '.meta', '.cs', '.tscn', '.tres', '.uproject', '.uasset', '.umap', '.pak', '.utoc', '.ucas', '.dll', '.bundle', '.assets', '.fbx', '.obj', '.glb', '.gltf', '.dds', '.tga', '.shader', '.vfx']);
+const nameRules = [
+    [/(^|[\W_])(sword|longsword|katana|axe|rifle|ak47|pistol|shotgun|weapon)([\W_]|$)/i, 'weapon'],
+    [/(^|[\W_])(building|house|warehouse|tower)([\W_]|$)/i, 'building'],
+    [/(^|[\W_])(vehicle|car|truck|kart)([\W_]|$)/i, 'vehicle'],
+    [/(^|[\W_])(character|soldier|hero|npc|enemy)([\W_]|$)/i, 'character'],
+    [/(^|[\W_])(terrain|landscape|environment)([\W_]|$)/i, 'environment'],
+];
+function gltfJSON(bytes, ext) {
+    if (ext === '.gltf') {
+        if (bytes.length > MAX_JSON)
+            throw Error('glTF JSON exceeds limit');
+        return JSON.parse(bytes.toString());
+    }
+    if (bytes.length < 20 || bytes.readUInt32LE(0) !== 0x46546c67 || bytes.readUInt32LE(4) !== 2 || bytes.readUInt32LE(8) !== bytes.length || bytes.readUInt32LE(16) !== 0x4e4f534a)
+        throw Error('Invalid GLB header');
+    const len = bytes.readUInt32LE(12);
+    if (len > MAX_JSON || 20 + len > bytes.length)
+        throw Error('Invalid GLB JSON length');
+    return JSON.parse(bytes.subarray(20, 20 + len).toString());
+}
+export function inspectAsset(path, bytes) {
+    const ext = extname(path).toLowerCase(), sha256 = digest(bytes), evidence = [];
+    const a = { id: `src_${digest(path).slice(0, 24)}`, path, name: basename(path, ext), format: ext.slice(1), bytes: bytes.length, sha256, kind: 'unknown', evidence, status: 'blocked', details: {}, suggestedKits: [] };
+    if (['.glb', '.gltf', '.fbx', '.obj'].includes(ext)) {
+        a.kind = 'prop';
+        const rule = nameRules.find(([r]) => r.test(path));
+        evidence.push({ source: path, reason: 'Mesh file format; role needs review', confidence: .4 });
+        if (rule) {
+            a.kind = rule[1];
+            evidence.push({ source: path, reason: 'Role suggested by filename, not verified visually', confidence: .55 });
+        }
+        if (ext === '.glb' || ext === '.gltf') {
+            try {
+                const doc = gltfJSON(bytes, ext);
+                if (doc.asset?.version !== '2.0')
+                    throw Error('Requires glTF 2');
+                a.details.meshes = doc.meshes?.length ?? 0;
+                a.details.materials = (doc.materials ?? []).map((m, i) => String(m.name ?? `material_${i}`));
+                a.details.clips = (doc.animations ?? []).map((m, i) => String(m.name ?? `clip_${i}`));
+                a.details.joints = [...new Set((doc.skins ?? []).flatMap((s) => (s.joints ?? []).map((i) => String(doc.nodes?.[i]?.name ?? `joint_${i}`))))];
+                if (a.details.joints.length) {
+                    a.details.rig = 'unclassified';
+                    evidence.push({ source: path, reason: 'glTF skin joints found; anatomy/retargeting not validated', confidence: 1 });
+                }
+                if (!a.details.meshes && a.details.clips?.length)
+                    a.kind = 'animation';
+                a.details.dependencies = [...(doc.buffers ?? []), ...(doc.images ?? [])].map((b) => b.uri).filter((s) => typeof s === 'string' && !s.startsWith('data:'));
+                a.status = ext === '.glb' && !a.details.dependencies.length ? 'ready' : 'convertible';
+                if (ext === '.glb' && a.details.dependencies.length) {
+                    a.status = 'blocked';
+                    a.reason = 'GLB references external resources; export a self-contained GLB';
+                }
+            }
+            catch (e) {
+                a.reason = String(e);
+            }
+        }
+        else
+            a.reason = 'Export to GLB with Blender or the source editor before import';
+    }
+    else if (media.has(ext)) {
+        const valid = ext === '.png' ? bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) : ['.jpg', '.jpeg'].includes(ext) ? bytes[0] === 255 && bytes[1] === 216 : ext === '.webp' ? bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP' : ext === '.wav' ? bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WAVE' : ext === '.ogg' ? bytes.toString('ascii', 0, 4) === 'OggS' : bytes.toString('ascii', 0, 3) === 'ID3' || bytes[0] === 255 && (bytes[1] & 0xe0) === 0xe0;
+        a.kind = ['.wav', '.ogg', '.mp3'].includes(ext) ? 'audio' : 'texture';
+        a.status = valid ? 'ready' : 'blocked';
+        if (!valid)
+            a.reason = 'File signature does not match extension';
+        evidence.push({ source: path, reason: valid ? 'Media signature verified' : 'Invalid media signature', confidence: 1 });
+    }
+    else {
+        const kind = { '.prefab': 'scene', '.unity': 'scene', '.umap': 'scene', '.tscn': 'scene', '.mat': 'material', '.anim': 'animation', '.cs': 'script', '.dll': 'script', '.shader': 'script', '.vfx': 'vfx', '.pak': 'container', '.utoc': 'container', '.ucas': 'container', '.assets': 'container', '.bundle': 'container' };
+        a.kind = kind[ext] ?? 'unknown';
+        a.reason = 'Requires an engine exporter or format-specific converter';
+    }
+    if (a.kind === 'weapon')
+        a.suggestedKits = ['weapons.loadout', 'combat.melee', 'combat.projectiles'];
+    if (a.kind === 'vehicle')
+        a.suggestedKits = ['vehicle.driveable', 'vehicle.enter_exit'];
+    return a;
+}
+/** Local orchestration, not a renderer. Source files are never executed or modified. */
+export class GameImportAgent {
+    job;
+    constructor(job) {
+        this.job = job;
+    }
+    async cancelled() { try {
+        await access(join(jobDirectory(this.job.id), 'cancel'));
+        return true;
+    }
+    catch {
+        return false;
+    } }
+    async checkpoint() { if (await this.cancelled()) {
+        this.job.status = 'cancelled';
+        await saveImportJob(this.job);
+        throw Error('Import cancelled');
+    } await saveImportJob(this.job); }
+    async discover_assets() {
+        const files = [], warnings = [], home = await realpath(importHome()), skipHome = !this.job.root.startsWith(home + sep);
+        const walk = async (dir, depth) => {
+            if (depth > 32) {
+                warnings.push(`Depth limit: ${relative(this.job.root, dir)}`);
+                return;
+            }
+            if (await this.cancelled())
+                throw Error('Import cancelled');
+            const entries = await readdir(dir, { withFileTypes: true });
+            for (const e of entries) {
+                if (OMIT.has(e.name) || e.name.startsWith('.env') || e.name.startsWith('.'))
+                    continue;
+                const p = join(dir, e.name);
+                if (skipHome && (p === home || p.startsWith(home + sep)))
+                    continue;
+                if (e.isSymbolicLink()) {
+                    warnings.push(`Skipped symlink: ${relative(this.job.root, p)}`);
+                    continue;
+                }
+                if (e.isDirectory())
+                    await walk(p, depth + 1);
+                else if (e.isFile()) {
+                    if (files.length >= MAX_FILES)
+                        throw Error('Scan exceeds 20,000 files; select a smaller source directory');
+                    files.push(relative(this.job.root, p).split(sep).join('/'));
+                }
+            }
+        };
+        await walk(this.job.root, 0);
+        return { files: files.sort(), warnings };
+    }
+    async detect_engine(files) {
+        const has = (r) => files.find(p => r.test(p));
+        const unity = has(/(?:UnityPlayer\.(?:dll|so|dylib)|global-metadata\.dat|ProjectSettings\/ProjectVersion\.txt|(?:^|\/)[^/]+_Data\/)/i);
+        const unreal = has(/\.uproject$|\.utoc$|(?:^|\/)Content\/Paks\//i);
+        const godot = has(/(?:^|\/)project\.godot$|\.pck$/i);
+        const web = has(/(?:^|\/)package\.json$/i);
+        const name = unity ? 'unity' : unreal ? 'unreal' : godot ? 'godot' : web ? 'web' : 'unknown';
+        const evidence = [{ source: unity ?? unreal ?? godot ?? web ?? '.', reason: name === 'unknown' ? 'No recognized engine marker; do not infer native engine from absence' : 'Engine filesystem marker', confidence: name === 'unknown' ? 0 : web ? .4 : .95 }];
+        let version;
+        const vf = has(/ProjectSettings\/ProjectVersion\.txt$/i);
+        if (vf)
+            version = (await readSource(this.job.root, vf)).toString().match(/m_EditorVersion:\s*(\S+)/)?.[1];
+        const uf = has(/\.uproject$/i);
+        if (uf) {
+            try {
+                version = JSON.parse((await readSource(this.job.root, uf)).toString()).EngineAssociation;
+            }
+            catch { }
+        }
+        return { name, version, runtime: name === 'unity' ? has(/global-metadata\.dat$|GameAssembly\.dll$/i) ? 'IL2CPP' : has(/Managed\/Assembly-CSharp\.dll$/i) ? 'Mono' : 'unknown' : name === 'unreal' ? 'native' : name === 'godot' ? 'GDScript / native (unverified)' : 'unknown', evidence };
+    }
+    select_toolchain(engine) {
+        const steps = [{ tool: 'GripForge file importer', purpose: 'Inspect GLB, pack glTF, index images/audio and Unity GUID references', status: 'builtin', reason: 'Known portable formats first' }];
+        if (engine.name === 'unity') {
+            steps.push({ tool: 'AssetRipper', purpose: 'Export Unity assets through an installed local AssetRipper HTTP instance, then rescan', status: 'external', reason: 'Set GRIPFORGE_ASSETRIPPER_URL to a dedicated loopback instance; external GPL tool, not bundled' });
+            steps.push({ tool: 'AssetStudio', purpose: 'Alternative asset exploration/export', status: 'manual', reason: 'Archived original repository; use only for compatible builds' });
+            if (engine.runtime === 'IL2CPP')
+                steps.push({ tool: 'Cpp2IL', purpose: 'Recover classes and metadata, not meshes', status: 'external', reason: 'Run an installed version with its documented options in an isolated output directory' });
+            else if (engine.runtime === 'Mono')
+                steps.push({ tool: 'ILSpy', purpose: 'Inspect managed controllers; code stays local', status: 'external', reason: 'Optional installed ilspycmd; does not export meshes' });
+        }
+        else if (engine.name === 'unreal')
+            steps.push({ tool: 'Unreal editor / GripForge Unreal export', purpose: 'Export an owned project through the existing Unreal scene pipeline', status: 'external', reason: 'Native project path supported; cooked packages require compatible extractor, not direct GLB import' });
+        else if (engine.name === 'godot')
+            steps.push({ tool: 'Godot editor', purpose: 'Export source scenes/meshes and inspect resources', status: 'manual', reason: 'PCK archives are indexed, not unpacked by this version' });
+        steps.push({ tool: 'Blender', purpose: 'Normalize extracted FBX/OBJ/DDS/TGA through a durable local manufacture worker', status: 'external', reason: 'Configure GRIPFORGE_BLENDER_BIN; preserves available embedded materials/rig/clips, missing resources require a self-contained source export' });
+        if (engine.name === 'unknown')
+            steps.push({ tool: 'Ghidra MCP / REA', purpose: 'Investigate unknown formats and document a converter', status: 'external', reason: 'Configure GRIPFORGE_GHIDRA_MCP_URL; use the bounded gripforge_reverse_* abstraction. Fallback only. Analysis is not an asset conversion; no untrusted game code is launched' });
+        return steps;
+    }
+    async analyze_asset_relationships(report) {
+        const guids = new Map();
+        for (const a of report.assets) {
+            try {
+                const meta = (await readSource(this.job.root, a.path + '.meta')).toString();
+                const guid = meta.match(/^guid:\s*([a-f0-9]{32})/m)?.[1];
+                if (guid) {
+                    a.details.guid = guid;
+                    if (guids.has(guid))
+                        report.warnings.push(`Duplicate Unity GUID: ${guid}`);
+                    else
+                        guids.set(guid, a.id);
+                }
+            }
+            catch { }
+        }
+        for (const a of report.assets) {
+            if (!['prefab', 'unity', 'mat', 'asset', 'anim'].includes(a.format) || a.bytes > MAX_JSON)
+                continue;
+            const text = (await readSource(this.job.root, a.path)).toString();
+            for (const guid of new Set([...text.matchAll(/guid:\s*([a-f0-9]{32})/g)].map(m => m[1]))) {
+                const to = guids.get(guid);
+                if (to && to !== a.id)
+                    report.relationships.push({ from: a.id, to, type: 'references', evidence: { source: a.path, reason: `Serialized Unity GUID reference ${guid}`, confidence: 1 } });
+            }
+        }
+    }
+    async analyze() {
+        const { files, warnings } = await this.discover_assets(), engine = await this.detect_engine(files);
+        const candidates = files.filter(p => media.has(extname(p).toLowerCase()) || structured.has(extname(p).toLowerCase())).filter(p => !p.endsWith('.meta'));
+        const report = { schema: 'gripforge.game-import.v1', id: this.job.id, source: basename(this.job.root), createdAt: this.job.createdAt, engine, assets: [], relationships: [], counts: {}, warnings, toolchain: this.select_toolchain(engine), normalization: { supported: ['Self-contained GLB preserving PBR/skins/clips', 'glTF 2 with embedded local buffers/images → GLB', 'PNG/JPEG/WebP and WAV/OGG/MP3', 'Installed Blender FBX/OBJ → GLB and DDS/TGA → PNG with persistent provenance'], requiresReview: ['Semantic kind/subtype', 'Skeleton anatomy and retargeting', 'PBR reconstruction for legacy formats', 'LOD and colliders', 'Sockets and Game Kit behavior mapping', 'GripForge renderer visual review before promotion'] } };
+        const previous = new Map(this.job.report?.assets.map(a => [a.path, a]) ?? []);
+        this.job.report = report;
+        this.job.total = candidates.length;
+        this.job.completed = 0;
+        for (const p of candidates) {
+            try {
+                const bytes = await readSource(this.job.root, p);
+                const old = previous.get(p);
+                const a = old?.sha256 === digest(bytes) ? old : inspectAsset(p, bytes);
+                if (a.format === 'gltf' && a.status === 'convertible') {
+                    a.details.resources = {};
+                    try {
+                        for (const uri of a.details.dependencies ?? []) {
+                            if (/^[a-z]+:/i.test(uri) || uri.startsWith('/') || uri.includes('\\'))
+                                throw Error('External resource URI rejected');
+                            const ref = relative(this.job.root, resolve(this.job.root, dirname(p), decodeURIComponent(uri)));
+                            a.details.resources[ref] = digest(await readSource(this.job.root, ref));
+                        }
+                    }
+                    catch (e) {
+                        a.status = 'blocked';
+                        a.reason = String(e);
+                    }
+                }
+                report.assets.push(a);
+            }
+            catch (e) {
+                report.warnings.push(`${p}: ${String(e)}`);
+            }
+            this.job.completed++;
+            if (this.job.completed % 10 === 0)
+                await this.checkpoint();
+        }
+        await this.analyze_asset_relationships(report);
+        for (const a of report.assets)
+            report.counts[a.kind] = (report.counts[a.kind] ?? 0) + 1;
+        this.job.status = 'awaiting_selection';
+        await this.checkpoint();
+        return report;
+    }
+    async normalize_assets(a) {
+        const bytes = await readSource(this.job.root, a.path);
+        if (digest(bytes) !== a.sha256)
+            throw Error('Source changed after analysis; analyze again');
+        if (a.details.normalization) {
+            const n = a.details.normalization;
+            const output = await readFile(normalizedPath(this.job, a.id, n.format));
+            if (n.sourceSha256 !== a.sha256 || digest(output) !== n.sha256)
+                throw Error('Normalized checkpoint changed; normalize again');
+            return { bytes: output, filename: basename(a.path, extname(a.path)) + '.' + n.format };
+        }
+        if (a.status === 'blocked')
+            throw Error(a.reason ?? 'Extraction/conversion required');
+        if (a.format !== 'gltf')
+            return { bytes, filename: basename(a.path) };
+        const doc = gltfJSON(bytes, '.gltf'), chunks = [], offsets = [];
+        let total = 0;
+        if (doc.extensionsUsed?.includes('EXT_meshopt_compression'))
+            throw Error('meshopt-compressed glTF requires decompression before packing');
+        const append = (b) => { const offset = total; chunks.push(b); total += b.length; const pad = (4 - total % 4) % 4; if (pad) {
+            chunks.push(Buffer.alloc(pad));
+            total += pad;
+        } if (total > MAX_BYTES)
+            throw Error('Packed glTF exceeds 256 MiB'); return offset; };
+        const resource = async (uri) => {
+            if (typeof uri !== 'string')
+                throw Error('Missing glTF resource URI');
+            if (uri.startsWith('data:')) {
+                const m = uri.match(/^data:[^;,]+;base64,([a-zA-Z0-9+/=\s]+)$/);
+                if (!m)
+                    throw Error('Unsupported data URI');
+                return Buffer.from(m[1], 'base64');
+            }
+            if (/^[a-z]+:/i.test(uri) || uri.startsWith('/') || uri.includes('\\'))
+                throw Error('Remote/absolute glTF resources are forbidden');
+            // ../ within the selected root is allowed for ordinary exporter layouts; never outside it.
+            const p = relative(this.job.root, resolve(this.job.root, dirname(a.path), decodeURIComponent(uri)));
+            const data = await readSource(this.job.root, p);
+            if (a.details.resources?.[p] !== digest(data))
+                throw Error('glTF dependency changed after analysis; analyze again');
+            return data;
+        };
+        for (const b of doc.buffers ?? []) {
+            const content = await resource(b.uri);
+            if (content.length < b.byteLength)
+                throw Error('Truncated glTF buffer');
+            offsets.push(append(content));
+        }
+        for (const v of doc.bufferViews ?? []) {
+            if (offsets[v.buffer] === undefined)
+                throw Error('Invalid glTF buffer binding');
+            v.byteOffset = (v.byteOffset ?? 0) + offsets[v.buffer];
+            v.buffer = 0;
+        }
+        for (const image of doc.images ?? [])
+            if (image.uri) {
+                const uri = image.uri, content = await resource(uri), mime = uri.startsWith('data:') ? uri.slice(5, uri.indexOf(';')) : /\.png$/i.test(uri) ? 'image/png' : /\.webp$/i.test(uri) ? 'image/webp' : /\.jpe?g$/i.test(uri) ? 'image/jpeg' : null;
+                if (!mime)
+                    throw Error('Image requires PNG/JPEG/WebP conversion');
+                doc.bufferViews ??= [];
+                image.bufferView = doc.bufferViews.length;
+                image.mimeType = mime;
+                doc.bufferViews.push({ buffer: 0, byteOffset: append(content), byteLength: content.length });
+                delete image.uri;
+            }
+        doc.buffers = [{ byteLength: total }];
+        const json = Buffer.from(JSON.stringify(doc)), padded = Buffer.concat([json, Buffer.alloc((4 - json.length % 4) % 4, 32)]), binary = Buffer.concat(chunks);
+        const header = Buffer.alloc(20);
+        header.writeUInt32LE(0x46546c67);
+        header.writeUInt32LE(2, 4);
+        header.writeUInt32LE(28 + padded.length + binary.length, 8);
+        header.writeUInt32LE(padded.length, 12);
+        header.writeUInt32LE(0x4e4f534a, 16);
+        const bh = Buffer.alloc(8);
+        bh.writeUInt32LE(binary.length);
+        bh.writeUInt32LE(0x004e4942, 4);
+        return { bytes: Buffer.concat([header, padded, bh, binary]), filename: basename(a.path, '.gltf') + '.glb' };
+    }
+    async import_to_gripforge(key) {
+        const job = this.job;
+        if (!job.report || !job.rights || !job.origin || !job.workspace || !job.selected?.length)
+            throw Error('Analysis, selection, workspace and rights basis required');
+        const headers = { 'x-api-key': key, 'x-workspace-id': job.workspace, 'x-gripforge-client': 'mcp' };
+        const request = async (body, json = false) => {
+            for (let attempt = 0; attempt < 6; attempt++) {
+                if (await this.cancelled())
+                    throw Error('Import cancelled');
+                const res = await fetch(job.origin + '/api/v1/game-imports', { method: 'POST', headers: { ...headers, ...(json ? { 'content-type': 'application/json' } : {}) }, body, signal: AbortSignal.timeout(120000) });
+                const result = await res.json();
+                if (res.status === 503 && result.code === 'import_busy' && attempt < 5) {
+                    await new Promise(r => setTimeout(r, Math.min(5000, 1000 * (attempt + 1))));
+                    continue;
+                }
+                if (!res.ok)
+                    throw Error(String(result.error ?? `HTTP ${res.status}`));
+                return result;
+            }
+            throw Error('Import persistence lane unavailable; resume later');
+        };
+        await request(JSON.stringify({ report: job.report, rights: job.rights }), true);
+        job.total = job.selected.length;
+        job.completed = job.selected.filter(id => job.receipts[id]).length;
+        await this.checkpoint();
+        for (const id of job.selected) {
+            if (job.receipts[id])
+                continue;
+            await this.checkpoint();
+            const a = job.report.assets.find(a => a.id === id);
+            if (!a)
+                throw Error('Selected asset not in inventory');
+            try {
+                const output = await this.normalize_assets(a), form = new FormData();
+                form.set('job_id', job.id);
+                form.set('asset_id', a.id);
+                form.set('file', new Blob([new Uint8Array(output.bytes)]), output.filename);
+                const result = await request(form);
+                job.receipts[id] = { itemId: result.item.id, revision: result.revision?.revisionId, studioUrl: result.studio_url };
+                delete job.errors[id];
+                job.completed++;
+            }
+            catch (e) {
+                job.errors[id] = e instanceof Error ? e.message : String(e);
+            }
+            await this.checkpoint();
+        }
+        job.status = job.selected.some(id => !job.receipts[id]) ? 'failed' : 'completed';
+        await this.checkpoint();
+    }
+}
+/** Exclusive per-job worker lease. Dead workers can be resumed without discarding receipts. */
+export async function claimImportJob(id) {
+    const lock = join(jobDirectory(id), 'worker.lock');
+    try {
+        const old = Number(await readFile(lock, 'utf8'));
+        try {
+            process.kill(old, 0);
+            throw Error('A worker is already running for this import');
+        }
+        catch (e) {
+            if (e.code !== 'ESRCH')
+                throw e;
+        }
+        await unlink(lock);
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    await writeFile(lock, String(process.pid), { flag: 'wx', mode: 0o600 });
+    return async () => { await unlink(lock).catch(() => { }); };
+}

package/dist/game-import-extract.js

@@ -0,0 +1,71 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mkdir, readdir, realpath, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { GameImportAgent, confinedFile, saveImportJob, jobDirectory } from './game-import-agent.js';
+const exec = promisify(execFile);
+/** Explicit adapters; never execute a binary discovered inside the source game. */
+export async function extractGame(job) {
+    const e = job.extraction;
+    if (!e || !job.rights || !job.report)
+        throw Error('Extraction plan and authorized rights basis required');
+    if (job.report.engine.name !== 'unity')
+        throw Error('This adapter only handles Unity. Use the existing Unreal source-project exporter for Unreal.');
+    // Preserve the original discovery graph before an extractor replaces the active inventory.
+    await writeFile(join(jobDirectory(job.id), 'source-report.json'), JSON.stringify(job.report, null, 2), { flag: 'wx', mode: 0o600 }).catch(error => { if (error.code !== 'EEXIST')
+        throw error; });
+    await mkdir(e.output, { recursive: true, mode: 0o700 });
+    const agent = new GameImportAgent(job);
+    await agent.checkpoint();
+    if (!e.completed) {
+        if (e.tool === 'assetripper') {
+            const url = new URL(e.endpoint ?? '');
+            if (url.protocol !== 'http:' || !['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname) || url.username || url.password || url.pathname !== '/')
+                throw Error('AssetRipper requires a dedicated local loopback HTTP instance');
+            // Version-compatible route discovery prevents invoking imaginary CLI options or a different local service.
+            const spec = await fetch(new URL('/openapi/v1.json', url), { signal: AbortSignal.timeout(10000) });
+            if (!spec.ok)
+                throw Error('AssetRipper OpenAPI unavailable; use a compatible web build or manual export');
+            const api = await spec.json();
+            if (!api.paths?.['/LoadFolder']?.post || !api.paths?.['/Export/PrimaryContent']?.post)
+                throw Error('AssetRipper API lacks required export routes');
+            e.version = String(api.info?.version ?? 'unreported');
+            await saveImportJob(job);
+            const post = async (route, path) => { await agent.checkpoint(); const res = await fetch(new URL(route, url), { method: 'POST', body: new URLSearchParams({ Path: path, CreateSubfolder: 'false' }), redirect: 'manual', signal: AbortSignal.timeout(20 * 60 * 1000) }); if (![200, 302, 303].includes(res.status))
+                throw Error(`AssetRipper ${route}: HTTP ${res.status}`); };
+            await post('/LoadFolder', e.sourceRoot);
+            await post('/Export/PrimaryContent', e.output);
+            if (!(await readdir(e.output)).length)
+                throw Error('Extractor returned no files; inspect AssetRipper failed-file log');
+        }
+        else {
+            const bin = process.env[e.tool === 'cpp2il' ? 'GRIPFORGE_CPP2IL_BIN' : 'GRIPFORGE_ILSPY_BIN'];
+            if (!bin)
+                throw Error(`Configure the installed ${e.tool} executable; no automatic installation`);
+            const version = await exec(bin, ['--version'], { cwd: e.output, timeout: 10000, maxBuffer: 1024 * 1024 }).catch(() => ({ stdout: 'version not reported' }));
+            e.version = version.stdout.trim().slice(0, 200);
+            await saveImportJob(job);
+            const args = e.tool === 'cpp2il' ? ['--game-path', e.sourceRoot, '--output-to', e.output] : ['--disable-updatecheck', '-p', '-o', e.output, await confinedFile(e.sourceRoot, job.report.assets.find(a => /(?:^|\/)Managed\/Assembly-CSharp\.dll$/i.test(a.path))?.path ?? '')];
+            await exec(bin, args, { cwd: e.output, timeout: 20 * 60 * 1000, maxBuffer: 4 * 1024 * 1024 });
+            job.report.warnings.push(`${e.tool} metadata/code exported locally to ${e.tool}-output. It is not a mesh extraction and is never uploaded to the Library.`);
+        }
+        e.completed = true;
+        await agent.checkpoint();
+    }
+    if (e.tool === 'assetripper') {
+        const engine = job.report.engine, source = job.report.source;
+        job.root = await realpath(e.output);
+        job.phase = 'analyze';
+        const report = await new GameImportAgent(job).analyze();
+        report.source = source;
+        report.engine = engine;
+        report.toolchain = agent.select_toolchain(engine);
+        report.warnings.push('Inventory is from AssetRipper export; native Unity formats still require their own converter.');
+        await saveImportJob(job);
+    }
+    else {
+        job.phase = 'analyze';
+        job.status = 'awaiting_selection';
+        await saveImportJob(job);
+    }
+}

package/dist/game-import-normalize.js

@@ -0,0 +1,72 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mkdir, readFile, writeFile, stat } from 'node:fs/promises';
+import { basename, join, isAbsolute, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+import { GameImportAgent, confinedFile, inspectAsset, jobDirectory, saveImportJob } from './game-import-agent.js';
+const exec = promisify(execFile), hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
+export function normalizedPath(job, id, format) { return join(jobDirectory(job.id), 'normalized', id, 'output.' + format); }
+/** Local durable conversions. Completed files survive cancellation/crashes; original sources are never modified. */
+export async function normalizeGame(job) {
+    if (!job.report || !job.selected?.length || !job.rights)
+        throw Error('Select sources and provide a rights basis');
+    const bin = process.env.GRIPFORGE_BLENDER_BIN;
+    if (!bin || !isAbsolute(bin))
+        throw Error('Configure GRIPFORGE_BLENDER_BIN with an installed Blender executable');
+    const agent = new GameImportAgent(job);
+    job.total = job.selected.length;
+    job.completed = 0;
+    for (const id of job.selected) {
+        await agent.checkpoint();
+        const asset = job.report.assets.find(a => a.id === id);
+        if (!asset || !['fbx', 'obj', 'dds', 'tga'].includes(asset.format))
+            throw Error('Blender normalization supports FBX/OBJ/DDS/TGA only');
+        const source = await readFile(await confinedFile(job.root, asset.path));
+        if (hash(source) !== asset.sha256)
+            throw Error('Source changed after analysis; analyze again');
+        const format = ['dds', 'tga'].includes(asset.format) ? 'png' : 'glb', output = normalizedPath(job, id, format), dir = dirname(output);
+        await mkdir(join(dir, 'source'), { recursive: true, mode: 0o700 });
+        try {
+            let bytes;
+            if (asset.details.normalization) {
+                const cached = await readFile(output).catch(() => undefined);
+                if (cached && hash(cached) === asset.details.normalization.sha256)
+                    bytes = cached;
+            }
+            if (!bytes) {
+                const input = join(dir, 'source', basename(asset.path));
+                await writeFile(input, source, { mode: 0o600 });
+                // Staging excludes source scripts and arbitrary external references. Embedded FBX materials are retained.
+                // OBJ material sidecars need explicit portable export: never follow unvalidated MTL references in Blender.
+                if (asset.format === 'obj' && /^\s*mtllib\s/m.test(source.toString()))
+                    throw Error('OBJ references an MTL sidecar; export a self-contained GLB or embedded FBX to preserve PBR');
+                const plan = join(dir, 'plan.json'), receipt = join(dir, 'receipt.json');
+                await writeFile(plan, JSON.stringify({ input, output, receipt }), { mode: 0o600 });
+                await exec(bin, ['--background', '--factory-startup', '--disable-autoexec', '--python-exit-code', '1', '--python', fileURLToPath(new URL('../runtime/game-import-normalize.py', import.meta.url)), '--', plan], { cwd: dir, timeout: 20 * 60 * 1000, maxBuffer: 4 * 1024 * 1024 });
+                await agent.checkpoint();
+                if ((await stat(output)).size > 256 * 1024 * 1024)
+                    throw Error('Normalized output exceeds 256 MiB');
+                bytes = await readFile(output);
+                const inspected = inspectAsset('output.' + format, bytes);
+                if (inspected.status !== 'ready')
+                    throw Error('Converter output is not a portable asset: ' + inspected.reason);
+                const version = String(JSON.parse(await readFile(receipt, 'utf8')).version).slice(0, 100);
+                asset.details = { ...asset.details, ...inspected.details, normalization: { format, sha256: hash(bytes), sourceSha256: asset.sha256, tool: 'blender', version } };
+                asset.evidence.push({ source: asset.path, reason: 'Blender conversion preserving available materials/rig/clips; visual and anatomy review required', confidence: 1 });
+            }
+            if (format === 'png')
+                asset.kind = 'texture';
+            asset.status = 'ready';
+            delete asset.reason;
+            delete job.errors[id];
+            job.completed++;
+        }
+        catch (e) {
+            job.errors[id] = e instanceof Error ? e.message : String(e);
+        }
+        await saveImportJob(job);
+    }
+    job.status = job.selected.some(id => job.errors[id]) ? 'failed' : 'awaiting_selection';
+    await saveImportJob(job);
+}

package/dist/game-import-reverse.js

@@ -0,0 +1,122 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { z } from 'zod/v4';
+import { readFile, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { confinedFile, jobDirectory, loadImportJob } from './game-import-agent.js';
+/** Detect containers locally before recommending native code investigation. No binaries are executed. */
+export function detectFormat(bytes) {
+    if (bytes.subarray(0, 4).equals(Buffer.from([0x7f, 69, 76, 70])))
+        return { format: 'ELF', native: true };
+    if (bytes.toString('ascii', 0, 2) === 'MZ')
+        return { format: 'PE', native: true };
+    if (bytes.length >= 4 && [0xfeedface, 0xfeedfacf, 0xcafebabe, 0xcefaedfe, 0xcffaedfe].includes(bytes.readUInt32BE()))
+        return { format: 'Mach-O', native: true };
+    for (const [magic, format] of [['glTF', 'GLB'], ['UnityFS', 'Unity bundle'], ['DDS ', 'DDS'], ['PK\u0003\u0004', 'ZIP']])
+        if (bytes.toString('latin1', 0, magic.length) === magic)
+            return { format, native: false };
+    return { format: 'unknown', native: false };
+}
+function endpoint() {
+    const url = new URL(process.env.GRIPFORGE_GHIDRA_MCP_URL ?? '');
+    if (url.protocol !== 'http:' || !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname) || url.username || url.password)
+        throw Error('Configure a dedicated loopback GRIPFORGE_GHIDRA_MCP_URL (for example http://127.0.0.1:8081/mcp)');
+    return url;
+}
+async function bridge(run) {
+    const client = new Client({ name: 'gripforge-game-import', version: '1.0' });
+    try {
+        await client.connect(new StreamableHTTPClientTransport(endpoint()));
+        return await run(client);
+    }
+    finally {
+        await client.close().catch(() => { });
+    }
+}
+async function call(client, name, args) {
+    const tool = (await client.listTools()).tools.find(t => t.name === name);
+    if (!tool)
+        throw Error('Compatible Ghidra tool unavailable: ' + name);
+    for (const key of tool.inputSchema.required ?? [])
+        if (!(key in args))
+            throw Error(`Installed Ghidra requires ${key} for ${name}; incompatible adapter contract`);
+    const response = await client.callTool({ name, arguments: args }, undefined, { timeout: 120000 });
+    if (response.isError)
+        throw Error(JSON.stringify(response.content).slice(0, 4000));
+    return response;
+}
+export function registerReverseTools(register) {
+    const jobId = z.string().regex(/^gi_[a-f0-9]{24}$/), path = z.string().min(1).max(4096);
+    const wrap = (run) => async (a) => { try {
+        return { content: [{ type: 'text', text: JSON.stringify(await run(a), null, 2) }] };
+    }
+    catch (e) {
+        return { isError: true, content: [{ type: 'text', text: e instanceof Error ? e.message : String(e) }] };
+    } };
+    const common = { job_id: jobId };
+    register('gripforge_reverse_detect_format', { title: 'Inspect file magic before reverse engineering', description: 'Local signatures, source hash and known-format-first recommendation. Unknown remains unknown. Does not execute or alter the source.', inputSchema: { ...common, path }, annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false } }, wrap(async (a) => {
+        const job = await loadImportJob(a.job_id), bytes = await readFile(await confinedFile(job.root, a.path)), found = detectFormat(bytes);
+        return { ...found, sha256: createHash('sha256').update(bytes).digest('hex'), next: found.native ? 'gripforge_reverse_open' : 'Known extractor/converter first; unknown data needs a format-specific investigation, not automatic native decompilation' };
+    }));
+    register('gripforge_reverse_open', { title: 'Open an authorized native binary in Ghidra', description: 'Imports a copy into a dedicated installed Ghidra analysis project, without running the binary. Requires a finished local import job, native file signature and rights basis. Records hash and explicit program selector, so later reads never depend on the shared current program. No extraction or visual approval is implied.', inputSchema: { ...common, path, rights: z.object({ basis: z.enum(['owned', 'authorized', 'compatible-license']), note: z.string().min(3).max(1000) }).strict() }, annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false } }, wrap(async (a) => {
+        const job = await loadImportJob(a.job_id), file = await confinedFile(job.root, a.path), bytes = await readFile(file);
+        if (!detectFormat(bytes).native)
+            throw Error('Use a known extractor or inspect the data format first; this is not a recognized native binary');
+        const response = await bridge(c => call(c, 'import_file', { file_path: file, project_folder: '/' + job.id, auto_analyze: true }));
+        const content = response.content;
+        let program;
+        for (const block of content)
+            if (block.text) {
+                try {
+                    const json = JSON.parse(block.text);
+                    program = json.data?.name ?? json.name;
+                }
+                catch { }
+            }
+        if (!program)
+            throw Error('Ghidra did not report the imported program name; no ambiguous current-program session saved');
+        const session = { path: a.path, sha256: createHash('sha256').update(bytes).digest('hex'), program: '/' + job.id + '/' + basename(program), endpoint: endpoint().href };
+        await writeFile(join(jobDirectory(job.id), 'reverse-session.json'), JSON.stringify({ ...session, rights: a.rights }), { mode: 0o600 });
+        return { program: session.program, sha256: session.sha256, analysis: response, next: 'gripforge_reverse_scan', source_unchanged: true };
+    }));
+    // A deliberately small allowlist. Upstream rename/patch/execute tools are never passed through.
+    for (const [name, tool, description, query, group] of [
+        ['gripforge_reverse_scan', 'find_functions', 'List native functions with an explicit program selector', false, 'listing'],
+        ['gripforge_reverse_find_asset_system', 'search_strings', 'Search native strings for asset loading/format clues; results are evidence, not inferred assets', true, 'listing'],
+        ['gripforge_reverse_trace_function', 'get_functions', 'Read one native function to investigate an asset loader; never changes executable code', true, 'function'],
+    ]) {
+        register(name, { title: description, description: 'Configured local Ghidra MCP bridge only. Verifies source hash and installed tool schema. Bounded output and persisted evidence; no unsupported converter is invented. ' + description, inputSchema: { ...common, ...(query ? { query: z.string().min(1).max(256) } : {}), offset: z.number().int().min(0).optional(), limit: z.number().int().min(1).max(100).optional() }, annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false } }, wrap(async (a) => {
+            const job = await loadImportJob(a.job_id), session = JSON.parse(await readFile(join(jobDirectory(job.id), 'reverse-session.json'), 'utf8'));
+            if (session.endpoint !== endpoint().href)
+                throw Error('Ghidra endpoint changed; open the binary again');
+            const bytes = await readFile(await confinedFile(job.root, session.path));
+            if (createHash('sha256').update(bytes).digest('hex') !== session.sha256)
+                throw Error('Binary changed; open it again');
+            const response = await bridge(async (c) => {
+                if (!(await c.listTools()).tools.some(t => t.name === tool))
+                    await call(c, 'load_tool_group', { group });
+                const schema = (await c.listTools()).tools.find(t => t.name === tool)?.inputSchema;
+                if (!schema?.properties?.program)
+                    throw Error('Installed Ghidra tool lacks explicit program selection; update the bridge');
+                const args = { program: session.program };
+                if (schema.properties.offset)
+                    args.offset = a.offset ?? 0;
+                if (schema.properties.limit)
+                    args.limit = a.limit ?? 40;
+                if (tool === 'get_functions' && schema.properties.fields)
+                    args.fields = 'decompiled_code,callers,callees,signature';
+                if (query) {
+                    const key = tool === 'get_functions' ? ['function', 'address', 'function_address', 'name', 'function_name'].find(k => schema.properties?.[k]) : ['query', 'search', 'search_term', 'filter'].find(k => schema.properties?.[k]);
+                    if (!key)
+                        throw Error('Installed Ghidra query schema incompatible');
+                    args[key] = a.query;
+                }
+                return call(c, tool, args);
+            });
+            const evidence = { source_sha256: session.sha256, program: session.program, operation: tool, query: a.query, observed_at: new Date().toISOString(), result: JSON.stringify(response).slice(0, 64000) };
+            await writeFile(join(jobDirectory(job.id), 'reverse-' + tool + '.json'), JSON.stringify(evidence), { mode: 0o600 });
+            return evidence;
+        }));
+    }
+}

package/dist/game-import-tools.js

@@ -0,0 +1,138 @@
+import { spawn } from 'node:child_process';
+import { open, writeFile, unlink, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod/v4';
+import { jobDirectory, loadImportJob, newImportJob, saveImportJob } from './game-import-agent.js';
+async function launch(job, key) {
+    const log = await open(join(jobDirectory(job.id), 'worker.log'), 'a', 0o600);
+    try {
+        const child = spawn(process.execPath, [fileURLToPath(new URL('./game-import-worker.js', import.meta.url)), job.id], { detached: true, stdio: ['ignore', log.fd, log.fd], env: { ...process.env, ...(key ? { GRIPFORGE_API_KEY: key } : {}) } });
+        await new Promise((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject); });
+        child.unref();
+    }
+    finally {
+        await log.close();
+    }
+}
+async function assertIdle(id) {
+    try {
+        const pid = Number(await readFile(join(jobDirectory(id), 'worker.lock'), 'utf8'));
+        try {
+            process.kill(pid, 0);
+        }
+        catch (e) {
+            if (e.code === 'ESRCH')
+                return;
+            throw e;
+        }
+        throw Error('Worker still running; cancel and wait for it to finish');
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+}
+export function registerGameImportTools(register, options) {
+    const result = (data) => ({ content: [{ type: 'text', text: JSON.stringify(data, null, 2) }], structuredContent: data });
+    const wrap = (run) => async (a) => { try {
+        return result(await run(a));
+    }
+    catch (e) {
+        return { isError: true, content: [{ type: 'text', text: e instanceof Error ? e.message : String(e) }] };
+    } };
+    const id = z.string().regex(/^gi_[a-f0-9]{24}$/);
+    const summary = (job) => ({ job_id: job.id, status: job.status, phase: job.phase, progress: { completed: job.completed, total: job.total }, engine: job.report?.engine, counts: job.report?.counts, errors: job.errors, imported: job.receipts, report_path: join(jobDirectory(job.id), 'report.json'), library_url: `${options.apiUrl}/library`, next: job.status === 'awaiting_selection' ? 'Read inventory, select asset ids, then gripforge_game_import_select' : 'gripforge_game_import_read' });
+    register('gripforge_game_import', {
+        title: 'Analyze an authorized local game or project',
+        description: 'LOCAL MCP ONLY. Analyze → discover → classify → normalize → private Library import. Starts a detached durable local job; returns immediately. Known portable formats first, Unity GUID relations carry evidence, unsupported formats stay blocked with an explicit toolchain. Does not launch the game, bypass encryption, guess sockets or claim behavior/visual validation. Read the inventory and select before uploading. Closing the MCP or Studio does not delete progress; read/resume by job_id. Analysis is free and local. Source files remain unchanged.',
+        inputSchema: { path: z.string().min(1).max(4096) }, annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, wrap(async (a) => { const job = await newImportJob(a.path); await launch(job); return summary(job); }));
+    register('gripforge_game_import_read', {
+        title: 'Read game import progress and inventory', description: 'Read persistent local state with paginated assets, role confidence, extraction blockers and verified relationship edges. The report_path can be opened in Library → Add asset → From Game. Unknown/bundled files are not counted as successfully imported assets.',
+        inputSchema: { job_id: id, kind: z.string().max(40).optional(), offset: z.number().int().min(0).optional(), limit: z.number().int().min(1).max(100).optional() }, annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, wrap(async (a) => { const job = await loadImportJob(a.job_id), all = (job.report?.assets ?? []).filter(x => !a.kind || x.kind === a.kind); return { ...summary(job), total: all.length, assets: all.slice(a.offset ?? 0, (a.offset ?? 0) + (a.limit ?? 40)), toolchain: job.report?.toolchain, normalization: job.report?.normalization, warnings: job.report?.warnings, relationships: job.report?.relationships }; }));
+    register('gripforge_game_import_extract', {
+        title: 'Run the selected known Unity extractor', description: 'LOCAL ONLY. Dedicated AssetRipper loopback HTTP adapter for assets; installed Cpp2IL/ILSpy adapters for local code/metadata only. The agent chooses AssetRipper first unless tool is explicit. Uses durable output/checkpoints and rescans exported assets; never executes game code. Requires installed tools configured in the MCP environment, compatible OpenAPI routes and an authorization basis. No Ghidra fallback is silently invoked. Tools/version and errors remain visible. Cancellation is checked between external operations, each bounded to 20 minutes.',
+        inputSchema: { job_id: id, tool: z.enum(['assetripper', 'cpp2il', 'ilspy']).optional(), rights: z.object({ basis: z.enum(['owned', 'authorized', 'compatible-license']), note: z.string().min(3).max(1000) }).strict() }, annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, wrap(async (a) => { await assertIdle(a.job_id); const job = await loadImportJob(a.job_id); if (!job.report || job.report.engine.name !== 'unity')
+        throw Error('Finish Unity analysis first'); if (Object.keys(job.receipts).length)
+        throw Error('Start a new import before extracting a different inventory'); const tool = a.tool ?? 'assetripper'; if (tool === 'cpp2il' && job.report.engine.runtime !== 'IL2CPP')
+        throw Error('Cpp2IL requires IL2CPP evidence'); if (tool === 'ilspy' && job.report.engine.runtime !== 'Mono')
+        throw Error('ILSpy requires Mono evidence'); if (job.extraction && job.extraction.tool !== tool)
+        throw Error('Start a separate analysis job for another extractor'); job.extraction ??= { tool, sourceRoot: job.root, output: join(jobDirectory(job.id), tool + '-output'), ...(tool === 'assetripper' ? { endpoint: process.env.GRIPFORGE_ASSETRIPPER_URL } : {}) }; job.rights = a.rights; job.phase = 'extract'; job.status = 'queued'; await unlink(join(jobDirectory(job.id), 'cancel')).catch(() => { }); await saveImportJob(job); await launch(job); return summary(job); }));
+    register('gripforge_game_import_select', {
+        title: 'Import selected game assets into a private workspace', description: 'Requires an analyzed local job, explicit source ids, workspace id and rights basis. Self-contained GLB and standard images/audio import directly; glTF packs its local resources into GLB. Engine-native formats require extraction first. Durable per-file checkpoints and server idempotency preserve completed imports across retries. Saved as work revisions, never published/promoted. Storage quotas apply; no paid AI call. Relations remain a knowledge graph and Game Kit suggestions require actual gameplay integration.',
+        inputSchema: { job_id: id, asset_ids: z.array(z.string().regex(/^src_[a-f0-9]{24}$/)).min(1).max(500), workspace_id: z.string().regex(/^ws_[A-Za-z0-9_-]+$/), rights: z.object({ basis: z.enum(['owned', 'authorized', 'compatible-license']), note: z.string().min(3).max(1000) }).strict() }, annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, wrap(async (a) => {
+        const key = options.getApiKey();
+        if (!key)
+            throw Error('GripForge API key required');
+        await assertIdle(a.job_id);
+        const job = await loadImportJob(a.job_id);
+        if (!job.report || job.completed < job.total && job.phase === 'analyze')
+            throw Error('Finish analysis before selecting assets');
+        if (job.workspace && job.workspace !== a.workspace_id)
+            throw Error('Start a new import to target another workspace');
+        const selected = [...new Set(a.asset_ids)];
+        for (const id of selected) {
+            const asset = job.report.assets.find(x => x.id === id);
+            if (!asset || asset.status === 'blocked')
+                throw Error(`Asset unavailable for import: ${id}`);
+        }
+        job.phase = 'import';
+        job.selected = selected;
+        job.rights = a.rights;
+        job.workspace = a.workspace_id;
+        job.origin = options.apiUrl.replace(/\/$/, '');
+        job.status = 'queued';
+        delete job.errors.worker;
+        await unlink(join(jobDirectory(job.id), 'cancel')).catch(() => { });
+        await saveImportJob(job);
+        await launch(job, key);
+        return summary(job);
+    }));
+    register('gripforge_game_import_normalize', {
+        title: 'Convert selected extracted assets with Blender',
+        description: 'LOCAL durable worker. Installed GRIPFORGE_BLENDER_BIN converts FBX/OBJ to GLB and DDS/TGA to PNG. Keeps available PBR, rig and animations; does not fabricate missing materials or validate appearance. Sources remain unchanged; checksummed outputs persist for resume. OBJ with external MTL and missing FBX textures fail explicitly; export embedded materials first. Run before registration/import. Source engine scenes still require their known exporter.',
+        inputSchema: { job_id: id, asset_ids: z.array(z.string().regex(/^src_[a-f0-9]{24}$/)).min(1).max(500), rights: z.object({ basis: z.enum(['owned', 'authorized', 'compatible-license']), note: z.string().min(3).max(1000) }).strict() },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, wrap(async (a) => {
+        await assertIdle(a.job_id);
+        const job = await loadImportJob(a.job_id);
+        if (!job.report || Object.keys(job.receipts).length || job.workspace)
+            throw Error('Normalize an analyzed inventory before registering/importing it');
+        for (const assetId of a.asset_ids)
+            if (!job.report.assets.some(x => x.id === assetId && ['fbx', 'obj', 'dds', 'tga'].includes(x.format)))
+                throw Error('Select FBX/OBJ/DDS/TGA inventory sources');
+        job.phase = 'normalize';
+        job.selected = [...new Set(a.asset_ids)];
+        job.rights = a.rights;
+        job.status = 'queued';
+        await unlink(join(jobDirectory(job.id), 'cancel')).catch(() => { });
+        await saveImportJob(job);
+        await launch(job);
+        return summary(job);
+    }));
+    register('gripforge_game_import_control', {
+        title: 'Cancel or resume a local game import', description: 'Cancel between files; an already committed upload remains imported. Resume preserves successful receipts and checkpoints. After a worker crash, resume with the same job_id. Credentials are supplied by the current MCP session, never saved in the job report.',
+        inputSchema: { job_id: id, action: z.enum(['cancel', 'resume']) }, annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, wrap(async (a) => {
+        const job = await loadImportJob(a.job_id);
+        if (a.action === 'cancel') {
+            await writeFile(join(jobDirectory(job.id), 'cancel'), 'cancel', { mode: 0o600 });
+            await assertIdle(job.id).then(async () => { job.status = 'cancelled'; await saveImportJob(job); }).catch(() => { });
+        }
+        else {
+            await assertIdle(job.id);
+            if (job.phase === 'import' && !options.getApiKey())
+                throw Error('API key required to resume import');
+            await unlink(join(jobDirectory(job.id), 'cancel')).catch(() => { });
+            job.status = 'queued';
+            delete job.errors.worker;
+            await saveImportJob(job);
+            await launch(job, options.getApiKey() ?? undefined);
+        }
+        return summary(job);
+    }));
+}

package/dist/game-import-types.js

@@ -0,0 +1 @@
+export {};

package/dist/game-import-worker.js

@@ -0,0 +1,34 @@
+import { GameImportAgent, claimImportJob, loadImportJob, saveImportJob } from './game-import-agent.js';
+import { normalizeGame } from './game-import-normalize.js';
+import { extractGame } from './game-import-extract.js';
+const id = process.argv[2];
+const release = await claimImportJob(id);
+const job = await loadImportJob(id);
+try {
+    job.status = 'running';
+    job.workerPid = process.pid;
+    await saveImportJob(job);
+    const agent = new GameImportAgent(job);
+    if (job.phase === 'normalize')
+        await normalizeGame(job);
+    else if (job.phase === 'extract')
+        await extractGame(job);
+    else if (job.phase === 'analyze')
+        await agent.analyze();
+    else {
+        const key = process.env.GRIPFORGE_API_KEY;
+        if (!key)
+            throw Error('API key required to resume import');
+        await agent.import_to_gripforge(key);
+    }
+}
+catch (e) {
+    job.status = await new GameImportAgent(job).cancelled() ? 'cancelled' : 'failed';
+    job.errors.worker = e instanceof Error ? e.message : String(e);
+    await saveImportJob(job);
+}
+finally {
+    delete job.workerPid;
+    await saveImportJob(job);
+    await release();
+}

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,6 +13,8 @@ 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',
@@ -279,6 +282,34 @@ 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_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.'),

package/dist/scene-tools.js

@@ -138,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 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gripforgeai/mcp",
-  "version": "0.1.16",
-  "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.18",
+  "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}))