MCP Integration

WCAG-Guide includes a Model Context Protocol (MCP) server that exposes accessibility scanning and remediation tools to AI agents. This lets an LLM-based agent autonomously scan sites, triage findings, update statuses, and trigger rescans.

Starting the MCP server

Prerequisite: Docker must be running. The MCP server auto-bootstraps the Docker Compose stack if it is not already running.

# From the cloned repo (no global install required)
node bin/wguide.js mcp

# Or, after `npm link` from the repo root
wguide mcp

# Or, once published to npm
npx wcag-guide mcp

The server connects via stdio transport. Use --no-bootstrap to disable auto-bootstrap, or --bootstrap=always to force it.

The MCP server surfaces a dashboard_url field in key responses (scan triggers, target overview, run summary) so agents can direct users to http://localhost:8080/dashboard to review findings visually.

Client configuration

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "wcag-guide": {
      "command": "node",
      "args": ["/absolute/path/to/wcag-guide/bin/wguide.js", "mcp"]
    }
  }
}

OpenCode

Add to ~/.config/opencode/opencode.json:

{
  "mcpServers": {
    "wcag-guide": {
      "command": "node",
      "args": ["/absolute/path/to/wcag-guide/bin/wguide.js", "mcp", "--no-bootstrap"],
      "env": {
        "WGUIDE_APP_BASE_URL": "http://127.0.0.1:8080"
      }
    }
  }
}

Other MCP clients

Any MCP client that supports stdio transport can connect. Point it at the absolute path to bin/wguide.js mcp.

Available tools

Tool	Description
list_compliance_profiles	List available compliance profiles (WCAG 2.1 A, AA, AAA targets) and identify the default.
list_scan_targets	List registered scan targets, optionally filtered by site key, environment, or branch.
upsert_scan_target	Create or update a scan target (site key + environment + branch + base URL).
get_target_overview	Get a compact remediation summary for one scan target: latest run state, open finding counts by severity, and recent trend.
list_triage_queue	Paginated list of findings for a target, filterable by status, severity, diff state, rule ID, and URL path prefix.
get_scan_run_summary	Detailed summary of one scan run: pages scanned, finding counts, diff breakdown, scanner context.
get_scan_run_hvt_groups	High-Value Target groupings for a run. Groups findings by rule + path cluster to identify root-cause patterns.
get_finding_detail	Full evidence for one finding: latest instance snippet, selector, page URL, rule metadata, and status history.
update_finding_status	Transition a finding's status (open, in_progress, resolved, ignored). Ignored findings require an expiration date.
trigger_page_rescan	Re-scan a single page URL to verify a fix.
trigger_path_rescan	Re-scan all pages under a URL path prefix.
trigger_full_scan	Trigger a full crawl + scan of the entire site.

Resource templates

The MCP server also exposes read-only resources via wcag-guide:// URIs:

URI template	Description
wcag-guide://compliance-profiles	Compliance profile catalog
wcag-guide://targets/{site_key}/{env}/{branch}/summary	Target remediation summary
wcag-guide://scan-runs/{id}/summary	Scan run summary
wcag-guide://scan-runs/{id}/hvt-groups?...	HVT groupings for a run
wcag-guide://findings/{id}	Finding detail with evidence
wcag-guide://queues/{site_key}/{env}/{branch}?...	Paginated triage queue

Example agent workflow

A typical AI agent session might look like:

1. Call list_scan_targets to discover registered sites
2. Call trigger_full_scan to start a new scan
3. Poll get_scan_run_summary until the run completes
4. Call get_scan_run_hvt_groups to identify high-impact clusters
5. Call list_triage_queue to see findings sorted by severity
6. Call get_finding_detail for the most critical findings
7. Fix the code, then call trigger_page_rescan to verify
8. Call update_finding_status to mark findings as resolved