{
  "markdown": "# VertaaUX MCP Server\n\nThe 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.\n\n## Why this server is different\n\n- **`verify_fixes` loop**: close the audit, fix, re-audit cycle without leaving the agent loop. Budget-capped at 3 iterations to prevent runaway billing.\n- **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).\n- **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.\n- **Deterministic finding IDs**: `rule:hash` format stable across audit runs so agents can reference findings without storing state.\n- **Multi-engine a11y**: `audit_a11y` combines axe-core, AccessLint, and VertaaUX analyzers in a single call.\n- **Policy-as-code**: `policy_check` mirrors the GitHub Action's threshold evaluator exactly so CI and agent verdicts match.\n\n## Features\n\n- **38 Tools** across audit, fix, PR, schedule, webhook, policy, and a11y categories\n- **7 Prompt Templates** for common workflows\n- **8 Resource URIs** for audit data and UX guidelines\n- **Enterprise Controls**: domain allowlist, rate limiting, PII redaction\n- **Dual Transport**: stdio (CLI/Desktop) + HTTP streaming (web)\n- **Official MCP SDK**: spec-compliant via `@modelcontextprotocol/sdk`\n\n## Install\n\n### MCP Official Registry\n\n```bash\nnpx -y @modelcontextprotocol/cli install io.github.PetriLahdelma/vertaaux-mcp\n```\n\n### npm\n\n```bash\nnpm install -g @vertaaux/mcp-server\nVERTAAUX_API_KEY=vx_live_... vertaaux-mcp\n```\n\n> **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`](docs/REGISTRY-PUBLISHING.md) for the runbook.\n\n## Quick Start\n\n```bash\n# Install & build\nnpm install && npm run build\n\n# Run (stdio transport, for Claude Desktop, VS Code, Cursor)\nVERTAAUX_API_KEY=vx_live_... npm start\n\n# Run (HTTP transport, for web clients)\nVERTAAUX_API_KEY=vx_live_... npm run start:http\n```\n\n## IDE Integration\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"vertaaux\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/mcp-server/dist/index.js\"],\n      \"env\": {\n        \"VERTAAUX_API_KEY\": \"vx_live_...\"\n      }\n    }\n  }\n}\n```\n\n### VS Code (with MCP extension)\n\nAdd to `.vscode/settings.json`:\n\n```json\n{\n  \"mcp.servers\": {\n    \"vertaaux\": {\n      \"command\": \"node\",\n      \"args\": [\"./mcp-server/dist/index.js\"],\n      \"env\": {\n        \"VERTAAUX_API_KEY\": \"vx_live_...\"\n      }\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"vertaaux\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/mcp-server/dist/index.js\"],\n      \"env\": {\n        \"VERTAAUX_API_KEY\": \"vx_live_...\"\n      }\n    }\n  }\n}\n```\n\n## Environment Variables\n\n| Variable | Required | Default | Purpose |\n|---|---|---|---|\n| `VERTAAUX_API_KEY` | Yes | — | API authentication key |\n| `VERTAAUX_API_BASE` | No | `https://vertaaux.ai/api/v1` | API endpoint URL |\n| `PORT` | No | `8787` | HTTP transport port |\n| `GITHUB_TOKEN` | No | — | GitHub API access for `generate_pr` |\n\n## Tools\n\n### Audit Tools (Core)\n\n| Tool | Description |\n|---|---|\n| **`audit_url`** | Run UX & accessibility audit on a deployed URL. Returns top 5 issues with severity breakdown. |\n| **`audit_repo`** | Static analysis on local codebase (React/Vue/Svelte/HTML). Finds missing alt text, unlabeled buttons/inputs/links. |\n| **`audit_artifact`** | Audit from HAR files (response times, failed requests, large payloads) or Lighthouse JSON (accessibility findings). |\n| **`get_findings`** | Retrieve findings from a completed audit with filtering by severity, rule, and pagination. |\n| **`get_audit`** | Get audit job status and results by job ID. |\n\n### Fix & Verify Tools\n\n| Tool | Description |\n|---|---|\n| **`explain_finding`** | Deep-dive into a finding: WCAG criteria, repro steps, fix guidance, before/after code examples. |\n| **`suggest_fix`** | Generate search/replace patch with confidence score. Supports single and batch mode. |\n| **`generate_patch`** | Generate accessibility fix patch for a specific issue from an audit. |\n| **`run_verification_suite`** | Verify a patch fixes the issue without regressions via before/after audit. |\n| **`generate_pr`** | Create a draft GitHub PR with fix patches. Requires `GITHUB_TOKEN`. |\n| **`create_pr_comment`** | Generate a PR comment with suggestion blocks, ordered by severity. |\n\n### Analysis Tools\n\n| Tool | Description |\n|---|---|\n| **`analyze_component`** | Heuristic UX review of component code (no browser needed). Checks images, buttons, inputs, links. |\n| **`run_llm_audit`** | Provider-agnostic LLM audit (Mistral/OpenAI via Vertaa adapter). |\n| **`capture_screenshot`** | Capture screenshot by running a quick audit. |\n| **`compare_competitors`** | Compare UX metrics against competitor URLs with category-level score deltas. |\n| **`explain_issue`** | Format an issue into developer-friendly markdown guidance. |\n\n### Management Tools\n\n| Tool | Description |\n|---|---|\n| **`create_webhook`** | Register webhook for audit notifications. |\n| **`list_webhooks`** / **`delete_webhook`** | Manage webhooks. |\n| **`create_schedule`** | Cron-based scheduled audits with score threshold alerts. |\n| **`get_schedule`** / **`list_schedules`** / **`update_schedule`** / **`delete_schedule`** | Manage schedules. |\n| **`get_quota`** | Check plan and remaining credits. |\n| **`get_engines`** | List available engine versions. |\n\n### Accessibility Tools (Multi-Engine)\n\n| Tool | Description |\n|---|---|\n| **`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). |\n| **`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. |\n\n### Deprecated\n\n| Tool | Description |\n|---|---|\n| **`run_audit`** | **DEPRECATED** — Use `audit_url` instead. |\n\n## Prompt Templates\n\nPre-built workflow prompts for common audit scenarios:\n\n| Prompt | Description | Arguments |\n|---|---|---|\n| **`quick_audit`** | Audit a URL and summarize top issues with fix recommendations | `url` |\n| **`fix_accessibility`** | Full audit → patch → PR comment workflow | `url` |\n| **`compare_ux`** | Compare against competitors and identify UX gaps | `url`, `competitors`, `industry?` |\n| **`monitor_regression`** | Set up scheduled monitoring with alerts | `url`, `frequency?` |\n| **`audit_codebase`** | Static analysis on local codebase | `path` |\n\n## Resources\n\nThe server exposes MCP resources via `vertaa://` URIs:\n\n| URI Pattern | Description |\n|---|---|\n| `vertaa://audits/{auditId}` | Full audit result |\n| `vertaa://audits/{auditId}/summary` | Lightweight summary |\n| `vertaa://audits/{auditId}/findings/{findingId}` | Single finding detail |\n| `vertaa://screenshots/{auditId}` | Screenshot metadata |\n| `vertaa://screenshots/{auditId}/annotated` | Annotated screenshot |\n| `vertaa://history/{encodedUrl}` | Audit history for URL |\n| `vertaa://history/{encodedUrl}/trend` | Score trend analysis |\n| `vertaa://guidelines/{topic}` | UX guidelines (buttons, forms, navigation, color-contrast, errors, content) |\n\n## Enterprise Controls\n\nConfigure domain allowlists, rate limits, and PII redaction programmatically:\n\n```typescript\nimport { configureEnterpriseControls } from './server.js';\n\nconfigureEnterpriseControls({\n  allowlist: {\n    allowed_domains: ['*.example.com'],\n    denied_domains: ['internal.example.com'],\n  },\n  budget: {\n    max_requests: 100,\n    max_pages: 50,\n    max_duration_ms: 60000,\n    max_concurrency: 3,\n  },\n  redaction: {\n    redact_emails: true,\n    redact_phone_numbers: true,\n    redact_credit_cards: true,\n    custom_patterns: [\n      { name: 'api_key', pattern: 'sk_[a-zA-Z0-9]{20,}', replacement: '[REDACTED]' }\n    ],\n  },\n});\n```\n\n## Example: Audit-to-PR Workflow\n\n```\n1. audit_url({ url: \"https://example.com\", mode: \"deep\" })\n   → Returns audit_id with top 5 issues\n\n2. get_findings({ audit_id: \"...\", severity: \"critical\" })\n   → Returns all critical findings with deterministic IDs\n\n3. suggest_fix({ audit_id: \"...\", finding_id: \"button-name:a1b2c3d4\" })\n   → Returns search/replace patch with 85% confidence\n\n4. run_verification_suite({ url: \"...\", selector: \"button.submit\", rule_id: \"button-name\" })\n   → Verifies fix resolves the issue\n\n5. create_pr_comment({ file_path: \"src/Button.tsx\", patches: [...] })\n   → Generates PR comment with suggestion blocks\n```\n\n## Development\n\n### Project Structure\n\n```\nmcp-server/\n├── src/\n│   ├── index.ts              # Main entry, tool registration\n│   ├── server.ts             # MCP server config, resources, middleware\n│   ├── a11y-tools.ts         # Multi-engine a11y audit & baseline diffing tools\n│   ├── http.ts               # HTTP transport entry point\n│   ├── prompts.ts            # MCP prompt templates\n│   ├── analysis.ts           # Component analysis engine\n│   ├── patch.ts              # Patch generation\n│   ├── verification.ts       # Patch verification\n│   ├── pr-comment.ts         # PR comment generation\n│   ├── tools/\n│   │   ├── audit-url.ts      # audit_url tool\n│   │   ├── audit-repo.ts     # audit_repo tool (static analysis)\n│   │   ├── audit-artifact.ts # audit_artifact tool (HAR/Lighthouse)\n│   │   ├── get-findings.ts   # get_findings tool\n│   │   ├── explain-finding.ts# explain_finding tool\n│   │   ├── suggest-fix.ts    # suggest_fix tool\n│   │   ├── generate-pr.ts    # generate_pr tool\n│   │   └── index.ts          # Tool exports\n│   ├── transports/\n│   │   ├── stdio.ts          # Stdio transport (default)\n│   │   └── http.ts           # HTTP streaming transport\n│   ├── middleware/\n│   │   ├── allowlist.ts      # Domain/path allowlist\n│   │   ├── budget.ts         # Rate limiting & quotas\n│   │   ├── redaction.ts      # PII redaction\n│   │   └── index.ts          # Middleware stack\n│   ├── resources/\n│   │   ├── audit-results.ts  # vertaa://audits/* resources\n│   │   ├── screenshots.ts    # vertaa://screenshots/* resources\n│   │   ├── historical.ts     # vertaa://history/* resources\n│   │   ├── legacy.ts         # Guidelines resources\n│   │   └── index.ts          # Resource exports\n│   ├── schemas/\n│   │   ├── audit.ts          # Audit schemas (mode, findings)\n│   │   ├── findings.ts       # Finding schemas\n│   │   ├── controls.ts       # Enterprise control schemas\n│   │   ├── errors.ts         # Error schemas\n│   │   └── index.ts\n│   ├── utils/\n│   │   ├── error-recovery.ts # Structured errors with recovery guidance\n│   │   ├── change-tracker.ts # Baseline change tracking\n│   │   └── deterministic-id.ts # Stable finding IDs\n│   └── index.test.ts         # Test suite\n├── README.md\n├── package.json\n├── tsconfig.json\n└── vitest.config.ts\n```\n\n### Testing\n\n```bash\nnpm test              # Run test suite\nnpm run test:watch    # Watch mode\nnpm run test:coverage # Coverage report\n```\n\n### Building\n\n```bash\nnpm run build         # TypeScript → dist/\n```\n\n## Error Handling\n\nAll errors include structured recovery guidance:\n\n```json\n{\n  \"code\": \"AUDIT_NOT_FOUND\",\n  \"message\": \"Audit abc123 not found.\",\n  \"recovery\": {\n    \"action\": \"Start a new audit for this URL\",\n    \"tool\": \"audit_url\",\n    \"params\": { \"url\": \"https://example.com\" }\n  }\n}\n```\n\nError codes follow JSON-RPC 2.0: `-32700` (parse), `-32600` (invalid request), `-32601` (method not found), `-32602` (invalid params), `-32603` (internal error).\n\n## API Reference\n\nThe MCP server communicates with the VertaaUX API v1. See the [API Documentation](https://vertaaux.ai/developer-docs).\n\n## License\n\nMIT\n",
  "bytes": 12350,
  "sha": "caa24be72a6eab1534227c37ef9e145c2ae0573fb14163fc97df8dc680e5f325",
  "repo_slug": "vertaaux/mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_petrilahdelma_vertaaux_mcp_f3fc5972/readme"
}