Konfigurationsreferenz

Diese Seite dokumentiert die Umgebungsvariablen, die der Axe MCP Server liest, und die empfohlenen benutzerdefinierten Anweisungen für Ihren KI-Agenten. Diese gelten für beide Docker- und npm-Distributionen. Wo diese Werte platziert werden sollen, erfahren Sie in Ihrem Client-Setup-Leitfaden.

Konfigurationsoptionen

Der Axe MCP Server unterstützt mehrere Umgebungsvariablen zur Anpassung:

AXE_SERVER_URL

Der Standardwert (https://axe.deque.com) ist für die meisten Benutzer korrekt — diejenigen, die die geteilte US-SaaS-Instanz von Deque verwenden. Wenn Ihre Organisation eines der folgenden verwendet, müssen Sie AXE_SERVER_URL auf die Basis-URL Ihrer Instanz setzen:

• Ein regionale SaaS-Instanz (EU, Australien, Frankfurt, etc.)
• Eine privates Cloud-Bereitstellung
• Eine lokale-Installation

Wenn Sie sich nicht sicher sind, welche Instanz Ihre Organisation verwendet, überprüfen Sie die URL, die Sie zum Einloggen in das Axe Account Portal verwenden, oder fragen Sie Ihren Administrator.

Setzen Sie AXE_SERVER_URL explizit im env-Block Ihrer MCP-Serverkonfiguration. Die Einrichtungsanleitungen für den Client enthalten Beispiele, die genau zeigen, wo es hinzugefügt werden muss.

AXE_CHROME_PATH

nur npm-Verteilung. Dies wird in Docker nicht unterstützt, da es immer den mitgelieferten Browser verwendet – der Server kann nicht gestartet werden, wenn AXE_CHROME_PATH unter der Docker-Distribution gesetzt ist.

Standardmäßig verwendet die npm-Distribution den Chromium-Build, den Sie über Playwright installieren. Setzen Sie AXE_CHROME_PATH auf den vollständigen Pfad einer vorhandenen Chrome/Chromium-Binärdatei, um diese stattdessen zu verwenden und die Playwright-Installation zu überspringen.

• Der Wert muss eine ausführbare Binärdatei sein, kein .app-Bundle oder Verzeichnis. Auf macOS verweisen Sie beispielsweise auf die Binärdatei im Bundle: /Applications/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing.
• Das Binary muss existieren und unter macOS und Linux starten und auf --version reagieren. Der Server überprüft dies beim Start und stoppt mit einer Meldung, die den Grund angibt, wenn er dies nicht kann, wie z.B. dass die Datei nicht ausführbar ist oder eine Systembibliothek fehlt. Unter Windows überprüft der Server nur, ob die Datei existiert, sodass ein Binary, das nicht starten kann, beim ersten Scan fehlschlägt.
• Branding von Google Chrome stable 137 und später wird nicht unterstützt. Verwenden Sie Chrome für Tests oder eine andere Chromium-kompatible Binärdatei.

Die analyze- und igt-Tools akzeptieren auch ein pro-Anruf chromePath-Argument, das für diesen Anruf AXE_CHROME_PATH übergeordnet ist.

AXE_ADVANCED_RULES

Setzt das Erweiterte Regeln-Vertrauen-Vorgabe für jeden Scan, den dieser Server ausführt, und überschreibt die Standardkonfiguration Ihrer Organisation für Axe — vorausgesetzt, Ihr Administrator erlaubt es den Benutzern, die Einstellung zu ändern.

Akzeptierte Werte sind "precise" (oder "90%"), "balanced" (oder "70%"), "thorough" (oder "50%") und "disabled". Die Werte sind nicht von der Groß- und Kleinschreibung abhängig.

{
  "env": {
    "AXE_ADVANCED_RULES": "thorough"
  }
}

Invalid Advanced Rules value: "high". Expected one of: 'precise' (90%), 'balanced' (70%), 'thorough' (50%), 'disabled'.

Das analyze-Werkzeug akzeptiert auch ein argumentabhängiges advancedRules, das für diesen Aufruf gegenüber AXE_ADVANCED_RULES Vorrang hat. Wenn Ihr Administrator die Einstellung gesperrt hat, werden beide zugunsten der Voreinstellung der Organisation ignoriert. Siehe Erweiterte Regeln für die vollständigen Vorrangregeln und den advancedRules-Antwortblock.

AXE_SCREENSHOT_DIR

Legt das Verzeichnis fest, in das das analyze-Werkzeug Screenshots speichert, wenn ein Aufruf screenshot.save ohne einen expliziten Pfad durchläuft. Es hat keinen Effekt auf Aufrufe, die screenshot.saveTo setzen, was immer Vorrang hat, und keinen auf Aufrufe, die überhaupt nichts speichern.

{
  "env": {
    "AXE_SCREENSHOT_DIR": "/Users/me/axe-screenshots"
  }
}

Relative Pfade werden relativ zum Arbeitsverzeichnis des Servers aufgelöst. Der Standard ist das temporäre Verzeichnis Ihres Betriebssystems.

Token-Aktualisierungsvariablen

Diese gelten nur für OAuth 2.0 und erlauben einem laufenden Server, ein frisch aktualisiertes Zugriffstoken zu akzeptieren, damit eine Sitzung, die ihr Token überlebt, keinen Neustart benötigt. Der Listener ist standardmäßig deaktiviert und startet nur, wenn sowohl AXE_TOKEN_REFRESH_PORT als auch AXE_TOKEN_REFRESH_SECRET gesetzt sind.

Normalerweise setzen Sie diese nicht manuell. @deque/axe-auth run überwacht den Server und stellt sie für Sie bereit — Sie wählen einen Port, und es generiert das Geheimnis.

Ihr Aktualisierungstoken wird niemals an den Server gesendet — nur kurzfristige Zugriffstokens werden übertragen, und das gemeinsame Geheimnis schützt den Endpunkt. Siehe Eine lange Sitzung am Leben halten für vollständige Docker- und npm-Konfigurationen.

IGT_TIMEOUT_MS

Begrenzt einen Intelligenter Geführter Test-Durchlauf, gemessen vom Moment des Teststarts bis zu dem Moment, in dem die Ergebnisse zurückkommen. Es gilt sowohl für analyze-Aufrufe, die igtTools bestehen, als auch für die veraltete igt Werkzeug.

Ein Test ist KI-gesteuert und arbeitet die interaktiven Elemente der Seite nacheinander ab, sodass er berechtigterweise viel länger dauert als ein Scan. Sein Standardwert ist darauf abgestimmt, weshalb er viel größer als BROWSER_TIMEOUT_MS ist. Ein Durchlauf, der das Budget überschreitet, schlägt mit einem Fehler fehl, der das überschrittene Budget benennt:

IGT timed out after 200000ms

Der Fehler benennt auch den letzten Schritt, den der Test erreicht hat, und wie lange er her ist, was Ihnen mitteilt, ob er noch Fortschritte machte oder gestoppt hatte:

IGT timed out after 200000ms (last checkpoint: keyboard:tabstops:start 83s ago; last step: analyze-tabstops-ai 61s ago; last tick 2s ago)

Erhöhen Sie IGT_TIMEOUT_MS, wenn eine Seite genügend interaktive Elemente hat, um die zusätzliche Zeit zu benötigen. Eine Erhöhung von BROWSER_TIMEOUT_MS wird nicht helfen: Jeder Timeout auf dieser Seite ist ein eigenes unabhängiges Budget, und der Scan war bereits beendet, bevor der Test begann.

{
  "env": {
    "IGT_TIMEOUT_MS": "400000"
  }
}

Proxy-Variablen

Wenn ausgehender Datenverkehr von Ihrem Netzwerk durch einen Proxy gehen muss, wie etwa Zscaler, stellen Sie die vollständige URL des Proxys ein und der Server sendet alle seine Anfragen durch ihn an den axe-Server, einschließlich Start, API-Schlüsselprüfungen und Behebungen.

Kleingeschriebene Schreibweisen (https_proxy, http_proxy, no_proxy) funktionieren ebenfalls und haben Vorrang, wenn beide gesetzt sind.

{
  "env": {
    "HTTPS_PROXY": "http://proxy.example.com:3128",
    "NO_PROXY": "intranet.example.com"
  }
}

• Der Scan-Browser verwendet denselben Proxy wie die Anfragen des Servers an den axe-Server. Listen Sie alle Intranet-Seiten auf, die Sie in NO_PROXY scannen.
• npm-Distribution: lokale Adressen (localhost, *.localhost, 127.0.0.0/8 und [::1]) verbinden immer direkt, sodass Scans von lokalen Entwicklungsservern nicht betroffen sind.
• Docker-Distribution: Der Server schreibt localhost-URLs auf die Adresse Ihres Docker-Hosts um (siehe Scans lokaler Entwicklungsserver), die innerhalb des Containers keine lokale Adresse ist. Fügen Sie diese Adresse zu NO_PROXY hinzu, damit diese Scans direkt verbinden. Der Server protokolliert die umgeschriebene URL jedes Mal, wenn er eine localhost-Seite scannt, unter Rewriting localhost URL using resolved IP of docker host.
• Der Scan-Browser kann keinen Proxy verwenden, der einen Benutzernamen und ein Passwort erfordert. Der Server protokolliert eine Warnung, wenn die Proxy-URL Anmeldedaten enthält.
• Die URL muss eine vollständige http://- oder https://-URL sein. Wenn der Proxy, den der Server für AXE_SERVER_URL verwendet, es nicht ist, stoppt der Server beim Start mit einer Meldung, die die Variable benennt. Eine Proxy-Variable, die der Server nicht verwendet, wie HTTP_PROXY mit dem Standard-https://-axe-Server, wird ignoriert.
• Wenn der Proxy den TLS-Verkehr inspiziert, setzen Sie NODE_EXTRA_CA_CERTS auch auf den Pfad des CA-Zertifikats des Proxys.

Für die Docker-Distribution geben Sie diese mit -e in den Container ein, genauso wie mit AXE_API_KEY.

Proxies mit OAuth 2.0

Wenn Sie OAuth 2.0 verwenden, benötigt der @deque/axe-auth CLI, der Sie anmeldet und Ihre Tokens aktualisiert, ebenfalls den Proxy. Setzen Sie NODE_USE_ENV_PROXY=1 neben HTTPS_PROXY, damit Node.js seine Anfragen durch den Proxy sendet. Dies erfordert Node.js 22.21 oder neuer.

Wenn Sie den Server über axe-auth run starten, fügen Sie ihn demselben env-Block hinzu:

{
  "env": {
    "HTTPS_PROXY": "http://proxy.example.com:3128",
    "NODE_USE_ENV_PROXY": "1"
  }
}

Wenn Sie axe-auth login selbst ausführen, setzen Sie zuerst beide Variablen im selben Terminal.

NODE_EXTRA_CA_CERTS

Setzen Sie NODE_EXTRA_CA_CERTS auf den Pfad einer PEM-Datei, die das CA-Zertifikat Ihrer Organisation enthält, wenn Ihr Netzwerk eine interne CA oder einen Proxy verwendet, der TLS-Verkehr inspiziert. Der Server liest es auf jeder Plattform, sodass seine eigenen Anfragen an den axe-Server dieser CA vertrauen, sobald die Datei analysiert wird.

Ob der Scan-Browser ebenfalls der CA vertraut, hängt von Ihrer Plattform ab:

• Docker — funktioniert automatisch. Binden Sie das Zertifikat in den Container ein und verweisen Sie die Variable darauf:

  {
    "mcpServers": {
      "axe-mcp-server": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "AXE_API_KEY",
          "-e",
          "NODE_EXTRA_CA_CERTS=/certs/ca.pem",
          "-v",
          "/path/to/your/ca.pem:/certs/ca.pem:ro",
          "dequesystems/axe-mcp-server"
        ],
        "env": {
          "AXE_API_KEY": "<your-api-key>"
        }
      }
    }
  }

