API и MCP для Discord
Читайте и меняйте панель, шаблоны, языки и профиль бота сервера через REST API, SDK и инструменты MCP с проверкой ревизий, чтобы ничего не перезаписалось случайно.
Всё, что делает страница сервера Discord, можно сделать и из кода: получить список серверов, прочитать действующую конфигурацию сервера, сохранить только изменённые части, поделиться шаблоном, опубликовать панель и применить профиль бота. Правила те же, что в панели управления: только серверы и картинки вашего рабочего пространства, ограничения тарифа Free на имя, картинку и подвал бота и проверка ревизии при каждом изменении.
Что нужно
| Чтение | Любой ключ Developer API. |
| Изменение | Ключ с правом integrations:write (Full access его включает). Без него: 403 INSUFFICIENT_SCOPE. |
| Шаблоны | Ключ на всё рабочее пространство. Ключ, ограниченный несколькими проектами, видит только серверы этих проектов и на шаблонах отвечает 403 DISCORD_WORKSPACE_ACCESS_REQUIRED. |
| Размер тела | До 128 КиБ. |
Маршруты
Все маршруты находятся под https://api.luaward.com/v3 и отвечают { "success": true, "data": … }.
| Метод и путь | Что делает |
|---|---|
GET /discord/schema | Текущая схема конфигурации. Прочитайте её, прежде чем собирать тело запроса. |
GET /discord/guilds | Подключённые серверы с проектом, шаблоном и ревизией. |
GET /discord/guilds/{guildId}/config | Действующая конфигурация, собственные изменения сервера, шаблон, которому он следует, что разрешает тариф и устарело ли опубликованное сообщение. |
PATCH /discord/guilds/{guildId}/config | Сохранить собственные изменения. Тело: expectedRevision, expectedPresetRevision, overrides. |
POST /discord/guilds/{guildId}/config/reset | Отбросить собственные изменения, чтобы сервер снова следовал шаблону. Тело: обе ревизии и paths. |
PUT /discord/guilds/{guildId}/preset | Привязать шаблон или null, чтобы отвязать. Тело: presetId, expectedRevision, preserveOverrides. |
GET /discord/presets, GET /discord/presets/{id} | Список шаблонов или один шаблон с его spec. |
POST /discord/presets | Создать шаблон: name и spec. |
PATCH /discord/presets/{id} | Заменить шаблон: name, spec, expectedRevision. Серверы, которые ему следуют, меняются вместе с ним. |
DELETE /discord/presets/{id} | Удалить шаблон: expectedRevision. Серверы, которые его использовали, сохраняют текущий вид. |
POST /discord | Одна точка входа для всех операций с полем op (её используют SDK), включая panel.publish и profile.apply. |
Собственное изменение это плоский путь, например title, color, buttons, locales, redeemModal, show.guide или bot.nick. Списки и разделы языков и формы заменяются целиком; путь, который вы не передали, продолжает следовать шаблону, а null или пустой список очищает его.
Правила
Правила сервера это ещё три override, каждый заменяется целиком: rules.script, rules.redeem и rules.reset.
{
"overrides": {
"rules.script": { "mode": "both", "scripts": "all", "universes": ["<loader universe id>"] },
"rules.redeem": { "maxKeys": 2 },
"rules.reset": { "allowed": null, "cooldownDays": 7, "maxPerKey": 5, "maxPer30Days": 2, "confirm": true, "warning": null }
}
}rules.script:modeравенscripts,universeилиboth;scriptsэто"all"или список id скриптов проекта сервера;universesэто список до 10 id Loader Universe рабочего пространства (для режимаuniverseнужен хотя бы один).rules.redeem:maxKeysот 1 до 10 илиnullбез ограничения. Ключи с истёкшим сроком и заблокированные не считаются.rules.reset:allowedиcooldownDaysравныnull, чтобы следовать проекту;maxPerKeyиmaxPer30Daysравныnullбез ограничения;confirmсначала спрашивает игрока, сwarning(до 300 символов) или встроенным предупреждением.
Изменение только правил не делает опубликованную панель устаревшей.
Ревизии
У каждого сервера есть ревизия конфигурации, и у каждого шаблона есть своя. Изменение должно передавать ревизию, на которой оно основано. Если кто-то изменил раньше, вызов отвечает 409 DISCORD_CONFIG_CONFLICT и ничего не меняет; прочитайте конфигурацию заново и повторите. Именно это не даёт двум людям, или скрипту и панели управления, перезаписать друг друга.
Публикация
panel.publish публикует новое сообщение (mode: "post" с channelId) или правит уже опубликованное (mode: "update"). Передавайте стабильный requestId и используйте его снова при повторе того же намерения: уже выполненный запрос не выполняется дважды. Перевод опубликованного embed в Components V2 требует confirmConvertToV2: true, а опубликованное сообщение V2 нельзя вернуть в embed (опубликуйте новое сообщение). profile.apply отправляет в Discord имя, картинку, баннер и текст о боте для одного сервера.
Ошибки, которые вы можете увидеть
| Код | Значение |
|---|---|
| 409 DISCORD_CONFIG_CONFLICT | Переданная ревизия устарела. |
| 403 DISCORD_BRANDING_PAID | Изменение задаёт имя или картинку бота либо подвал на тарифе Free. |
| 404 GUILD_NOT_FOUND, PRESET_NOT_FOUND, IMAGE_NOT_FOUND | Сервера, шаблона или картинки нет в вашем рабочем пространстве. |
| 403 DISCORD_PRESET_LIMIT | Рабочее пространство хранит не более 100 шаблонов. |
| 409 DISCORD_OPERATION_BUSY | Другое изменение этого сервера ещё выполняется. Повторите через минуту. |
| 409 DISCORD_PUBLICATION_UNCERTAIN | Discord не подтвердил публикацию. Проверьте канал, прежде чем повторять новым запросом. |
| 404 DISCORD_RULES_UNIVERSE_NOT_FOUND, DISCORD_RULES_SCRIPT_NOT_FOUND | Loader Universe нет в вашем рабочем пространстве или скрипта нет в проекте сервера. |
| 400 DISCORD_RULES_UNIVERSE_REQUIRED | Для режима universe нужен хотя бы один Loader Universe. |
SDK
SDK для JavaScript и Python оборачивают POST /discord. Записи они сами не повторяют.
import { LuawardClient } from "@luaward/sdk";
const luaward = new LuawardClient({ apiKey: process.env.LUAWARD_API_KEY });
const { data: guilds } = await luaward.discord.listGuilds();
const { data: config } = await luaward.discord.getConfiguration(guilds[0].guildId);
await luaward.discord.saveConfiguration({
guildId: config.guildId,
expectedRevision: config.revision,
expectedPresetRevision: config.preset?.revision ?? null,
overrides: { title: "My Hub keys", color: 0x23a559 },
});Доступные функции: listGuilds, getConfiguration, saveConfiguration, resetOverrides, attachPreset, listPresets, getPreset, createPreset, updatePreset, deletePreset, publish, applyProfile и schema. Установка и учётные данные описаны в разделе SDK и CLI.
Инструменты MCP
ИИ-ассистент, подключённый к Luaward, получает два инструмента. discord_read показывает список серверов и шаблонов, читает конфигурацию сервера и возвращает схему (guilds.list, config.get, presets.list, presets.get, schema.get). discord_write сохраняет и сбрасывает собственные изменения, управляет шаблонами, привязывает шаблон, публикует панель и применяет профиль бота с теми же проверками, что и панель управления. Попросите ассистента сначала прочитать конфигурацию, а затем менять её с полученными ревизиями. Для обоих нужно право manage у личного токена, подключённая игра не требуется.