@vertaaux/mcp-server

VertaaUX MCP Server

Model Context Protocol (MCP) server for VertaaUX.ai — run UX & accessibility audits, generate fixes, and monitor quality from your LLM or IDE.

Features

• 38 Tools for the full audit-to-fix lifecycle
• 7 Prompt Templates for common workflows
• 8 Resource URIs for audit data and UX guidelines
• Enterprise Controls — domain allowlist, rate limiting, PII redaction
• Dual Transport — stdio (CLI/Desktop) + HTTP streaming (web)
• Official MCP SDK — spec-compliant via @modelcontextprotocol/sdk

Install

VertaaUX MCP is listed on the three major MCP registries. Pick whichever your client supports:

Smithery.ai

npx -y @smithery/cli install @vertaaux/mcp-server --client claude

Server page: https://smithery.ai/server/@vertaaux/vertaaux-mcp

Glama.ai

Browse and install from: https://glama.ai/mcp/servers/@vertaaux/vertaaux-mcp

MCP Official Registry

npx -y @modelcontextprotocol/cli install io.github.vertaa/vertaaux-mcp

Manual (npm)

npm install -g @vertaaux/mcp-server
VERTAAUX_API_KEY=vx_live_... vertaaux-mcp

Drift policy: smithery.yaml, glama.json, and server.json are auto-generated from the live MCP tool registry by npm run generate:manifests. Never hand-edit them. See docs/REGISTRY-PUBLISHING.md for the runbook.

Quick Start

# Install & build
npm install && npm run build

# Run (stdio transport — for Claude Desktop, VS Code, Cursor)
VERTAAUX_API_KEY=vx_live_... npm start

# Run (HTTP transport — for web clients)
VERTAAUX_API_KEY=vx_live_... npm run start:http

IDE Integration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "vertaaux": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"],
      "env": {
        "VERTAAUX_API_KEY": "vx_live_..."
      }
    }
  }
}

VS Code (with MCP extension)

Add to .vscode/settings.json:

