VPX MCP Server

An implementation of the Model Context Protocol (MCP) that enables AI assistants (like Claude) to directly read, analyze, and edit Visual Pinball X (.vpx) table files.

This tool unlocks the ability to inspect a pinball table's script, elements, layers, collections, and images, and perform programmatic modifications (such as changing light states, moving items to layers, bulk-updating physics properties, or patching scripts) without opening the GUI editor.

---

Features

🔍 Table Inspection

• Summary statistics: Get counts of items, collections, images, sounds, and VBScript characters.
• Table Info Metadata: Read details such as table name, author, version, description, and release date.
• Item listing: List all table elements (Lights, Primitives, Flippers, Bumpers, Walls, etc.) with regex search and filtering by type or layer.
• Property inspection: Dump all low-level BIFF tags and raw/decoded values for any specific item.

📝 Script Management

• Script Extraction: Read the complete VBScript embedded inside the table.
• Script Search: Search the script using regular expressions with line number reporting.
• Script Patching: Search and replace text/code patterns (supporting plain text or regex substitutions).
• Script Replacement: Write an entirely new VBScript to the file.

💡 Element & Property Editing

• Property modification: Read and write 4-character BIFF properties on individual items (e.g., light states, visibility, locked status, timers).
• Bulk updates: Set properties across multiple elements matching specific filters (type, layer, name pattern).
• Structural modifications: Rename, duplicate (clone), or delete table elements.

📂 Layers & Collections

• Layer Management: List existing layers, create new layers, rename layers, delete layers, or move specific elements onto a layer.
• Collection Management: List, create, rename, delete collections, and add/remove element indices.

🖼️ Asset Manipulation

• Image Listing: List embedded textures/images with dimensions, format, and data sizes.
• Image Extraction: Save embedded images directly to disk.
• Image Replacement: Swap textures/images inside the .vpx file (supports JPEG).

🕹️ Simulation & Persist

• Save changes: Save modifications safely to a new .vpx file, or overwrite the original.
• Integrity Validation: Computes the required cryptographic signature (MAC) so Visual Pinball loads modified files successfully.
• Launch capability: Open Visual Pinball X directly in Edit mode or Play mode to test your changes instantly.

---

Architecture & How It Works

Visual Pinball X (.vpx) files are OLE compound files (structured storage documents), containing a hierarchy of streams. This server leverages Python libraries to manipulate these files directly:

1. Structured Storage Parsing: Uses olefile to read the internal file structure and win32com.client / pythoncom (via pywin32) to write and commit structured storage streams.
2. BIFF Serializer (biff_io.py): VPX elements are serialized in a Binary Interchange File Format (BIFF), consisting of Tag-Length-Value (TLV) records. This component handles low-level reading and writing of integers, floats, booleans, strings, and wide strings.
3. Cryptographic MAC Hashing: Visual Pinball checks a custom MD2 hash ("MAC") of the table's streams to prevent corruption/tampering. vpx_file.py computes this hash using the Windows CryptoAPI (win32crypt) during saves to ensure the resulting table is recognized as valid by Visual Pinball.

---

Prerequisites

Because VPX uses OLE Structured Storage and computes file integrity hashes using the Windows CryptoAPI, this server must run on Windows.

Installation Requirements

• Python 3.10+
• A working Visual Pinball X installation (default path assumed: C:\VirtualPinball\VisualPinball\VPinballX_GL.exe)
• The following python packages:
  • olefile
  • pywin32
  • mcp (or fastmcp)

Setup Environment

Install dependencies:

pip install olefile pywin32 mcp fastmcp

Ensure your VPX executable and tables folder are correctly path-mapped in server.py:

VPX_EXE = r"C:\VirtualPinball\VisualPinball\VPinballX_GL.exe"
TABLES_DIR = r"C:\VirtualPinball\VisualPinball\tables"

---

Configuration

To add this server to your Claude Desktop client, edit your claude_desktop_config.json (typically located at %APPDATA%\Roaming\Claude\claude_desktop_config.json or %USERPROFILE%\.config\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "vpx-mcp": {
      "command": "python",
      "args": [
        "N:/dev/vpx-mcp/server.py"
      ]
    }
  }
}

Make sure to adjust the directory path to match where this repository is checked out on your system.

---

Exposed MCP Tools

The server registers the following tools under the vpx namespace:

Table Summary & Discovery

• table_summary(path): High-level overview of elements, layers, collections, and metadata.
• list_items(path, type_filter, layer_filter, name_pattern): Search and list elements.
• get_item_properties(path, item_index): View all BIFF tags and values of a single item.

Element Editing

• set_item_property(path, item_index, tag, value, value_type): Modify a specific BIFF tag on an item.
• bulk_set_property(path, tag, value, value_type, type_filter, name_pattern, layer_filter): Apply property change to filtered items.
• rename_item(path, item_index, new_name): Change an item's editor name.
• duplicate_item(path, item_index, new_name): Clone an item.
• delete_item(path, item_index): Remove an item and update collection references.
• set_item_visible(path, item_index, visible): Show/hide an item.
• set_item_locked(path, item_index, locked): Lock/unlock an item in the editor view.

Layer Control

• list_layers(path): List all layers and active item counts.
• set_item_layer(path, item_index, layer_name): Move an item to a layer.
• move_items_to_layer(path, layer_name, item_indices, type_filter, name_pattern, from_layer): Bulk move items to a layer.
• create_layer(path, name, item_indices): Define a new editor layer.
• delete_layer(path, name): Delete a layer (items are moved to the default/unlayered state).
• rename_layer(path, old_name, new_name): Rename a layer.

Collections & Groups

• list_collections(path): List collections and their member indices.
• create_collection(path, name, item_indices): Group items into a new collection.
• add_to_collection(path, collection_name, item_index): Add an item index to a collection.
• remove_from_collection(path, collection_name, item_index): Remove an item from a collection.
• rename_collection(path, collection_name, new_name): Rename a collection.
• delete_collection(path, collection_name): Dissolve a collection (retains individual items).

Embedded Script Editing

• get_script(path): Retrieve the VBScript of a table.
• set_script(path, script): Replace the VBScript.
• search_script(path, pattern, case_sensitive): Run regex search on VBScript.
• patch_script(path, find, replace, case_sensitive, regex): Perform search-and-replace edits.

Embedded Image Assets

• list_images(path): List textures/images embedded in the table.
• extract_image(path, image_index, output_path): Extract raw image data to disk.
• replace_image(path, image_index, source_file): Replace image data with a new JPEG file.

Engine Operations

• save_vpx(path, output_path): Save the current state to disk.
• reload_vpx(path): Revert in-memory changes to the disk state.
• launch_vpx(path, play): Load the table directly inside Visual Pinball X (Play or Edit mode).

---

File Structure

vpx-mcp/
│
├── biff_io.py        # Stream-based Reader/Writer for BIFF (Binary Interchange File Format)
├── vpx_file.py       # Core VPXFile class handling OLE containers, MAC generation, and element helpers
└── server.py         # FastMCP Server exposing functions as standard tool endpoints

---

Safety & Backups

Warning

Editing .vpx binary files directly can result in table corruption if BIFF layouts mismatch or stream sizes are corrupted. Always save your edits to a separate output path or keep backups of your original .vpx tables before overwriting them.

---

License

The parser and serialization modules include logic adapted from GPL-licensed projects (such as vpx-lightmapper by Vincent Bousquet). Please review license notices inside biff_io.py and related files for compliance details.