# PoB PoE2 MCP

MCP для [официального Path of Building — Path of Exile 2](https://github.com/PathOfBuildingCommunity/PathOfBuilding-PoE2). Работает с уже установленным приложением или его portable-версией. Все игровые расчёты выполняют оригинальные классы Lua.

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

Оба режима предоставляют одинаковые 13 инструментов.

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

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

1. Скачайте [pob-poe2-mcp-windows-x64.zip](https://github.com/Hecatoncheir/pob-poe2-mcp/releases/download/v0.2.0/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-версии или нестандартного пути укажите каталог вручную:

```powershell
./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 может заменить `Launch.lua`. В этом случае повторите запуск `connect-app.cmd` и перезапустите PoB.
- **`disconnect-app.cmd`** удаляет подключение; затем нужно перезапустить PoB. Последующие изменения исходного файла сохраняются при удалении блока моста.

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

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

```powershell
./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` подставит фактический путь вместо примера:

```json
{
  "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 ещё не установлен

Установите его из [официальных выпусков](https://github.com/PathOfBuildingCommunity/PathOfBuilding-PoE2/releases). Для отдельного расчёта можно вместо графического приложения загрузить закреплённые исходники и runtime:

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

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

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

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

```powershell
python -m venv .venv
./.venv/Scripts/python -m pip install "git+https://github.com/Hecatoncheir/pob-poe2-mcp.git@v0.2.0"
./.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](https://setuptools.pypa.io/en/stable/). В готовый ZIP включён официальный [CPython 3.14.10 embeddable x64](https://www.python.org/downloads/release/python-31410/); исходный архив проверяется по опубликованному SHA-256.

## Инструменты

| Инструмент | Назначение |
| --- | --- |
| `pob_catalog` | Каталоги классов, камней, баз предметов, слотов, узлов и условий. |
| `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_poe2_mcp/data/tools.json) · [Описание API](docs/api.md) · [Пример Python API](examples/build_fireball.py).

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

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

Поддерживается Windows x64. Проверена обычная официальная установка **PoB 0.23.1**, включая чтение и изменение текущей сборки в настоящем окне, ручные правки и обнаружение устаревшей ревизии. Отдельно проверяются исходники официального репозитория в закреплённой ревизии. Совместимость будущих версий не предполагается автоматически: например, отсутствие заметок узлов в старой версии возвращается как `UNSUPPORTED_OPERATION`.

```powershell
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](CHANGELOG.md). Для выпуска обновите версию в `pyproject.toml` и `pob_poe2_mcp/__init__.py`, добавьте раздел с датой в changelog, затем отправьте коммит и тег:

```powershell
git tag v0.2.0
git push origin main v0.2.0
```

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

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

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

Адаптер первоначально выделен из [app/tools форка](https://github.com/Hecatoncheir/PathOfBuilding-PoE2/tree/b565cd99ec9fad46167bc4de145d3491b9c669e7/app/tools); зависимости от этого форка для установки и работы нет. Служебные headless-определения включены из официального репозитория, ревизия `bb52d6b368307457eb9c54bb13f1829993d390b1`. Игровые классы и данные используются из выбранного PoB без переноса формул в Python.

[MIT](LICENSE); сохранён [исходный файл лицензий PoB](licenses/PathOfBuilding-PoE2.txt). В ZIP также входит лицензия CPython. Данные и ресурсы Path of Exile принадлежат их правообладателям; проект не является официальным продуктом Grinding Gear Games.