Pob Poe2

MCP для официального Path of Building — Path of Exile 2. Работает с уже установленным приложением или его portable-версией. Все игровые расчёты выполняют оригинальные классы Lua.

Режим	Поведение
engine	Использует файлы установленного PoB для отдельной сессии расчёта. Окно программы можно закрыть.
app	Читает и изменяет текущую сборку прямо в открытом окне PoB через устанавливаемый Lua-мост.

Оба режима предоставляют одинаковые 14 инструментов, включая создание PNG-отчётов о сборке.

Простая установка на Windows

Если PoB уже установлен, Python, pip, Git и второй экземпляр движка не нужны.

1. Скачайте pob-poe2-mcp-windows-x64.zip и распакуйте в постоянный каталог, например C:/Tools/. Внутри появится папка pob-poe2-mcp.
2. Запустите check.cmd: он автоматически найдёт установленный PoB и проверит расчёт через Lua.
3. Для работы с открытым окном один раз запустите connect-app.cmd, затем перезапустите PoB и откройте нужную сборку. Для режима engine этот шаг не требуется.
4. Запустите mcp-config.cmd и скопируйте показанную настройку в свой MCP-клиент. Она уже содержит правильные абсолютные пути и оба сервера: pob-engine и pob-app.

Файлы .cmd можно запускать двойным щелчком. В ZIP входит изолированный Python: он не устанавливается в систему. Обычная установка PoB определяется по реестру Windows и стандартным каталогам.

Для portable-версии или нестандартного пути укажите каталог вручную:

./pob-mcp.cmd doctor --pob-dir "D:/Games/PoB2"
./pob-mcp.cmd install-bridge --pob-dir "D:/Games/PoB2"

Добавьте "--pob-dir", "D:/Games/PoB2" в args сервера pob-engine. Режим app находит адрес моста сам. При нескольких найденных установках требуется явный выбор каталога.

Работа с открытым окном

connect-app.cmd добавляет отмеченный блок загрузки в Launch.lua, сохраняет резервную копию и копирует Lua-мост в %LOCALAPPDATA%/pob-poe2-mcp/bridge/. После перезапуска MCP работает с той же сборкой и расчётами, которые видны в окне. Изменения сохраняются обычной кнопкой Save в PoB.

• Ручные изменения в окне обнаруживаются по ревизии. После STALE_REVISION заново прочитайте сборку перед изменением.
• Создание новой сборки и импорт XML блокируются при несохранённых изменениях. Сначала сохраните текущую сборку в PoB.
• При открытом диалоге изменения возвращают APP_BUSY.
• Одновременно к окну подключается один MCP-клиент. Для независимого расчёта используйте pob-engine.
• После закрытия или перезапуска PoB сервер pob-app подключается заново при следующем запросе. Прерванный запрос чтения повторяется один раз; команды изменения автоматически не повторяются, поскольку могли уже выполниться. После потери ответа на изменение сначала прочитайте текущую сборку.
• Обновление PoB может заменить Launch.lua. В этом случае повторите запуск connect-app.cmd и перезапустите PoB.
• disconnect-app.cmd удаляет подключение; затем нужно перезапустить PoB. Последующие изменения исходного файла сохраняются при удалении блока моста.

Мост слушает только 127.0.0.1 на автоматически выбранном порту и проверяет случайный токен в каждом запросе. Токен хранится локально, в настройку MCP-клиента его копировать не нужно. Публичного HTTP-сервера нет.

Команды и настройка

./pob-mcp.cmd doctor                     # Проверить установленный движок
./pob-mcp.cmd doctor --mode app          # Проверить связь с открытым окном
./pob-mcp.cmd serve --mode engine        # MCP: отдельный расчёт
./pob-mcp.cmd serve --mode app           # MCP: текущая сборка окна
./pob-mcp.cmd config                     # Показать готовую настройку обоих серверов
./pob-mcp.cmd install-bridge             # Установить Lua-мост
./pob-mcp.cmd uninstall-bridge           # Удалить Lua-мост

Пример настройки из ZIP; команда config подставит фактический путь вместо примера:

