Unofficial MCP Server for USWDS

uswds-mcp

让 AI 生成的政府 UI 真正符合 USWDS 规范。

一个 MCP 服务，为 Claude、Cursor、Copilot、Windsurf 及其他任何 MCP 客户端提供官方 U.S. Web Design System 标记、了解所有真实 USWDS 类的验证器，以及可输出无障碍、通过验证的页面的页面组合器。

非官方且独立。与 GSA、TTS 或官方 USWDS 团队无关联，未获其认可，也非由其维护。请参阅 NOTICE.md。

问题

大模型凭记忆编写 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-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

示例

“构建一个页面，让居民续办钓鱼许可证：资格要求、费用表、办理步骤、常见问题、联系方式。”

模型调用 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 个页面全部没有验证器错误；不使用该工具时，5 个页面中有 1 个出现错误。两种情况下，模型都没有编造类名；但在不使用工具时，它遗漏了一些结构，例如让移动菜单正常工作的页眉叠加层、横幅内部结构和折叠面板按钮类型。样本规模较小，且每项任务只运行一次；请参阅 docs/COMPARISON.md 中的注意事项和方法。

工作原理

1. 导入（npm run ingest）：使用 JSON 夹具渲染每个官方 @uswds/uswds twig 模板，生成规范 HTML；从官方样式表中提取所有类名，并为官方文档编制索引（uswds-site）。
2. 根据真实数据进行验证：验证器会针对每个官方代码片段进行测试（这些片段必须通过），并针对包含 30 种典型 LLM 错误的语料库进行测试（这些错误必须被捕获）。
3. 保持最新：文档和标记来自同一个 USWDS 版本（由测试强制保证），每月工作流都会重新导入并创建 PR。

当前数据：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。