• npm auf Linux — funktioniert automatisch, sobald certutil installiert ist (libnss3-tools auf Debian/Ubuntu, nss-tools auf RHEL/Fedora). Ohne sie startet der Server ohne Browservertrauen und protokolliert eine Warnung. Die CA bleibt von Chromium auf diesem Rechner vertraut, nachdem der Server beendet wird.

• npm auf macOS und Windows — fügen Sie die CA selbst zu Ihrer Anmelde-Schlüsselbund (macOS) oder Ihrem derzeitigen Benutzer vertrauenswürdigen Stammzertifikatsspeicher (Windows) hinzu, nur für SSL vertrauenswürdig. Der Server protokolliert beim Start, welchen Speicher er verwenden soll.

Unter Linux und Docker wird nur das erste Zertifikat in der Datei dem Browser hinzugefügt, daher richten Sie NODE_EXTRA_CA_CERTS auf die einzelne CA aus, zu der Ihre Seiten verkettet werden.

Der Server liest NODE_EXTRA_CA_CERTS nur beim Start, daher starten Sie ihn neu, nachdem Sie die Variable gesetzt oder geändert haben. Siehe Nicht vertrauenswürdige Zertifikate, wenn Scans immer noch fehlschlagen.

NODE_TLS_REJECT_UNAUTHORIZED