{
  "mcpServers": {
    "pob-engine": {
      "command": "C:/Tools/pob-poe2-mcp/python/python.exe",
      "args": ["-X", "utf8", "-m", "pob_poe2_mcp", "serve", "--mode", "engine"]
    },
    "pob-app": {
      "command": "C:/Tools/pob-poe2-mcp/python/python.exe",
      "args": ["-X", "utf8", "-m", "pob_poe2_mcp", "serve", "--mode", "app"]
    }
  }
}

Приоритет выбора движка: --pob-dir, POB_DIR, автоматически найденная установка, каталог команды setup. Рабочий каталог клиента может быть любым. Режим app использует адрес запущенного Lua-моста; при явном --pob-dir проверяет совпадение с подключённым приложением.

При запуске serve процесс ожидает запросы по stdin. stdout содержит только сообщения MCP, диагностика — в stderr. Обычный облачный чат сам не подключается к локальному процессу: нужен клиент с поддержкой MCP stdio.

Если PoB ещё не установлен

Установите его из официальных выпусков. Для отдельного расчёта можно вместо графического приложения загрузить закреплённые исходники и runtime:

./pob-mcp.cmd setup
./pob-mcp.cmd doctor

Только команда setup требует Git и скачивает движок. Она использует PathOfBuildingCommunity/PathOfBuilding-PoE2, ревизия записана в engine-lock.json. Автоматически найденная установленная версия имеет приоритет над этой копией. При обычной работе MCP ничего не скачивает.

Для разработчиков

Установка из GitHub: Python 3.11+ и Git; Windows x64, Linux x64 или macOS arm64.

python -m venv .venv
./.venv/Scripts/python -m pip install "git+https://github.com/Hecatoncheir/[email protected]"
./.venv/Scripts/python -m pob_poe2_mcp doctor
./.venv/Scripts/python -m pob_poe2_mcp config

Или git clone https://github.com/Hecatoncheir/pob-poe2-mcp.git, затем python -X utf8 run.py doctor. Во всех командах pob-mcp.cmd можно заменить на python -m pob_poe2_mcp или python -X utf8 run.py из клона.

Во время работы сторонние Python-пакеты не нужны. Для сборки wheel используется setuptools. В готовый ZIP включён официальный CPython 3.14.10 embeddable x64; исходный архив проверяется по опубликованному SHA-256.

Инструменты

pob_get_tree возвращает компактную геометрию настоящего дерева Lua для собственного интерфейса: координаты, связи, имена, типы и выбранные узлы, версию и строку очков. Он не зависит от PNG или Direct3D.

Инструмент	Назначение
pob_catalog	Каталоги классов, камней, баз предметов, слотов, узлов и условий.
pob_gem_icons	Оригинальные изображения по ID камней, с SHA-256 и кешем; игровые ресурсы скачиваются отдельно.
pob_gem_supports	Подходящие поддержки для черновика группы; проверка исходного PoB в отдельном Lua без изменения текущей сборки.
pob_update_skill_group	Изменение существующей группы без дублирования, с сохранением дополнительных параметров камней через исходный Lua.
pob_delete_skill_group	Удаление группы исходным SkillListControl с пересчётом выбранного основного умения.
pob_create_build	Создание сборки с классом и уровнем.
pob_import_xml	Импорт полного XML PathOfBuilding2.
pob_add_skill_group	Добавление группы камней.
pob_add_item	Разбор игрового текста предмета и установка в слот.
pob_set_config	Условия расчёта.
pob_set_custom_mods	Пользовательские модификаторы.
pob_tree_action	Назначение и возврат узлов, атрибуты, заметки при поддержке версии PoB.
pob_tree_options	Класс, восхождение, оружейный режим, набор дерева.
pob_select_main_skill	Выбор основного умения.
pob_node_tooltip	Подсказка узла и изменения расчётов.
pob_check_build	Отчёт, предупреждения и проверка числовых целей.
pob_export_xml	Экспорт полного XML.
pob_render_image	PNG: сводка, схема дерева, характеристики, предметы, камни, условия, заметки и предупреждения.

