LuawardDocs

API y MCP de Discord

Lee y cambia el panel, las plantillas, los idiomas y el perfil del bot de un servidor desde la API REST, los SDK y las herramientas MCP, con comprobación de revisiones para que nada se sobrescriba por accidente.

Todo lo que hace la página del servidor de Discord también se puede hacer desde código: listar tus servidores, leer la configuración efectiva de un servidor, guardar solo las partes que cambiaste, compartir una plantilla, publicar el panel y aplicar el perfil del bot. Las reglas son las del panel de control: solo los servidores y las imágenes de tu propio espacio de trabajo, los límites del plan Free sobre el nombre, la imagen y el pie del bot, y una comprobación de revisión en cada cambio.

Qué necesitas

LeerCualquier clave de la API para desarrolladores.
CambiarUna clave con el permiso integrations:write (Full access lo incluye). Sin él: 403 INSUFFICIENT_SCOPE.
PlantillasUna clave de todo el espacio de trabajo. Una clave limitada a algunos proyectos solo llega a los servidores de esos proyectos y responde 403 DISCORD_WORKSPACE_ACCESS_REQUIRED con las plantillas.
Tamaño del cuerpoHasta 128 KiB.

Rutas

Todas las rutas cuelgan de https://api.luaward.com/v3 y responden { "success": true, "data": … }.

Método y rutaQué hace
GET /discord/schemaEl esquema de configuración actual. Léelo antes de construir un cuerpo.
GET /discord/guildsLos servidores vinculados, con proyecto, plantilla y revisión.
GET /discord/guilds/{guildId}/configLa configuración efectiva, los cambios propios del servidor, la plantilla que sigue, lo que permite el plan y si el mensaje publicado está desactualizado.
PATCH /discord/guilds/{guildId}/configGuarda cambios propios. Cuerpo: expectedRevision, expectedPresetRevision, overrides.
POST /discord/guilds/{guildId}/config/resetDescarta cambios propios para que el servidor vuelva a seguir su plantilla. Cuerpo: las dos revisiones y paths.
PUT /discord/guilds/{guildId}/presetAsocia una plantilla, o null para quitarla. Cuerpo: presetId, expectedRevision, preserveOverrides.
GET /discord/presets, GET /discord/presets/{id}Lista las plantillas, o lee una con su spec.
POST /discord/presetsCrea una plantilla: name y spec.
PATCH /discord/presets/{id}Reemplaza una plantilla: name, spec, expectedRevision. Los servidores que la siguen cambian con ella.
DELETE /discord/presets/{id}Elimina una plantilla: expectedRevision. Los servidores que la usaban conservan su aspecto actual.
POST /discordUn único endpoint para todas las operaciones, con un campo op (lo usan los SDK), incluidas panel.publish y profile.apply.

Un cambio propio es una ruta plana como title, color, buttons, locales, redeemModal, show.guide o bot.nick. Las listas y las secciones de idiomas y de formulario se reemplazan enteras; una ruta que omites sigue a la plantilla, y null o una lista vacía la borra.

Reglas

Las reglas de un servidor son tres overrides más, cada uno reemplazado como un todo: rules.script, rules.redeem y 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 es scripts, universe o both; scripts es "all" o una lista de ids de scripts del proyecto del servidor; universes es una lista de hasta 10 ids de Loader Universe del espacio de trabajo (el modo universe necesita al menos uno).
  • rules.redeem: maxKeys va de 1 a 10, o null para no tener límite. Las claves vencidas o bloqueadas no cuentan.
  • rules.reset: allowed y cooldownDays son null para seguir al proyecto; maxPerKey y maxPer30Days son null para no tener límite; confirm pregunta antes al jugador, con warning (hasta 300 caracteres) o la advertencia integrada.

Cambiar solo las reglas no deja desactualizado el panel publicado.

Revisiones

Cada servidor tiene una revisión de configuración, y cada plantilla tiene la suya. Un cambio debe enviar la revisión en la que se basa. Si otra persona cambió antes, la llamada responde 409 DISCORD_CONFIG_CONFLICT y no cambia nada; vuelve a leer la configuración y reintenta. Así se evita que dos personas, o un script y el panel de control, se sobrescriban.

Publicación

panel.publish publica un mensaje nuevo (mode: "post" con un channelId) o edita el ya publicado (mode: "update"). Envía un requestId estable y reutilízalo al reintentar la misma intención: una solicitud que ya se llevó a cabo no se ejecuta dos veces. Convertir un embed publicado a Components V2 requiere confirmConvertToV2: true, y un mensaje V2 publicado no puede volver a ser un embed (publica un mensaje nuevo). profile.apply envía a Discord el nombre, la imagen, el banner y el texto "acerca de" del bot de un servidor.

Errores que puedes ver

CódigoSignificado
409 DISCORD_CONFIG_CONFLICTLa revisión que enviaste está desactualizada.
403 DISCORD_BRANDING_PAIDEl cambio fija el nombre o la imagen del bot o el pie en el plan Free.
404 GUILD_NOT_FOUND, PRESET_NOT_FOUND, IMAGE_NOT_FOUNDEl servidor, la plantilla o la imagen no están en tu espacio de trabajo.
403 DISCORD_PRESET_LIMITUn espacio de trabajo guarda como máximo 100 plantillas.
409 DISCORD_OPERATION_BUSYOtro cambio en este servidor sigue en curso. Inténtalo en un momento.
409 DISCORD_PUBLICATION_UNCERTAINDiscord no confirmó la publicación. Revisa el canal antes de reintentar con una solicitud nueva.
404 DISCORD_RULES_UNIVERSE_NOT_FOUND, DISCORD_RULES_SCRIPT_NOT_FOUNDUn Loader Universe no está en tu espacio de trabajo, o un script no está en el proyecto del servidor.
400 DISCORD_RULES_UNIVERSE_REQUIREDEl modo universe necesita al menos un Loader Universe.

SDK

Los SDK de JavaScript y Python envuelven POST /discord. No reintentan las escrituras por su cuenta.

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 },
});

Las funciones son listGuilds, getConfiguration, saveConfiguration, resetOverrides, attachPreset, listPresets, getPreset, createPreset, updatePreset, deletePreset, publish, applyProfile y schema. Consulta SDK y CLI para la instalación y las credenciales.

Herramientas MCP

Un asistente de IA conectado a Luaward recibe dos herramientas. discord_read lista servidores y plantillas, lee la configuración de un servidor y devuelve el esquema (guilds.list, config.get, presets.list, presets.get, schema.get). discord_write guarda y restablece cambios propios, gestiona plantillas, asocia una plantilla, publica el panel y aplica el perfil del bot, con las mismas comprobaciones que el panel de control. Pide al asistente que lea primero la configuración y que la cambie después con las revisiones recibidas. Ambas necesitan el permiso manage en el token personal, y no hace falta un juego conectado.