@gripforgeai/mcp 0.1.0 → 0.1.2

package/README.md

@@ -23,7 +23,7 @@ Or in `.mcp.json`:
 }
 ```
 
-Get a free API key (3 attaches / month) at https://gripforge.ai/login.
+Get a free API key at https://gripforge.ai/login — the free plan includes **3 API/MCP attaches per month** to try it out (plus 15 in the web Studio). Paid plans from €29/mo for production use.
 
 ## Install (Grok)
 
@@ -52,6 +52,9 @@ Also works with Cursor, Windsurf and any MCP-compatible client — same
 
 - `gripforge_attach` — character + prop in, bone-local bind + Three.js / Unity /
   Godot snippets out. Styles: melee, gun, shield, staff (scythe/polearm).
+  With `export_glb: true` (+ `out_dir`) it also writes `attached.glb`: the
+  character with the fist closed and the prop attached, textures preserved —
+  use this for mitten-hand rigs, whose closed fist cannot travel in a JSON bind.
 - `gripforge_formats` — supported formats & options.
 
 ## Env

package/dist/server.js

@@ -15,19 +15,38 @@ import { z } from 'zod';
 const API_URL = process.env.GRIPFORGE_API_URL ?? 'https://gripforge.ai';
 const API_KEY = process.env.GRIPFORGE_API_KEY;
 const SUPPORTED = ['.glb', '.gltf', '.fbx', '.obj'];
-const server = new McpServer({ name: 'gripforge', version: '0.1.0' });
+const server = new McpServer({ name: 'gripforge', version: '0.1.2' });
 const err = (text) => ({ content: [{ type: 'text', text }], isError: true });
 server.tool('gripforge_attach', 'Attach a prop (sword, shield, gun, staff/scythe…) onto a rigged character. ' +
     'Finds the hand bone across naming schemes, scales to body height, seats the grip, ' +
-    'and returns a bind + ready-to-paste Three.js / Unity / Godot snippets.', {
+    'and returns a bind + ready-to-paste Three.js / Unity / Godot snippets. ' +
+    'Exact placement: add an Empty/locator named "grip" on the handle inside the weapon file — ' +
+    'GripForge puts that point in the palm and skips all grip heuristics. ' +
+    'Hand closing: rigs WITH finger bones get bind.gripPose rotations (applied by the snippets); ' +
+    'rigs WITHOUT finger bones (mitten hands) need export_glb: true + out_dir to receive ' +
+    'attached.glb with the fist baked in — the JSON bind alone cannot close a mitten hand.', {
     character_path: z.string().describe('Absolute path to the rigged character (.glb .gltf .fbx .obj)'),
     prop_path: z.string().describe('Absolute path to the prop mesh'),
     style: z.enum(['melee', 'gun', 'shield', 'staff']).optional().describe('Grip style (default: guessed from the filename)'),
     hand: z.enum(['right', 'left']).optional().describe('Hand side (default right)'),
     height_ratio: z.number().min(0.05).max(1.5).optional().describe('Prop size as a fraction of body height'),
     fist: z.number().min(0).max(1).optional().describe('Fist closing amount, 0 open → 1 closed (default 1)'),
+    grip_offset: z
+        .array(z.number())
+        .length(3)
+        .optional()
+        .describe('Grip fine-tune [palm, lateral, along-handle] in palm units — overrides the weapon-class defaults'),
+    ai_refine: z
+        .boolean()
+        .optional()
+        .describe('Vision-model verification of the grip: renders the fist+weapon, checks the hold, auto-corrects (adds ~10-30s)'),
+    export_glb: z
+        .boolean()
+        .optional()
+        .describe('Bake character + closed fist + prop into one attached.glb (requires out_dir; .glb/.gltf inputs only). ' +
+        'Use this for mitten-hand rigs: the closed fist cannot travel in the bind JSON.'),
     out_dir: z.string().optional().describe('Write bind.json + engine snippets into this folder'),
-}, async ({ character_path, prop_path, style, hand, height_ratio, fist, out_dir }) => {
+}, async ({ character_path, prop_path, style, hand, height_ratio, fist, grip_offset, ai_refine, export_glb, out_dir }) => {
     if (!API_KEY) {
         return err('GRIPFORGE_API_KEY missing. Create a free account at ' +
             API_URL +
@@ -41,6 +60,13 @@ server.tool('gripforge_attach', 'Attach a prop (sword, shield, gun, staff/scythe
             return err(`Unsupported format: ${p} — use ${SUPPORTED.join(' ')}`);
         }
     }
+    if (charPath === propPath) {
+        return err('character_path and prop_path point to the same file. Export the weapon as its own GLB ' +
+            '(Blender: select the weapon only, File > Export > glTF, check "Selected Objects") and pass that as prop_path.');
+    }
+    if (export_glb && !out_dir) {
+        return err('export_glb needs out_dir — that is where attached.glb will be written.');
+    }
     const form = new FormData();
     form.append('character', new Blob([await readFile(charPath)]), basename(charPath));
     form.append('prop', new Blob([await readFile(propPath)]), basename(propPath));
@@ -52,12 +78,22 @@ server.tool('gripforge_attach', 'Attach a prop (sword, shield, gun, staff/scythe
         form.append('ratio', String(height_ratio));
     if (fist != null)
         form.append('fist', String(fist));
+    if (grip_offset)
+        form.append('grip_offset', grip_offset.join(','));
+    if (ai_refine)
+        form.append('refine', 'ai');
+    if (export_glb)
+        form.append('export', 'glb');
     form.append('fingers', '1');
     let res;
     try {
         res = await fetch(`${API_URL}/api/v1/attach`, {
             method: 'POST',
-            headers: { 'x-api-key': API_KEY },
+            headers: {
+                'x-api-key': API_KEY,
+                'x-gripforge-client': 'mcp',
+                'user-agent': 'gripforge-mcp/0.1',
+            },
             body: form,
         });
     }
@@ -67,6 +103,9 @@ server.tool('gripforge_attach', 'Attach a prop (sword, shield, gun, staff/scythe
     const data = (await res.json().catch(() => ({})));
     if (res.status === 401)
         return err('Invalid GRIPFORGE_API_KEY — check it on ' + API_URL + '/account#api');
+    if (res.status === 403) {
+        return err(`MCP access requires a paid plan (indie or studio); the free plan covers the Studio only. Upgrade at ${API_URL}/#pricing`);
+    }
     if (res.status === 402) {
         const u = data;
         return err(`Quota exceeded (${u.used}/${u.limit}, plan ${u.plan}) — upgrade at ${API_URL}/#pricing`);
@@ -75,6 +114,8 @@ server.tool('gripforge_attach', 'Attach a prop (sword, shield, gun, staff/scythe
         return err(`Attach failed (${res.status}): ${String(data.error ?? 'unknown error')}`);
     const exportsObj = (data.exports ?? {});
     let wrote = null;
+    let glbFile = null;
+    let glbNotes = [];
     if (out_dir) {
         const dir = resolve(out_dir);
         await mkdir(dir, { recursive: true });
@@ -85,15 +126,35 @@ server.tool('gripforge_attach', 'Attach a prop (sword, shield, gun, staff/scythe
             await writeFile(join(dir, 'unity.cs.txt'), exportsObj.unity);
         if (exportsObj.godot)
             await writeFile(join(dir, 'godot.gd.txt'), exportsObj.godot);
+        const glb = data.glb;
+        if (glb?.base64) {
+            glbFile = join(dir, glb.filename ?? 'attached.glb');
+            await writeFile(glbFile, Buffer.from(glb.base64, 'base64'));
+        }
+        if (glb?.notes?.length)
+            glbNotes = glb.notes;
         wrote = dir;
     }
     const credits = data.credits;
+    // Mitten rigs (no real finger bones): the fist is a mesh swap that cannot
+    // travel in the bind JSON — steer the caller toward export_glb.
+    const bind = data.bind;
+    const isMitten = bind?.fingerRig?.generated === true || (bind?.fingerRig && (bind.fingerRig.bones ?? 0) === 0);
+    const noPose = !bind?.gripPose || bind.gripPose.length === 0;
+    const mittenHint = !glbFile && isMitten && noPose
+        ? '\nNOTE: this rig has no real finger bones, so the closed fist exists only as a mesh swap ' +
+            'and is NOT in the bind JSON — the hand will stay open in your engine. ' +
+            'Re-run gripforge_attach with export_glb: true and an out_dir to get attached.glb ' +
+            '(character with the fist closed + prop attached, textures preserved).'
+        : '';
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify({ bind: data.bind, confidence: data.confidence, exports: exportsObj, wrote }, null, 2) +
-                    (credits ? `\ncredits: ${credits.remaining}/${credits.limit} remaining (${credits.plan})` : ''),
+                text: JSON.stringify({ bind: data.bind, confidence: data.confidence, exports: exportsObj, wrote, glbFile }, null, 2) +
+                    (credits ? `\ncredits: ${credits.remaining}/${credits.limit} remaining (${credits.plan})` : '') +
+                    (glbNotes.length ? `\nglb notes:\n- ${glbNotes.join('\n- ')}` : '') +
+                    mittenHint,
             },
         ],
     };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gripforgeai/mcp",
-  "version": "0.1.0",
-  "description": "GripForge MCP server — attach weapons & props to rigged characters from Claude Code, Cursor or any MCP client. Calls the GripForge API.",
+  "version": "0.1.2",
+  "description": "GripForge MCP server \u2014 attach weapons & props to rigged characters from Claude Code, Cursor or any MCP client. Calls the GripForge API.",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -37,5 +37,6 @@
   "devDependencies": {
     "@types/node": "^20",
     "typescript": "^5"
-  }
-}
+  },
+  "mcpName": "io.github.gripforgeai/mcp"
+}