wowaudit-mcp-server

MCP-сервер для документированного WoWAudit API. Он предоставляет состав гильдии, планирование рейдов, посещаемость, еженедельную активность, списки желаемого, историю лута и заявки в виде структурированных инструментов для Raid Lens и других MCP-клиентов.

Сервер использует stdio и @modelcontextprotocol/server 2.x. Он поддерживает текущий протокол MCP и сохраняет устаревшее рукопожатие инициализации эпохи 2025 года из SDK для старых клиентов. Каждый результат включает нативный structuredContent, а также тот же JSON в виде текстового блока для клиентов, которые не потребляют структурированные результаты.

Requirements

• Node.js 20 или новее.

• Ключ API команды WoWAudit. Администратор команды может скопировать его из поля Settings > Team > API key или открыть https://wowaudit.com/api и выбрать команду. WoWAudit в настоящее время не предоставляет ограниченный ключ Public API только для чтения; этот сервер по умолчанию применяет доступ только для чтения локально.

Related MCP server: wow-mcp

Setup

npm install

Создайте .env из .env.example, затем установите:

WOWAUDIT_API_KEY=your-team-api-key

Соберите сервер:

npm run build

Ключ API загружается лениво, поэтому процесс MCP может запуститься и перечислить инструменты без настроенного ключа. Вызовы API возвращают структурированную ошибку конфигурации, пока ключ не станет доступен.

MCP client configuration

Используйте скомпилированную точку входа из MCP-клиента:

{
  "mcpServers": {
    "wowaudit": {
      "command": "node",
      "args": [
        "C:\\programming\\typescript\\wowaudit-mcp-server\\dist\\index.js"
      ]
    }
  }
}

Сервер разрешает .env относительно своего установленного местоположения, а не рабочей директории MCP-клиента. Учётные данные могут быть предоставлены через конфигурацию env клиента.

Security model

Ключ API команды WoWAudit может получить доступ ко всей среде команды. Сервер применяет следующие меры защиты:

• Ключ отправляется только в заголовке Authorization: Bearer. Он никогда не помещается в URL, результат или ошибку.

• Доступны только документированные маршруты /v1/. Нет произвольного HTTP-инструмента.

• Инструменты записи не рекламируются и не вызываются, если WOWAUDIT_ENABLE_WRITES=true не установлен. HTTP-клиент независимо блокирует запросы на изменение, пока они отключены.

• Разрушительные инструменты удаления дополнительно требуют confirm: true при каждом вызове.

• Инструменты заявок отключены, если WOWAUDIT_ENABLE_APPLICATIONS=true не установлен, поскольку заявки могут содержать удостоверения личности, ответы на опросники и URL-адреса загруженных файлов.

• Аннотации инструментов идентифицируют операции только для чтения, идемпотентные и разрушительные для современных MCP-клиентов.

• Ответы по умолчанию ограничены 2 МиБ. Регулируйте WOWAUDIT_MAX_RESPONSE_BYTES только при необходимости.

• Ответы GET кэшируются в процессе на 30 секунд. Успешные записи очищают кэш.

Включение инструментов заявок не обеспечивает авторизацию канала. Интеграция Discord должна обеспечивать доступ только для офицеров перед открытием этих инструментов. Аналогично, мульти-гильдийный бот должен привязать свой доверенный ID гильдии Discord к правильным учётным данным WoWAudit вне управляемых моделью аргументов инструментов.

Configuration

Конфигурация по умолчанию предоставляет 11 нечувствительных GET-инструментов. Установка WOWAUDIT_ENABLE_APPLICATIONS=true добавляет два инструмента заявок только для чтения. Установка WOWAUDIT_ENABLE_WRITES=true добавляет инструменты мутации; оставьте её неустановленной для строго read-only поверхности MCP.

Tools

Инструменты мутации, показанные ниже, регистрируются только при WOWAUDIT_ENABLE_WRITES=true. Инструменты заявок регистрируются только при WOWAUDIT_ENABLE_APPLICATIONS=true.

Команда и состав

Активность и посещаемость

Рейды и запись

wowaudit_update_raid поддерживает изменение статуса и расписания, списки включения/отключения встреч, статусы записи, комментарии, переопределения ролей/классов, выбранный статус и выборки для конкретных встреч.

Списки желаемого и лут

Конечные точки списков желаемого для всех персонажей и лута могут быть большими. Предпочитайте вызовы для конкретных персонажей и используйте limit в инструментах коллекций, где это возможно.

Заявки

Заявки отдельно контролируются WOWAUDIT_ENABLE_APPLICATIONS=true. Их изменение также требует WOWAUDIT_ENABLE_WRITES=true.

Result envelope

Успешные инструменты возвращают:

{
  "data": {},
  "meta": {
    "endpoint": "/v1/team",
    "method": "GET"
  }
}

Инструменты коллекций, принимающие limit, дополнительно сообщают totalItems, returnedItems и truncated. Лимит применяется после ответа WoWAudit, поскольку публичный API не документирует пагинацию на стороне сервера.

Ошибки возвращают isError: true, структурированное { "error": "..." } и текстовый запасной вариант. Ошибки вышестоящего сервера также включают kind, HTTP-status и retryAfterSeconds, если доступны.

Development

npm run dev
npm test

Тесты компилируют сервер, проверяют как современное, так и устаревшее согласование протокола, проверяют все схемы и аннотации инструментов, испытывают защитные механизмы и тестируют HTTP-клиент без использования реального ключа API.

Для небольшой живой проверки только для чтения:

npm run test:live

Живой дымовой тест вызывает конечные точки команды, периода, состава и списка рейдов. Он никогда не вызывает инструменты заявок или записи.

WoWAudit API caveats

• Публичная документация не определяет ни пагинацию, ни ограничение скорости.

• Документация в основном предоставляет примеры ответов, а не строгие повторно используемые схемы, поэтому поля полезной нагрузки могут изменяться.

• Встроенная документация содержит URL сервера, похожий на разработочный. Этот проект по умолчанию использует подтверждённый рабочий источник https://api.wowaudit.com.

• WoWAudit принимает ключ API в параметре запроса, но этот сервер намеренно использует только заголовок авторизации для уменьшения утечки учётных данных.

License

MIT, авторские права принадлежат участникам WoWAudit MCP Server.