Konfigurationsreferenz

Diese Seite dokumentiert die Umgebungsvariablen, die der axe MCP-Server liest, sowie die empfohlenen benutzerdefinierten Anweisungen für Ihren KI-Agenten. Diese gelten für beide Docker- und npm-Distributionen. Informationen dazu, wo diese Werte platziert werden sollen, finden 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 nicht sicher sind, welche Instanz Ihre Organisation verwendet, überprüfen Sie die URL, die Sie verwenden, um sich im Kontenportal von axe anzumelden, 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.
• Die Binärdatei muss gestartet werden und auf --version antworten. Der Server validiert dies beim Start und schlägt bei Unable to find specified chrome instance schnell fehl, wenn es nicht möglich ist.
• 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 die Erweiterte Regeln-Vertrauensvoreinstellung für jeden Scan, den dieser Server durchführt, außer Kraft und überschreibt die axe-Konfigurationsvoreinstellung Ihrer Organisation — vorausgesetzt, Ihr Administrator erlaubt es 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.

Konfiguration Ihres KI-Agenten (Empfohlen)

Um sicherzustellen, dass Ihr KI-Coding-Agent die axe MCP Server-Tools korrekt verwendet und bewährte Praktiken zur Barrierefreiheit befolgt, 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.