# WolvenKit MCP — Cyberpunk 2077 Modding Tools

MCP server that gives Claude Code access to [WolvenKit](https://github.com/WolvenKit/WolvenKit) for Cyberpunk 2077 modding. Extract archives, convert game files to JSON, inspect meshes and textures, manage mods, and build mod projects — all from your terminal.

Works offline (no game running needed). Pairs with [CET MCP](https://github.com/Y4rd13/cyber-engine-tweak-mcp) for a complete AI-assisted modding pipeline.

## How it works

```
Claude Code → stdio/JSON-RPC → MCP Server → WolvenKit CLI (cp77tools) → filesystem
```

## Requirements

- **Node.js** >= 18
- **[WolvenKit CLI](https://www.nuget.org/packages/WolvenKit.CLI)** (installed via dotnet):
  ```bash
  dotnet tool install -g WolvenKit.CLI
  ```
- **Cyberpunk 2077** (for game archives)

## Setup

```bash
# 1. Clone and build
git clone https://github.com/Y4rd13/wolvenkit-mcp.git
cd wolvenkit-mcp
npm install
npm run build

# 2. Add to Claude Code globally
claude mcp add wolvenkit -s user \
  -e "WOLVENKIT_CLI=cp77tools" \
  -e "CP77_GAME_DIR=/path/to/Cyberpunk 2077" \
  -e "CP77_MOD_DIR=/path/to/Cyberpunk 2077/archive/pc/mod" \
  -- node /path/to/wolvenkit-mcp/build/index.js
```

## Tools (45)

### Archive Operations
| Tool | Description |
|------|-------------|
| `unbundle_archive` | Extract files from .archive with wildcard filter |
| `pack_archive` | Pack folder into .archive |
| `archive_info` | List all files inside an archive |
| `list_archives` | List all game archives |
| `search_archives` | Search files across ALL game archives by pattern |
| `list_installed_mods` | List installed mod archives with sizes |
| `mod_conflicts` | Detect file conflicts between installed mods |

### File Conversion
| Tool | Description |
|------|-------------|
| `convert_to_json` | REDengine file → editable JSON |
| `convert_from_json` | JSON → REDengine file |
| `inspect_file` | Quick structural summary of a game file |
| `get_game_file` | One-step: find in archives → extract → convert to JSON |
| `batch_convert` | Convert multiple files to JSON at once |
| `patch_json` | Modify specific fields in a game file JSON |

### Asset Inspection
| Tool | Description |
|------|-------------|
| `get_file_dependencies` | List all files referenced by a game file |
| `extract_mesh_info` | Mesh details: submeshes, materials, bones |
| `get_texture_info` | Texture details: resolution, format, mipmaps |
| `list_entity_components` | List entity components and appearances |
| `find_appearances` | Search for .app files by pattern |
| `find_materials` | List all materials used by a mesh |
| `list_inkatlas_slots` | List UI texture atlas slots |
| `get_animation_list` | List animations in .anims/.rig files |
| `search_game_files` | Search by extension + pattern within an archive |

### Asset Export/Import
| Tool | Description |
|------|-------------|
| `export_file` | Export to raw format (mesh→GLB, texture→PNG) |
| `import_file` | Import raw file back to REDengine format |
| `uncook_archive` | Extract + export in one step |

### Mod Projects
| Tool | Description |
|------|-------------|
| `create_mod_project` | Scaffold a mod project structure |
| `build_mod` | Pack and optionally install mod to game |
| `list_project_files` | List files in a mod project |
| `copy_to_project` | Extract a game file directly into a mod project |
| `validate_mod` | Check project structure and report issues |
| `strip_unused` | Find unreferenced/orphaned files in a project |
| `get_cooked_size` | Estimate final mod size by file type |
| `generate_tweakxml` | Generate TweakXL YAML templates |

### Mod Management
| Tool | Description |
|------|-------------|
| `backup_archive` | Create .bak backup of an archive |
| `restore_archive` | Restore archive from .bak backup |
| `compare_archives` | Compare mod archive vs original (added/removed files) |
| `merge_archives` | Merge multiple archive sources into one |
| `install_mod_from_url` | Download and install mod from direct URL |

### Info & Analysis
| Tool | Description |
|------|-------------|
| `wolvenkit_status` | CLI version, paths, availability check |
| `hash_value` | Compute FNV1a64 hash for game paths |
| `find_by_hash` | Search for a file by its hash value |
| `diff_files` | Compare two REDengine files showing changes |
| `analyze_performance` | Estimate mod performance impact (mesh/texture sizes) |
| `decompile_script` | Search for script files (.reds, .ws) in archives |
| `generate_xlmap` | Generate ArchiveXL resource mapping template |

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `WOLVENKIT_CLI` | `cp77tools` | WolvenKit CLI command |
| `CP77_GAME_DIR` | (see .mcp.json) | Game installation path |
| `CP77_MOD_DIR` | `<game>/archive/pc/mod` | Mod installation directory |

## WSL2 Notes

The MCP server runs on WSL2 but calls the Windows WolvenKit CLI via `cmd.exe`. Paths are automatically converted between WSL (`/mnt/g/...`) and Windows (`G:\...`) formats.

## License

MIT