PoB MCP Server

Model Context Protocol (MCP) сервер для интеграции с Path of Building (PoB)

Этот проект предоставляет полный MCP сервер для работы с Path of Building - популярным планировщиком билдов для игры Path of Exile 2.

📦 Версия 0.3.3 - GUI Автоматизация PoB

✨ Революционные улучшения в версии 0.3.3:

• 🖥️ Полная GUI автоматизация PoB - прямое взаимодействие с интерфейсом
• 🚀 Автоматический запуск и управление окнами PoB
• 🖱️ Симуляция пользовательского ввода (клики, клавиатура)
• 📊 Извлечение данных из GUI в реальном времени
• ⚡ Автоматизированное создание билдов через интерфейс
• 🔍 Поиск и активация окон PoB
• 💾 Автоматическое сохранение/загрузка билдов
• 📈 Извлечение статистики из визуального интерфейса
• 🤖 Динамическое обнаружение UI элементов с помощью Windows UI Automation API
• 📷 OCR интеграция для чтения текста с экрана
• 🎯 Валидация координат UI элементов в реальном времени

📋 Новые GUI инструменты:

Управление приложением:

• launch_pob_gui - Запуск PoB с автоматической настройкой
• find_pob_windows - Поиск всех открытых окон PoB
• activate_pob_window - Переключение между окнами

Работа с билдами:

• create_build_gui - Создание билда через GUI
• load_build_gui - Загрузка билда из файла
• save_build_gui - Сохранение билда
• calculate_build_gui - Расчет характеристик
• get_build_stats_gui - Извлечение статистики из интерфейса
• validate_build_gui - Валидация билда
• backup_build_gui - Создание резервной копии
• generate_build_report_gui - Генерация отчета о билде

Управление навыками:

• switch_tab_gui - Переключение между вкладками
• add_skill_gem_gui - Добавление гемов к навыкам
• search_skill_tree_gui - Поиск в дереве навыков
• set_character_level_gui - Установка уровня персонажа
• set_ascendancy_gui - Выбор ветки аскенданси
• simulate_level_progression_gui - Симуляция прокачки

Расширенные возможности:

• take_screenshot_gui - Скриншот интерфейса
• perform_hotkey_gui - Выполнение горячих клавиш
• export_build_code_gui - Экспорт кода билда
• import_build_code_gui - Импорт билда из кода

Обнаружение UI элементов:

• detect_elements_gui - Динамическое обнаружение UI элементов
• validate_ui_coordinates_gui - Валидация координат UI элементов

🔄 Изменения в версии 0.3.3:

• ❌ Удалены устаревшие инструменты:
  • create_build, load_gems, load_items, create_optimized_build
  • validate_build, search_gems, search_items, load_passive_tree
• ✅ Переход на GUI автоматизацию:
  • Все операции теперь выполняются через GUI PoB
  • Улучшенная надежность и точность данных
  • Поддержка всех современных функций PoB
• 🗑️ Удалены модули:
  • lua_parser.py - больше не нужен для парсинга Lua файлов
  • xml_builder.py - заменен на GUI-создание билдов

📋 Логирование

Проект поддерживает подробное логирование для отладки и мониторинга работы MCP сервера.

Уровни логирования

• DEBUG - Максимально подробная информация (все операции, параметры, кэширование)
• INFO - Основная информация о работе (запуск, инициализация, результаты)
• WARNING - Предупреждения о потенциальных проблемах
• ERROR - Критические ошибки

Настройка уровня логирования

# Установить уровень DEBUG
export LOG_LEVEL=DEBUG

# Установить уровень INFO (по умолчанию)
export LOG_LEVEL=INFO

# Запуск с логированием
LOG_LEVEL=DEBUG pob-mcp

Файлы логов

• Консоль - Логи выводятся в реальном времени
• pob-mcp.log - Подробные логи с метками времени и именами функций

Примеры логов