Схемы инструментов · Описание API · Пример Python API.

Изображения сборки

pob_render_image возвращает настоящий PNG в блоке MCP image и небольшие метаданные в structuredContent. Файлы на диск не записываются. В режиме engine окно PoB не нужно; в режиме app используются отчёт и XML текущей сборки через уже установленный мост. Для дерева MCP открывает этот XML в отдельной сессии Lua. Для обновления изображений достаточно обновить MCP и перезапустить его сервер; файлы установленного PoB только читаются.

Раздел view: overview, tree, stats, skills, items, config, notes, warnings, node, item или all. Для отдельного узла/предмета задайте id из каталога/отчёта. Дерево рисует оригинальный PassiveTreeView Lua: сохраняются размеры иконок, рамки, свечение, портреты, цвета оружейных наборов и дуги связей. Ресурсы DDS BC1/BC7 и PNG читаются из выбранной установки; штатный Direct3D 11 WARP воспроизводит команды без открытия окна. Служебные линии между началом класса и восхождением скрыты. treeScope: "allocated" показывает область назначенных узлов, "full" — всё дерево. query фильтрует строки отчёта или выбирает область дерева по имени/ID узла. zoom (0.25–8, по умолчанию 1) меняет масштаб дерева и всех его изображений вместе. Подписи узлов по умолчанию скрыты; включение — showLabels: true.

Размер по умолчанию — 1600×1100, допустимы width 640–2400 и height 480–2400. Длинные разделы разбиваются на страницы: запрашивайте page от 1 до pages из результата. Полный отчёт all включает все исходные показатели, настройки и подсказки PoB, пользовательские модификаторы, группы, предметы, слоты, наборы и заметки. Ошибки камней и неподдерживаемые строки входят в предупреждения. Используются штатные Windows GDI/Direct3D и zstd.dll из PoB; установка дополнительных пакетов не нужна.

Сначала читайте каталоги. Проверяйте предупреждения, ошибки камней, неподдержанные строки модификаторов и условия config. Успешный расчёт означает проверку в PoB; испытание в игре, стоимость и доступность предметов сюда не входят. Share-коды, торговля, импорт аккаунта и удалённый HTTP-транспорт не реализованы.

Совместимость и проверки

Режим engine поддерживает Windows x64, Linux x64 и macOS Apple Silicon. CI запускает настоящий Lua на всех трёх ОС. Режим app и PNG через GDI/Direct3D требуют Windows. На Windows проверена обычная официальная установка PoB 0.23.1, включая чтение и изменение текущей сборки в настоящем окне, ручные правки и обнаружение устаревшей ревизии. Отдельно проверяются исходники официального репозитория в закреплённой ревизии. Совместимость будущих версий не предполагается автоматически: например, отсутствие заметок узлов в старой версии возвращается как UNSUPPORTED_OPERATION.

На Linux/macOS скачайте соответствующий pob-poe2-mcp-native-*.zip из того же выпуска, что и исходники, проверьте SHA256SUMS и распакуйте его в pob_poe2_mcp/: получится каталог pob_poe2_mcp/native/. Затем выполните python3 run.py setup --destination .engine и python3 run.py doctor --mode engine --pob-dir .engine. Для явного каталога библиотек есть POB_MCP_NATIVE_DIR. Библиотеки не устанавливаются в системные каталоги.

Для самостоятельной сборки на Linux/macOS запустите python3 tools/build_native.py: нужны Git, make и компилятор C. Закреплённые исходники и лицензии записаны в tools/native-lock.json и архиве. Готовые библиотеки Linux собраны на Ubuntu 22.04; macOS — для arm64 с минимальной системой 11.0. Минимальная система не означает отдельную проверку на каждом её выпуске.

python -X utf8 -m unittest discover -s tests -v
python -X utf8 examples/build_fireball.py
python -X utf8 tools/build_portable.py

Без движка проверки настоящего Lua пропускаются. CI проверяет транспорт, выбор установки, обратимость моста, настоящий Lua, режим текущей сборки через общий API, wheel и готовый ZIP. Проверка общего API без окна в CI дополняет отдельную проверку настоящего графического приложения.