Wenn Sie NODE_TLS_REJECT_UNAUTHORIZED auf "0" setzen, werden die Zertifikatsprüfungen sowohl im Server als auch im Scan-Browser deaktiviert. Es ist ein letzter Ausweg für den Fall, dass NODE_EXTRA_CA_CERTS keine Option ist, wie bei einem schnellen lokalen Test gegen eine Seite mit eigenhändig signiertem Zertifikat.

{
  "env": {
    "NODE_TLS_REJECT_UNAUTHORIZED": "0"
  }
}

Für die Docker-Distribution geben Sie es mit -e NODE_TLS_REJECT_UNAUTHORIZED=0 in den Container ein.

Variablen für die phasenweise Auswahl

Diese gelten für phasenweise Auswahl für die interaktiven Elemente IGT. Der erste Aufruf pausiert den Durchlauf und hält den Browser geöffnet, bis Ihr Agent den zweiten Aufruf macht. Diese Begrenzungen regeln, wie lange ein pausierter Durchlauf wartet und wie viele Browser gleichzeitig geöffnet gehalten werden können.

Erhöhen Sie SELECTION_SESSION_TTL_MS, wenn Sie regelmäßig mehr als drei Minuten benötigen, um eine lange Liste von Elementen zu überprüfen. Beide Werte müssen positive ganze Zahlen sein, sonst verweigert der Server den Start.