2025-01-02 18:41:14,207 - src.mcp_server - INFO - 🚀 Starting PoB MCP Server...
2025-01-02 18:41:14,208 - src.mcp_server - INFO - 📂 PoB Path: D:\Programs\Path of Building Community (PoE2)
2025-01-02 18:41:14,209 - src.lua_parser - DEBUG - 📄 Parsing Lua file: Data/Gems.lua
2025-01-02 18:41:14,211 - src.build_validator - ERROR - ❌ PoB executable not found

🚀 Возможности

Основные инструменты MCP:

📊 Анализ и работа с данными PoB:

• ~~create_build - Создание нового билда с нуля~~ (устарел - используйте GUI инструменты)
• ~~load_gems - Загрузка данных о гемах~~ (устарел - используйте GUI инструменты)
• ~~load_items - Загрузка данных о предметах~~ (устарел - используйте GUI инструменты)
• ~~create_optimized_build - Создание оптимизированных билдов по стилю игры~~ (устарел - используйте GUI инструменты)
• ~~validate_build - Валидация билда через PoB~~ (устарел - используйте GUI инструменты)
• ~~search_gems - Поиск гемов по различным критериям~~ (устарел - используйте GUI инструменты)
• ~~search_items - Поиск предметов по типу и свойствам~~ (устарел - используйте GUI инструменты)
• ~~load_passive_tree - Загрузка данных пассивного дерева~~ (устарел - используйте GUI инструменты)
• analyze_pob_structure - Анализ структуры директорий и файлов PoB
• load_pob_directory - Загрузка содержимого директорий PoB

🖥️ GUI Автоматизация PoB:

• launch_pob_gui - Запуск графического интерфейса PoB
• find_pob_windows - Поиск и перечисление окон PoB
• activate_pob_window - Активация конкретного окна PoB
• create_build_gui - Создание билда через GUI PoB
• load_build_gui - Загрузка билда через GUI PoB
• save_build_gui - Сохранение билда через GUI PoB
• calculate_build_gui - Запуск расчета билда в GUI
• get_build_stats_gui - Извлечение статистики билда из GUI

Ключевые особенности:

• ⚡ Высокая производительность с системой кэширования
• 🔧 Гибкая конфигурация через переменные окружения
• 🛡️ Надежная обработка ошибок с детальным логированием
• 📊 Подробная аналитика данных PoB
• 🎯 Интеллектуальный поиск по гемам и предметам
• 🖥️ GUI автоматизация для прямого взаимодействия с PoB

🖥️ GUI Автоматизация

Новая система автоматизации графического интерфейса PoB позволяет:

🎯 Основные возможности:

• 🚀 Автоматический запуск PoB с правильными настройками
• 🔍 Поиск и управление окнами PoB
• 🖱️ Симуляция пользовательского ввода (клики, клавиатура)
• 📊 Извлечение данных из интерфейса PoB
• ⚡ Автоматизированное создание и тестирование билдов

📋 GUI Инструменты:

Управление приложением:

• launch_pob_gui - Запускает PoB и проверяет готовность
• find_pob_windows - Находит все открытые окна PoB
• activate_pob_window - Переключается на нужное окно PoB

Работа с билдами:

• create_build_gui - Создает новый билд через интерфейс
• load_build_gui - Загружает существующий билд
• save_build_gui - Сохраняет текущий билд
• calculate_build_gui - Запускает расчет характеристик

Извлечение данных:

• get_build_stats_gui - Получает статистику билда из GUI
  • Урон (DPS, Physical, Elemental)
  • Защита (Life, Armour, Evasion)
  • Ресурсы (Mana, Spirit)
  • Скорость (Attack/Cast Speed)

⚠️ Текущее состояние:

GUI инструменты находятся в активной разработке. Полная функциональность требует:

• Детекции UI элементов PoB
• OCR для чтения текста с экрана
• Кросс-платформенной поддержки
• Обработки различных разрешений экрана

🔧 Требования для GUI автоматизации:

# Для Windows (рекомендуется)
pip install pywin32 pyautogui