{
  "mcp.servers": {
    "vertaaux": {
      "command": "node",
      "args": ["./mcp-server/dist/index.js"],
      "env": {
        "VERTAAUX_API_KEY": "vx_live_..."
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "vertaaux": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"],
      "env": {
        "VERTAAUX_API_KEY": "vx_live_..."
      }
    }
  }
}

Environment Variables

Variable	Required	Default	Purpose
VERTAAUX_API_KEY	Yes	—	API authentication key
VERTAAUX_API_BASE	No	https://vertaaux.ai/api/v1	API endpoint URL
PORT	No	8787	HTTP transport port
GITHUB_TOKEN	No	—	GitHub API access for generate_pr

Tools

Audit Tools (Core)

Tool	Description
audit_url	Run UX & accessibility audit on a deployed URL. Returns top 5 issues with severity breakdown.
audit_repo	Static analysis on local codebase (React/Vue/Svelte/HTML). Finds missing alt text, unlabeled buttons/inputs/links.
audit_artifact	Audit from HAR files (response times, failed requests, large payloads) or Lighthouse JSON (accessibility findings).
get_findings	Retrieve findings from a completed audit with filtering by severity, rule, and pagination.
get_audit	Get audit job status and results by job ID.

Fix & Verify Tools

Tool	Description
explain_finding	Deep-dive into a finding: WCAG criteria, repro steps, fix guidance, before/after code examples.
suggest_fix	Generate search/replace patch with confidence score. Supports single and batch mode.
generate_patch	Generate accessibility fix patch for a specific issue from an audit.
run_verification_suite	Verify a patch fixes the issue without regressions via before/after audit.
generate_pr	Create a draft GitHub PR with fix patches. Requires GITHUB_TOKEN.
create_pr_comment	Generate a PR comment with suggestion blocks, ordered by severity.

Analysis Tools

Tool	Description
analyze_component	Heuristic UX review of component code (no browser needed). Checks images, buttons, inputs, links.
run_llm_audit	Provider-agnostic LLM audit (Mistral/OpenAI via Vertaa adapter).
capture_screenshot	Capture screenshot by running a quick audit.
compare_competitors	Compare UX metrics against competitor URLs with category-level score deltas.
explain_issue	Format an issue into developer-friendly markdown guidance.

Management Tools

Tool	Description
create_webhook	Register webhook for audit notifications.
list_webhooks / delete_webhook	Manage webhooks.
create_schedule	Cron-based scheduled audits with score threshold alerts.
get_schedule / list_schedules / update_schedule / delete_schedule	Manage schedules.
get_quota	Check plan and remaining credits.
get_engines	List available engine versions.

Accessibility Tools (Multi-Engine)

Tool	Description
audit_a11y	Multi-engine accessibility audit using axe-core, AccessLint, and custom analyzers. Returns WCAG-mapped findings with structured fix suggestions and fixability ratings. Supports min_impact filtering and mode (basic/standard/deep).
diff_a11y	Compare current accessibility findings against a saved baseline. Returns fixed, new, and unchanged findings with net change summary. Requires a prior audit_a11y call to establish the baseline.

Deprecated

Tool	Description
run_audit	DEPRECATED — Use audit_url instead.

Prompt Templates

Pre-built workflow prompts for common audit scenarios:

Prompt	Description	Arguments
quick_audit	Audit a URL and summarize top issues with fix recommendations	url
fix_accessibility	Full audit → patch → PR comment workflow	url
compare_ux	Compare against competitors and identify UX gaps	url, competitors, industry?
monitor_regression	Set up scheduled monitoring with alerts	url, frequency?
audit_codebase	Static analysis on local codebase	path

Resources

The server exposes MCP resources via vertaa:// URIs:

URI Pattern	Description
vertaa://audits/{auditId}	Full audit result
vertaa://audits/{auditId}/summary	Lightweight summary
vertaa://audits/{auditId}/findings/{findingId}	Single finding detail
vertaa://screenshots/{auditId}	Screenshot metadata
vertaa://screenshots/{auditId}/annotated	Annotated screenshot
vertaa://history/{encodedUrl}	Audit history for URL
vertaa://history/{encodedUrl}/trend	Score trend analysis
vertaa://guidelines/{topic}	UX guidelines (buttons, forms, navigation, color-contrast, errors, content)

Enterprise Controls

Configure domain allowlists, rate limits, and PII redaction programmatically:

import { configureEnterpriseControls } from './server.js';

configureEnterpriseControls({
  allowlist: {
    allowed_domains: ['*.example.com'],
    denied_domains: ['internal.example.com'],
  },
  budget: {
    max_requests: 100,
    max_pages: 50,
    max_duration_ms: 60000,
    max_concurrency: 3,
  },
  redaction: {
    redact_emails: true,
    redact_phone_numbers: true,
    redact_credit_cards: true,
    custom_patterns: [
      { name: 'api_key', pattern: 'sk_[a-zA-Z0-9]{20,}', replacement: '[REDACTED]' }
    ],
  },
});

Example: Audit-to-PR Workflow

1. audit_url({ url: "https://example.com", mode: "deep" })
   → Returns audit_id with top 5 issues

2. get_findings({ audit_id: "...", severity: "critical" })
   → Returns all critical findings with deterministic IDs

3. suggest_fix({ audit_id: "...", finding_id: "button-name:a1b2c3d4" })
   → Returns search/replace patch with 85% confidence

4. run_verification_suite({ url: "...", selector: "button.submit", rule_id: "button-name" })
   → Verifies fix resolves the issue

5. create_pr_comment({ file_path: "src/Button.tsx", patches: [...] })
   → Generates PR comment with suggestion blocks

Development

Project Structure

mcp-server/
├── src/
│   ├── index.ts              # Main entry, tool registration
│   ├── server.ts             # MCP server config, resources, middleware
│   ├── a11y-tools.ts         # Multi-engine a11y audit & baseline diffing tools
│   ├── http.ts               # HTTP transport entry point
│   ├── prompts.ts            # MCP prompt templates
│   ├── analysis.ts           # Component analysis engine
│   ├── patch.ts              # Patch generation
│   ├── verification.ts       # Patch verification
│   ├── pr-comment.ts         # PR comment generation
│   ├── tools/
│   │   ├── audit-url.ts      # audit_url tool
│   │   ├── audit-repo.ts     # audit_repo tool (static analysis)
│   │   ├── audit-artifact.ts # audit_artifact tool (HAR/Lighthouse)
│   │   ├── get-findings.ts   # get_findings tool
│   │   ├── explain-finding.ts# explain_finding tool
│   │   ├── suggest-fix.ts    # suggest_fix tool
│   │   ├── generate-pr.ts    # generate_pr tool
│   │   └── index.ts          # Tool exports
│   ├── transports/
│   │   ├── stdio.ts          # Stdio transport (default)
│   │   └── http.ts           # HTTP streaming transport
│   ├── middleware/
│   │   ├── allowlist.ts      # Domain/path allowlist
│   │   ├── budget.ts         # Rate limiting & quotas
│   │   ├── redaction.ts      # PII redaction
│   │   └── index.ts          # Middleware stack
│   ├── resources/
│   │   ├── audit-results.ts  # vertaa://audits/* resources
│   │   ├── screenshots.ts    # vertaa://screenshots/* resources
│   │   ├── historical.ts     # vertaa://history/* resources
│   │   ├── legacy.ts         # Guidelines resources
│   │   └── index.ts          # Resource exports
│   ├── schemas/
│   │   ├── audit.ts          # Audit schemas (mode, findings)
│   │   ├── findings.ts       # Finding schemas
│   │   ├── controls.ts       # Enterprise control schemas
│   │   ├── errors.ts         # Error schemas
│   │   └── index.ts
│   ├── utils/
│   │   ├── error-recovery.ts # Structured errors with recovery guidance
│   │   ├── change-tracker.ts # Baseline change tracking
│   │   └── deterministic-id.ts # Stable finding IDs
│   └── index.test.ts         # Test suite
├── README.md
├── package.json
├── tsconfig.json
└── vitest.config.ts

Testing

npm test              # Run test suite
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report

Building

npm run build         # TypeScript → dist/

Error Handling

All errors include structured recovery guidance:

{
  "code": "AUDIT_NOT_FOUND",
  "message": "Audit abc123 not found.",
  "recovery": {
    "action": "Start a new audit for this URL",
    "tool": "audit_url",
    "params": { "url": "https://example.com" }
  }
}

Error codes follow JSON-RPC 2.0: -32700 (parse), -32600 (invalid request), -32601 (method not found), -32602 (invalid params), -32603 (internal error).

API Reference

The MCP server communicates with the VertaaUX API v1. See the API Documentation.

License

MIT