uswds-mcp

Unofficial MCP server for the U.S. Web Design System (USWDS).

uswds-mcp is an independent local stdio Model Context Protocol server that helps AI coding tools and IDEs use USWDS components, design patterns, page templates, packages, design tokens, and accessibility guidance.

This project is not affiliated with, endorsed by, sponsored by, or maintained by the U.S. General Services Administration (GSA), Technology Transformation Services (TTS), or the official USWDS team.

The package includes a prebuilt index generated from public USWDS sources:

• uswds/uswds-site
• uswds/uswds

USWDS is an official project of GSA/TTS. This package is an independent developer tool for working with public USWDS materials.

Features

• Search USWDS documentation and implementation records.
• Retrieve structured component, pattern, template, token, and package records.
• Recommend USWDS page and service structures.
• Generate framework-neutral USWDS HTML with framework adaptation notes.
• Provide framework-specific integration recipes for Next.js, React/Vite, static HTML, Rails, and Drupal.
• Validate common USWDS markup, accessibility, and token-usage issues.
• Validate project setup risks such as wrong package import paths, missing scripts, CDN usage, copied assets, and global CSS impact.
• Include a Codex Skill at .agents/skills/uswds/SKILL.md for agent workflow guidance.

Use the Published Package

Most MCP clients can run the published package directly:

npx -y uswds-mcp

For a project dependency:

npm install uswds-mcp

The published package includes data/records.json, so documentation-backed tools work without running an ingest step.

Develop from Source

npm install
npm run build

To refresh the bundled index from upstream USWDS repositories:

npm run ingest

MCP Configuration

Use the package with an MCP client that supports stdio servers:

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

Registry name:

io.github.bibekpdl/uswds-mcp

AI Tool and IDE Setup

USWDS MCP uses the standard stdio MCP transport and can be used by MCP-compatible AI tools and IDEs. See docs/CLIENTS.md for examples covering:

• Claude Desktop
• Claude Code
• Cursor
• VS Code with GitHub Copilot MCP support
• Windsurf Cascade
• Generic MCP clients

Example configs are also available in examples/.

For framework-specific setup guidance, see docs/INTEGRATION.md.

For a tool-by-tool usage guide, see docs/TOOLS.md.

Development

npm run typecheck
npm test
npm run build
npm run dev

Tools

• search_uswds
• get_component
• get_pattern
• get_template
• recommend_uswds_structure
• generate_uswds_page
• validate_uswds_markup
• get_uswds_integration_recipe
• validate_uswds_project_setup

Resources

• uswds://component/{slug}
• uswds://pattern/{slug}
• uswds://template/{slug}
• uswds://token/{category}
• uswds://package/{name}

Prompts

• build_agency_website
• build_service_page
• audit_uswds_page
• convert_page_to_uswds
• integrate_uswds_in_project

License

MIT

See NOTICE.md for USWDS attribution, upstream source links, and licensing notes for indexed USWDS material.