PoB MCP Server

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

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

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

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

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

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

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

📦 Установка через 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)"
      }
    }
  }
}

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

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

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

📚 Использование 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 файлов по актам)

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

# Запуск всех тестов
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.