GripForge

@gripforgeai/mcp

为你的 AI 打造游戏提供所需工具。

将提示词变成可用于生产的游戏资产 — 带有武器的动画角色、无缝纹理、地形、VFX、HUD — 以及可玩的游戏套件。

GripForge API 的 MCP 客户端 — 可在 Claude Code、Cursor、Windsurf、VS Code 或任何 MCP 客户端中使用。

使用方法

托管版 — 无需安装。 将任何支持远程连接的 MCP 客户端指向 https://gripforge.ai/mcp 并提供你的 API 密钥（在此创建）：

{
  "mcpServers": {
    "gripforge": {
      "url": "https://gripforge.ai/mcp",
      "headers": { "x-api-key": "gf_..." }
    }
  }
}

Claude Code，一行即可：

claude mcp add --transport http gripforge https://gripforge.ai/mcp --header "x-api-key: gf_..."

本地安装，通过 npm — 适用于 Agent 需要将文件写入你的代码库的情况：

{
  "mcpServers": {
    "gripforge": {
      "command": "npx",
      "args": ["-y", "@gripforgeai/mcp"],
      "env": { "GRIPFORGE_API_KEY": "gf_..." }
    }
  }
}

主要功能

• 会动的角色。 描述一个角色，即可获得绑定好的 T-Pose 和一组动画 — 待机、奔跑、攻击 — 可直接放入场景。
• 手持武器。 GripForge 可在任意骨架上找到手部骨骼、缩放道具、让拳头握住握柄，并返回绑定数据以及 Three.js、Unity 和 Godot 代码片段。
• 无缝纹理。 根据提示词或你自己的图片生成可平铺的材质集，并在放大时不凭空添加内容。
• 地形和地图。 可玩的房间图、带有出生点和通道的俯视角射击游戏布局，以及根据参考图重建的灰盒场景。
• VFX 和 HUD。 为你的引擎导出的动画特效和界面套件。
• 可玩的游戏套件。 组合移动、战斗、敌人、世界等模块化功能，打造可在浏览器中运行的游戏，然后绑定你自己的资产。
• 统一的 Library。 所有生成内容都会存入一个可供你的引擎拉取的储物库，Agent 也可以按外观进行搜索（如“Devil May Cry 风格”“genshin”）。

使用场景

• “把这把剑装到我的骑士右手上，然后导出装备武器的 GLB。” — Agent 会处理骨骼、缩放和握拳；你会得到一个可加载的文件。
• “为灰烬地狱打造一个有三个阶段和一个竞技场的 Boss。” — 统计数据、攻击方式和引擎代码片段会一并生成。
• “给这个地板做一套可以平铺的苔藓鹅卵石纹理。” — 生成无缝纹理集并保存到 Library。
• “做一个我可以在浏览器里试玩的 Roguelike 游戏切片。” — 生成一个绑定了资产的游戏套件项目，并可通过链接进行游玩。

常见问题

我需要安装任何东西吗？ 不需要。托管端点可供任何支持流式 HTTP 的 MCP 客户端使用。npm 包的用途只有一个：让 Agent 能直接将文件写入你的代码库。

支持哪些引擎？ Unity、Godot、Unreal 和 Three.js — 资产会附带各引擎所需的绑定数据和代码片段。

如何计费？ 按每次生成消耗点数。读取 Library、为现有角色制作动画、生成关卡和地图套件都不收费；生成角色或武器则需要 10 点。

我的资产存放在哪里？ 在你的工作区 Library 中。你可以将它们拉取到代码库、推送自己的资产，也可以与社区目录分享。

我可以使用自己的概念图吗？ 可以 — 传入图片后，GripForge 会根据图片生成 T-Pose 设定图，而不是凭空创造角色。

托管端点

无需 Node — 将任何支持远程连接的 MCP 客户端指向：

https://gripforge.ai/mcp

身份验证：x-api-key: gf_... 请求头（或 Authorization: Bearer）。资产以 URL（character_url、prop_url）传入 — Tripo/Meshy 下载链接可直接使用。

// Cursor (.cursor/mcp.json)
{
  "mcpServers": {
    "gripforge": {
      "url": "https://gripforge.ai/mcp",
      "headers": { "x-api-key": "gf_..." }
    }
  }
}

示例

“把这把剑装到我的骑士右手上，然后导出装备武器的 GLB。”

Agent 会使用两个资产 URL（或在 npm 包中使用本地路径）调用 gripforge_attach；GripForge 会找到手部骨骼，将道具缩放到与角色的手匹配，让拳头握住握柄，并返回绑定 JSON、可直接粘贴使用的 Three.js / Unity / Godot 代码片段，以及可选的装备武器后的 GLB。