Changelog и автоматический релиз

История версий хранится в CHANGELOG.md. Для выпуска обновите версию в pyproject.toml и pob_poe2_mcp/__init__.py, добавьте раздел с датой в changelog, затем отправьте коммит и тег:

git tag v0.5.2
git push origin main v0.5.2

Workflow «Публикация релиза» проверит соответствие версий и наличие changelog, выполнит весь CI, соберёт wheel, Windows ZIP и нативные архивы Linux/macOS, затем опубликует GitHub Release с описанием из changelog и файлом SHA256SUMS. Ошибка проверок блокирует публикацию. Личный токен не требуется: используется стандартный GITHUB_TOKEN с правом записи только в задании публикации.

Для повторного запуска существует workflow_dispatch с обязательным указанием существующего тега. Уже опубликованный релиз при повторном запуске не перезаписывается.

Происхождение и лицензии

Адаптер первоначально выделен из app/tools форка; зависимости от этого форка для установки и работы нет. Служебные headless-определения включены из официального репозитория, ревизия bb52d6b368307457eb9c54bb13f1829993d390b1. Игровые классы и данные используются из выбранного PoB без переноса формул в Python.

MIT; сохранён исходный файл лицензий PoB. В ZIP также входит лицензия CPython. Данные и ресурсы Path of Exile принадлежат их правообладателям; проект не является официальным продуктом Grinding Gear Games.

Дерево для собственного интерфейса

pob_get_tree возвращает оригинальные координаты, связи, имена, типы, drawSize, выбранные состояния и ключи icon. Передайте до 32 ключей в pob_tree_icons: ответ содержит icons: [{key, png}], где png — base64 PNG RGBA. Неизвестный ресурс даёт error в записи. Геометрия и допустимость действий принадлежат Lua; Flutter может самостоятельно рисовать узлы, подписи и масштабирование. Декодирование всех 524 иконок проверяется на Windows/Linux/macOS. Исходные игровые ресурсы не включены в MCP.

Готовое оригинальное дерево

В MCP 0.7.0 pob_get_tree({includeScene:true}) вызывает исходный PassiveTreeView.Draw и отдаёт scene с scale, offsetX/Y и упорядоченными командами: позиции четырёх вершин, UV, цвет, режим смешивания, clamp и непрозрачный токен текстуры. pob_tree_textures({token}) возвращает base64 PNG RGBA только для ресурса выданной сцены. Это позволяет Flutter воспроизводить готовое дерево с оригинальными фонами, портретами, дугами и рамками. Исходники и игровые ресурсы остаются в отдельном установленном PoB.

На Windows DDS BC7 декодирует Direct3D WARP без окна; Linux/macOS используют bcdec из закреплённой ревизии, собранный в native-архив. Лицензии bcdec и Zstandard включены рядом с библиотеками. PNG возвращается без изменений. Текущая проверенная сцена использует ALPHA; неподдерживаемые маски завершаются явной ошибкой. Большие DDS используют mip-уровни около 512–1002 px для ограничения памяти.

pob_tree_hover({id, compare:true}) в MCP 0.8.0 возвращает оригинальную подсказку и небольшой дополнительный слой готовой подсветки пути. Для назначенного узла показывается штатная подсветка зависимых узлов при возврате. Перед этим загрузите базовую сцену; после изменения сборки загрузите её заново. Наведение не изменяет XML и ревизию.

Поиск влияния узлов

pob_node_power использует оригинальный Lua PoB в режиме engine: сначала action: catalog, затем start с stat и необязательным maxDistance (1–200; отсутствие означает всё дерево). Повторяйте poll с полученным job до complete: true; доступны allocation: unallocated|allocated|all и includeScene: true. cancel с тем же job отменяет работу. Строки уже отсортированы Lua и содержат powerStr, pathDist, pathPowerStr и id для фокусировки. Тепловая карта — оригинальная сцена PassiveTreeView, текстуры загружаются по выданным токенам. Ревизия и XML не меняются, после изменения сборки отчёт необходимо пересчитать.