@gripforgeai/mcp 0.1.10 → 0.1.11

package/README.md

@@ -6,7 +6,87 @@ Turn prompts into production-ready game assets — animated characters with thei
 
 MCP client for the [GripForge](https://gripforge.ai) API — from Claude Code, Cursor, Windsurf, VS Code or any MCP client.
 
-## Hosted endpoint (zero install)
+## How to use
+
+**Hosted — nothing to install.** Point any remote-capable MCP client at `https://gripforge.ai/mcp`
+with your API key ([create one here](https://gripforge.ai/account)):
+
+```jsonc
+{
+  "mcpServers": {
+    "gripforge": {
+      "url": "https://gripforge.ai/mcp",
+      "headers": { "x-api-key": "gf_..." }
+    }
+  }
+}
+```
+
+**Claude Code**, in one line:
+
+```bash
+claude mcp add --transport http gripforge https://gripforge.ai/mcp --header "x-api-key: gf_..."
+```
+
+**Local, via npm** — when the agent must write files into your repository:
+
+```jsonc
+{
+  "mcpServers": {
+    "gripforge": {
+      "command": "npx",
+      "args": ["-y", "@gripforgeai/mcp"],
+      "env": { "GRIPFORGE_API_KEY": "gf_..." }
+    }
+  }
+}
+```
+
+## Key features
+
+- **Characters that move.** Describe one, get a rigged T-pose with an animation set — idle, run,
+  attack — ready to drop into a scene.
+- **Weapons in hand.** GripForge finds the hand bone on any rig, scales the prop, closes the fist
+  around the grip, and returns the bind plus Three.js, Unity and Godot snippets.
+- **Seamless textures.** Tileable material sets from a prompt or from your own image, upscaled
+  without invention.
+- **Terrain and maps.** Playable room graphs, top-down shooter layouts with spawns and lanes,
+  greybox reconstruction from references.
+- **VFX and HUD.** Animated effects and interface kits exported for your engine.
+- **Playable game kits.** Assemble modular capabilities — movement, combat, enemies, worlds — into
+  a game that runs in the browser, then bind your own assets to it.
+- **One Library.** Everything generated lands in a locker your engine can pull from, and that your
+  agent can search by look ("Devil May Cry like", "open world adventure").
+
+## Use cases
+
+- *"Attach this sword to my knight, right hand, then export the armed GLB."* — the agent handles the
+  bone, the scale and the fist; you get a file that loads.
+- *"Make me a boss for an ashen underworld, with three phases and an arena."* — stats, attacks and
+  engine snippets come back together.
+- *"Give this floor a mossy cobblestone texture that tiles."* — a seamless set, saved to the Library.
+- *"Build a playable roguelike slice I can try in the browser."* — a game kit project with its
+  assets bound, playable from a link.
+
+## FAQ
+
+**Do I need to install anything?** No. The hosted endpoint works from any MCP client that speaks
+streamable HTTP. The npm package exists for one reason: letting the agent write files directly into
+your repository.
+
+**Which engines are supported?** Unity, Godot, Unreal and Three.js — assets come with the binds and
+snippets each one expects.
+
+**How is it billed?** Credits, per generation. Reading the Library, animating an existing character,
+level and map kits cost nothing; generating a character or a weapon costs 10.
+
+**Where do my assets live?** In your workspace Library. You can pull them into your repository, push
+your own, and share them with the community catalog.
+
+**Can I use my own concept art?** Yes — pass an image and GripForge builds the T-pose sheet from it
+rather than inventing a character.
+
+## Hosted endpoint
 
 No Node required — point any remote-capable MCP client at:
 
@@ -85,19 +165,22 @@ Also works with Cursor, Windsurf and any MCP-compatible client — same
 `command` / `args` / `env` triple.
 
 
-## Tools
+## Tool reference
 
 Hosted HTTP MCP (`https://gripforge.ai/mcp`) is always current. This npm package
 writes files into the repo (`out_dir`), including `gripforge_hud`,
 `gripforge_hud_bar` and `gripforge_cape`. Hosted-only: `gripforge_make_seamless`.
 Full list: https://gripforge.ai/mcp-docs
 
-- `gripforge_style_kit` — resolve "Devil May Cry like" / "genshin" to locker ids
+- `gripforge_style_kit` — resolve "Devil May Cry like" / "open world adventure" to locker ids
   already tagged with that look. **Call this before generating.** Reuse the ids.
 - `gripforge_generate_character` — new T-pose + auto-rig into Library (10 credits).
   `kind=enemy` or the word "enemy" in the prompt. Skip this if style_kit already
   returned a character.
-- `gripforge_boss` — playable boss kit (stats, phases, attacks, arena, engine snippets).
+- `gripforge_boss` — boss configuration (stats, phases, attacks, arena, engine integration snippets). Rigging, clips and in-engine combat integration remain separate.
+- `gripforge_abilities` — reusable `combat.abilities` skills: `schema`, `example`, `validate`, `export`; executable adapters for Three.js, Godot, Unity and Unreal. Common timing/cost/cooldown/targeting; connect the game's combat and presentation backend. No rig or animation manufacture. Persist through gamekit config/data. 0 generation credits. See [abilities documentation](../../docs/abilities.md).
+- `gripforge_creature_rig_schema`, `gripforge_creature_analyze`, `gripforge_creature_rig` — reusable anatomy detection and Blender rigging for owned GLBs. Four annotated views → editable anatomy → new private rigged draft, starting clips, GLB, .blend and deformation report. Persistent progress/cancel/retry; source and validated assets stay intact. Review uncertain anatomy and inspect the result in Character Studio. [Creature rig documentation](../../docs/creature-rig.md).
+- `gripforge_architecture_schema`, `gripforge_generate_building`, `gripforge_generate_district` — free plan, optional building concepts (1–4 views conditioned on one master, saved to the workspace), visual review, then Meshy PBR manufacture. Separate concept/3D budgets; owned single/multi-image references, configurable geometry/texture quality, immutable Library assets and editable instances. Persistent progress/cancel/retry and Studio links; private work versions. [Architecture documentation](../../docs/architecture-generation.md).
   0 credits. Reuses a locker enemy. `generate=true` forges a new kind=enemy (10 credits).
   Then `gripforge_animate` with the returned archetype.
 - `gripforge_concept_correct` — concept image → strict T-pose sheet (1 credit).
@@ -125,6 +208,7 @@ Full list: https://gripforge.ai/mcp-docs
 - `gripforge_scene_kit` — locker props + suggested layout for a game look.
 - `gripforge_light_kit` / `gripforge_font` / `gripforge_navmesh` — lights+fog, webfont+ranks, walkable AABB. 0 credits.
 - `gripforge_input_kit` — FPS InputMap (WASD + arrows). Write input.json, autoload GfInput.
+- `gripforge_joystick_kit` — ready-to-integrate touch/mouse joystick files for Unreal, Godot, Unity and Three.js. Independent movement/look sticks, radial deadzone, continuous hold and focus/release reset. Free, shared with hosted MCP; see below.
   Optional `third_person: true` adds portable character-facing JavaScript and a
   Three.js integration example; the existing input map is unchanged. 0 credits.
 - `gripforge_viewmodel_kit` — CS-style FPS arms + gun under Camera3D/Hold. Write viewmodel.json + gf_viewmodel.gd. 0 credits.
@@ -168,6 +252,10 @@ Full parameters: https://gripforge.ai/mcp-docs
 - `gripforge_game_capabilities` — what the project provides, what is missing for a goal and which kits fill each gap.
 - `gripforge_game_project` — `action=list|create|get|bind|data|delete` on projects (bindings slot → `lib_…`, data collections, `confirm=true` to delete).
 - `gripforge_game_play_url` — browser play URL of the project's current revision (`{ url, absolute }`).
+- `gripforge_moba_map` — the map of a MOBA project as a gameplay plan: generate (1–5 lanes, divider), validate (lanes open, everything reachable), set.
+- `gripforge_ability_vfx` — a cast effect written and bound for every ability of a project (needs `fx.ability_vfx`; 0 credits).
+- `gripforge_terrain_map_use` — a terrain studio map (`lvl_…`) or a scene terrain becomes the world of a game with `world.terrain`: baked file bound to `terrain_map`, reference in `terrain_maps`.
+- `gripforge_moba_roster` — champions with an ability pack become the roster of a moba project (`moba_heroes`, `abilities`, `moba_hero_<n>` and `player_character` bindings).
 
 ## Character facing for third-person games
 
@@ -198,6 +286,22 @@ network systems. Omitting `third_person`, or setting it to `false`, returns the
 existing input kit without the additional section. The option is available in
 the hosted MCP and this source checkout; it is not in published npm `0.1.5`.
 
+## Asset production for games
+
+`gripforge_asset_search` searches real Library and Community assets, independently
+of the Game Kit catalogue. Filter by visual role (`q`), `kind`, `source` and the
+connected `workspace_id`. Search is free. `gripforge_asset_clone` copies a suitable
+Community item into the workspace; the first take costs one generation credit
+(one per piece for an armor set).
+
+Generate only missing roles. Keep a stable `idempotency_key` for each generation,
+save its returned `job_id`, poll `gripforge_generation_read`, then download and
+integrate the completed asset in the actual engine. A queued job is not a model.
+The hosted generation responses preserve job ids and progress/Studio URLs.
+
+These additions are available in the hosted MCP and this source checkout.
+Updating the hosted service does not update an installed npm package.
+
 ## Performance diagnostics
 
 `gripforge_performance` is included in this source checkout and the hosted MCP.
@@ -244,7 +348,174 @@ CPU/driver time already included in `cpuMs`; `gpuMs` is meaningful only when
 actually measured. This tool does not control a browser, change game settings,
 publish code or automatically fix a game.
 
+## Concept-first maps and Unreal references
+
+`gripforge_map_schema` describes the shared Map Studio generation workflow.
+`gripforge_map_generate` supports two separate persistent jobs:
+
+1. `stage: "concept"` saves a private master image and returns its immutable
+   `{assetId, revisionId}` reference. Optional `reference` is a pinned Library
+   image of an existing environment: it guides the art direction of a **new**
+   layout. Use `gripforge_scene_asset_pin` after importing a viewport screenshot.
+   Request `views: ["overview", "top_down", "entrance", "objective"]` for a
+   complete concept set. Every additional angle is conditioned on that same
+   pinned master. The overview is always included; omitting `views` keeps the
+   single-image workflow.
+2. Poll `gripforge_generation_read` with `include_preview: true` to receive all
+   available views, or add `preview_view: "entrance"` to see just one. Show the
+   concept to the user. These illustrations convey the intended appearance;
+   they do not establish exact geometry, scale or visibility. Verify those with
+   camera captures from the same built 3D scene.
+3. After selection, submit a new `stage: "build"` request with the returned
+   `concept`, a new idempotency key and the same workspace. The result contains
+   editable terrain, regions, paths, zones and independent asset instances in
+   the shared Scene Engine. `sources` can select `workspace`, `community` and/or
+   `catalog` resources. Inspect the actual scene before requesting visual review.
+
+Each newly generated concept image costs 1 credit: one for the master, up to
+three for additional views. To add angles without regenerating the chosen
+master, use `source_concept: {assetId, revisionId}` instead of `reference` in a
+new concept request. Reusing that master costs nothing; only new views are
+billed. A build job costs 1 credit. Cancellation and retry retain each completed
+view and avoid repeating successful image generation or billing. Neither stage
+promotes the validated version. Omitting `stage` preserves the existing build workflow.
+`concept_item` remains a legacy Library image shortcut; prefer `concept` to pin
+the precise chosen image even if the Library source is later replaced.
+
+```json
+{
+  "stage": "concept",
+  "prompt": "A new desert canyon for third-person melee combat, two open arenas and a raised shortcut",
+  "wizard": {
+    "style": "stylized", "world": "linear", "terrain": "desert_canyon",
+    "size": "medium", "dimensions": { "width": 500, "depth": 500 },
+    "boundary": "fixed", "spawn": "single", "boss": true
+  },
+  "reference": { "assetId": "lib_your_image", "revisionId": "rev_pinned_image" },
+  "views": ["overview", "top_down", "entrance", "objective"],
+  "idempotency_key": "desert-concept-01"
+}
+```
+
+The result exposes `concept_views` with each view's pinned `asset`, `image_url`
+and authenticated `preview_url`. `concept` and the suggested build request keep
+the master reference. To extend an existing concept, keep the prompt and wizard,
+replace `reference` with `source_concept`, list the additional views and use a new
+idempotency key. These options are part of this source checkout; they require a
+matching deployed API and an updated MCP client before use in production.
+
+`wizard.dimensions` sets width and depth in **metres** (100–5,000 each), overriding
+the size preset and world-type multiplier. Carry the same dimensions from concept
+to build. Explicitly dimensioned outdoor terrain uses those exact edge-to-edge
+bounds; decorative backdrops can extend beyond the playable footprint. Four-team
+maps require a square. Concept images communicate the intended scale; they are
+not a measured reconstruction. Omitting dimensions preserves legacy framing.
+
+For an existing Unreal project, the source checkout also provides
+`gripforge_map_unreal_reference_local`:
+
+```json
+{
+  "project_file": "/absolute/path/Game/Game.uproject",
+  "content_path": "/Game/StylizedDesertEnv"
+}
+```
+
+It inventories only the selected pack and returns native asset paths. It does
+not upload packages, decode mesh geometry, read editor actor transforms or
+write to the project. Kinds are directory hints until verified in Unreal.
+The hosted MCP cannot access a user's local disk. Build this checkout and run
+`packages/mcp-client/dist/server.js` to use the local tool; changing source code
+or deploying the website does not update an installed npm package.
+
+Native delivery uses the reusable `gripforge.unreal-scene.v1` adapter after concept
+selection. It consumes the **common SceneDocument**, a `.uproject`, a new level
+path, and pinned asset revision bindings. Map-specific layouts, asset choices and
+lighting values belong to the recipe, not the importer.
+
+For explicit 3D layouts, `gripforge_map_generate` also accepts `structure` with
+schema `gripforge.map-structures.v1`. Read `gripforge_map_schema` for a complete
+example. Terraces carry polygons and elevations; ramps/bridges name their
+endpoints, widths and slope/clearance limits. The common builder preserves canyon
+voids, rejects buried connections and creates separate surface/cliff/bridge
+assets with persistent per-piece checkpoints. Match `wizard.dimensions`; this
+branch currently supports solo maps with spawn and optional objective. Results
+are structural work versions requiring visual review and dressing. Existing
+callers without `structure` keep their previous generation pipeline.
+
+1. `gripforge_map_unreal_prepare_local({plan_file, job_directory})` validates and
+   snapshots the scene/bindings and packages the installed Python worker.
+2. `gripforge_map_unreal_import_local({job_directory, editor_executable})` launches
+   the local UE editor; the persistent job continues after the MCP call ends.
+3. `gripforge_map_unreal_import_status_local({job_directory})` reads actual progress,
+   errors, measurements and viewport capture paths.
+4. `gripforge_map_unreal_import_cancel_local({job_directory})` requests cancellation
+   at a saved checkpoint. Close that editor, then import the same job to resume.
+
+The worker creates a **new work level** under `/Game/GripForge/Maps/`, reuses native
+meshes/PBR materials, imports per-asset GLBs and preserves instance transforms,
+hierarchy and IDs. Paths/region/zone outlines become editable splines. Player
+starts bind spawn zones; the full scene data is also carried on actor tags.
+Coordinate conversion is metres/Y-up to centimetres/Z-up, including native pivot
+offsets and rotations. Material overrides affect components, not shared source
+meshes. Terrain geometry has a size check and complex collision on its generated
+asset. Source packages are not rewritten. A changed scene needs a new job and
+level revision; reopening the same saved job does not duplicate completed actors.
+
+See `docs/unreal-scene-import.md` in the source
+repository for the manifest contract and CLI. The worker is shipped in the MCP
+package's `runtime/` folder. It requires the full Unreal editor with Python and
+Editor Scripting Utilities, tested against UE 5.7. It is not a headless web service.
+The current adapter handles static map content and native Blueprint props;
+skeletal retargeting, animation/attachments, terrain layer authoring as native
+Landscape, navigation baking, HDRI/cloud translation and bidirectional edits
+need their own adapters. Unsupported features fail explicitly. A generated
+terrain is an editable static-mesh actor, not a sculptable Landscape.
+
+Successful import ends at **awaiting_visual_review**, not validated/current.
+Review the actual UE render, collision and gameplay before accepting that work
+version. The legacy `gripforge_map_export` merged FPS GLB is not this native import.
+
 ## Env
 
 - `GRIPFORGE_API_KEY` (required) — 1 credit = 1 successful attach
 - `GRIPFORGE_API_URL` (optional) — defaults to https://gripforge.ai
+
+### Joystick for Unreal, Godot, Unity and Three.js
+
+Call `gripforge_joystick_kit` with:
+
+```json
+{"target":"unreal","layout":"dual","deadzone":0.15,"radius":72,"accent":"#ff681f"}
+```
+
+`target` also accepts `godot`, `unity`, `threejs` or `all`. The response includes
+complete `deliveries[].files[]` (relative path + source) and a README per engine.
+Write those files into the project and follow that README. No asset generation,
+API key or credit is required. Both hosted and npm MCP expose the same tool.
+
+Unreal receives a runtime Pawn component/plugin; Godot a CanvasLayer scene;
+Unity a UGUI component; Three.js a DOM overlay and camera-relative input example.
+Movement and optional camera sticks own independent fingers, hold their axes
+continuously, and reset on release/cancel/focus loss. The radial deadzone preserves
+analog magnitude. Existing movement physics and physical gamepad bindings stay
+with the game. Installation and actual game verification are separate from file
+generation; Unreal source must be compiled for the project's UE version.
+# Unreal environments in Map Studio
+
+The local tools `gripforge_map_unreal_export_local`,
+`gripforge_map_unreal_export_status_local`, `gripforge_map_unreal_export_cancel_local`
+and `gripforge_map_unreal_upload_local` export a saved Unreal map and import it into
+the authenticated workspace. Supply the installed UE 5.7 editor, `.uproject`,
+`/Game/...` level and a persistent job directory. Per-file progress survives closed
+calls; upload returns a GripForge Studio link after the persistent server job completes.
+The source project is not saved. Imported scenes remain private work versions.
+
+The hosted equivalents `gripforge_map_import_unreal_schema` and
+`gripforge_map_import_unreal` accept exported common scene data, not native `.umap`
+bytes. The hosted service cannot start a local editor. PBR meshes, transforms,
+foliage patches and Landscape data are portable; Blueprints, Niagara and custom
+water/sky shaders need separate adapters. Foliage patches are edited as groups.
+Read the live contract at `GET /api/v1/maps/import/unreal` and the public MCP/API docs.
+
+`gripforge_generation_quote` (hosted MCP / source client) estimates model, concept, texture, rig or animation operations before spending. It returns subscription/credit funding, remaining usage and an operation estimate. Propose missing assets and obtain a generation budget; a quote for one operation is not a fixed price for an entire game.

package/dist/ability-tools.js

@@ -0,0 +1,21 @@
+import { z } from 'zod/v4';
+export const ABILITY_TOOL_NAMES = ['gripforge_abilities'];
+export function registerAbilityTools(register, options, schema = z) {
+    const shape = { action: schema.enum(['schema', 'example', 'validate', 'export']), target: schema.enum(['threejs', 'godot', 'unity', 'unreal', 'all']).optional(), pack: schema.record(schema.string(), schema.unknown()).optional().describe('Versioned ability pack. Read schema/example first; author a reusable pack then validate it.'), model_asset: schema.string().regex(/^lib_[A-Za-z0-9_-]{8,64}$/).optional().describe('Library model id bound to the example. Does not rig or animate it.') };
+    register('gripforge_abilities', { title: 'Abilities / skills · four engines', description: 'combat.abilities: inspect schema, get an editable Chrono Crab example, validate a pack or export executable Three.js, Godot, Unity and Unreal source adapters. Shared costs, cooldowns, conditions, targeting, windup/active/recovery and presentation cues. Native adapters require the game combat backend and asset bindings. Returns relative path/content files; no rig/animation/VFX generation or automatic installation. Persist through gripforge_gamekit_configure config.pack or project data. 0 credits.', inputSchema: shape, annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false } }, async (args) => {
+        const parsed = schema.object(shape).strict().safeParse(args);
+        if (!parsed.success)
+            return { isError: true, content: [{ type: 'text', text: parsed.error.message }] };
+        const key = options.getApiKey();
+        if (!key)
+            return { isError: true, content: [{ type: 'text', text: 'GripForge API key required.' }] };
+        try {
+            const response = await fetch(options.apiUrl.replace(/\/$/, '') + '/api/v1/abilities', { method: 'POST', headers: { 'content-type': 'application/json', 'x-api-key': key, 'x-gripforge-client': 'mcp' }, body: JSON.stringify(parsed.data), signal: AbortSignal.timeout(30000) });
+            const data = await response.json();
+            return { ...(!response.ok ? { isError: true } : {}), content: [{ type: 'text', text: JSON.stringify(data) }], structuredContent: data };
+        }
+        catch (e) {
+            return { isError: true, content: [{ type: 'text', text: e instanceof Error ? e.message : 'Ability request failed' }] };
+        }
+    });
+}

package/dist/architecture-tools.js

@@ -0,0 +1,73 @@
+import { z } from 'zod/v4';
+export const ARCHITECTURE_TOOL_NAMES = ['gripforge_architecture_schema', 'gripforge_generate_building', 'gripforge_generate_district'];
+/** 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 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(),
+        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.'),
+        roof: schema.enum(['flat', 'pitched']).optional(), facade: schema.string().max(120).optional(),
+        polycount: schema.number().int().min(4000).max(80000).optional(),
+        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.'),
+        source: ref.optional().describe('Reuse an owned static GLB revision instead of paying for this building. The source is never modified.'),
+    }).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({
+        version: schema.literal(1).optional(), name: schema.string().min(1).max(100).optional(),
+        buildings: schema.array(building).min(1).max(8).describe('Unique building definitions with distinct ids. Each new model is manufactured once.'),
+        repetitions: schema.number().int().min(1).max(4).optional().describe('Instances per definition, without additional model generation cost.'),
+        streetWidth: schema.number().min(6).max(30).optional(), sidewalkWidth: schema.number().min(1).max(8).optional(), gap: schema.number().min(1).max(30).optional(),
+        materials: schema.object({ road: material.optional(), sidewalk: material.optional() }).strict().optional(),
+    }).strict();
+    const shared = {
+        stage: schema.enum(['plan', 'build']).optional().describe('Default plan is free and does not generate. Read its quote, then explicitly build.'),
+        budget: schema.object({ credits: schema.number().nonnegative().optional(), usd: schema.number().nonnegative().optional() }).strict().optional().describe('Required for paid concept/build: maximum GripForge credits OR subscription USD accepted. Use the quote funding currency: insufficient AI allowance falls back to GripForge credits for the whole new job, never both. Use plan.concept_quote for images, plan.quote for Meshy. Provider credits are separate.'),
+        workspace_id: schema.string().max(100).optional(),
+        idempotency_key: schema.string().regex(/^[a-zA-Z0-9_.:-]{8,160}$/).optional(),
+    };
+    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[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_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.' },
+    ];
+    for (const tool of definitions)
+        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);
+            if (!parsed.success)
+                return { isError: true, content: [{ type: 'text', text: parsed.error.message }] };
+            const key = options.getApiKey();
+            if (!key && tool.kind !== 'schema')
+                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(/\/$/, '') + '/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({ ...body, kind: tool.kind }) }),
+                    signal: AbortSignal.any([AbortSignal.timeout(60_000), ...(extra?.signal ? [extra.signal] : [])]),
+                });
+                const data = await response.json();
+                for (const field of ['studio_url', 'status_url'])
+                    if (typeof data[field] === 'string' && data[field].startsWith('/'))
+                        data[field] = new URL(data[field], options.apiUrl).href;
+                return { ...(!response.ok ? { isError: true } : {}), structuredContent: data, content: [{ type: 'text', text: JSON.stringify(data) }] };
+            }
+            catch (error) {
+                return { isError: true, content: [{ type: 'text', text: error instanceof Error ? error.message : 'Architecture request failed.' }] };
+            }
+        });
+}

package/dist/asset-production-tools.js

@@ -0,0 +1,101 @@
+import { z } from 'zod/v4';
+/** Shared hosted/npm contract: assets are discovered independently of game modules. */
+export function registerAssetProductionTools(register, options, schema = z) {
+    const origin = options.apiUrl.replace(/\/$/, '');
+    const workspace = schema.string().max(100).optional().describe('Authorized workspace; defaults to the connected workspace.');
+    const result = (data) => ({ content: [{ type: 'text', text: JSON.stringify(data, null, 2) }], structuredContent: data });
+    async function request(path, workspaceId, method = 'GET', body) {
+        const key = options.getApiKey();
+        if (!key)
+            throw Error('GripForge API key required.');
+        const response = await fetch(origin + '/api/v1/' + path, { method, headers: { 'x-api-key': key, 'x-gripforge-client': 'mcp', ...(body ? { 'content-type': 'application/json' } : {}), ...(typeof workspaceId === 'string' ? { 'x-workspace-id': workspaceId } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}), signal: AbortSignal.timeout(60000) });
+        const data = await response.json();
+        if (!response.ok)
+            throw Error(String(data.error ?? `HTTP ${response.status}`));
+        return data;
+    }
+    const wrap = (run) => async (args) => {
+        try {
+            return result(await run(args));
+        }
+        catch (e) {
+            return { isError: true, content: [{ type: 'text', text: e instanceof Error ? e.message : String(e) }] };
+        }
+    };
+    register('gripforge_generate_weapon_catalog', {
+        title: 'Generate a weapon catalogue',
+        description: 'Plan then manufacture 1–64 original static weapon models using the existing Meshy PBR pipeline. plan is free and returns an exact aggregate quote and plan_hash. build requires that hash, an explicit budget covering the quote and a stable idempotency_key. One durable job, two bounded fabrication lanes, per-weapon checkpoints and billing; cancellation/retry preserves finished work and provider task IDs. Results remain private work assets. Inspect geometry, textures and actual renderer output before publishing. Does not create attack/reload animations, grip bindings, or flexible-chain physics. Poll gripforge_generation_read; result.items contains Library IDs and Studio links.',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        inputSchema: {
+            stage: schema.enum(['plan', 'build']), workspace_id: workspace,
+            entries: schema.array(schema.object({ key: schema.string().regex(/^[a-z0-9][a-z0-9_-]{0,47}$/), name: schema.string().min(1).max(160), prompt: schema.string().min(3).max(600), subtype: schema.string().min(1).max(60), style: schema.enum(['gun', 'melee', 'shield', 'staff']).optional(), polycount: schema.number().int().min(500).max(20000).optional(), tags: schema.array(schema.string().min(1).max(60)).max(16).optional() }).strict()).min(1).max(64),
+            plan_hash: schema.string().regex(/^[a-f0-9]{64}$/).optional(),
+            budget: schema.object({ credits: schema.number().nonnegative().optional(), usd: schema.number().nonnegative().optional() }).strict().optional(),
+            idempotency_key: schema.string().regex(/^[a-zA-Z0-9_.:-]{8,160}$/).optional(),
+        },
+    }, wrap(args => request('weapons/catalog', args.workspace_id, 'POST', args)));
+    register('gripforge_generation_quote', {
+        title: 'Estimate generation usage before spending',
+        description: 'Free quote for a model, concept, texture, rig or animation. Reports the account funding mode, available balance and estimated operation cost. A subscription combines AI and paid asset generation in one monthly limit without also charging generation credits. Quote every missing role, propose the plan, and obtain a generation budget before submitting paid jobs. Estimates cover one operation, not the full concept/rig/review pipeline.',
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        inputSchema: { kind: schema.enum(['model', 'concept', 'texture', 'rig', 'animation']), provider: schema.enum(['meshy', 'tripo', 'xai', 'openai']).optional(), count: schema.number().int().min(1).max(20).optional(), workspace_id: workspace },
+    }, wrap(args => {
+        const params = new URLSearchParams({ kind: String(args.kind), count: String(args.count ?? 1) });
+        if (args.provider)
+            params.set('provider', String(args.provider));
+        return request(`generation-quote?${params}`, args.workspace_id);
+    }));
+    register('gripforge_asset_search', {
+        title: 'Search workspace and Community assets',
+        description: 'Search actual asset models, materials and animations, independently of Game Kit modules. Returns provenance, import requirements and Library ids. Results are ranked best first by fitness for a GripForge game (score/100, grade A–D, reasons: triangle budget for the target, rigged and clean rig, clips, empty-handed characters, attachable weapons, classified, file size, adoption); `best` is the top pick across sources. Prefer grade A/B; read the reasons before choosing a C/D. Search both sources before manufacturing missing roles. An empty kit search does not mean there are no assets. Search is free; never substitutes proxy geometry for finished models.',
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        inputSchema: {
+            q: schema.string().max(200).describe('Visual role or style, e.g. sci-fi turret, rock, soldier.'),
+            kind: schema.enum(['character', 'fps-arms', 'enemy', 'weapon', 'equipment', 'prop', 'texture', 'skybox', 'vfx', 'animation', 'audio', 'kit']).optional().describe('Optional asset kind.'),
+            source: schema.enum(['workspace', 'community', 'both']).optional().describe('Defaults to both.'),
+            limit: schema.number().int().min(1).max(48).optional().describe('Results per source; default 12.'),
+            offset: schema.number().int().min(0).max(10000).optional().describe('Pagination offset per source; default 0.'),
+            target: schema.enum(['mobile', 'desktop']).optional().describe('Platform the game ships on: sets the triangle and file budgets of the rank. Defaults to mobile.'),
+            sort: schema.enum(['rank', 'newest']).optional().describe('rank (default): best fit first; newest: most recent first.'),
+            workspace_id: workspace,
+        },
+    }, wrap(async (args) => {
+        const limit = Number(args.limit ?? 12), offset = Number(args.offset ?? 0);
+        const target = args.target === 'desktop' ? 'desktop' : 'mobile';
+        const qs = new URLSearchParams({ q: String(args.q ?? ''), limit: String(limit), offset: String(offset), sort: args.sort === 'newest' ? 'newest' : 'rank', target });
+        if (args.kind)
+            qs.set('kind', String(args.kind));
+        const sources = args.source === 'workspace' ? ['workspace'] : args.source === 'community' ? ['community'] : ['workspace', 'community'];
+        const data = await Promise.all(sources.map(async (source) => {
+            const response = await request(`${source === 'workspace' ? 'library' : 'community'}?${qs}`, args.workspace_id);
+            const items = (Array.isArray(response.items) ? response.items : []).slice(0, limit);
+            return { source, total: response.total ?? items.length, items: items.map(item => {
+                    const meta = (item.meta && typeof item.meta === 'object' ? item.meta : {});
+                    const rank = (item.rank && typeof item.rank === 'object' ? item.rank : null);
+                    return { id: item.id, name: item.name, kind: item.kind, filename: item.filename, source,
+                        score: rank?.score ?? null, grade: rank?.grade ?? null, reasons: (rank?.reasons ?? []).slice(0, 5).map(r => `${r.points > 0 ? '+' : ''}${r.points} ${r.note}`),
+                        triangles: meta.triangles, tags: meta.tags, rigged: meta.rigged, placeholder: meta.placeholder === true || /proxy_|volume de travail/i.test(String(item.filename) + ' ' + String(item.name)),
+                        next: source === 'community' ? 'gripforge_asset_clone, then gripforge_library_pull' : 'gripforge_library_get / gripforge_library_pull',
+                    };
+                }) };
+        }));
+        // The top pick across sources; a workspace copy wins a tie (no credit to take it).
+        const best = data.flatMap(d => d.items).filter(i => typeof i.score === 'number' && !i.placeholder)
+            .sort((a, b) => b.score - a.score || (a.source === 'workspace' ? -1 : 1))[0] ?? null;
+        return { target, best, results: data, note: 'Ranked for a GripForge game (see reasons). Inspect suitability and textures/animations before importing. Downloads alone are not runtime integration.' };
+    }));
+    register('gripforge_asset_clone', {
+        title: 'Copy a Community asset to the workspace',
+        description: 'Copy a published Community asset into the connected workspace. Assets and armor sets are free by default. Only an explicit creator price is charged, using paid credits. Repeated takes are not billed again but may create another copy: reuse an existing workspace id when possible. Returns the private Library item and signed file URL. Download it with gripforge_library_pull, then import into the actual game.',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        inputSchema: { id: schema.string().regex(/^lib_[A-Za-z0-9_-]+$/).describe('Published Community Library id.'), workspace_id: workspace },
+    }, wrap(args => request(`community/${encodeURIComponent(String(args.id))}/clone`, args.workspace_id, 'POST')));
+}
+/** 202 response: do not strip job ids or misrepresent a queued model as a Library item. */
+export function assetGenerationOutput(schema = z) {
+    return schema.object({
+        job: schema.string().optional(), job_id: schema.string().optional(), status: schema.string().optional(), stage: schema.string().optional(),
+        status_url: schema.string().optional(), studio_url: schema.string().optional(), library_url: schema.string().optional(),
+        item: schema.record(schema.string(), schema.unknown()).optional(), provider: schema.string().optional(), notes: schema.array(schema.string()).optional(),
+    }).passthrough();
+}

package/dist/creature-rig-tools.js

@@ -0,0 +1,41 @@
+import { z } from 'zod/v4';
+export const CREATURE_RIG_TOOL_NAMES = ['gripforge_creature_rig_schema', 'gripforge_creature_analyze', 'gripforge_creature_rig'];
+/** Same contract for hosted MCP and the local client; Blender runs in the durable worker. */
+export function registerCreatureRigTools(register, options, schema = z) {
+    const shared = { workspace_id: schema.string().max(100).optional(), name: schema.string().min(1).max(100).optional(), idempotency_key: schema.string().regex(/^[a-zA-Z0-9_.:-]{8,160}$/).optional() };
+    const analyze = { ...shared, source_id: schema.string().regex(/^lib_[A-Za-z0-9_-]{8,64}$/), kind: schema.enum(['enemy', 'character']).optional() };
+    const rig = { ...shared, analysis_job: schema.string().regex(/^gen_[A-Za-z0-9_-]{8,64}$/), profile: schema.record(schema.string(), schema.unknown()).optional().describe('Optional corrected anatomy in the exact coordinate system returned by analyze. Read the schema and inspect the multiview preview first.'), reviewed_anatomy: schema.boolean().optional().describe('Required: true only after inspecting/correcting the anatomy and its skeleton overlay.'), allow_rerig: schema.boolean().optional().describe('Explicitly create a NEW rigged copy if the source already contains bones. The source is never overwritten.') };
+    async function call(action, args, signal) {
+        const key = options.getApiKey();
+        if (!key && action !== 'schema')
+            return { isError: true, content: [{ type: 'text', text: 'GripForge API key required.' }] };
+        const { workspace_id, ...body } = args;
+        try {
+            const response = await fetch(options.apiUrl.replace(/\/$/, '') + '/api/v1/creature-rigs', {
+                method: action === '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 } : {}) },
+                ...(action === 'schema' ? {} : { body: JSON.stringify({ action, ...body }) }), signal: AbortSignal.any([AbortSignal.timeout(60_000), ...(signal ? [signal] : [])]),
+            });
+            const data = await response.json();
+            for (const field of ['studio_url', 'status_url'])
+                if (typeof data[field] === 'string' && data[field].startsWith('/'))
+                    data[field] = new URL(data[field], options.apiUrl).href;
+            return { ...(!response.ok ? { isError: true } : {}), structuredContent: data, content: [{ type: 'text', text: JSON.stringify(data) }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: 'text', text: error instanceof Error ? error.message : 'Creature rig request failed.' }] };
+        }
+    }
+    const tools = [
+        { name: CREATURE_RIG_TOOL_NAMES[0], action: 'schema', title: 'Creature rig · schema', shape: {}, description: 'Read the reusable creature anatomy/rig workflow, coordinate contract, limits and export formats. Detect anatomy before authoring; source GLB, asset instances and draft rig stay separate. Blender is the worker, GripForge is the review renderer.' },
+        { name: CREATURE_RIG_TOOL_NAMES[1], action: 'analyze', title: 'Creature rig · detect anatomy', shape: analyze, description: 'Queue multiview mesh inspection and vision anatomy detection for an OWNED GLB. Detect actual body, legs, arms, claws, wings or tail without imposing a humanoid/eight-leg template. Returns a persistent job_id. Poll gripforge_generation_read with include_preview=true for the annotated views, editable profile and uncertainty flags. No rig mutation. 0 GripForge credits; configured server vision/Blender required.' },
+        { name: CREATURE_RIG_TOOL_NAMES[2], action: 'rig', title: 'Creature rig · manufacture', shape: rig, description: 'Create a NEW private draft character/enemy from a completed creature analysis and optional corrected anatomy. Blender builds the skeleton, surface-smoothed skin weights and procedural starting/diagnostic clips. Grounded leg chains get in-place walk/run with IK. Returns job_id; poll gripforge_generation_read for the Character Studio link, skinned GLB, editable .blend, anatomy and deformation report. Never automatically replaces or validates the source. Every anatomy proposal requires explicit review; use generation_cancel/retry to control durable work. Finger/facial authoring and finished combat choreography are outside v1. 0 GripForge credits.' },
+    ];
+    for (const tool of tools)
+        register(tool.name, { title: tool.title, description: tool.description, inputSchema: tool.shape,
+            annotations: { readOnlyHint: tool.action === 'schema', destructiveHint: false, idempotentHint: tool.action === 'schema', openWorldHint: false } }, async (args, extra) => {
+            const parsed = schema.object(tool.shape).strict().safeParse(args);
+            if (!parsed.success)
+                return { isError: true, content: [{ type: 'text', text: parsed.error.message }] };
+            return call(tool.action, parsed.data, extra?.signal);
+        });
+}