Unofficial MCP Server for USWDS

uswds-mcp

AI が生成した政府向け UI を、実際に USWDS 準拠にします。

Claude、Cursor、Copilot、Windsurf など、あらゆる MCP クライアントに公式の U.S. Web Design System のマークアップと、実在するすべての USWDS クラスを把握したバリデーター、そしてアクセシブルで検証済みのページを出力するページコンポーザーを提供する MCP サーバーです。

非公式の独立したプロジェクトです。GSA、TTS、公式 USWDS チームとは提携、推奨、保守のいずれの関係もありません。NOTICE.md をご覧ください。

課題

LLM は記憶を頼りに USWDS を記述します。usa-btn を捏造したり、モバイルメニューの動作に必要な usa-overlay を忘れたり、コンテナーなしで usa-card のマークアップを配置したり、アコーディオンを何にも接続しなかったりします。その結果、一見もっともらしく見えても、微妙な不具合が生じます。

uswds-mcp はこの問題を解決します。

recommend_uswds_structure  →  get_component_markup  →  compose_uswds_page  →  validate_uswds_markup
        (what to use)          (official HTML)         (accessible page)       (fix until 0 errors)

なしの場合	uswds-mcp を使用した場合
クラス名を記憶から呼び出す	@uswds/uswds のテンプレートから公式 HTML を生成（178 個のスニペット、約 70 個のコンポーネントとページテンプレート、すべてのバリアント）
「正しそうに見える」	USWDS のスタイルシートにない usa-* クラスをバリデーターが拒否し、類似候補を提示
構造の不足が見過ごされる	BEM、必須の子要素、ARIA の接続、フォームコントロールの構造、ヘッダーのオーバーレイ、スクリプト、見出しの順序、重複 ID、リンク／画像／ボタンの名前を検証
標準テンプレートの出力	compose_uswds_page が実際のセクションからページを作成。CI で axe-core 違反ゼロ

バリデーターの検出結果の例

{
  "severity": "error",
  "rule": "unknown-class",
  "message": "\"usa-alrt\" is not a class defined by USWDS.",
  "selector": "div.usa-alrt",
  "snippet": "<div class=\"usa-alrt usa-alert--eror\">",
  "suggestion": "Did you mean \"usa-alert\"?"
}

検出結果には、該当要素、修正候補、参照すべきコンポーネント、ドキュメントへのリンクが含まれるため、モデルは自身の出力を修正できます。

クイックスタート

npx -y uswds-mcp

MCP クライアントに追加します。

{
  "mcpServers": {
    "uswds": { "command": "npx", "args": ["-y", "uswds-mcp"] }
  }
}

Claude Code：claude mcp add uswds -- npx -y uswds-mcp

Claude Desktop、Cursor、VS Code、Windsurf などのセットアップ：docs/CLIENTS.md。すぐに使える設定は examples/ にあります。

ネットワーク、API キー、取り込み手順は不要です。データはパッケージに含まれています。

ツール

ツール	用途
get_component_markup	コンポーネント／ページテンプレートとそのバリアント（accordion、footer + slim、sign-in など）の公式 HTMLを取得します。一般的な呼び方（dropdown → select）にも対応します。
compose_uswds_page	構造化されたセクションからページ全体を作成します：ヒーロー、コンテンツ、アラート、サマリーボックス、カード、プロセスリスト、ステップインジケーター、アコーディオン、テーブル、フォーム、連絡先。
validate_uswds_markup	断片またはページ全体を検証します：実在するクラス名、コンポーネントの構造、フォーム、ARIA、アクセシビリティの基本事項。
find_uswds_classes	ユーティリティやレスポンシブバリアント（margin top 2、tablet grid col 6）を含む、実在するクラスを検索します。
generate_uswds_page	自由記述の要件からすばやく作成します。編集可能なセクション仕様、角括弧付きのプレースホルダー、独自の検証結果を返します。
recommend_uswds_structure	サービスやページに適した、USWDS を優先した構造を提案します。
search_uswds	ドキュメント、アクセシビリティ、使用方法に関するガイダンスを検索します（同義語の展開に対応）。
get_component / get_pattern / get_template	構造化されたガイダンスと、コンポーネントの正式なマークアップを提供します。
get_uswds_integration_recipe	Next.js、Vite/React、静的 HTML、Rails、Drupal 向けのフレームワーク設定を提供します。
validate_uswds_project_setup	CSS のインポートパスの誤り、スクリプトの不足、CDN の使用、dist のコピー、グローバル CSS のリスクを検出します。