# Для других платформ
pip install pyautogui

🎮 Пример использования:

# Запуск PoB
await launch_pob_gui()

# Поиск окон
windows = await find_pob_windows()

# Создание билда
await create_build_gui("WITCH", 95, "My Fire Witch")

# Получение статистики
stats = await get_build_stats_gui(["damage", "defense"])

📦 Установка через npm

Глобальная установка:

npm install -g pob-mcp

Локальная установка (для разработки):

npm install pob-mcp

🏗️ Архитектура

src/
├── mcp_server.py     # Основной MCP сервер
├── lua_parser.py      # Парсер Lua файлов PoB
├── xml_builder.py     # Строитель XML билдов
├── cache_manager.py   # Менеджер кэширования
├── build_validator.py # Валидатор билдов
└── config.py         # Конфигурация проекта

📋 Требования

• Node.js 16.0.0+
• Python 3.13+
• Path of Building (PoE2) установлен
• MCP клиент (например, Claude Desktop)

⚙️ Настройка

1. Установите Path of Building

Убедитесь, что Path of Building (PoE2) установлен на вашем компьютере.

2. Настройте переменные окружения:

# Путь к PoB (обязательно)
export POB_PATH="D:\Programs\Path of Building Community (PoE2)"

# Опциональные настройки
export POB_CACHE_ENABLED=true
export POB_LOG_LEVEL=INFO
export MCP_LOG_REQUESTS=false

3. Для Windows пользователей:

set POB_PATH=D:\Programs\Path of Building Community (PoE2)
set POB_CACHE_ENABLED=true

🚀 Запуск

Через npm (рекомендуется):

# Глобальная установка
pob-mcp

# Или локальная
npx pob-mcp

Через Python (альтернативный способ):

# Из корня проекта
python -m src.mcp_server

# С указанием пути к PoB
python -m src.mcp_server "D:\Programs\Path of Building Community (PoE2)"

Тестирование:

# Python тесты
python -m pytest tests/

# npm скрипты
npm test
npm run lint
npm run type-check

🔧 Конфигурация MCP клиента

Для Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "pob-mcp": {
      "command": "pob-mcp",
      "env": {
        "POB_PATH": "D:\\Programs\\Path of Building Community (PoE2)"
      }
    }
  }
}

Переменные окружения:

| Переменная | Описание | По умолчанию | |------------|----------|--------------| | POB_PATH | Путь к PoB | D:\Programs\Path of Building Community (PoE2) | | POB_CACHE_ENABLED | Включить кэширование | true | | POB_CACHE_DIR | Директория кэша | cache | | POB_LOG_LEVEL | Уровень логирования | INFO | | POB_VALIDATION_TIMEOUT | Таймаут валидации (сек) | 30 | | POB_SEARCH_LIMIT | Лимит поиска | 50 | | MCP_LOG_REQUESTS | Логировать запросы | false |

Пример файла .env:

POB_PATH=D:\Programs\Path of Building Community (PoE2)
POB_CACHE_ENABLED=true
POB_LOG_LEVEL=DEBUG
MCP_LOG_REQUESTS=true

📚 API Документация

🎯 Обнаружение UI элементов

detect_elements_gui

Динамическое обнаружение UI элементов с помощью различных методов.

Параметры:

• search_text (string, optional): Текст для поиска в UI элементах
• element_type (string, optional): Тип элемента ("button", "edit", "combobox", "label")
• use_ocr (boolean, optional): Использовать OCR для чтения текста (по умолчанию: true)

Пример:

{
  "method": "tools/call",
  "params": {
    "name": "detect_elements_gui",
    "arguments": {
      "search_text": "Calculate",
      "element_type": "button",
      "use_ocr": true
    }
  }
}

validate_ui_coordinates_gui

Валидация и обновление координат UI элементов.

Параметры:

• element_name (string, optional): Имя конкретного элемента для валидации
• auto_update (boolean, optional): Автоматически обновлять координаты (по умолчанию: true)
• validation_timeout (number, optional): Таймаут валидации в секундах (по умолчанию: 30)

