BetterQA Scanner MCP Server

MCP (Model Context Protocol) server for the BetterQA Ecosystem Scanner. Enables AI agents like Claude to scan, analyze, and auto-fix SEO/GEO issues across the 13-site ecosystem.

Installation

npm install @betterqa/scanner-mcp

Or run directly:

npx @betterqa/scanner-mcp

Configuration

Add to your Claude Code MCP settings (~/.claude/settings.json):

{
  "mcpServers": {
    "scanner": {
      "command": "npx",
      "args": ["@betterqa/scanner-mcp"],
      "env": {
        "SCANNER_URL": "https://betterqa-ecosystem-scanner-production.up.railway.app",
        "SCANNER_USER": "betterqa",
        "SCANNER_PASS": "your-password"
      }
    }
  }
}

Available Tools

Scan Operations

| Tool | Description | |------|-------------| | scanner_trigger_scan | Trigger scan for one or all sites (quick/full/deep) | | scanner_scan_status | Get current scan status and queue | | scanner_cancel_scan | Cancel running scan | | scanner_list_projects | List all ecosystem sites | | scanner_scan_history | Get recent scan history |

Results & Analysis

| Tool | Description | |------|-------------| | scanner_get_results | Get latest results for all sites | | scanner_get_domain_report | Get detailed report for a domain | | scanner_get_issues | Get issues filtered by severity/category | | scanner_get_ai_analysis | Get AI-powered recommendations | | scanner_get_low_geo_pages | Find pages with low GEO scores | | scanner_get_gsc_opportunities | Get GSC click/impression opportunities | | scanner_get_issues_summary | Summary of issues by category |

Fix Generation

| Tool | Description | |------|-------------| | scanner_suggest_fixes | Generate fix suggestions with code changes | | scanner_get_fix_details | Get detailed fix with before/after code | | scanner_generate_geo_fix | Generate GEO improvements for a page | | scanner_generate_security_fix | Generate security header config | | scanner_list_fixable_issues | List what can be auto-fixed |

Monitoring & Debugging

| Tool | Description | |------|-------------| | scanner_health_check | Check scanner service health | | scanner_detect_stuck | Detect stuck scans | | scanner_scan_progress | Get detailed scan progress | | scanner_get_errors | Get recent errors for debugging | | scanner_domain_scan_history | Get scan history for a domain | | scanner_compare_scans | Compare current vs previous scan |

Usage Examples

Scan All Sites

mcp__scanner__trigger_scan domain="all" type="quick"

Get Issues for a Site

mcp__scanner__get_issues domain="betterqa.co" severity="critical"

Check for Stuck Scans

mcp__scanner__detect_stuck

Generate Fixes

mcp__scanner__suggest_fixes domain="auditi.ro" issueType="security"

Auto-Fix Workflow

The MCP enables this automated workflow:

1. Scan: trigger_scan → Run ecosystem scan
2. Analyze: get_ai_analysis → Get prioritized issues
3. Generate: suggest_fixes → Get code changes
4. Apply: Use Claude Code to apply changes to codebase
5. Verify: trigger_scan → Rescan to confirm fixes

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | SCANNER_URL | No | Scanner API URL (defaults to Railway deployment) | | SCANNER_USER | No | Username (defaults to "betterqa") | | SCANNER_PASS | Yes | Password for authentication |

Project Mappings

The MCP maps domains to local project directories:

| Domain | Project Directory | |--------|------------------| | betterqa.co | betterqa-wordpress | | bugboard.co | bugboard-ai-scribe | | auditi.ro | wcag-journey-auditor | | betterflow.eu | internal-tool2 | | hireo.ro | recruit-renaissance | | jrny.ro | excel-chatter | | factos.ro | lovable-factos-forge | | menute.ro | menute | | nis2manager.ro | nis2-platform | | finds.ro | finds | | articworks.ro | arctic-blast-bookings-hub | | electricworks.ro | electric-works | | psysign.ro | seal-and-schedule |

License

MIT