@scarlet-mesh/mcp-rhds/README.md

RHDS MCP Server - All-in-One Model Context Protocol server for Red Hat Design System components with manifest discovery, HTML validation, and developer tooling

# Red Hat Design System (RHDS) MCP Server

## Overview

This comprehensive MCP (Model Context Protocol) server provides advanced Red Hat Design System (RHDS) component development capabilities. It offers enterprise-grade features for component creation, HTML validation, ID generation, template management, and accessibility compliance for RHDS web components.

## Features

### Core Features
* **Component Creation**: Generate RHDS components with proper structure, IDs, and attributes
* **HTML Validation**: Validate HTML against RHDS standards and best practices
* **ID Generation**: Generate RHDS-compliant component IDs following naming conventions
* **Template Management**: Get component templates with required and optional attributes
* **Component Discovery**: List and search all available RHDS components
* **Composition Builder**: Create compositions of multiple RHDS components

### Enterprise Features
* **Accessibility Compliance**: Automatic inclusion of required accessibility attributes
* **Validation Engine**: Comprehensive validation against RHDS standards
* **Type Safety**: Full TypeScript support with detailed interfaces
* **Manifest Integration**: Dynamic component discovery from RHDS manifests
* **Standards Enforcement**: Built-in RHDS naming conventions and best practices

## Supported Components

The server supports 38+ RHDS components including:

**Navigation & Layout**
- `rh-navigation`, `rh-navigation-secondary`, `rh-subnav`
- `rh-breadcrumb`, `rh-jump-links`, `rh-skip-link`
- `rh-footer`, `rh-surface`

**Interactive Elements**
- `rh-button`, `rh-switch`, `rh-chip`
- `rh-accordion`, `rh-disclosure`, `rh-tabs`
- `rh-dialog`, `rh-popover`, `rh-tooltip`

**Content Display**
- `rh-card`, `rh-tile`, `rh-badge`, `rh-tag`
- `rh-blockquote`, `rh-code-block`
- `rh-table`, `rh-pagination`

**Media & Indicators**
- `rh-icon`, `rh-avatar`, `rh-spinner`
- `rh-audio-player`, `rh-video-embed`
- `rh-alert`, `rh-announcement`

**Progress & Status**
- `rh-progress-steps`, `rh-health-index`
- `rh-site-status`, `rh-statistic`
- `rh-timestamp`

And more! Use the `list-components` tool to see all available components.

## Tools

The server provides the following MCP tools:

### Component Tools
* `create-component`: Create a new RHDS component with proper structure, IDs, and attributes
* `get-component-template`: Get a complete template for an RHDS component with all required attributes
* `create-composition`: Create a composition of multiple RHDS components with proper structure

### Utility Tools
* `generate-component-id`: Generate RHDS-compliant IDs following naming conventions
* `validate-component`: Validate HTML against RHDS standards and provide improvement suggestions
* `list-components`: List all available RHDS components with descriptions and capabilities

## Data Source

The server uses the RHDS Custom Elements Manifest and package definitions from:
- `@rhds/elements` (default package)
- Custom manifests via URL or package specifications

## Setup

### Prerequisites

* Node.js (v18 or higher)
* An MCP client (e.g., Cursor, Claude Desktop, or compatible AI tool)

### Installation

1. Clone this repository
2. Install the dependencies:
   ```bash
   npm install
   ```
3. Build the server:
   ```bash
   npm run build
   ```

### Running the Server

1. Start the server:
   ```bash
   npm start
   ```
   The server will listen for MCP requests via standard input/output.

2. For development with auto-rebuild:
   ```bash
   npm run dev
   ```

## Usage Examples

### Basic Component Creation

Create a simple button:
```json
{
  "tool_name": "create-component",
  "input": {
    "tagName": "rh-button",
    "content": "Click me"
  }
}
```

Create a button with custom attributes:
```json
{
  "tool_name": "create-component",
  "input": {
    "tagName": "rh-button",
    "id": "primary-submit-btn",
    "attributes": {
      "variant": "primary",
      "size": "large"
    },
    "content": "Submit Form"
  }
}
```

### Component Templates

Get a template for a card component:
```json
{
  "tool_name": "get-component-template",
  "input": {
    "tagName": "rh-card",
    "includeOptional": true,
    "includeAccessibility": true
  }
}
```

### ID Generation

Generate RHDS-compliant IDs:
```json
{
  "tool_name": "generate-component-id",
  "input": {
    "componentType": "button",
    "purpose": "primary",
    "context": "form"
  }
}
```

