React Uswds

This MCP server indexes your locally installed @trussworks/react-uswds package from your host project and exposes tools that help you discover components, inspect Props surfaces, generate accurate import and usage snippets, and suggest components for a UI use case. It enables code assistants to understand and work with the React USWDS components more efficiently.

How to use

You run this MCP server locally and connect a client that supports MCP to it. The server indexes your host project’s react-uswds package from node_modules and provides tooling to list available components, search for components by use case, retrieve component usage details, fetch specific component information, and get component suggestions. Use these capabilities to accelerate coding by discovering components that fit your UI needs and generating correct import paths and usage snippets.

How to install

Prerequisites you need to prepare before starting include Node.js 18 or newer and Yarn (recommended Yarn 4.12). Install the package dependencies, build the MCP server, and then run it locally.

# Install dependencies
yarn install

# Build the MCP server
yarn build

# Start the MCP server
yarn start

# Optional: run in development mode without a build
# yarn dev

Configuration and environment

The MCP server accepts an environment variable to determine which package to index. By default it resolves the package name @trussworks/react-uswds, but you can override it with REACT_USWDS_PACKAGE if you need to point to a different package.

MCP host configuration example

To run the MCP server as a local process via Node, you can specify the runtime command and the path to the built index file, along with the environment variable that designates the package to index.

{
  "mcpServers": {
    "react-uswds-mcp": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/react-uswds-mcp/dist/index.js"],
      "env": {
        "REACT_USWDS_PACKAGE": "@trussworks/react-uswds"
      }
    }
  }
}

Tools

The MCP server exposes a set of tools to interact with components. You can list all components, search for components by name or capability, retrieve details about a specific component, obtain usage examples, and get suggested components for a UI use case.

Resources

Access to component resources is provided through internal endpoints that map to the underlying react-uswds package structure, enabling you to explore components and their props surfaces.

Available tools

list_components

List all components detected in the indexed package.

search_components

Search for components by name or capability.

get_component

Retrieve detailed information about a specific component.

get_component_usage

Fetch usage examples and props surfaces for a component.

suggest_components

Suggest components suitable for a given UI use case.