snag-mcp

Snag CLI and MCP server for visual QA — explore and check frontend apps locally with Playwright + Claude, or connect to the Snag cloud API.

Install in your project

Requirements

• Node.js 20+
• ANTHROPIC_API_KEY — required for local snag explore / snag check on localhost
• SNAG_API_KEY — optional; only for cloud/MCP API reviews (snag_live_...)
• SNAG_API_URL — optional; defaults to https://api.snag.dev

npm install -g snag-mcp
# or per-project:
npm install --save-dev snag-mcp

On install, Playwright Chromium is downloaded automatically. To install all browsers (full matrix):

SNAG_PLAYWRIGHT_BROWSERS=all npm install -g snag-mcp

Skip browser download (e.g. CI): PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install -g snag-mcp

Manual fallback:

npx playwright install chromium

Quick start (local explore)

export ANTHROPIC_API_KEY=sk-ant-...

cd your-frontend-app
mkdir -p .snag/profiles

# optional login credentials for apps behind auth
cp "$(npm root -g)/snag-mcp/auth.example.json" .snag/auth.json
# edit .snag/auth.json with your test account

snag explore http://localhost:5173 --verbose

Localhost URLs run in local mode automatically (no cloud API). Artifacts are saved under .snag/runs/<id>/.

Project layout (in your repo)

.snag/
  context.md          # optional app context for Claude
  auth.json           # gitignore — test login credentials
  profiles/
    default.md        # optional persona / flow hints
  sites/              # gitignore — remembered explore credentials
  runs/               # gitignore — screenshots, logs, findings

Add to your app .gitignore:

.snag/auth.json
.snag/profiles/*.auth.json
.snag/sites/
.snag/runs/

CLI commands

Local mode (no cloud API)

# Explore like a first-time user — documents flows to .snag/runs/<id>/flows.json
snag explore http://localhost:5173
snag explore http://localhost:5173 --headed --slow-mo 400 --profile default

# Targeted check with intent
snag check http://localhost:5173 --route /schedule --intent "user can create an event"

# Auth for login/signup screens
snag explore http://localhost:5173 --auth login
snag check http://localhost:5173/login --intent "sign in works" \
  --email [email protected] --password secret

# Inspect past runs
snag local list
snag local show <run-id>
snag local logs <run-id>
snag local tail <run-id>

Use --cwd /path/to/app to read .snag/ from a specific directory.

Cloud mode (optional)

Requires SNAG_API_KEY (format: snag_live_...).

snag check https://staging.example.com --route /checkout --intent "guest checkout" --cloud
snag review https://preview.example.com --pr-url https://github.com/o/r/pull/1 --pr-number 1
snag await <review-id>
snag findings <review-id>
snag profiles

Environment variables

| Variable | Required | Default | Purpose | |----------|----------|---------|---------| | ANTHROPIC_API_KEY | Local mode | — | Claude vision for explore/check | | SNAG_API_KEY | Cloud/MCP | — | Snag API authentication | | SNAG_API_URL | No | https://api.snag.dev | Snag API base URL | | SNAG_PLAYWRIGHT_BROWSERS | No | chromium | Set to all for full browser matrix |

MCP server (Cursor / Claude Code)

Local explore/check uses the CLI directly. MCP tools proxy to the Snag cloud API when configured:

{
  "mcpServers": {
    "snag": {
      "command": "npx",
      "args": ["-y", "snag-mcp"],
      "env": {
        "SNAG_API_KEY": "snag_live_your_key_here"
      }
    }
  }
}

For local API development from the Snag monorepo:

{
  "mcpServers": {
    "snag": {
      "command": "npx",
      "args": ["-y", "snag-mcp"],
      "env": {
        "SNAG_API_KEY": "snag_live_your_key_here",
        "SNAG_API_URL": "http://localhost:3001"
      }
    }
  }
}

MCP tools

| Tool | Description | |------|-------------| | snag_profiles | List .snag/profiles/*.md | | snag_check | Start agent-loop review (returns review ID) | | snag_await | Poll until review completes | | snag_check_and_await | Start + wait in one call | | snag_review | Trigger PR gate review | | snag_status | Non-blocking review status | | snag_findings | Get review findings | | snag_fix_prompts | Get fix prompts for findings |

Monorepo development

pnpm install
pnpm --filter snag-mcp build
pnpm snag -- explore http://localhost:5173
pnpm bootstrap:dev   # writes SNAG_API_KEY to .env + .cursor/mcp.json

What works without cloud?

| Command | Cloud API required? | |---------|---------------------| | snag explore http://localhost:5173 | No | | snag check http://localhost:5173 --intent "..." | No | | snag local list/show/logs/tail | No | | snag-mcp MCP tools | Yes (SNAG_API_KEY) | | snag check https://staging... | Yes (unless --local) |

License

MIT