Пример:

{
  "method": "tools/call",
  "params": {
    "name": "validate_ui_coordinates_gui",
    "arguments": {
      "element_name": "calculate_button",
      "auto_update": true,
      "validation_timeout": 30
    }
  }
}

🖥️ GUI Управление PoB

launch_pob_gui

Запуск Path of Building с автоматической настройкой.

Параметры:

• pob_path (string, optional): Путь к исполняемому файлу PoB
• wait_for_ready (boolean, optional): Ожидать готовности приложения (по умолчанию: true)
• timeout (number, optional): Таймаут запуска в секундах (по умолчанию: 30)

find_pob_windows

Поиск всех открытых окон Path of Building.

Возвращает: Список найденных окон с их свойствами (handle, title, position, etc.)

create_build_gui

Создание нового билда через GUI PoB.

Параметры:

• class_name (string): Класс персонажа ("Witch", "Warrior", "etc.")
• level (number, optional): Уровень персонажа (по умолчанию: 100)
• ascendancy (string, optional): Ветка аскенданси

📊 Извлечение данных

get_build_stats_gui

Извлечение статистики билда из GUI.

Параметры:

• stat_types (array, optional): Типы запрашиваемой статистики
  • "damage" - Урон (DPS, Physical, Elemental)
  • "defense" - Защита (Life, Armour, Evasion)
  • "resources" - Ресурсы (Mana, Spirit)
  • "speed" - Скорость (Attack/Cast Speed)

Пример:

{
  "method": "tools/call",
  "params": {
    "name": "get_build_stats_gui",
    "arguments": {
      "stat_types": ["damage", "defense", "resources"]
    }
  }
}

📚 Использование MCP инструментов

Создание билда:

{
  "method": "tools/call",
  "params": {
    "name": "create_build",
    "arguments": {
      "class_name": "Witch",
      "level": 100,
      "ascendancy": "Elementalist"
    }
  }
}

Поиск гемов:

{
  "method": "tools/call",
  "params": {
    "name": "search_gems",
    "arguments": {
      "query": "fire",
      "gem_type": "Active Skill",
      "limit": 10
    }
  }
}

Валидация билда:

{
  "method": "tools/call",
  "params": {
    "name": "validate_build",
    "arguments": {
      "build_xml": "<Build>...</Build>",
      "timeout": 30
    }
  }
}

🔍 Структура данных PoB

Анализ проведен для следующих компонентов:

• Система расчетов (7 модулей, 99 типов модификаторов урона)
• Система модификаторов (BASE, INC, MORE, FLAG, OVERRIDE)
• Пассивное дерево (4 версии, 20+ секций)
• Описания статов (2393 описания)
• Система навыков (9 файлов по актам)

🎮 Примеры использования

📋 Полный цикл работы с билдом

1. Запуск и настройка PoB:

{
  "method": "tools/call",
  "params": {
    "name": "launch_pob_gui",
    "arguments": {
      "wait_for_ready": true,
      "timeout": 30
    }
  }
}

2. Обнаружение UI элементов:

{
  "method": "tools/call",
  "params": {
    "name": "detect_elements_gui",
    "arguments": {
      "search_text": "New Build",
      "element_type": "button",
      "use_ocr": true
    }
  }
}

3. Создание нового билда:

{
  "method": "tools/call",
  "params": {
    "name": "create_build_gui",
    "arguments": {
      "class_name": "Witch",
      "level": 95,
      "ascendancy": "Elementalist"
    }
  }
}

4. Добавление навыков:

{
  "method": "tools/call",
  "params": {
    "name": "add_skill_gem_gui",
    "arguments": {
      "gem_name": "Fireball",
      "socket_index": 1,
      "level": 20,
      "quality": 20
    }
  }
}

5. Расчет и получение статистики:

{
  "method": "tools/call",
  "params": {
    "name": "calculate_build_gui",
    "arguments": {}
  }
}

