VertaaUX MCP Server

The only MCP server with an autonomous audit, fix, and verify loop. Detects UX and accessibility issues across 7 categories, generates framework-aware patches (React, Vue, Angular, Svelte), opens atomic GitHub PRs via the Git Trees API, and verifies the fix landed in production. Built for CI/CD pipelines with policy-as-code thresholds.

Why this server is different

verify_fixes loop: close the audit, fix, re-audit cycle without leaving the agent loop. Budget-capped at 3 iterations to prevent runaway billing.
Framework-aware patches: suggest_fix detects React/Vue/Angular/Svelte/Nuxt via the nearest package.json and emits idiomatic patches (JSX rewrites for React, HTML attrs preserved elsewhere).
Atomic Git Trees PRs: generate_pr applies N patches in a single commit or zero. Conflict graph + AST gate (Babel, vue-eslint-parser, svelte/compiler) refuse unparseable patches before they reach the PR.
Deterministic finding IDs: rule:hash format stable across audit runs so agents can reference findings without storing state.
Multi-engine a11y: audit_a11y combines axe-core, AccessLint, and VertaaUX analyzers in a single call.
Policy-as-code: policy_check mirrors the GitHub Action's threshold evaluator exactly so CI and agent verdicts match.

Features

38 Tools across audit, fix, PR, schedule, webhook, policy, and a11y categories
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

MCP Official Registry

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

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

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.gitignore		.gitignore
DX-ASSESSMENT.md		DX-ASSESSMENT.md
LICENSE		LICENSE
README.md		README.md
banner-dark.svg		banner-dark.svg
banner-light.svg		banner-light.svg
glama.json		glama.json
package.json		package.json
server.json		server.json
smithery.yaml		smithery.yaml

Folders and files

Latest commit

History

Repository files navigation

VertaaUX MCP Server

Why this server is different

Features

Install

MCP Official Registry

npm

Quick Start

IDE Integration

Claude Desktop

VS Code (with MCP extension)

Cursor

Environment Variables

Tools

Audit Tools (Core)

Fix & Verify Tools

Analysis Tools

Management Tools

Accessibility Tools (Multi-Engine)

Deprecated

Prompt Templates

Resources

Enterprise Controls

Example: Audit-to-PR Workflow

Development

Project Structure

Testing

Building

Error Handling

API Reference

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Packages