Vertaaux/mcp Server

VertaaUX MCP 服务

唯一具备自主审计、修复和验证循环的 MCP 服务。可检测 7 个类别中的 UX 和无障碍问题，生成适配框架的补丁（React、Vue、Angular、Svelte），通过 Git Trees API 创建原子化 GitHub PR，并验证修复是否已部署到生产环境。专为 CI/CD 流水线打造，支持策略即代码阈值。

此服务的独特之处

• verify_fixes 循环：在不中断 Agent 循环的情况下完成审计、修复、重新审计流程。最多迭代 3 次，防止费用失控。
• 适配框架的补丁：suggest_fix 会通过最近的 package.json 检测 React/Vue/Angular/Svelte/Nuxt，并生成符合相应惯例的补丁（为 React 重写 JSX，其他框架则保留 HTML 属性）。
• 原子化 Git Trees PR：generate_pr 要么在一次提交中应用 N 个补丁，要么一个也不应用。冲突图和 AST 门禁（Babel、vue-eslint-parser、svelte/compiler）会在无法解析的补丁进入 PR 前将其拒绝。
• 确定性问题 ID：rule:hash 格式在多次审计中保持稳定，因此 Agent 无需存储状态即可引用问题。
• 多引擎无障碍检测：audit_a11y 在一次调用中结合 axe-core、AccessLint 和 VertaaUX 分析器。
• 策略即代码：policy_check 与 GitHub Action 的阈值评估器完全一致，因此 CI 和 Agent 的判定相符。

功能

• 38 个工具，涵盖审计、修复、PR、计划、Webhook、策略和无障碍检测类别
• 7 个提示词模板，适用于常见工作流
• 8 个资源 URI，用于审计数据和 UX 指南
• 企业级控制：域名允许列表、速率限制、PII 脱敏
• 双传输方式：stdio（CLI/桌面端）+ HTTP 流式传输（Web）
• 官方 MCP SDK：通过 @modelcontextprotocol/sdk 符合规范

安装

MCP 官方注册表

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

npm

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

漂移策略：smithery.yaml、glama.json 和 server.json 由实时 MCP 工具注册表通过 npm run generate:manifests 自动生成。**切勿手动编辑。**运行手册请参阅 docs/REGISTRY-PUBLISHING.md。

快速开始

# 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 集成

Claude Desktop

添加到 ~/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（使用 MCP 扩展）

添加到 .vscode/settings.json：

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

Cursor

添加到 .cursor/mcp.json：

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

环境变量

变量	必填	默认值	用途
VERTAAUX_API_KEY	是	—	API 身份验证密钥
VERTAAUX_API_BASE	否	https://vertaaux.ai/api/v1	API 端点 URL
PORT	否	8787	HTTP 传输端口
GITHUB_TOKEN	否	—	generate_pr 的 GitHub API 访问令牌

工具

审计工具（核心）

工具	描述
audit_url	对已部署的 URL 执行 UX 和无障碍审计。返回排名前 5 的问题及严重程度细分。
audit_repo	对本地代码库进行静态分析（React/Vue/Svelte/HTML）。查找缺少替代文本的元素，以及未添加标签的按钮/输入框/链接。
audit_artifact	根据 HAR 文件（响应时间、失败请求、大型负载）或 Lighthouse JSON（无障碍问题）进行审计。
get_findings	获取已完成审计的问题，并按严重程度、规则筛选和分页。
get_audit	根据作业 ID 获取审计作业状态和结果。

修复与验证工具

工具	描述
explain_finding	深入分析一项发现：WCAG 标准、复现步骤、修复指南，以及修复前后的代码示例。
suggest_fix	生成带置信度评分的搜索/替换补丁。支持单项和批量模式。
generate_patch	针对审计中的特定问题生成无障碍修复补丁。
run_verification_suite	通过修复前后的审计，验证补丁是否解决问题且未引入回归。
generate_pr	创建包含修复补丁的 GitHub PR 草稿。需要 GITHUB_TOKEN。
create_pr_comment	生成包含建议代码块的 PR 评论，并按严重程度排序。

分析工具

工具	描述
analyze_component	对组件代码进行启发式 UX 评审（无需浏览器）。检查图片、按钮、输入框和链接。
run_llm_audit	与提供商无关的大模型审计（通过 Vertaa 适配器使用 Mistral/OpenAI）。
capture_screenshot	通过运行快速审计来截取屏幕截图。
compare_competitors	将 UX 指标与竞争对手 URL 进行比较，并提供分类级别的分数差异。
explain_issue	将问题整理成便于开发者阅读的 Markdown 指南。

管理工具

工具	描述
create_webhook	注册用于接收审计通知的 webhook。
list_webhooks / delete_webhook	管理 webhook。
create_schedule	基于 Cron 的定时审计，并支持分数阈值提醒。
get_schedule / list_schedules / update_schedule / delete_schedule	管理计划任务。
get_quota	查看套餐和剩余额度。
get_engines	列出可用的引擎版本。

无障碍工具（多引擎）

工具	描述
audit_a11y	使用 axe-core、AccessLint 和自定义分析器进行多引擎无障碍审计。返回映射到 WCAG 的发现，并附带结构化修复建议和可修复性评级。支持 min_impact 筛选和 mode（basic/standard/deep）。
diff_a11y	将当前无障碍问题与已保存的基线进行比较。返回已修复、新增和未变更的问题，并提供净变化摘要。需要先调用 audit_a11y 来建立基线。

已弃用

工具	描述
run_audit	已弃用 — 请改用 audit_url。

提示词模板

为常见审计场景预先构建的工作流提示词：

提示词	描述	参数
quick_audit	审计 URL，并总结主要问题及修复建议	url
fix_accessibility	完整的审计 → 补丁 → PR 评论工作流	url
compare_ux	与竞争对手进行比较并找出 UX 差距	url、competitors、industry?
monitor_regression	设置定时监控和提醒	url、frequency?
audit_codebase	对本地代码库进行静态分析	path

资源

该服务通过 vertaa:// URI 提供 MCP 资源：

URI 模式	描述
vertaa://audits/{auditId}	完整审计结果
vertaa://audits/{auditId}/summary	轻量级摘要
vertaa://audits/{auditId}/findings/{findingId}	单项发现的详细信息
vertaa://screenshots/{auditId}	屏幕截图元数据
vertaa://screenshots/{auditId}/annotated	已标注的屏幕截图
vertaa://history/{encodedUrl}	URL 的审计历史
vertaa://history/{encodedUrl}/trend	分数趋势分析
vertaa://guidelines/{topic}	UX 指南（按钮、表单、导航、颜色对比度、错误、内容）

企业级控制

以编程方式配置域名允许列表、速率限制和 PII 脱敏：

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]' }
    ],
  },
});

示例：从审计到 PR 的工作流

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

开发

项目结构

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

测试

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

构建

npm run build         # TypeScript → dist/

错误处理

所有错误都包含结构化的恢复指导：

{
  "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" }
  }
}

错误代码遵循 JSON-RPC 2.0：-32700（解析错误）、-32600（无效请求）、-32601（未找到方法）、-32602（无效参数）、-32603（内部错误）。

API 参考

MCP 服务通过 VertaaUX API v1 进行通信。请参阅API 文档。

许可证

MIT