deadlock-mcp 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. deadlock_mcp-0.1.0/LICENSE +21 -0
  2. deadlock_mcp-0.1.0/PKG-INFO +146 -0
  3. deadlock_mcp-0.1.0/README.md +122 -0
  4. deadlock_mcp-0.1.0/deadlock_mcp/__init__.py +3 -0
  5. deadlock_mcp-0.1.0/deadlock_mcp/__main__.py +3 -0
  6. deadlock_mcp-0.1.0/deadlock_mcp/assets.py +441 -0
  7. deadlock_mcp-0.1.0/deadlock_mcp/bridge.py +365 -0
  8. deadlock_mcp-0.1.0/deadlock_mcp/config.py +181 -0
  9. deadlock_mcp-0.1.0/deadlock_mcp/consolelog.py +97 -0
  10. deadlock_mcp-0.1.0/deadlock_mcp/css.py +279 -0
  11. deadlock_mcp-0.1.0/deadlock_mcp/env.py +56 -0
  12. deadlock_mcp-0.1.0/deadlock_mcp/errors.py +20 -0
  13. deadlock_mcp-0.1.0/deadlock_mcp/game.py +184 -0
  14. deadlock_mcp-0.1.0/deadlock_mcp/js/bridge_main.js +62 -0
  15. deadlock_mcp-0.1.0/deadlock_mcp/js/core.js +408 -0
  16. deadlock_mcp-0.1.0/deadlock_mcp/js/request_main.js +159 -0
  17. deadlock_mcp-0.1.0/deadlock_mcp/layout.py +125 -0
  18. deadlock_mcp-0.1.0/deadlock_mcp/resource.py +68 -0
  19. deadlock_mcp-0.1.0/deadlock_mcp/server.py +675 -0
  20. deadlock_mcp-0.1.0/deadlock_mcp/templates/inbox.vxml_c +0 -0
  21. deadlock_mcp-0.1.0/deadlock_mcp/templates/script.vjs_c +0 -0
  22. deadlock_mcp-0.1.0/deadlock_mcp/toolchain.py +220 -0
  23. deadlock_mcp-0.1.0/deadlock_mcp/vpk.py +126 -0
  24. deadlock_mcp-0.1.0/deadlock_mcp/watchdog.py +59 -0
  25. deadlock_mcp-0.1.0/deadlock_mcp.egg-info/PKG-INFO +146 -0
  26. deadlock_mcp-0.1.0/deadlock_mcp.egg-info/SOURCES.txt +41 -0
  27. deadlock_mcp-0.1.0/deadlock_mcp.egg-info/dependency_links.txt +1 -0
  28. deadlock_mcp-0.1.0/deadlock_mcp.egg-info/entry_points.txt +2 -0
  29. deadlock_mcp-0.1.0/deadlock_mcp.egg-info/requires.txt +8 -0
  30. deadlock_mcp-0.1.0/deadlock_mcp.egg-info/top_level.txt +1 -0
  31. deadlock_mcp-0.1.0/pyproject.toml +44 -0
  32. deadlock_mcp-0.1.0/setup.cfg +4 -0
  33. deadlock_mcp-0.1.0/tests/test_assets.py +260 -0
  34. deadlock_mcp-0.1.0/tests/test_bridge.py +382 -0
  35. deadlock_mcp-0.1.0/tests/test_config.py +86 -0
  36. deadlock_mcp-0.1.0/tests/test_css.py +127 -0
  37. deadlock_mcp-0.1.0/tests/test_e2e.py +168 -0
  38. deadlock_mcp-0.1.0/tests/test_js.py +678 -0
  39. deadlock_mcp-0.1.0/tests/test_layout.py +81 -0
  40. deadlock_mcp-0.1.0/tests/test_server.py +437 -0
  41. deadlock_mcp-0.1.0/tests/test_toolchain.py +90 -0
  42. deadlock_mcp-0.1.0/tests/test_vpk.py +39 -0
  43. deadlock_mcp-0.1.0/tests/test_watchdog.py +55 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 John Susek
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,146 @@
1
+ Metadata-Version: 2.4
2
+ Name: deadlock-mcp
3
+ Version: 0.1.0
4
+ Summary: MCP server for live-editing Deadlock's Panorama UI (XML / CSS / JS)
5
+ License-Expression: MIT
6
+ Project-URL: Homepage, https://github.com/johnsusek/DeadlockMCP
7
+ Project-URL: Issues, https://github.com/johnsusek/DeadlockMCP/issues
8
+ Keywords: mcp,deadlock,panorama,source2,modding
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: Operating System :: POSIX :: Linux
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Topic :: Games/Entertainment
13
+ Requires-Python: >=3.11
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Requires-Dist: mcp<3,>=2.3
17
+ Requires-Dist: esprima>=4.0
18
+ Requires-Dist: gdown>=6.5
19
+ Provides-Extra: dev
20
+ Requires-Dist: pytest>=8; extra == "dev"
21
+ Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
22
+ Requires-Dist: mini-racer>=0.12; extra == "dev"
23
+ Dynamic: license-file
24
+
25
+ <p align="center"><img src="https://raw.githubusercontent.com/johnsusek/DeadlockMCP/main/logo.svg" alt="deadlock-mcp logo" width="160"></p>
26
+ <!-- mcp-name: io.github.johnsusek/deadlock-mcp -->
27
+
28
+ # DeadlockMCP
29
+
30
+ An [MCP](https://modelcontextprotocol.io) server for building Deadlock UI mods.
31
+
32
+ Live-edit Deadlock's Panorama UI (XML/CSS/JS) while the game runs.
33
+
34
+ Connect it to an MCP client with an agent and ask for things like "find the panel that shows my stat boosts and move it to bottom-center".
35
+
36
+ The server installs an addon that uses the dev tools to update the UI. The agent inspects the live panel tree, tries CSS and JS in the running game, takes screenshots to check the result, and then compiles the change into a mod VPK.
37
+
38
+ > ⚠️ **Status: Alpha.** Tested only on Bazzite (KDE Wayland) with Proton, Deadlock build #6,861 (Nov 2026). Other Linux setups may work but are untested. Windows and macOS aren't supported yet; help supporting other platforms is welcome.
39
+
40
+ ## Getting started
41
+
42
+ You need Linux with Deadlock installed through Steam (running under Proton) and [uv](https://docs.astral.sh/uv/). Steam must be running when the game launches, so the game can log in.
43
+
44
+ 1. **Add the server to your MCP client** (stdio). It must run on the same Linux desktop session as the game:
45
+ ```json
46
+ {
47
+ "mcpServers": {
48
+ "deadlock": {
49
+ "command": "uvx",
50
+ "args": ["deadlock-mcp"]
51
+ }
52
+ }
53
+ }
54
+ ```
55
+ With Claude Code: `claude mcp add deadlock -- uvx deadlock-mcp`. Paths are auto-detected; [TECH.md](TECH.md#environment-overrides) lists the environment variables to override them.
56
+ 2. **Ask your agent to set it up.** It runs `setup`, which downloads [Source 2 Viewer CLI](https://github.com/ValveResourceFormat/ValveResourceFormat) and [CSDK 13](https://deadlockmodding.pages.dev/modding-tools/csdk-13) (about 1.6 GB) and creates a Wine prefix for the compiler. If the CSDK download fails, it asks you to download the `.7z` into `~/Downloads` yourself. `setup` also lists any missing system tools (`7z`, `xdotool`, ImageMagick, `umu-run`) with the install command for your distro.
57
+ 3. **Ask it to start the game**: it runs `bridge_install`, then `launch_game(map="new_player_basics")`. The game boots straight into a sandbox match with the full HUD, ready for changes.
58
+
59
+ ## Making a mod
60
+
61
+ 1. **Get set up** as described above, with the game running in the sandbox.
62
+ 2. **Tell your agent what you want**, for example "move my stat boosts to bottom-center" or "make the ability cooldown numbers bigger". It finds the panels, tries the change live, and takes screenshots to check. Keep giving feedback until it looks right.
63
+ 3. **Ask it to package the mod**, for example "make that permanent and install it as a mod called my_hud". You get `~/.local/share/deadlock-mcp/mods/my_hud/pak01_dir.vpk`, and with install it's also copied into `game/citadel/addons/` under the next free `pakNN_dir.vpk` name.
64
+
65
+ The exported VPK is a normal mod: it doesn't include the bridge and doesn't need this tool to run.
66
+
67
+ ## Tools
68
+
69
+ Most tools take `ui='hud' | 'dashboard' | 'overlay'` to pick a panel tree; the default `auto` uses the first one that's ready.
70
+
71
+ **Game**
72
+
73
+ | tool | description |
74
+ |---|---|
75
+ | `status` | Reports paths, game and bridge state, and anything that needs fixing, and pings each in-game bridge. |
76
+ | `launch_game` | Launches Deadlock with the dev addon mounted, optionally straight into the sandbox map with the full HUD. |
77
+ | `quit_game` | Closes Deadlock. |
78
+ | `console_log` | Returns recent game console output, optionally regex-filtered. |
79
+ | `screenshot` | Captures the game window (or the whole screen) as an image, with an optional crop. |
80
+
81
+ **Game files**
82
+
83
+ | tool | description |
84
+ |---|---|
85
+ | `ui_files` | Lists the Panorama files shipped in the game, with a regex filter. |
86
+ | `ui_source` | Decompiles a shipped Panorama layout, stylesheet or script to source. |
87
+
88
+ **Live editing**
89
+
90
+ | tool | description |
91
+ |---|---|
92
+ | `panel_tree` | Dumps the live panel hierarchy (id, type, layout, size, position, text) under a panel. |
93
+ | `panel_find` | Finds live panels with a CSS-like selector. |
94
+ | `js_eval` | Runs JavaScript in the game's UI and returns the result. |
95
+ | `css_apply` | Applies CSS to live panels as inline styles, re-applying it as panels are recreated. |
96
+ | `css_clear` | Removes one live CSS sheet, or all of them. |
97
+ | `xml_load` | Compiles Panorama XML (and optional CSS) and loads it into the live UI. |
98
+ | `layout_live_edit` | Live-edits an existing game layout's stylesheet, applying only the changed declarations. |
99
+ | `layout_live_revert` | Reloads the original layout into panels changed by `layout_live_edit`. |
100
+ | `panel_delete` | Deletes a live panel by id. |
101
+
102
+ **Building and exporting**
103
+
104
+ | tool | description |
105
+ |---|---|
106
+ | `compile_source` | Compiles a Panorama file into the dev addon as a permanent override (applies after a restart). |
107
+ | `list_overrides` | Lists the compiled files in the dev addon. |
108
+ | `remove_override` | Removes a compiled override from the dev addon. |
109
+ | `export_mod` | Exports the overrides, without the bridge, as a standalone mod VPK, and optionally installs it into the game. |
110
+
111
+ **Setup**
112
+
113
+ | tool | description |
114
+ |---|---|
115
+ | `setup` | Installs Source 2 Viewer CLI, CSDK 13 and the compiler's Wine prefix, and lists missing system tools. |
116
+ | `bridge_install` | Builds the in-game bridges and packs them into the dev addon; re-run after a game update. |
117
+ | `bridge_uninstall` | Removes the bridge files from the dev addon. |
118
+ | `addons_mount` | Adds or removes the dev addon's search path in `gameinfo.gi`. |
119
+
120
+ Parameters and implementation details: [TECH.md](TECH.md#tools).
121
+
122
+ ## What it installs
123
+
124
+ `setup` puts everything under `~/.local/share/deadlock-mcp/` (`$DEADLOCK_MCP_DATA` to move it):
125
+
126
+ * `tools/s2v/`: [Source 2 Viewer CLI](https://github.com/ValveResourceFormat/ValveResourceFormat), to decompile game files.
127
+ * `tools/Reduced_CSDK_13/`: [CSDK 13](https://deadlockmodding.pages.dev/modding-tools/csdk-13), whose `resourcecompiler.exe` compiles Panorama files (about 5.4 GB).
128
+ * `wine/`: a Wine prefix made by Proton, to run the compiler.
129
+ * `mods/`: exported mods.
130
+
131
+ It doesn't install system packages.
132
+
133
+ ## What it modifies
134
+
135
+ * **`game/citadel/gameinfo.gi`**: `launch_game` adds a marked block that mounts the dev addon (and `citadel/addons`, so installed mods still load), saving the previous file as `gameinfo.gi.mcp-bak`. The addon is unmounted automatically when that game exits; if the game crashed or the PC rebooted, `status` warns and `addons_mount(False)` removes it.
136
+ * **`game/citadel/mcp_addons/`**: the dev addon, holding the bridge, your compiled overrides, and the request files the server talks to the game through.
137
+ * **`game/citadel/console.log`**: the game writes it (`-condebug`) and the server deletes it on each launch.
138
+ * **`game/citadel/addons/`**: `export_mod(install=True)` copies the mod there.
139
+ * **`~/.local/share/deadlock-mcp/tools/Reduced_CSDK_13/{content,game}/citadel_addons/mcp_bridge/`**: sources and compiler output.
140
+ * **`~/.cache/deadlock-mcp/`**: decompiled sources, launch and watcher logs.
141
+
142
+ No shipped game files are changed. Agent-launched games are for building mods: play your matches from a normal Steam launch, which doesn't load the bridge.
143
+
144
+ ## License
145
+
146
+ MIT. Deadlock and its assets belong to Valve.
@@ -0,0 +1,122 @@
1
+ <p align="center"><img src="https://raw.githubusercontent.com/johnsusek/DeadlockMCP/main/logo.svg" alt="deadlock-mcp logo" width="160"></p>
2
+ <!-- mcp-name: io.github.johnsusek/deadlock-mcp -->
3
+
4
+ # DeadlockMCP
5
+
6
+ An [MCP](https://modelcontextprotocol.io) server for building Deadlock UI mods.
7
+
8
+ Live-edit Deadlock's Panorama UI (XML/CSS/JS) while the game runs.
9
+
10
+ Connect it to an MCP client with an agent and ask for things like "find the panel that shows my stat boosts and move it to bottom-center".
11
+
12
+ The server installs an addon that uses the dev tools to update the UI. The agent inspects the live panel tree, tries CSS and JS in the running game, takes screenshots to check the result, and then compiles the change into a mod VPK.
13
+
14
+ > ⚠️ **Status: Alpha.** Tested only on Bazzite (KDE Wayland) with Proton, Deadlock build #6,861 (Nov 2026). Other Linux setups may work but are untested. Windows and macOS aren't supported yet; help supporting other platforms is welcome.
15
+
16
+ ## Getting started
17
+
18
+ You need Linux with Deadlock installed through Steam (running under Proton) and [uv](https://docs.astral.sh/uv/). Steam must be running when the game launches, so the game can log in.
19
+
20
+ 1. **Add the server to your MCP client** (stdio). It must run on the same Linux desktop session as the game:
21
+ ```json
22
+ {
23
+ "mcpServers": {
24
+ "deadlock": {
25
+ "command": "uvx",
26
+ "args": ["deadlock-mcp"]
27
+ }
28
+ }
29
+ }
30
+ ```
31
+ With Claude Code: `claude mcp add deadlock -- uvx deadlock-mcp`. Paths are auto-detected; [TECH.md](TECH.md#environment-overrides) lists the environment variables to override them.
32
+ 2. **Ask your agent to set it up.** It runs `setup`, which downloads [Source 2 Viewer CLI](https://github.com/ValveResourceFormat/ValveResourceFormat) and [CSDK 13](https://deadlockmodding.pages.dev/modding-tools/csdk-13) (about 1.6 GB) and creates a Wine prefix for the compiler. If the CSDK download fails, it asks you to download the `.7z` into `~/Downloads` yourself. `setup` also lists any missing system tools (`7z`, `xdotool`, ImageMagick, `umu-run`) with the install command for your distro.
33
+ 3. **Ask it to start the game**: it runs `bridge_install`, then `launch_game(map="new_player_basics")`. The game boots straight into a sandbox match with the full HUD, ready for changes.
34
+
35
+ ## Making a mod
36
+
37
+ 1. **Get set up** as described above, with the game running in the sandbox.
38
+ 2. **Tell your agent what you want**, for example "move my stat boosts to bottom-center" or "make the ability cooldown numbers bigger". It finds the panels, tries the change live, and takes screenshots to check. Keep giving feedback until it looks right.
39
+ 3. **Ask it to package the mod**, for example "make that permanent and install it as a mod called my_hud". You get `~/.local/share/deadlock-mcp/mods/my_hud/pak01_dir.vpk`, and with install it's also copied into `game/citadel/addons/` under the next free `pakNN_dir.vpk` name.
40
+
41
+ The exported VPK is a normal mod: it doesn't include the bridge and doesn't need this tool to run.
42
+
43
+ ## Tools
44
+
45
+ Most tools take `ui='hud' | 'dashboard' | 'overlay'` to pick a panel tree; the default `auto` uses the first one that's ready.
46
+
47
+ **Game**
48
+
49
+ | tool | description |
50
+ |---|---|
51
+ | `status` | Reports paths, game and bridge state, and anything that needs fixing, and pings each in-game bridge. |
52
+ | `launch_game` | Launches Deadlock with the dev addon mounted, optionally straight into the sandbox map with the full HUD. |
53
+ | `quit_game` | Closes Deadlock. |
54
+ | `console_log` | Returns recent game console output, optionally regex-filtered. |
55
+ | `screenshot` | Captures the game window (or the whole screen) as an image, with an optional crop. |
56
+
57
+ **Game files**
58
+
59
+ | tool | description |
60
+ |---|---|
61
+ | `ui_files` | Lists the Panorama files shipped in the game, with a regex filter. |
62
+ | `ui_source` | Decompiles a shipped Panorama layout, stylesheet or script to source. |
63
+
64
+ **Live editing**
65
+
66
+ | tool | description |
67
+ |---|---|
68
+ | `panel_tree` | Dumps the live panel hierarchy (id, type, layout, size, position, text) under a panel. |
69
+ | `panel_find` | Finds live panels with a CSS-like selector. |
70
+ | `js_eval` | Runs JavaScript in the game's UI and returns the result. |
71
+ | `css_apply` | Applies CSS to live panels as inline styles, re-applying it as panels are recreated. |
72
+ | `css_clear` | Removes one live CSS sheet, or all of them. |
73
+ | `xml_load` | Compiles Panorama XML (and optional CSS) and loads it into the live UI. |
74
+ | `layout_live_edit` | Live-edits an existing game layout's stylesheet, applying only the changed declarations. |
75
+ | `layout_live_revert` | Reloads the original layout into panels changed by `layout_live_edit`. |
76
+ | `panel_delete` | Deletes a live panel by id. |
77
+
78
+ **Building and exporting**
79
+
80
+ | tool | description |
81
+ |---|---|
82
+ | `compile_source` | Compiles a Panorama file into the dev addon as a permanent override (applies after a restart). |
83
+ | `list_overrides` | Lists the compiled files in the dev addon. |
84
+ | `remove_override` | Removes a compiled override from the dev addon. |
85
+ | `export_mod` | Exports the overrides, without the bridge, as a standalone mod VPK, and optionally installs it into the game. |
86
+
87
+ **Setup**
88
+
89
+ | tool | description |
90
+ |---|---|
91
+ | `setup` | Installs Source 2 Viewer CLI, CSDK 13 and the compiler's Wine prefix, and lists missing system tools. |
92
+ | `bridge_install` | Builds the in-game bridges and packs them into the dev addon; re-run after a game update. |
93
+ | `bridge_uninstall` | Removes the bridge files from the dev addon. |
94
+ | `addons_mount` | Adds or removes the dev addon's search path in `gameinfo.gi`. |
95
+
96
+ Parameters and implementation details: [TECH.md](TECH.md#tools).
97
+
98
+ ## What it installs
99
+
100
+ `setup` puts everything under `~/.local/share/deadlock-mcp/` (`$DEADLOCK_MCP_DATA` to move it):
101
+
102
+ * `tools/s2v/`: [Source 2 Viewer CLI](https://github.com/ValveResourceFormat/ValveResourceFormat), to decompile game files.
103
+ * `tools/Reduced_CSDK_13/`: [CSDK 13](https://deadlockmodding.pages.dev/modding-tools/csdk-13), whose `resourcecompiler.exe` compiles Panorama files (about 5.4 GB).
104
+ * `wine/`: a Wine prefix made by Proton, to run the compiler.
105
+ * `mods/`: exported mods.
106
+
107
+ It doesn't install system packages.
108
+
109
+ ## What it modifies
110
+
111
+ * **`game/citadel/gameinfo.gi`**: `launch_game` adds a marked block that mounts the dev addon (and `citadel/addons`, so installed mods still load), saving the previous file as `gameinfo.gi.mcp-bak`. The addon is unmounted automatically when that game exits; if the game crashed or the PC rebooted, `status` warns and `addons_mount(False)` removes it.
112
+ * **`game/citadel/mcp_addons/`**: the dev addon, holding the bridge, your compiled overrides, and the request files the server talks to the game through.
113
+ * **`game/citadel/console.log`**: the game writes it (`-condebug`) and the server deletes it on each launch.
114
+ * **`game/citadel/addons/`**: `export_mod(install=True)` copies the mod there.
115
+ * **`~/.local/share/deadlock-mcp/tools/Reduced_CSDK_13/{content,game}/citadel_addons/mcp_bridge/`**: sources and compiler output.
116
+ * **`~/.cache/deadlock-mcp/`**: decompiled sources, launch and watcher logs.
117
+
118
+ No shipped game files are changed. Agent-launched games are for building mods: play your matches from a normal Steam launch, which doesn't load the bridge.
119
+
120
+ ## License
121
+
122
+ MIT. Deadlock and its assets belong to Valve.
@@ -0,0 +1,3 @@
1
+ """Deadlock Panorama live-editing MCP server."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,3 @@
1
+ from .server import main
2
+
3
+ main()