Skip to main content
Glama

FModel MCP v2

MCP server (stdio) đọc trực tiếp file .pak của Unreal Engine bằng 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 (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á

Related MCP server: uiautomation-mcp

Cài đặt

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

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

./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)

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

Hoặc dùng bản exe:

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

Claude Desktop (claude_desktop_config.json)

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

Cursor (.cursor/mcp.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):

    {
      "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ụ

// 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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to control Windows systems using AutoHotkey v2 and the UI Automation accessibility tree for efficient, text-based computer interaction. It provides tools for window management, keystrokes, and UI inspection while significantly reducing token costs compared to screenshot-based approaches.
      9
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to inspect and automate Windows desktop UI elements by exploring UI trees, checking properties, performing actions like clicking and typing, and generating Python automation scripts.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables Windows UI Automation through MCP, allowing agents to inspect, search, navigate, and interact with desktop UI elements via the UIAutomation framework. Supports actions such as focus, invoke, set-value, toggle, and event waiting, with CLI and VS Code extension variants.
      4
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables reading and interacting with native Windows application UI through the UI Automation API, allowing listing windows, extracting structured content, and performing clicks/typing without screenshot-based vision.
      2
      MIT