war-selection-mcp

Локальный MCP-сервер (stdio) для моддинга War Selection (Glyph Worlds) на Lua.

Русский | English | Client setup / Подключение клиентов | API dump / Выгрузка API | Changelog

Неофициальный проект, не связан с Glyph Worlds. War Selection является товарным знаком Glyph Worlds.

Русский

Обзор

Сервер даёт MCP-клиенту доступ к локальным файлам установленной игры:

• код скачанных модов в modsStorage;

• игровые JSON-данные в Cache/Projects/WarSelection;

• лог gen/log.txt;

• индекс Lua API: встроенный (имена и сигнатуры из дерева WSUS, игра 258.4018, плюс заметки с источниками) и живой, выгруженный из запущенной игры скриптом из lua/ (docs/api-dump.md);

• встроенное руководство по моддингу на русском (src/ws_mcp/data/guide-ru.md).

Кроме чтения, сервер проверяет код модов статически (синтаксис Lua 5.4 и известные ошибки), сравнивает версии модов, разбирает ошибки Lua в логе и выдаёт заготовки модов. Сетевых запросов сервер не делает.

Требования

• Python 3.10 или новее; CI проверяет 3.13 и 3.14.

• Установленная War Selection (Windows или Linux через Steam/Proton).

• MCP-клиент с поддержкой stdio.

Установка

python -m venv .venv
.venv/bin/pip install git+https://github.com/fixees/war-selection-mcp.git

На Windows: .venv\Scripts\pip install git+https://github.com/fixees/war-selection-mcp.git.

Обновление: та же команда с --upgrade. Пакет устанавливает команду war-selection-mcp; эквивалент: python -m ws_mcp.

Настройка

Подключение клиента

Большинство клиентов принимают блок mcpServers:

{
  "mcpServers": {
    "war-selection": {
      "command": "C:\\path\\to\\.venv\\Scripts\\python.exe",
      "args": ["-m", "ws_mcp"],
      "env": {
        "WS_GAME_DIR": "C:\\Program Files (x86)\\Steam\\steamapps\\common\\War Selection"
      }
    }
  }
}

Готовый фрагмент с путём к текущему интерпретатору печатает war-selection-mcp --print-config <client>; список клиентов: --list-clients. Пути к файлам конфигурации и форматы для конкретных клиентов: docs/clients.md.

После обновления пакета перезапустите сервер в клиенте, чтобы получить новый список инструментов.

Инструменты

lint_mod проверяет код статически. Неизвестные имена выдаются как предупреждения. Без живого индекса имена сверяются с WSUS 258.4018 и модами из кэша. После import_api_dump добавляется правило absent-in-engine: функция из WSUS 258, которой нет в выгрузке текущего движка.

Обновление индекса API из игры

1. Возьмите lua/wsdump.lua (запуск через мод) или lua/wsdump-oneline.lua (консоль F8), либо сгенерируйте скрипт через api_dump_script.

2. Запустите его в режиме разработчика на своей карте. Выгрузка пишется в gen/log.txt.

3. Вызовите import_api_dump. Чтобы раскрыть ветки из unexplored, повторите шаги 1–3.

Подробно, с форматом и списком проверенного и предположений: docs/api-dump.md.

Asset Editor и карты

• asset_editor_info, list_asset_manifests: редактор ассетов Steam и пакеты в modsStorage/manifests+blobs. Подробно: docs/asset-editor.md.

• list_map_drafts: черновики карт редактора.

• F8: session.gameplay.dumpToFile=<имя> (=; только имя файла → корень игры, проверено 01.11.2026). Session dump, не API: docs/console-dump.md. Workspace карты: docs/mods-workspace.md.

Черновики и кэш модов

Проверено по логам игроков (2023, 2025) и папке modsStorage на живой установке:

• Кэш опубликованных модов: modsStorage/<id>_<версия>-<hash16>.lua и .prm. <id> — 11 символов (mod-<id> в игре), <hash16> постоянен для мода во всех версиях.

• Черновики: modsStorage/draft/<id>_<версия>-<hash16>.lua. В логе они видны как Using gameplay modifications: draft/<id>_<версия> и /modsStorage/draft/...lua в ошибках.

