Fmodel Unpack

fmodel-unpack

Overview

fmodel-mcp is a minimal, headless alternative to the FModel GUI for ripping assets out of Unreal Engine games. It is not a fork of FModel — it wraps the underlying CUE4Parse library directly so an assistant (or a script) can search, read, and export UE assets without clicking through the FModel window.

It is split into two layers on purpose:

• Cli/ — the only component that links to CUE4Parse. A single self-contained fmodel-cli.exe exposing subcommands (status, search, read, inspect, export-tex, export-mesh, export-mesh-uf, export-anim, export-raw, list) that all print one JSON object to stdout. Usable standalone for ad-hoc scripts.
• Server/ — a thin FastMCP (Python, stdio) server that invokes the CLI as a subprocess and exposes each subcommand as an MCP tool (fmodel_*).

All asset knowledge lives in CUE4Parse; this toolkit only marshals arguments and parses JSON. That means the CLI can be evolved independently of any LLM integration.

The repo checkout used here is ..\fmodel-mcp. The CLI is already built at ..\fmodel-mcp\Cli\bin\publish\fmodel-cli.exe.

When to use this skill

Trigger this skill when any of the following appear:

• "Extract / unpack / rip assets from <UE game>" (e.g. Duet Night Abyss, Expedition 33).
• "Set up config.json for a game so I can read its paks."
• "Export this texture / mesh / animation / material from the game files."
• Driving the fmodel_* MCP tools, or invoking fmodel-cli.exe directly.
• Troubleshooting "paks dir not found", mount-point mismatches, Oodle download, AES, or .usmap mapping errors.

Prerequisites

• .NET runtime — not needed for the self-contained fmodel-cli.exe (runtime is embedded). Only needed if running the framework-dependent .dll via dotnet exec.
• Internet on first run — fmodel-cli downloads the Oodle decompression DLL (oo2core_9_win64.dll on Windows) on demand from the OodleUE GitHub release. The DLL is not redistributable and is gitignored. After the first successful run it sits next to the exe and is reused.
• For the MCP server: Python ≥ 3.11 and uv (uv sync in Server/).
• The game's paks present on disk (.pak / .utoc / .ucas).

Note on versions: Cli/FModelCli.csproj targets net10.0. The README still mentions net9.0 in places (and Server/src/server.py defaults its fallback DLL path to Debug/net9.0/...). This mismatch is harmless — the server prefers the published bin/publish/fmodel-cli.exe first. Always prefer the published exe; only fall back to a Debug .dll build if you deliberately made one.

Step 1 — Configure for the game (the central step)

Copy config.json.example to config.json next to the CLI binary (Cli/bin/publish/config.json) or point the FMODEL_MCP_CONFIG env var at an absolute path. Config lookup order inside the CLI: FMODEL_MCP_CONFIG → <baseDir>/config.json → <repoRoot>/config.json → a fake <EDIT-ME> placeholder (which surfaces a "paks dir not found" error if nothing is set).

Config keys:

Detailed, copy-paste configs (Duet Night Abyss, Expedition 33) and where each value comes from (FModel AppSettings.json) are in references/game-configs.md.

Step 2 — Verify the provider

Run status first. If it errors, almost everything else will too.

# via the MCP tool
fmodel_status()

# or directly
..\fmodel-mcp\Cli\bin\publish\fmodel-cli.exe status

Expected shape:

{
    "ok": true,
    "paksDir": "...",
    "outputDir": "...",
    "ueVersion": "GAME_UE4_27",
    "mappings": "....usmap",
    "mappingsLoaded": true,
    "files": 123456
}

files is the number of indexed package entries — a non-zero count means paks mounted and Oodle + AES + mappings all applied.

Step 3 — Locate the asset (search)

search takes a glob over package paths (the same keys CUE4Parse indexes). Rules: ** matches any number of path components, * matches a single component, ? matches one character. Case-insensitive.

fmodel-cli.exe search "**/MI_*"            # material instances
fmodel-cli.exe search "**/MI_Curator*"     # exact-ish
fmodel-cli.exe search "EM/Content/Characters/**/*" 1000

Returns { ok, pattern, count, truncated, matches:[...] }. truncated is true when the optional limit (default 200) was hit.