Vertaaux/mcp Server

VertaaUX MCP サーバー

自律的な監査、修正、検証のループを備えた唯一の MCP サーバーです。7 つのカテゴリにわたる UX とアクセシビリティの問題を検出し、フレームワークに対応したパッチ（React、Vue、Angular、Svelte）を生成します。Git Trees API 経由でアトミックな GitHub PR を作成し、修正が本番環境に反映されたことを検証します。ポリシーをコードとして扱うしきい値を備え、CI/CD パイプライン向けに構築されています。

このサーバーが他と異なる理由

• verify_fixes ループ：エージェントのループから離れることなく、監査、修正、再監査のサイクルを完了できます。暴走する課金を防ぐため、最大 3 回のイテレーションに制限されています。
• フレームワーク対応パッチ：suggest_fix は最も近い package.json を使って React/Vue/Angular/Svelte/Nuxt を検出し、慣用的なパッチを出力します（React では JSX を書き換え、それ以外では HTML 属性を保持します）。
• アトミックな Git Trees PR：generate_pr は、N 個のパッチを 1 回のコミットですべて適用するか、まったく適用しません。競合グラフと AST ゲート（Babel、vue-eslint-parser、svelte/compiler）により、解析できないパッチが PR に到達する前に拒否されます。
• 決定的な検出結果 ID：rule:hash 形式は監査の実行をまたいで安定しているため、エージェントは状態を保存せずに検出結果を参照できます。
• マルチエンジン a11y：audit_a11y は axe-core、AccessLint、VertaaUX のアナライザーを 1 回の呼び出しで組み合わせます。
• ポリシーをコードとして管理：policy_check は GitHub Action のしきい値評価機能を正確に再現するため、CI とエージェントの判定が一致します。

機能

• 監査、修正、PR、スケジュール、Webhook、ポリシー、a11y のカテゴリにわたる 38 個のツール
• 一般的なワークフロー向けの 7 個のプロンプトテンプレート
• 監査データと UX ガイドライン向けの 8 個のリソース URI
• エンタープライズ向け制御：ドメインの許可リスト、レート制限、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	プロバイダーに依存しない LLM 監査です（Vertaa アダプター経由の Mistral/OpenAI）。
capture_screenshot	簡易監査を実行してスクリーンショットを撮影します。
compare_competitors	競合の URL と UX 指標を比較し、カテゴリーごとのスコア差を表示します。
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