Generate navigation menu ID:
```json
{
  "tool_name": "generate-component-id",
  "input": {
    "componentType": "navigation",
    "purpose": "header",
    "context": "main"
  }
}
```

### HTML Validation

Validate RHDS component HTML:
```json
{
  "tool_name": "validate-component",
  "input": {
    "html": "<rh-button variant=\"primary\" aria-label=\"Submit form\">Submit</rh-button>",
    "checkAccessibility": true,
    "checkIds": true
  }
}
```

### Component Discovery

List all available components:
```json
{
  "tool_name": "list-components",
  "input": {}
}
```

Search for specific components:
```json
{
  "tool_name": "list-components",
  "input": {
    "search": "button",
    "category": "interactive"
  }
}
```

### Component Composition

Create a card with button composition:
```json
{
  "tool_name": "create-composition",
  "input": {
    "components": [
      {
        "tagName": "rh-card",
        "attributes": { "variant": "default" },
        "slots": {
          "header": "Card Title",
          "default": "Card content here"
        }
      },
      {
        "tagName": "rh-button",
        "attributes": { "variant": "primary" },
        "content": "Action Button"
      }
    ],
    "wrapperElement": "section",
    "wrapperId": "card-section",
    "wrapperClass": "card-container"
  }
}
```

## Accessibility Features

The server automatically includes accessibility attributes based on RHDS standards:

- **Required Attributes**: Automatically adds required ARIA attributes for each component
- **Validation**: Checks for accessibility compliance during validation
- **Standards**: Follows WCAG guidelines and RHDS accessibility requirements
- **Suggestions**: Provides improvement suggestions for better accessibility

## ID Naming Conventions

RHDS component IDs follow specific patterns:

- **Component IDs**: `component-purpose-context` (e.g., `button-primary-form`)
- **Section IDs**: `section-purpose-context` (e.g., `navigation-main-header`)
- **Form IDs**: `form-purpose-context` (e.g., `input-email-registration`)
- **Navigation IDs**: `nav-purpose-context` (e.g., `menu-primary-header`)

## Validation Features

The validation engine checks for:

### Errors
- Unknown RHDS elements
- Invalid attributes for components
- Missing required attributes
- Invalid slot usage
- Non-compliant ID formats

### Warnings
- Deprecated attributes
- Missing documentation
- Accessibility concerns
- Naming convention violations

### Suggestions
- Alternative attribute values
- Accessibility improvements
- Better naming conventions
- Component alternatives

## Data Structures

```typescript
interface RHDSComponent {
  name: string;
  tagName: string;
  description: string;
  attributes: Attribute[];
  slots: Slot[];
  examples: ComponentExample[];
  documentationUrl: string;
  category: string;
  requiredAttributes: string[];
  accessibilityAttributes: string[];
}

interface ValidationResult {
  isValid: boolean;
  errors: ValidationError[];
  warnings: ValidationWarning[];
  suggestions: string[];
}

interface ComponentTemplate {
  name: string;
  tagName: string;
  template: string;
  requiredAttributes: Record<string, string>;
  optionalAttributes: Record<string, string>;
  slots: string[];
  accessibilityRequirements: string[];
}
```

## Architecture

The server follows a modular architecture with separation of concerns:

- **Services**: Core business logic for components, validation, and ID generation
- **Container**: Dependency injection for service management
- **Formatters**: Response formatting and output generation
- **Types**: Complete TypeScript definitions
- **Constants**: RHDS standards and component definitions

## Development

### Building
```bash
npm run build
```

### Development Mode
```bash
npm run dev
```

### Testing
Use the included test guide (`test-rhds-tools.md`) for comprehensive testing scenarios.

## Integration with AI Tools

Perfect for use with:
- **Cursor**: Direct MCP integration for RHDS development
- **Claude Desktop**: Component creation and validation
- **VS Code**: With MCP extensions for RHDS workflows
- **Custom AI Tools**: Via MCP protocol implementation

## Enterprise Benefits

- **Consistency**: Ensures all RHDS components follow standards
- **Productivity**: Rapid component creation with proper structure
- **Quality**: Built-in validation and accessibility compliance
- **Maintainability**: Type-safe interfaces and clear architecture
- **Scalability**: Support for custom manifests and component libraries

This server is designed for front-end developers, design system teams, and enterprise organizations building with Red Hat Design System components.