すべてのツールは読み取り専用です。引数と推奨される使用手順については、docs/TOOLS.md をご覧ください。

リソース： uswds://component/{slug}、uswds://pattern/{slug}、uswds://template/{slug}、uswds://token/{category}、uswds://package/{name} プロンプト： build_agency_website、build_service_page、audit_uswds_page、convert_page_to_uswds、integrate_uswds_in_project

例

「住民が漁業許可証を更新するページを作成してください：対象条件、料金表、手順、FAQ、お問い合わせ先。」

モデルは compose_uswds_page を呼び出し、バナー、スキップナビ、ヘッダー（usa-overlay を含む）、パンくずリスト、概要ボックス、キャプションとスコープ付きヘッダーを備えた縞模様の表、手順リスト、アコーディオン、お問い合わせ先、簡易フッターと識別情報を含む完全なページを取得します。さらに、実際のコンテンツがまだ必要な placeholders の一覧と、検証結果も返します。

先に実際に見てみたいですか？スコアカードを実行してください。

npm run eval

scenario                        unknown classes  errors  warnings  axe violations
'Apply for housing assistance'  0                0       0         0
'Renew a fishing permit'        0                0       0         0
...

役に立ちますか？

小規模なテスト（5つのタスクで、同じモデルをサーバーあり・なしで比較）では、uswds-mcp で作成したページは、サーバーなしでは5ページ中1ページだったのに対し、5ページすべてでバリデーターエラーが0件でした。どちらの場合も、モデルはクラス名をでっち上げることはありませんでした。ツールなしで見落としたのは、モバイルメニューを機能させるヘッダーオーバーレイ、バナーの内部構造、アコーディオンのボタンタイプなどの構造でした。これは単一回の実行による小規模なサンプルです。注意事項と手法については、docs/COMPARISON.md をご覧ください。

仕組み

1. 取り込み（npm run ingest）：公式の @uswds/uswds Twig テンプレートをすべて、それぞれの JSON フィクスチャとともにレンダリングして正規 HTML を生成し、公式スタイルシートからすべてのクラス名を抽出し、公式ドキュメント（uswds-site）をインデックス化します。
2. グラウンドトゥルースに照らした検証：バリデーターは、公式スニペットすべて（合格すること）と、よくある LLM の誤りを集めたコーパス（30件、検出されること）を使ってテストされます。
3. 最新状態の維持：ドキュメントとマークアップは同じ USWDS バージョンのものです（テストで確認されます）。また、毎月のワークフローで再取り込みを行い、プルリクエストを作成します。

現在のデータ：USWDS 3.14.0。

制限事項

• 静的解析です。色のコントラスト、レンダリングされたページの読み上げ順序、実際のスクリーンリーダーでの動作は判断できません。USWDS のコンポーネントだけではサイトは Section 508 に準拠しないため、axe、キーボード、スクリーンリーダーを使ったテストを続けてください。
• カスタム（usa- で始まらない）クラスは使用できますが、検証されません。
• 上流のフィクスチャにある山括弧付きのテキスト（例：<Project title>）はプレースホルダーのコンテンツです。

開発

npm install
npm test         # unit, self-consistency over official markup, MCP end-to-end, axe-core
npm run eval
npm run ingest   # refresh from upstream

CONTRIBUTING.md と CHANGELOG をご覧ください。

ライセンス

MIT。USWDS の帰属表示と、インデックス化された USWDS 素材のライセンスに関する注記については、NOTICE.md をご覧ください。