若要根据图片（而非文本提示词）打造角色，请传入 concept_item（Library 中的 lib_… T-Pose/概念图），或者在 npm 包中传入本地 path / file_url。这是 Meshy 的图像转 3D 功能。不提供这些字段时，该工具仅支持文本转 3D。

安装（适用于任何 MCP 客户端）

将服务添加到客户端的 MCP 配置中（.mcp.json、mcp.json、设置 — 在任何地方格式都相同）：

{
  "mcpServers": {
    "gripforge": {
      "command": "npx",
      "args": ["-y", "@gripforgeai/mcp"],
      "env": { "GRIPFORGE_API_KEY": "gf_..." }
    }
  }
}

在 https://gripforge.ai/login 获取 API 密钥 — 免费：每月 15 次 Studio 附加和 3 次 API/MCP 试用附加。积分包起价为 €29（100 积分，永不过期）。

安装（Grok）

grok mcp add gripforge --env GRIPFORGE_API_KEY=gf_... -- npx -y @gripforgeai/mcp

或者在 ~/.grok/config.toml 中：

[mcp_servers.gripforge]
command = "npx"
args = ["-y", "@gripforgeai/mcp"]
enabled = true
startup_timeout_sec = 45

[mcp_servers.gripforge.env]
GRIPFORGE_API_KEY = "gf_..."

也适用于 Cursor、Windsurf 和任何兼容 MCP 的客户端 — 使用相同的 command / args / env 三元组。

工具参考

托管 HTTP MCP（https://gripforge.ai/mcp）始终保持最新。此 npm 包会将文件写入仓库（out_dir），包括 gripforge_hud、 gripforge_hud_bar 和 gripforge_cape。仅限托管版：gripforge_make_seamless。 完整列表：https://gripforge.ai/mcp-docs