• Создание мода в режиме разработчика происходит на сервере (Start request "Create mod" в логе), локальный файл при этом не появляется. Файл черновика создаёт игра при «Редактировать скрипт» или при запуске карты с этим модом. Поэтому write_draft только перезаписывает существующий черновик и не создаёт файлы.

Обновления игры

При старте сервер сравнивает игру с последним снимком и при изменениях делает новый (отключается WS_MCP_AUTO_SNAPSHOT=0). Первый снимок — точка отсчёта; diff появится после следующего обновления игры. После патча: diff_game_versions, затем mod_impact. Подробно: docs/game-snapshots.md.

Ошибки в реальном времени

• В клиенте: watch_log_start, затем периодически watch_log_poll(since_seq=<next_seq>). Или log_tail(cursor) для сырых строк.

• В терминале: war-selection-mcp --watch-log (с --from-start — с начала текущего лога), остановка Ctrl+C.

Форматы ошибок, что проверено и что предполагается: docs/log-watch.md.

Безопасность

• Все инструменты, кроме write_draft, import_api_dump, snapshot_game и diff_game_versions, только читают файлы и помечены readOnlyHint.

• import_api_dump, snapshot_game и diff_game_versions пишут только в WS_MCP_DATA_DIR (api_index_live.json, snapshots/, diffs/). Если эта папка оказалась внутри папки игры, они отказываются.

• Скрипт выгрузки только читает поля движка внутри pcall и не вызывает функции f_*.

• write_draft перезаписывает только существующий файл в modsStorage/draft (атомарно). Копия прежнего файла сохраняется в WS_MCP_DATA_DIR/draft-backups, в папке игры лишних файлов не появляется. Пути за пределами папки и симлинки отклоняет.

• Файлы игры вне modsStorage/draft сервер не изменяет.

• По словам разработчика (Wouw, Discord, 30.07.2023), правка файлов модов в обход внутриигрового редактора может затронуть релизную версию мода, а за это кикают из матчей и банят. Применяйте и публикуйте моды через редактор в режиме разработчика. write_draft используется на свой риск.

Разработка

git clone https://github.com/fixees/war-selection-mcp.git
cd war-selection-mcp
python -m venv .venv
.venv/bin/pip install -e ".[test]"
.venv/bin/pytest -q

Тесты работают на синтетической папке игры. Чтобы прогнать дополнительный тест на реальных файлах, задайте WS_SAMPLE_DIR. Если в PATH есть lua5.4, скрипт выгрузки прогоняется на макете движка (tests/fixtures/mock_engine.lua). Встроенный индекс API пересобирается скриптом scripts/build_api_index.py, файлы в lua/ скриптом scripts/build_lua.py, тестовая выгрузка скриптом scripts/make_dump_fixture.py. Не коммитьте файлы игры (modsStorage, Cache, логи, *.pack); они перечислены в .gitignore.

Благодарности

• wsunitstats.com: дерево API WSUS.

• AdrienRmd/War_Selection_Modding.

• Сообщество War Selection на английском и СНГ Discord-серверах.

Лицензия

MIT, см. LICENSE.

Related MCP server: mcplocal

English

Overview

Local stdio MCP server for War Selection (Glyph Worlds) Lua modding. It gives an MCP client access to local game files:

• cached mod source in modsStorage;

• game data JSON in Cache/Projects/WarSelection;

• the game log gen/log.txt;

• a Lua API index: bundled (names and signatures from the WSUS tree, game 258.4018, plus sourced notes) and a live one dumped from the running game with the script in lua/ (docs/api-dump.md);

• a bundled Russian modding guide (src/ws_mcp/data/guide-ru.md).

It also lints mod code (Lua 5.4 syntax and known pitfalls), diffs mod versions, parses Lua errors from the log and returns mod scaffolds. The server makes no network requests.

Requirements

• Python 3.10+; CI runs 3.13 and 3.14.

• An installed copy of War Selection (Windows, or Linux via Steam/Proton).

• An MCP client with stdio support.

Installation

python -m venv .venv
.venv/bin/pip install git+https://github.com/fixees/war-selection-mcp.git

On Windows use .venv\Scripts\pip. Upgrade with the same command plus --upgrade. The package installs the war-selection-mcp command; python -m ws_mcp is equivalent.

Configuration

Client setup

