Quickstart

Get WCAG-Guide running locally in under five minutes.

Prerequisites

• Docker and Docker Compose (v2)
• Node.js 20+ (only needed for the CLI or MCP server)

Option A: Docker Compose (full stack)

This starts the API server, worker, PostgreSQL database, and a bundled demo site.

1. Clone and start

git clone https://github.com/jesseslone/wcag-guide.git
cd wcag-guide
./scripts/dev/up.sh

2. Open the dashboard

Navigate to http://127.0.0.1:8080/dashboard in your browser.

3. Launch your first scan

Use the "Add site + start scan" button in the dashboard, or run:

curl -fsS -X POST http://127.0.0.1:8080/scan-runs \
  -H "content-type: application/json" \
  -d '{
    "scan_target": {
      "site_key": "demo-site",
      "environment": "local",
      "branch": "main",
      "base_url": "http://demo-site:8081"
    }
  }'

The worker picks up the job, crawls the demo site with Playwright + axe-core, and writes findings to the database. Refresh the dashboard to see results. Click any page URL to open it in a new tab, or click a selector or code snippet to copy it to your clipboard for pasting into your editor's search.

4. Scan your own site

Replace the base_url with any publicly accessible URL. Use site_key, environment, and branch to organize your targets.

5. Stop the stack

# Stops containers but keeps your scan data
./scripts/dev/down.sh

# Removes everything including the database volume
./scripts/dev/down.sh --purge

Option B: CLI + MCP server

If you want to use WCAG-Guide with an AI agent (Claude Code, OpenCode, etc.), start the MCP server from the repo root:

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

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

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

The MCP server connects via stdio and requires Docker to be running. It auto-bootstraps the Docker Compose stack if not already running. See the MCP page for client configuration.

Configuration

Environment variables control the CLI behavior:

Variable	Default	Description
WGUIDE_BOOTSTRAP	auto	Bootstrap mode: auto, always, or never
WGUIDE_APP_BASE_URL	http://127.0.0.1:8080	Base URL for the API server
WGUIDE_WAIT_SECONDS	90	Seconds to wait for the API server health check