Skip to main content
Glama
README.md
# FModel MCP v2

MCP server (stdio) đọc trực tiếp file `.pak` của Unreal Engine bằng [CUE4Parse](https://github.com/FabianFG/CUE4Parse) — **không cần mở FModel GUI**.

Khác với v1 (UI Automation), v2 mount pak và đọc asset bằng code, nên nhanh hơn nhiều và có thêm các tool phân tích cấu trúc (widget tree, object search, dependency, extract file thô).

## Yêu cầu

- Windows / Linux / macOS
- [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) (nếu build từ source) hoặc .NET 8 Runtime (nếu chạy bản có sẵn)
- File `.pak` của game (không kèm theo repo)
- AES key của game nếu pak bị mã hoá

## Cài đặt

### Cách 1 — Build từ source (khuyến nghị khi dev)

```powershell
git clone https://github.com/5coinin1/fmodel_mcp.git
cd fmodel_mcp
dotnet build -c Release
```

File chạy: `bin/Release/net8.0/FModelMcp.dll`

### Cách 2 — Publish 1 file exe self-contained

```powershell
./publish.ps1
```

Kết quả: `dist/FModelMcp.exe` (~35 MB, không cần cài .NET trên máy đích).

## Đăng ký MCP

### opencode (`~/.config/opencode/opencode.jsonc`)

```jsonc
{
  "mcp": {
    "servers": {
      "fmodel-v2": {
        "type": "local",
        "command": ["dotnet", "C:\\path\\to\\FModelMcp.dll"]
      }
    }
  }
}
```

Hoặc dùng bản exe:

```jsonc
"fmodel-v2": {
  "type": "local",
  "command": ["C:\\path\\to\\dist\\FModelMcp.exe"]
}
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "fmodel-v2": {
      "command": "C:\\path\\to\\dist\\FModelMcp.exe"
    }
  }
}
```

### Cursor (`.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "fmodel-v2": {
      "command": "C:\\path\\to\\dist\\FModelMcp.exe"
    }
  }
}
```

## Quy trình sử dụng

1. **`load_package`** — mount thư mục pak (gọi 1 lần mỗi session):
   ```json
   {
     "directory": "D:/Game/Content/Paks",
     "game_version": "UE4_25",
     "aes_key": "0x..."
   }
   ```
2. **`search_assets` / `browse_assets`** — tìm asset theo tên hoặc duyệt theo path.
3. **`load_asset` / `read_properties`** — xem export list và property.
4. **`find_objects` / `get_class` / `get_dependencies`** — phân tích sâu bên trong asset.
5. **`export_asset`** — dump toàn bộ object ra file text.
6. **`extract_file` / `extract_files`** — lấy file thô (Lua, CSV, JSON, ...) ra khỏi pak.

### Ví dụ

```jsonc
// 1. Mount
{"name":"load_package","arguments":{
  "directory":"D:/CalabiYau/PM/Content/Paks",
  "game_version":"UE4_25",
  "aes_key":"0x7456667C...CDE40"
}}

// 2. Tìm widget chat
{"name":"search_assets","arguments":{"query":"WBP_Chat","limit":50}}

// 3. Đọc property của export đầu tiên
{"name":"read_properties","arguments":{
  "asset_path":"PM/Content/PaperMan/UI/BP/PC/Frontend/Chat/WBP_ChatInput.uasset",
  "export_index":0
}}

// 4. Tìm button bên trong widget
{"name":"find_objects","arguments":{
  "asset_path":"PM/Content/PaperMan/UI/BP/PC/Frontend/Chat/WBP_ChatInput.uasset",
  "name":"Btn_Send"
}}