Use the mcpServers JSON from the Russian section. war-selection-mcp --print-config <client> prints a ready snippet with the current interpreter path; --list-clients lists the supported names. Per-client file locations and formats are in docs/clients.md; the client table above applies. Restart the server in your client after upgrading so it picks up the new tool list.

Tools

lint_mod is static analysis. Unknown names are warnings. Without a live index, names are checked against WSUS 258.4018 and cached mods. After import_api_dump the absent-in-engine rule reports WSUS 258 functions that the current engine does not have.

Refreshing the API index from the game

1. Take lua/wsdump.lua (run as a mod) or lua/wsdump-oneline.lua (F8 console), or generate one with api_dump_script.

2. Run it in developer mode on your own map. The dump goes to gen/log.txt.

3. Call import_api_dump. Repeat steps 1-3 to expand the subtrees listed in unexplored.

Details, record format, and what is verified versus assumed: docs/api-dump.md.

Asset Editor and maps

• asset_editor_info, list_asset_manifests: Steam Asset Editor and packs under modsStorage/manifests+blobs. Details: docs/asset-editor.md.

• list_map_drafts: map editor drafts.

• F8: session.gameplay.dumpToFile=<name> (=; filename only → game root, verified 2026-11-01). Session dump, not an API tree: docs/console-dump.md. Map workspace: docs/mods-workspace.md.

Drafts and the mod cache

Verified from player logs (2023, 2025) and the modsStorage folder of a live install:

• Published mod cache: modsStorage/<id>_<version>-<hash16>.lua and .prm. <id> has 11 characters (mod-<id> in game); <hash16> stays the same for a mod across versions.

• Drafts: modsStorage/draft/<id>_<version>-<hash16>.lua. The log shows them as Using gameplay modifications: draft/<id>_<version> and as /modsStorage/draft/...lua in errors.

• Creating a mod in developer mode is a server request (Start request "Create mod" in the log); no local file appears. The game writes the draft file on "Edit script" or when a map with the mod is started. write_draft therefore only overwrites an existing draft and never creates files.

Game updates

On start the server compares the game with the latest snapshot and stores a new one if it changed (disable with WS_MCP_AUTO_SNAPSHOT=0). The first snapshot is the baseline; a diff becomes available after the next game update. After a patch: diff_game_versions, then mod_impact. Details: docs/game-snapshots.md.

Live errors

• In a client: watch_log_start, then watch_log_poll(since_seq=<next_seq>) periodically, or log_tail(cursor) for raw lines.

• In a terminal: war-selection-mcp --watch-log (--from-start reads the current log from the beginning); stop with Ctrl+C.

Error formats, verified and assumed: docs/log-watch.md.

Safety notes

• All tools except write_draft, import_api_dump, snapshot_game and diff_game_versions are read-only and annotated with readOnlyHint.

• import_api_dump, snapshot_game and diff_game_versions write only to WS_MCP_DATA_DIR (api_index_live.json, snapshots/, diffs/) and refuse if that folder is inside the game folder.

• The dump script only reads engine fields inside pcall and never calls f_* functions.

• write_draft only overwrites an existing file in modsStorage/draft (atomic replace). The previous content is copied to WS_MCP_DATA_DIR/draft-backups, so no extra files appear in the game folder. Path traversal and symlinks are rejected.

• The server does not modify game files outside modsStorage/draft.

• According to the developer (Wouw, Discord, 2023-07-30), editing mod files outside the in-game editor can affect the released mod version and may result in kicks and bans. Apply and publish mods through the editor in developer mode. Use write_draft at your own risk.

Development

pip install -e ".[test]"
pytest -q

Tests use a synthetic game directory; set WS_SAMPLE_DIR to run the optional test against real files. With lua5.4 on PATH the dump script is also run against an engine mock (tests/fixtures/mock_engine.lua). Rebuild the bundled index with scripts/build_api_index.py, the files in lua/ with scripts/build_lua.py, and the dump fixture with scripts/make_dump_fixture.py. Do not commit game files; they are listed in .gitignore.

Credits

• wsunitstats.com for the WSUS API tree.

• AdrienRmd/War_Selection_Modding.

• The War Selection community on the English and CIS Discord servers.

License

MIT, see LICENSE.

Unofficial project, not affiliated with Glyph Worlds. War Selection is a trademark of Glyph Worlds.