• gripforge_style_kit — 将“Devil May Cry like”/“genshin”解析为已标记了相应外观的储物柜 ID。生成前先调用此工具。 复用这些 ID。
• gripforge_generate_character — 生成新的 T 姿角色并自动绑定，存入库（10 积分）。 使用 kind=enemy 或在提示词中包含“enemy”。如果 style_kit 已返回角色，则跳过此步骤。
• gripforge_boss — 可游玩的 Boss 套件（属性、阶段、攻击、竞技场、引擎代码片段）。 0 积分。复用储物柜中的敌人。设置 generate=true 可锻造新的 kind=enemy（10 积分）。 然后使用返回的 archetype 调用 gripforge_animate。
• gripforge_concept_correct — 概念图 → 严格的 T 姿设定图（1 积分）。
• gripforge_attach — 输入角色 + 道具（路径或库 ID），输出骨骼局部绑定 + Three.js / Unity / Godot 代码片段。样式：melee、gun、shield、staff（scythe/polearm）。 attach_id 可将已有武装绑定作为角色复用；prop_id_2 / prop_path_2 可附加第二件手持物品（副手）。 设置 export_glb: true（+ out_dir）还会写入 attached.glb：闭合拳头并附带道具的角色，保留纹理 — 可用于拳头无法在 JSON 绑定中移动的连指手套手部绑定。
• gripforge_loadout — 一次调用生成多武器角色（套装 + 清单 + 动画片段）。每件道具 1 积分。
• gripforge_generate_weapon — 将 Meshy 武器 GLB 存入库（kind=weapon、polycount、style=melee|gun）。10 积分。不是 generate_character。
• gripforge_hud — 生存游戏 HUD 套件（hud.json + PNG + .tscn + 代码片段）。写入 out_dir（默认为 ./gripforge-hud）。1 积分。
• gripforge_hud_bar — 原创主题生命条框架 + 填充 PNG。写入 out_dir。2 积分。
• gripforge_cape — 斗篷骨骼网格 + 蒙皮 attached_cape.glb + Godot/Three 代码片段。写入 out_dir（默认为 ./gripforge-cape）。1 积分。
• gripforge_formats — 支持的格式和选项。
• gripforge_library_list / get / push / pull / tag — 库储物柜。 kind=animation|audio 有效。pull 会将网格 及 VFX 附属文件（tex0..png/json） 写入当前打开的仓库（out_dir，默认为 ./gripforge-library）。 attach 后保存绑定不需要额外积分。
• gripforge_audio_kit — 适用于游戏外观的储物柜音效 + 音乐。免费。
• gripforge_animate — 将动画片段包应用到 Mixamo 库角色（archetype：sword/claws/heavy/brawler/puppet）。0 积分。
• gripforge_retarget — 将骨架 A 的动画片段重定向到骨架 B。
• gripforge_rest_pose — 根据此网格计算双臂下垂的静止姿势（武器仍会保留在武装绑定上）。
• gripforge_render — 生成服务端 PNG 预览，让 Agent 无需浏览器即可查看。
• gripforge_scene_kit — 适用于游戏外观的储物柜道具 + 建议布局。
• gripforge_light_kit / gripforge_font / gripforge_navmesh — 灯光 + 雾效、Web 字体 + 等级、可行走 AABB。0 积分。
• gripforge_input_kit — FPS InputMap（WASD + 方向键）。写入 input.json，自动加载 GfInput。 可选的 third_person: true 会添加可移植的角色朝向 JavaScript 和 Three.js 集成示例；现有输入映射保持不变。0 积分。
• gripforge_viewmodel_kit — CS 风格的 FPS 手臂 + 枪械，位于 Camera3D/Hold 下。写入 viewmodel.json + gf_viewmodel.gd。0 积分。
• gripforge_loading_page — 覆盖层 html/css/js + Godot/Unity/Unreal。传入 character_id 可生成 16:9 静帧（1 积分）。
• gripforge_level — 根据提示词生成可游玩的房间图。0 积分。
• gripforge_map_plan — 俯视 FPS/炸弹地图（出生点、A/B 点、通道、墙壁）。预览：https://gripforge.ai/map-plan?prompt=dust2。0 积分。
• gripforge_map_wires — 下垂电线跨度（2 个锚点 + 下垂），不是电缆网格。与 map_plan 配合使用。0 积分。
• gripforge_map_look — 静帧 → 摄像机 + 场景布置 ID（shot21a A-site）。仅使用 LINK，不使用 Meshy 图像转 3D。0 积分。
• gripforge_map_reconstruct — 采集 → 图结构 → 灰盒 → 区域 → 摄像机匹配 → 场景布置。Dust II Valve IP：仅限灰盒基准测试，不含 BSP。stage=dress = 原创纹理 + 道具 + 电线。0 积分。
• gripforge_hitbox — 根据绑定或 loadout 生成身体胶囊体 + weapons[]。
• gripforge_texture_prep — 本地路径或 texture_id → 无缝融合 + 保真 Lanczos 放大（1×/2×/4×，最大 1024 或 2048）。将 PNG 写入 out_dir， 并返回库 albedo URL。不是生成器。不消耗积分。
• gripforge_vfx_generate — 单独将 preset 设为 slash-trail、slash-steel、slash-fire、slash-ice 或 slash-nature，即可在不使用 AI 的情况下获取可直接游玩的配方；否则将文本/图像转换为可编辑的动画 VFX 规范（管理员密钥）。接受 prompt、visual_style，以及 base64 格式的 image_data 或自有库中的 image_id。
• gripforge_vfx / gripforge_vfx_preview — 保存/导出和示例 VFX（管理员密钥）。将生成的 emitters 和 generation 与效果参数一并传入，以保留生成结果。
• gripforge_shaders — 列出已授权的着色器目录（{ id, name, engines }）。使用 q=slash_reveal 搜索。
• gripforge_shader_pull — id + engine（godot|unity|three）+ out_dir → 将源文件写入仓库，并返回赋值代码片段。v1 pull 免费。
• gripforge_performance — 分析实测游戏 FPS、帧耗时、CPU/渲染提交、可选 GPU 耗时和网络延迟。检索明确共享的工作区捕获数据，或直接提供报告。0 积分。

游戏套件（模块化）

可组合的游戏玩法套件（vehicle.driveable、mission.objectives、npc.wanted……） 安装到 Game Kit 项目（gkp_…）中，并解析依赖、生成锁定文件 和浏览器游玩 URL，随后交付到 Godot、Unity 或 Unreal 项目中。除首次向某个引擎交付某个套件主版本外，均不消耗点数（每个工作区 1 点）。 完整参数：https://gripforge.ai/mcp-docs

