wowaudit-mcp-server

Servidor MCP para la API de WoWAudit documentada. Expone el roster de la hermandad, la planificación de incursiones, la asistencia, la actividad semanal, las listas de deseos, el historial de botín y las solicitudes como herramientas estructuradas para Raid Lens y otros clientes MCP.

El servidor usa stdio y @modelcontextprotocol/server 2.x. Sirve el protocolo MCP actual y conserva el handshake de inicialización heredado de la era 2025 del SDK para clientes antiguos. Cada resultado incluye structuredContent nativo más el mismo JSON como bloque de texto para clientes que no consumen resultados estructurados.

Requisitos

• Node.js 20 o más reciente.

• Una clave de API de equipo de WoWAudit. Un administrador del equipo puede copiarla desde el campo Configuración > Equipo > Clave de API del equipo, o abrir https://wowaudit.com/api y seleccionar el equipo. WoWAudit actualmente no expone una clave de API pública de solo lectura con ámbito; este servidor impone acceso de solo lectura localmente por defecto.

Related MCP server: wow-mcp

Configuración

npm install

Crea .env a partir de .env.example, luego establece:

WOWAUDIT_API_KEY=your-team-api-key

Compila el servidor:

npm run build

La clave de API se carga de forma diferida, por lo que el proceso MCP puede iniciarse y listar herramientas sin una clave configurada. Las llamadas a la API devuelven un error de configuración estructurado hasta que la clave esté disponible.

Configuración del cliente MCP

Usa el punto de entrada compilado desde un cliente MCP:

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

El servidor resuelve .env en relación con su ubicación de instalación, no con el directorio de trabajo del cliente MCP. Las credenciales también se pueden proporcionar a través de la configuración env del cliente.

Modelo de seguridad

Una clave de API de equipo de WoWAudit puede acceder a todo el entorno del equipo. El servidor aplica estas salvaguardas:

• La clave se envía solo como un encabezado Authorization: Bearer. Nunca se coloca en una URL, resultado o error.

• Solo las rutas documentadas /v1/ están disponibles. No hay una herramienta HTTP arbitraria.

• Las herramientas de escritura no se anuncian ni se pueden invocar a menos que WOWAUDIT_ENABLE_WRITES=true. El cliente HTTP bloquea de forma independiente las solicitudes de mutación mientras está deshabilitado.

• Las herramientas de eliminación destructiva requieren adicionalmente confirm: true en cada llamada.

• Las herramientas de solicitudes están deshabilitadas a menos que WOWAUDIT_ENABLE_APPLICATIONS=true porque las solicitudes pueden contener identidades, respuestas de cuestionarios y URL de archivos cargados.

• Las anotaciones de herramientas identifican operaciones de solo lectura, idempotentes y destructivas para clientes MCP modernos.

• Las respuestas están limitadas a 2 MiB por defecto. Ajusta WOWAUDIT_MAX_RESPONSE_BYTES solo cuando sea necesario.

• Las respuestas GET se almacenan en caché en el proceso durante 30 segundos. Las escrituras exitosas limpian la caché.

Habilitar las herramientas de solicitudes no proporciona autorización de canal. Una integración de Discord debe imponer el acceso solo para oficiales antes de exponer esas herramientas. Del mismo modo, un bot de múltiples hermandades debe vincular su ID de gremio de Discord de confianza a la credencial correcta de WoWAudit fuera de los argumentos de la herramienta controlados por el modelo.

Configuración

La configuración predeterminada expone 11 herramientas GET no sensibles. Establecer WOWAUDIT_ENABLE_APPLICATIONS=true agrega las dos herramientas de solicitudes de solo lectura. Establecer WOWAUDIT_ENABLE_WRITES=true agrega herramientas de mutación; déjalo sin establecer para una superficie MCP estrictamente de solo lectura.

Herramientas

Las herramientas de mutación que se muestran a continuación solo se registran cuando WOWAUDIT_ENABLE_WRITES=true. Las herramientas de solicitudes solo se registran cuando WOWAUDIT_ENABLE_APPLICATIONS=true.

Equipo y roster

Actividad y asistencia

Incursiones y apuntarse

wowaudit_update_raid admite cambios de estado y horario, listas de habilitación/deshabilitación de encuentros, estados de apuntarse, comentarios, anulaciones de rol/clase, estado seleccionado y selecciones específicas de encuentro.

Listas de deseos y botín

Los puntos finales de lista de deseos de todos los personajes y de historial de botín pueden ser grandes. Prefiere llamadas específicas de personaje y usa limit en herramientas de colección cuando sea posible.

Solicitudes

Las solicitudes están bloqueadas por separado mediante WOWAUDIT_ENABLE_APPLICATIONS=true. Mutarlas también requiere WOWAUDIT_ENABLE_WRITES=true.

Envoltura de resultados

Las herramientas exitosas devuelven:

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

Las herramientas de colección que aceptan limit también reportan totalItems, returnedItems y truncated. El límite se aplica después de que WoWAudit responda porque la API pública no documenta la paginación del lado del servidor.

Los errores devuelven isError: true, { "error": "..." } estructurado y un texto de respaldo. Los errores ascendentes también incluyen kind, el estado HTTP status y retryAfterSeconds cuando están disponibles.

Desarrollo

npm run dev
npm test

Las pruebas compilan el servidor, verifican la negociación de protocolo tanto moderna como heredada, inspeccionan todos los esquemas y anotaciones de herramientas, ejercitan las barreras de seguridad y prueban el cliente HTTP sin usar una clave de API real.

Para una pequeña comprobación de solo lectura en vivo:

npm run test:live

La prueba de humo en vivo llama a los puntos finales de equipo, período, roster y lista de incursiones. Nunca invoca herramientas de solicitudes o escritura.

Advertencias de la API de WoWAudit

• La documentación pública no define ningún contrato de paginación o límite de velocidad.

• La documentación proporciona principalmente ejemplos de respuesta en lugar de esquemas reutilizables estrictos, por lo que los campos de la carga útil pueden evolucionar.

• La documentación incorporada contiene una URL de servidor de aspecto de desarrollo. Este proyecto utiliza el origen de producción confirmado https://api.wowaudit.com por defecto.

• WoWAudit acepta una clave de API en un parámetro de consulta, pero este servidor usa deliberadamente solo el encabezado de autorización para reducir la fuga de credenciales.

Licencia

MIT, copyright de los contribuyentes de WoWAudit MCP Server.