{
  "env": {
    "SELECTION_SESSION_TTL_MS": "600000"
  }
}

AXE_PAGE_LOAD_DELAY_MS

Anders als die oben genannten Variablen ist dies kein Timeout. Es ist eine feste Verzögerung, die der Server immer nach Abschluss der Navigation abwartet, bevor er eine before Aktionen ausführt und bevor er scannt. Sie existiert für Seiten, die nach dem Laden weiter gerendert werden, ohne dass es etwas Verlässliches zum Warten gibt. Jeder Scan, den dieser Server ausführt, zahlt die Verzögerung vollständig, also halten Sie sie klein.

{
  "env": {
    "AXE_PAGE_LOAD_DELAY_MS": "2000"
  }
}

Bevorzugen Sie ein waitFor Schritt im analyze-Werkzeug's before-Array, wo Sie ein Element benennen können, das erst existiert, wenn sich die Seite gesetzt hat. waitFor setzt genau dann fort, wenn dieses Element erscheint, daher ist es sowohl zuverlässiger als auch in der Regel schneller als eine pauschale Verzögerung.

Konfiguration Ihres KI-Agenten (Empfohlen)

Um sicherzustellen, dass Ihr KI-Codeagent die Tools des Axe MCP Servers korrekt verwendet und den besten Praktiken für Barrierefreiheit folgt, können Sie ihm benutzerdefinierte Anweisungen geben. Diese Anweisungen helfen dem Agenten, den richtigen Workflow zur Analyse und Behebung von Barrierefreiheitsproblemen zu verstehen.

Wo Anweisungen Hinzufügen

Die Methode variiert je nach Client:

• VS Code mit GitHub Copilot - Fügen Sie zu .github/copilot-instructions.md in Ihrem Projektstamm hinzu
• Cursor - Fügen Sie in den Einstellungen zu „Cursor Rules“ hinzu
• Claude-Code - Fügen Sie zu einer CLAUDE.md-Datei in Ihrem Projektstamm hinzu
• Claude Desktop - Fügen Sie benutzerdefinierte Anweisungen in den Einstellungen hinzu
• Andere MCP-Clients - Konsultieren Sie die Dokumentation Ihres Clients für die Konfiguration benutzerdefinierter Anweisungen

Beispiel-Workflow-Anweisungen

Unten ist eine empfohlene Vorlage, die Sie für Ihren Agenten anpassen können:

# Accessibility Testing and Remediation Workflow

## MANDATORY WORKFLOW - DO NOT DEVIATE

When working with accessibility issues, you MUST follow this exact workflow:

### 1. Analysis Phase

When asked to analyze pages for accessibility issues, you MUST:

- Use the `analyze` tool to scan the page
- Do NOT manually identify accessibility issues
- Always provide the complete URL being analyzed

### 2. Authentication & Pre-Scan Setup

When the user's request involves credentials, form input, dismissing
overlays, or waiting for content before the scan, you MUST:

- Pass an ordered `before` array to the `analyze` tool using the
  `click`, `fill`, and `waitFor` actions
- Resolve any references to env vars, `.env*` files, or local
  configuration into literal strings BEFORE calling the tool — the
  server treats `value` as a literal and will not expand `${VAR}`,
  `$VAR`, or `{{VAR}}` syntax
- Use `fill` for secret values so the server's redaction protections
  apply; never embed secrets in a `selector`, which appears in logs
  and error messages
- ASK the user when the source of a credential or value is ambiguous;
  do NOT guess or fabricate values
- Use ONLY selectors the user provided; if a step needs a selector
  the user did not name, ASK rather than guess
- Use `waitFor` after any `click`/`fill` that triggers async UI
  (route changes, late-rendered content) to deterministically gate
  the next step or the scan — pick a selector that exists ONLY in
  the post-interaction state (e.g., a logout button or dashboard
  heading), never a generic one like `body` or `#app` that already
  exists beforehand

### 3. Remediation Phase

When asked to remediate or fix accessibility issues, you MUST:

- Collect ALL violations from the analysis and pass them to the
  `remediate` tool in a SINGLE batched call — do NOT call `remediate`
  once per issue
- Give each issue a unique `id` so each result can be correlated
  back to its input
- Provide the exact HTML element, rule ID, and issue description for
  every issue in the batch
- Review the remediation guidance before making any code changes
- Apply fixes based on the remediate tool's recommendations
- Do NOT manually fix accessibility issues without first using the remediate tool

### 4. Verification Phase

After applying fixes, you MUST:

- Re-run `analyze` to verify all issues are resolved
- Confirm zero violations before considering the task complete

## Required Workflow Example:

1. analyze → Find violations
2. remediate → Pass ALL violations in one batched call to get fix guidance
3. Apply recommended fixes to code
4. analyze → Verify fixes

## Enforcement

- NEVER skip the remediate tool when fixing accessibility issues
- ALWAYS use both analyze and remediate tools as specified
- This workflow ensures proper accessibility best practices and compliance

Warum das Wichtig ist

Diese Anweisungen stellen sicher, dass Ihr Agent:

• Verwendet das Fachwissen von Deque - Nutzt KI-Modelle, die auf jahrzehntelangen Daten aus Barrierefreiheitsbewertungen trainiert wurden, anstatt allgemeines LLM-Wissen
• Befolgt bewährte Praktiken - Wendet konsistente, WCAG-konforme Korrekturen an, anstatt generische Lösungen
• Überprüft Änderungen - Bestätigt immer, dass die Korrekturen die Probleme tatsächlich behoben haben
• Vermeidet falsches Vertrauen - Geht nicht davon aus, dass es weiß, wie Barrierefreiheitsprobleme ohne fachkundige Anleitung zu beheben sind

Obwohl optional, verbessern diese Anweisungen erheblich die Qualität und Zuverlässigkeit der Zugänglichkeitskorrekturen in Ihrem Codebestand.