Content
# uswds-mcp
**Unofficial MCP server for the U.S. Web Design System (USWDS).**
`uswds-mcp` is an independent local stdio [Model Context Protocol](https://modelcontextprotocol.io/) 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`](https://github.com/uswds/uswds-site)
- [`uswds/uswds`](https://github.com/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:
```sh
npx -y uswds-mcp
```
For a project dependency:
```sh
npm install uswds-mcp
```
The published package includes `data/records.json`, so documentation-backed tools work without running an ingest step.
## Develop from Source
```sh
npm install
npm run build
```
To refresh the bundled index from upstream USWDS repositories:
```sh
npm run ingest
```
## MCP Configuration
Use the package with an MCP client that supports stdio servers:
```json
{
"mcpServers": {
"uswds": {
"command": "npx",
"args": ["-y", "uswds-mcp"]
}
}
}
```
Registry name:
```text
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](./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/](./examples).
For framework-specific setup guidance, see [docs/INTEGRATION.md](./docs/INTEGRATION.md).
For a tool-by-tool usage guide, see [docs/TOOLS.md](./docs/TOOLS.md).
## Development
```sh
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](./NOTICE.md) for USWDS attribution, upstream source links, and licensing notes for indexed USWDS material.
