内容
# fmodel-mcp
用于通过 [CUE4Parse](https://github.com/FabianFG/CUE4Parse) 检查和导出虚幻引擎资产的最小MCP服务器，CUE4Parse是[FModel](https://github.com/4sval/FModel)所依赖的解析库。设计用于与LLM编码助手（Claude Code等）一起使用，以便其可以搜索、读取和导出UE资产，而无需通过FModel GUI进行往返。
> **不是FModel的分支。** FModel本身是一个WPF应用程序，没有命令行界面（CLI）。该项目直接封装了底层CUE4Parse库。从精神上讲，它是一个 sibling 工具 — 将FModel交互式公开的功能以编程方式公开。
## 为什么
在另一个引擎（这里是 Unity 2019.4 + Vivify for Beat Saber）中处理从UE游戏（这里是 *Expedition 33*）中提取的资产意味着很多“打开FModel，导航，导出，复制到项目”的操作。摩擦力与促使封装Unity编辑器的[unity-mcp](https://github.com/CoplayDev/unity-mcp)的摩擦力相同。相同的答案：提供一个助手可以直接驱动的工具。
## 架构
```
fmodel-mcp/
├── Cli/ # 独立的.NET 9二进制文件
│ └── ... # 使用CUE4Parse，单文件发布
├── Server/ # FastMCP Python服务器（stdio传输）
│ └── src/
└── mappings/ # .usmap文件（gitignored，游戏特定）
```
按设计分为两层：
- **Cli/** 是唯一链接到CUE4Parse的部分。它公开了子命令（`status`、`search`、`read`、`inspect`、`export-tex`、`export-mesh`、`export-mesh-uf`、`export-anim`、`export-raw`、`list`），这些子命令将JSON打印到stdout。单独使用时对临时脚本很有用。
- **Server/** 是一个薄的Python MCP服务器，它调用CLI作为子进程，并将其功能公开为MCP工具。比CUE4Parse独立演化更便宜。
## 工具（第一层）
| 工具 | 功能 |
|---|---|
| `fmodel_status` | 健康检查：提供者初始化，# paks，# 文件索引 |
| `fmodel_search(模式)` | 包名称的glob/正则表达式：`**/MI_Curator*` |
| `fmodel_read(路径)` | 返回包JSON而不导出 |
| `fmodel_inspect_material(路径)` | 快捷方式：仅限纹理 + 标量 + 矩阵 + 父级 + 混合模式 |
| `fmodel_export_texture(路径)` | PNG/TGA到`Output/Exports/...` |
| `fmodel_export_mesh(路径)` | SkeletalMesh/StaticMesh作为ActorX `.psk`/`.pskx`到`Output/Exports/...` |
| `fmodel_export_mesh_uf(路径)` | SkeletalMesh/StaticMesh作为`.uemodel`（UEFormat）— 与`fmodel_export_anim`中的`.ueanim`绑定 |
| `fmodel_export_anim(路径)` | AnimSequence/AnimMontage作为`.ueanim`（UEFormat，保持骨骼缩放）到`Output/Exports/...` |
| `fmodel_export_raw(路径)` | 完整的JSON转储（材质实例JSON最终成为的种类） |
| `fmodel_list_exports(前缀)` | 列出已导出的内容 |
## 项目约定
- 输出目录在`config.json`中配置（参见下面的设置），并被视为临时目录 — 与FModel的`Output/Exports/`具有相同的角色。
- “将精选的子集提升到实际项目”的步骤在此故意不涉及；工具导出，您复制您保留的内容。
## 设置
### 构建CLI
```pwsh
cd <repo>/Cli
dotnet publish -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -o bin/publish
```
这会生成一个单独的`fmodel-cli.exe`（~90 MB，嵌入.NET运行时）。第一次运行时，会从[WorkingRobot/OodleUE](https://github.com/WorkingRobot/OodleUE)下载Oodle DLL（`oodle-data-shared.dll`）到同一文件夹。Oodle不可重新分发，因此存储库不包含它。
### 为您的游戏配置
将`config.json.example`复制到`config.json`，并放在.exe旁边（或任何地方，然后将`FMODEL_MCP_CONFIG`指向它），然后为您的游戏编辑路径。示例值针对*Expedition 33* — 该CLI最初为其构建的游戏 — 作为工作参考。
配置键：
- `PaksDir`：包含游戏的`*.pak` / `*.utoc` / `*.ucas`的目录。
- `OutputDir`：导出目的地的目录。
- `UeVersion`：CUE4Parse版本枚举（例如`GAME_UE5_4`）。
- `MappingsFile`：`.usmap`文件的路径（某些游戏需要它；可为空）。
- `AesKey`：加密密钥作为十六进制字符串（大多数游戏不需要它；可为空）。
### 安装MCP服务器
```pwsh
cd <repo>/Server
uv sync
```
### 连接到Claude Code
在`~/.claude.json`中添加以下内容到`mcpServers`下（使用本地代码库的绝对路径）：
```json
"fmodel": {
"type": "stdio",
"command": "uv",
"args": ["run", "--directory", "<absolute-path-to>/fmodel-mcp/Server", "python", "src/server.py"]
}
```
重启Claude Code；`mcp__fmodel__*`工具应该会出现。
## 状态
最初为*Expedition 33*（UE 5.4，无AES）构建 — 这些值在`config.json.example`中提供。尚未推广到其他游戏：`Program.cs`中的包路径规范化器硬编码了E33的`Sandfall/Content`挂载点，因此具有不同挂载点的第二个游戏需要使该帮助程序可配置。