• gripforge_gamekit_search — 从这里开始：按文本、能力、标签或目标搜索目录；提供 project_id 时，每条结果都会附带其安装状态。
• gripforge_gamekit_get — 获取某个套件的清单、README、配置架构和默认值、版本（with_usage 会列出使用该套件的项目）。
• gripforge_gamekit_install — 将套件添加到项目；自动解析清单中的依赖（使用 dry_run 预览）。
• gripforge_gamekit_remove — 卸载套件（通过 force 忽略 kit_in_use，通过 prune 清理孤立依赖）。
• gripforge_gamekit_configure — 合并配置值或切换 enabled，无需卸载。
• gripforge_gamekit_dependencies — 获取项目的依赖关系图，或目录中某个套件的清单树。
• gripforge_gamekit_update — 获取更新计划（试运行），或设置 apply=true 写入锁定文件并运行迁移；省略 id 可更新所有套件。
• gripforge_gamekit_deliver — 生成计划（dry_run），然后打包引擎文件，适用于 godot / unity / unreal（web 为原生目标）；根据 plan.actions 写入 bundle.files。
• gripforge_gamekit_deliver_local（仅适用于此 npm 客户端）— 直接交付到 project_dir：计算 gripforge/** 的哈希、读取锁定文件，并执行操作，同时将备份保存到 gripforge/.backup/<plan id>/；设置 verify=true 且存在 GODOT_BIN 时，会以无头模式运行 Godot。
• gripforge_gamekit_rollback_local（仅适用于此 npm 客户端）— 恢复上次交付的备份，并还原之前的锁定文件。
• gripforge_game_capabilities — 查看项目提供的能力、目标所缺少的能力，以及可填补各项缺口的套件。
• gripforge_game_project — 对项目执行 action=list|create|get|bind|data|delete 操作（绑定项为 slot → lib_…，支持数据集合；删除需设置 confirm=true）。
• gripforge_game_play_url — 获取项目当前修订版本的浏览器游玩 URL（{ url, absolute }）。

第三人称游戏的角色朝向

使用 { "prompt": "third person", "third_person": true } 调用 gripforge_input_kit。 将返回的 third_person.source_js 保存为 character-facing.js；它导出：

// Keep this object for the lifetime of one character.
const facingState = { velocity: 0, targetYaw: currentYaw };
updateCharacterFacing(currentYaw, {
  moveX, moveZ, lookYaw, aiming, firing, building
}, dtSeconds, facingState)

传入世界空间中的移动方向（前方为 -Z）、以弧度表示的角度，以及以秒为单位的经过时间。自由移动时，角色会朝向移动方向；静止时，会完成最后一次转向并保持该朝向。瞄准、开火或建造时，角色会转向 lookYaw。转向沿最短弧线进行，并受角速度和角加速度限制，同时保持模拟输入方向的连续性。长时间暂停后，经过时间会被限制为不超过 0.1 秒。可选状态支持平滑加速和制动；旧版三参数调用仍可使用速度上限。传送角色或替换角色后，请重置状态。

返回的 usage_three 会旋转外层角色组，保留导入模型的四元数，并使相机控制保持独立。此辅助工具仅提供朝向。请保留现有的移动、物理、碰撞、相机和网络系统。省略 third_person 或将其设为 false 时，会返回现有输入套件，不含附加部分。此选项可在托管 MCP 和此源代码检出中使用；已发布的 npm 0.1.5 中不包含此选项。

性能诊断

gripforge_performance 已包含在此源代码检出版本和托管 MCP 中。 已发布的 npm 0.1.5 包不包含它。请使用上方的托管端点，或使用 pnpm --filter @gripforgeai/mcp build 构建此检出版本，并将 MCP 客户端配置为运行 node，并传入 packages/mcp-client/dist/server.js 的绝对路径。部署网站不会更新 已安装的 npm 包。

要检索 API 密钥工作区中从游戏明确共享的最新捕获数据：

{ "kit_id": "lib_your_kit_id" }

省略 kit_id 可使用该工作区的最新捕获数据。如果没有可用数据，该工具会请求提供捕获数据或报告；不会捏造测量结果。 或者，提供复制的诊断 JSON：

{
  "report": {
    "game": "Eclat Royale",
    "viewport": { "width": 1920, "height": 1080 },
    "samples": [
      { "fps": 32, "frameMs": 31.25, "p95Ms": 48, "cpuMs": 12, "submitMs": 7, "networkMs": 65 },
      { "fps": 34, "frameMs": 29.41, "p95Ms": 43, "cpuMs": 11, "submitMs": 6, "networkMs": 70 },
      { "fps": 31, "frameMs": 32.26, "p95Ms": 50, "cpuMs": 13, "submitMs": 8, "networkMs": 62 }
    ]
  }
}

这些示例值用于展示格式。请提供受影响游戏会话的测量数据。报告接受 1–120 个样本，每个样本都需要 fps 或 frameMs。可选字段包括 pixelRatio、quality、level、gpuMs、 drawCalls、triangles 和 snapshotAgeMs，以及上文所述的计时字段。 该工具会在发送报告给 GripForge 前剔除无法识别的报告字段。显式提交的报告使用分析模式，且不会保存为捕获数据。

结果会区分测量所得的发现与建议。渲染器提交耗时是已计入 cpuMs 的 CPU／驱动程序耗时；只有实际测得时，gpuMs 才有意义。该工具不会控制浏览器、更改游戏设置、发布代码或自动修复游戏。

环境变量

• GRIPFORGE_API_KEY（必需）——1 个额度 = 1 次成功连接
• GRIPFORGE_API_URL（可选）——默认为 https://gripforge.ai