wowaudit-mcp-server

MCP-Server für die dokumentierte WoWAudit API. Er stellt Gilden-Roster, Raid-Planung, Anwesenheit, wöchentliche Aktivität, Wunschlisten, Beuteverlauf und Bewerbungen als strukturierte Tools für Raid Lens und andere MCP-Clients bereit.

Der Server verwendet stdio und @modelcontextprotocol/server 2.x. Er bedient das aktuelle MCP-Protokoll und behält den Legacy-Initialize-Handshake des SDKs aus der 2025-Ära für ältere Clients bei. Jedes Ergebnis enthält natives structuredContent sowie dasselbe JSON als Textblock für Clients, die keine strukturierten Ergebnisse verarbeiten.

Anforderungen

• Node.js 20 oder neuer.

• Ein WoWAudit-Team-API-Schlüssel. Ein Team-Administrator kann ihn aus dem Feld Einstellungen > Team > API-Schlüssel des Teams kopieren oder https://wowaudit.com/api öffnen und das Team auswählen. WoWAudit bietet derzeit keinen eingeschränkten schreibgeschützten Public-API-Schlüssel; dieser Server erzwingt standardmäßig lokal schreibgeschützten Zugriff.

Related MCP server: wow-mcp

Einrichtung

npm install

Erstelle .env aus .env.example und setze dann:

WOWAUDIT_API_KEY=your-team-api-key

Baue den Server:

npm run build

Der API-Schlüssel wird verzögert geladen, sodass der MCP-Prozess starten und Tools auflisten kann, ohne dass ein konfigurierter Schlüssel vorhanden ist. API-Aufrufe geben einen strukturierten Konfigurationsfehler zurück, bis der Schlüssel verfügbar ist.

MCP-Client-Konfiguration

Verwende den kompilierten Einstiegspunkt von einem MCP-Client:

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

Der Server löst .env relativ zu seinem Installationsort auf, nicht zum Arbeitsverzeichnis des MCP-Clients. Anmeldeinformationen können stattdessen über die env-Konfiguration des Clients bereitgestellt werden.

Sicherheitsmodell

Ein WoWAudit-Team-API-Schlüssel kann auf die gesamte Umgebung des Teams zugreifen. Der Server wendet folgende Sicherheitsvorkehrungen an:

• Der Schlüssel wird nur als Authorization: Bearer-Header gesendet. Er wird niemals in eine URL, ein Ergebnis oder einen Fehler eingefügt.

• Nur dokumentierte /v1/-Routen sind verfügbar. Es gibt kein beliebiges HTTP-Tool.

• Schreib-Tools werden nicht beworben oder aufrufbar, es sei denn, WOWAUDIT_ENABLE_WRITES=true. Der HTTP-Client blockiert unabhängig Mutationsanfragen, solange sie deaktiviert sind.

• Zerstörerische Lösch-Tools erfordern zusätzlich confirm: true bei jedem Aufruf.

• Bewerbungs-Tools sind deaktiviert, es sei denn, WOWAUDIT_ENABLE_APPLICATIONS=true, da Bewerbungen Identitäten, Fragebogenantworten und URLs hochgeladener Dateien enthalten können.

• Tool-Annotationen kennzeichnen schreibgeschützte, idempotente und zerstörerische Operationen für moderne MCP-Clients.

• Antworten sind standardmäßig auf 2 MiB begrenzt. Passe WOWAUDIT_MAX_RESPONSE_BYTES nur bei Bedarf an.

• GET-Antworten werden prozessintern 30 Sekunden lang zwischengespeichert. Erfolgreiche Schreibvorgänge leeren den Cache.

Das Aktivieren von Bewerbungs-Tools bietet keine Kanalautorisierung. Eine Discord-Integration muss den Zugriff nur für Offiziere erzwingen, bevor diese Tools bereitgestellt werden. Ebenso muss ein Multi-Gilden-Bot seine vertrauenswürdige Discord-Gilden-ID außerhalb der modellgesteuerten Tool-Argumente an die richtigen WoWAudit-Anmeldeinformationen binden.

Konfiguration

Die Standardkonfiguration stellt 11 nicht sensible GET-Tools bereit. Das Setzen von WOWAUDIT_ENABLE_APPLICATIONS=true fügt die beiden schreibgeschützten Bewerbungs-Tools hinzu. Das Setzen von WOWAUDIT_ENABLE_WRITES=true fügt Mutations-Tools hinzu; lasse es für eine streng schreibgeschützte MCP-Oberfläche ungesetzt.

Tools

Die unten gezeigten Mutations-Tools werden nur registriert, wenn WOWAUDIT_ENABLE_WRITES=true. Bewerbungs-Tools werden nur registriert, wenn WOWAUDIT_ENABLE_APPLICATIONS=true.

Team und Roster

Aktivität und Anwesenheit

Raids und Anmeldungen

wowaudit_update_raid unterstützt Status- und Zeitplanänderungen, Listen zum Aktivieren/Deaktivieren von Begegnungen, Anmeldestatus, Kommentare, Rollen-/Klassenüberschreibungen, ausgewählten Status und begegnungsspezifische Auswahlen.

Wunschlisten und Beute

Die Wunschlisten- und Beute-Endpunkte für alle Charaktere können groß sein. Bevorzuge charakterspezifische Aufrufe und verwende limit bei Sammlungs-Tools, wo möglich.

Bewerbungen

Bewerbungen werden separat durch WOWAUDIT_ENABLE_APPLICATIONS=true gesteuert. Ihre Mutation erfordert ebenfalls WOWAUDIT_ENABLE_WRITES=true.

Ergebnis-Umschlag

Erfolgreiche Tools geben zurück:

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

Sammlungs-Tools, die limit akzeptieren, melden zusätzlich totalItems, returnedItems und truncated. Der Grenzwert wird angewendet, nachdem WoWAudit geantwortet hat, da die öffentliche API keine serverseitige Paginierung dokumentiert.

Fehler geben isError: true, strukturiertes { "error": "..." } und einen Text-Fallback zurück. Upstream-Fehler enthalten ebenfalls kind, HTTP-status und retryAfterSeconds, wenn verfügbar.

Entwicklung

npm run dev
npm test

Tests kompilieren den Server, überprüfen sowohl moderne als auch Legacy-Protokollverhandlung, inspizieren alle Tool-Schemata und -Annotationen, testen Sicherheitsgates und testen den HTTP-Client ohne Verwendung eines echten API-Schlüssels.

Für eine kleine Live-Überprüfung im Nur-Lese-Modus:

npm run test:live

Der Live-Smoke-Test ruft Team-, Perioden-, Roster- und Raid-Listen-Endpunkte auf. Er ruft niemals Bewerbungs- oder Schreib-Tools auf.

WoWAudit-API-Hinweise

• Die öffentliche Dokumentation definiert keinen Paginierungs- oder Ratenbegrenzungsvertrag.

• Die Dokumentation liefert hauptsächlich Antwortbeispiele anstelle strenger wiederverwendbarer Schemata, daher können sich Nutzlastfelder weiterentwickeln.

• Die eingebettete Dokumentation enthält eine entwicklungsähnliche Server-URL. Dieses Projekt verwendet standardmäßig den bestätigten Produktionsursprung https://api.wowaudit.com.

• WoWAudit akzeptiert einen API-Schlüssel in einem Abfrageparameter, aber dieser Server verwendet bewusst nur den Autorisierungs-Header, um das Durchsickern von Anmeldeinformationen zu reduzieren.