VADS MCP Server

An MCP (Model Context Protocol) server that gives AI coding agents structured, accurate knowledge of the VA Design System — components, tokens, patterns, and usage guidance. This prevents AI from hallucinating component APIs and ensures generated code uses correct <va-*> web component attributes, events, and tokens.

MCP is an open protocol supported by Claude Code, GitHub Copilot, Cursor, Windsurf, Zed, and other AI coding tools.

Build

git clone <repo-url> vads-mcp-server
cd vads-mcp-server
npm install
npm run build

This compiles TypeScript source into dist/. The built server entry point is dist/index.js.

How It Connects to AI Agents

The MCP server uses stdio transport — it communicates over stdin/stdout. You do not run it as a standalone process. Instead, your AI coding tool reads a config file, spawns node dist/index.js as a child process, and manages its lifecycle automatically.

Each tool has its own config file format. The VA Prototype Kit ships pre-configured files for all three:

| AI Tool | Config file (in prototype kit) | How the path works | |---------|-------------------------------|-------------------| | Claude Code | .claude/settings.json | Absolute path to dist/index.js — update for your machine | | GitHub Copilot | .vscode/mcp.json | ${workspaceFolder}/../vads-mcp-server/dist/index.js — works when repos are siblings | | Cursor | .cursor/mcp.json | ../vads-mcp-server/dist/index.js — works when repos are siblings |

Claude Code

Add to .claude/settings.json in the project that should have VADS knowledge:

{
  "mcpServers": {
    "vads": {
      "command": "node",
      "args": ["/absolute/path/to/vads-mcp-server/dist/index.js"]
    }
  }
}

GitHub Copilot (VS Code)

Add to .vscode/mcp.json:

{
  "servers": {
    "vads": {
      "command": "node",
      "args": ["${workspaceFolder}/../vads-mcp-server/dist/index.js"]
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "vads": {
      "command": "node",
      "args": ["../vads-mcp-server/dist/index.js"]
    }
  }
}

CLI Usage

The package also works as a CLI tool — useful when MCP is unavailable or you want to reduce token overhead by calling it via a bash/terminal tool instead of the MCP protocol.

npm install -g @department-of-veterans-affairs/vads-mcp-server

vads-mcp find-components alert
vads-mcp get-component va-alert
vads-mcp get-tokens --category color
vads-mcp get-guide installation
vads-mcp map-figma-component "Alert - Warning"

All commands output JSON to stdout. When called with no arguments, vads-mcp starts in MCP server mode (existing behavior).

See AGENTS.md for the full CLI reference including all 9 subcommands with examples and output shapes.

Tools

| Tool | Parameters | Description | |------|-----------|-------------| | find_components | query?: string | Search components by name, tag, or keyword. No query returns all 77+ components. | | get_component | tag: string | Full API docs for a component: props (with HTML attr names, types, defaults), events, slots, CSS parts, dependency graph. | | validate_component_api | tag: string, attributes: string[] | Validate HTML attributes against the component spec. Identifies invalid attributes and suggests corrections. | | get_tokens | category?: string | Design tokens (CSS custom properties) filtered by category: color, font, spacing, elevation, size, component, legacy. | | find_tokens | query: string | Search tokens by CSS variable name or value. | | get_guide | topic: string | Implementation guides: installation, page-structure, form-patterns, accessibility, frameworks/vanilla, figma-to-code. | | get_utility_classes | category?: string | VADS CSS utility classes: margin, padding, display, flexbox, typography, color, border, sizing, position, visibility, grid. | | map_figma_component | figmaComponentName: string | Map a Figma component name to the corresponding <va-*> web component tag, with attribute mappings and HTML example. |

Resources

| URI | Content | |-----|---------| | vads://components | JSON list of all components with tag names and summaries | | vads://component/{tag} | Full component documentation as JSON | | vads://tokens | All design tokens with CSS variable names | | vads://tokens/{category} | Tokens filtered by category: color, font, spacing, elevation, size, component, legacy | | vads://guides/{topic} | Static guides: installation, page-structure, form-patterns, accessibility, figma-to-code, frameworks/vanilla |

Prompts

| Prompt | Description | |--------|-------------| | vads_mode | Activates VADS-aware coding mode. Provides the AI with rules for using components, tokens, page structure, and accessibility — plus a list of all available tools and components. |

Example Prompts

These work in any MCP-connected AI tool (Claude Code, GitHub Copilot, Cursor, etc.) once the server is configured:

| Prompt | What the AI does | |--------|-----------------| | "What props does va-text-input accept?" | Calls get_component for va-text-input, returns all props with HTML attribute names, types, defaults, and events | | "What color tokens are available?" | Calls get_tokens with category color, returns all VADS color CSS custom properties | | "Convert this Figma component called 'Alert - Warning' to code" | Calls map_figma_component, resolves to <va-alert status="warning"> with correct attributes | | "Is error-message a valid attribute on va-text-input?" | Calls validate_component_api to check and suggests error if the attribute name is wrong | | "Show me spacing utility classes" | Calls get_utility_classes with category margin or padding, returns VADS utility class names | | "How do I set up VADS in a new project?" | Calls get_guide with topic installation, returns step-by-step setup instructions | | "I need an action link to start an application" | Calls find_components for "link", sees disambiguation hint, uses get_component for va-link-action |

Data Sources

| Source | Package | What it provides | |--------|---------|-----------------| | Stencil component-docs.json | @department-of-veterans-affairs/web-components | 77+ components with props, events, slots, CSS parts, dependency graphs | | CSS Library | @department-of-veterans-affairs/css-library | Design tokens as CSS custom properties, utility classes | | Static guides | data/guides/ | Installation, page structure, form patterns, accessibility, vanilla JS, Figma-to-code | | Figma mapping | data/figma-component-map.json | 68 Figma component name to <va-*> web component mappings | | Utility classes | data/utility-classes.json | VADS CSS utility class catalogue |

Project Structure

vads-mcp-server/
  src/
    index.ts                    # CLI entry point (#!/usr/bin/env node, stdio transport)
    server.ts                   # McpServer setup — registers all tools, resources, prompts
    lib/
      component-parser.ts       # Parses Stencil component-docs.json
      token-parser.ts           # Parses CSS custom properties from the CSS library
    tools/
      component-tools.ts        # find_components, get_component, validate_component_api
      token-tools.ts            # get_tokens, find_tokens
      guide-tools.ts            # get_guide
      utility-tools.ts          # get_utility_classes
      figma-tools.ts            # map_figma_component
    resources/
      components.ts             # vads://components, vads://component/{tag}
      tokens.ts                 # vads://tokens, vads://tokens/{category}
      guides.ts                 # vads://guides/{topic}
    prompts/
      vads-mode.ts              # System prompt for VADS-aware mode
  data/
    figma-component-map.json    # Figma-to-VADS component mapping
    utility-classes.json        # Utility class catalogue
    guides/                     # Static markdown guides
      installation.md
      page-structure.md
      form-patterns.md
      accessibility.md
      figma-to-code.md
      frameworks/
        vanilla.md
  test/                         # 7 test files, 108 tests
  dist/                         # Compiled output (after npm run build)

Commands

npm run build        # Compile TypeScript to dist/
npm run dev          # Compile in watch mode
npm run start        # Run the server directly (for debugging — normally launched by AI tools)
npm run test         # Run all tests
npm run test:watch   # Run tests in watch mode

License

MIT