{
  "method": "tools/call",
  "params": {
    "name": "get_build_stats_gui",
    "arguments": {
      "stat_types": ["damage", "defense", "resources"]
    }
  }
}

6. Сохранение билда:

{
  "method": "tools/call",
  "params": {
    "name": "save_build_gui",
    "arguments": {
      "file_path": "my_fire_witch.xml"
    }
  }
}

🔧 Расширенные сценарии

Валидация координат UI:

{
  "method": "tools/call",
  "params": {
    "name": "validate_ui_coordinates_gui",
    "arguments": {
      "auto_update": true,
      "validation_timeout": 60
    }
  }
}

Скриншот для анализа:

{
  "method": "tools/call",
  "params": {
    "name": "take_screenshot_gui",
    "arguments": {
      "area": "stats",
      "save_path": "build_stats.png"
    }
  }
}

Генерация отчета:

{
  "method": "tools/call",
  "params": {
    "name": "generate_build_report_gui",
    "arguments": {
      "output_format": "text",
      "include_skills": true,
      "include_items": true
    }
  }
}

💡 Практические сценарии использования

Сценарий 1: Быстрое создание билда

1. Запустить PoB
2. Создать новый билд (Witch, 95, Elementalist)
3. Добавить ключевые гемы (Fireball, Arcane Surge, etc.)
4. Рассчитать статистику
5. Сохранить билд

Сценарий 2: Анализ существующего билда

1. Загрузить билд из файла
2. Извлечь текущую статистику
3. Сделать скриншот для визуального анализа
4. Сгенерировать отчет

Сценарий 3: Оптимизация билда

1. Обновить уровень персонажа
2. Изменить ветку аскенданси
3. Добавить новые гемы
4. Пересчитать и сравнить статистику

🧪 Тестирование

# Запуск всех тестов
python -m pytest tests/

# Тестирование с подробным выводом
python -m pytest tests/ -v

# Тестирование производительности
python -m pytest tests/ -k "performance"

# Через npm
npm test
npm run lint
npm run type-check

📈 Производительность

Кэширование:

• Автоматическое кэширование парсированных данных
• Проверка актуальности файлов по хэшу
• Настраиваемый TTL кэша (по умолчанию 24 часа)

Оптимизации:

• Ленивая загрузка данных
• Пул соединений для валидации
• Асинхронная обработка запросов

🐛 Обработка ошибок

Сервер предоставляет детальную обработку следующих типов ошибок:

• FileNotFoundError (-32001): Файл не найден
• PermissionError (-32002): Отсутствуют права доступа
• ValueError (-32003): Некорректные значения
• InternalError (-32000): Внутренние ошибки сервера
• ParseError (-32700): Ошибки парсинга JSON

📝 Логирование

Уровни логирования:

• DEBUG: Детальная информация для разработки
• INFO: Основная информация о работе
• WARNING: Предупреждения
• ERROR: Ошибки

Включение логирования запросов:

export MCP_LOG_REQUESTS=true

📦 Публикация npm пакета

Подготовка к публикации:

# Установка зависимостей
npm install

# Тестирование
npm run prepublishOnly

# Публикация (требуется аккаунт npm)
npm publish

Для бета-версий:

npm publish --tag beta

🤝 Вклад в проект

1. Fork репозиторий
2. Создайте feature branch (git checkout -b feature/amazing-feature)
3. Commit изменений (git commit -m 'Add amazing feature')
4. Push в branch (git push origin feature/amazing-feature)
5. Откройте Pull Request

📄 Лицензия

Этот проект распространяется под лицензией MIT. См. файл LICENSE для подробностей.

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

• Сообществу Path of Building за отличный инструмент
• Разработчикам Grinding Gear Games за Path of Exile
• Сообществу MCP за протокол интеграции

Примечание: Этот MCP сервер разработан для интеграции с Path of Building Community (PoE2). Для работы требуется установленный Path of Building.