// 5. Extract Lua
{"name":"extract_file","arguments":{
  "file_path":"PM/Content/Script/Business/Chat/Init.lua",
  "output_dir":"C:/exports/lua"
}}
```

## Danh sách tool (15)

| Tool | Tham số | Chức năng |
| --- | --- | --- |
| `list_packages` | `directory` | Liệt kê file `.pak` trong thư mục |
| `load_package` | `directory`, `game_version`, `aes_key` | Mount pak, khởi tạo provider |
| `browse_assets` | `path`, `offset`, `limit` | Duyệt asset theo path (phân trang) |
| `search_assets` | `query`, `limit` | Tìm asset theo substring |
| `load_asset` | `asset_path` | Trả về danh sách export (tên, type, outer) |
| `read_properties` | `asset_path`, `export_index` | Đọc toàn bộ property của 1 export |
| `list_tree` | `path`, `depth` | Liệt kê cây thư mục |
| `get_info` | — | Thống kê provider (số file, extension) |
| `get_class` | `asset_path` | Class name + chuỗi kế thừa |
| `find_objects` | `asset_path`, `class_name`, `name` | Tìm object bên trong asset |
| `get_dependencies` | `asset_path` | Asset mà asset này tham chiếu tới |
| `get_references` | `asset_path` | Asset tham chiếu tới asset này (quét chậm) |
| `export_asset` | `asset_path`, `output_dir` | Export toàn bộ object ra `.txt` |
| `extract_file` | `file_path`, `output_path`/`output_dir` | Extract 1 file thô từ pak |
| `extract_files` | `file_paths[]`, `output_dir` | Extract nhiều file thô |

## Lưu ý & giới hạn

- **AES key**: pak của nhiều game bị mã hoá. Key có thể lấy từ `FModel/AppSettings.json` (mục `AesKeys.mainKey`) hoặc cộng đồng. Truyền vào `load_package`.
- **Đường dẫn asset**: CUE4Parse dùng path dạng `PM/Content/...` (theo pak), không phải `/Game/...`. Dùng `search_assets` để xem path thật.
- **Blueprint function bodies**: CUE4Parse không decompile bytecode Blueprint, nên `export_asset` chỉ có metadata/property, không có logic function.
- **Lua**: `extract_file` lấy được bytes thô. Một số game mã hoá nội dung file (file-level encryption) — khi đó bytes vẫn là ciphertext, cần key riêng để giải mã. Nếu không mã hoá, file là Lua bytecode và có thể decompile bằng `unluac` (nếu dùng Slua/UnLua).
- **UStringTable / UDataTable**: có thể chỉ export được metadata (RowStruct) do CUE4Parse chưa deserialize đầy đủ; dùng `extract_file` với file CSV gốc nếu có trong pak.
- **`get_references`** quét toàn bộ pak (hàng trăm nghìn file) nên rất chậm — chỉ dùng khi thật cần.
- **Output mặc định** là thư mục `exports/` tương đối theo working directory của client. Nên truyền `output_dir` tuyệt đối.

## Troubleshooting

| Lỗi | Nguyên nhân / cách xử lý |
| --- | --- |
| `No package loaded` | Chưa gọi `load_package` |
| `File not found in pak` | Sai path — dùng `search_assets` để lấy path đúng |
| `RequiredKeys` > 0, 0 file | Thiếu/sai `aes_key` |
| Build lỗi `file is locked by .NET Host` | MCP server đang chạy giữ DLL — tắt client hoặc `Stop-Process` các tiến trình `dotnet` đang chạy `FModelMcp.dll` rồi build lại |
| Không thấy tool trong client | Kiểm tra `command` trỏ đúng DLL/exe, chạy thử `dotnet FModelMcp.dll` trong terminal để xem lỗi |

## Cấu trúc project

```
fmodel_mcp/
├── Program.cs        # MCP server (JSON-RPC stdio + 15 tools)
├── FModelMcp.csproj  # net8.0 + CUE4Parse 1.0.5
├── publish.ps1       # publish self-contained single-file
└── README.md
```

## License

Chỉ dùng cho mục đích học tập/nghiên cứu trên asset bạn sở hữu hợp pháp.