npm package: @marcelinodzn/ds-mcp-server
Description: MCP server for Jio Design System - exposes components, tokens, and validation tools. Supports stdio, HTTP, and Vercel serverless.
Author: Jio Design System Team
Latest version: 0.3.0

# Jio Design System MCP Server

Model Context Protocol (MCP) server that exposes the Jio Design System components, tokens, and validation tools to AI assistants like Claude.

## What is this?

This MCP server provides AI assistants with direct access to:
- **34 component schemas** with full TypeScript type definitions
- **4,182 design tokens** across 13 collections
- **Validation tools** for accessibility, token usage, and platform compatibility
- **AI sub-agents** for specialized design system guidance
- **Comprehensive documentation** optimized for AI consumption

## Features

### Resources (Read-Only Data)

#### Component Registry
- `jio-ds://registry` - Complete catalog of all 34 components
- `jio-ds://registry/category/{category}` - Components by category (Form, Typography, etc.)
- `jio-ds://registry/platform/{web|native}` - Components by platform

#### Component Schemas
- `jio-ds://schemas` - Index of all schemas
- `jio-ds://components/{name}/schema` - TypeScript interface for component props
- `jio-ds://components/{name}/spec` - Usage examples and patterns

#### Design Tokens
- `jio-ds://tokens/summary` - Lightweight overview (10KB, recommended default)
- `jio-ds://tokens/collection/{name}` - Specific token collection on-demand
- `jio-ds://tokens/search?pattern={pattern}` - Search tokens by name

#### Documentation
- `jio-ds://docs/quick-start` - AI Quick Start Guide
- `jio-ds://docs/index` - Navigation guide for all docs
- `jio-ds://docs/platform-parity` - Cross-platform compatibility
- `jio-ds://docs/component-api` - Complete component reference
- `jio-ds://docs/design-reference` - Core design principles
- `jio-ds://docs/ai-system` - Sub-agent architecture

### Tools (Actions)

#### 1. Resolve Token
```json
{
  "name": "resolve-token",
  "description": "Resolve a design token with context",
  "input": {
    "tokenName": "Surface/Bold/idle",
    "context": {
      "Platform": "Desktop (1440)",
      "Color Mode": "Light",
      "Density": "Default",
      "Surface": "Subtle",
      "Theme": "Pack1"
    }
  },
  "output": {
    "value": "oklch(0.95 0.02 264)",
    "cssValue": "oklch(95% 0.02 264)",
    "resolved": true
  }
}
```

**Use Cases:**
- Get the actual value of a token in a specific context
- Understand how tokens resolve across modes
- Debug token resolution issues

#### 2. Validate Token Usage
```json
{
  "name": "validate-token-usage",
  "description": "Check code for hard-coded values",
  "input": {
    "code": "const styles = { color: '#FF0000', padding: '16px' }",
    "componentName": "Button"
  },
  "output": {
    "valid": false,
    "violationCount": 2,
    "violations": [
      {
        "line": 1,
        "value": "#FF0000",
        "type": "color",
        "suggestion": "Use a design token from Surface/*, Brand/*, or Semantic/* collections"
      },
      {
        "line": 1,
        "value": "16px",
        "type": "spacing",
        "suggestion": "Use a spacing token from the Spacing/* collection"
      }
    ]
  }
}
```

**Use Cases:**
- Enforce no-literals policy (zero hard-coded values)
- Identify violations during code review
- Suggest correct tokens to use

#### 3. Check Accessibility
```json
{
  "name": "check-accessibility",
  "description": "Validate WCAG AA compliance",
  "input": {
    "componentProps": { "onPress": "handleClick" },
    "componentName": "Button",
    "code": "function Button() { ... }"
  },
  "output": {
    "wcagCompliant": false,
    "reactAriaCompliant": true,
    "errorCount": 1,
    "issues": [
      {
        "severity": "error",
        "criterion": "2.4.6 Headings and Labels",
        "description": "Button missing accessible label",
        "fix": "Add aria-label or visible text"
      }
    ]
  }
}
```

**Use Cases:**
- Validate accessibility before shipping
- Catch WCAG violations early
- Verify React Aria conformance

#### 4. Check Platform Compatibility
```json
{
  "name": "check-platform",
  "description": "Verify component availability",
  "input": {
    "componentName": "WebHeaderNavigation",
    "targetPlatform": "native"
  },
  "output": {
    "available": false,
    "platformType": "web-only",
    "alternatives": ["BottomNavigation", "HeaderNavigation"],
    "notes": "WebHeaderNavigation is web-only and not available for native..."
  }
}
```

**Use Cases:**
- Check if a component works on target platform
- Find cross-platform alternatives
- Avoid platform-specific API usage

### Prompts (AI Sub-Agents)

#### 1. Accessibility Agent
```
Prompt: "accessibility-agent"
Args: { componentCode, componentName }
```

Validates component against WCAG AA standards and React Aria conformance. Provides:
- Detailed accessibility audit
- Specific WCAG violations with criterion numbers
- Keyboard navigation requirements
- Screen reader testing guidance
- Remediation steps with code examples

**When to use:** Before shipping any interactive component, or when adding accessibility tests.

#### 2. Code Quality Agent
```
Prompt: "code-quality-agent"
Args: { componentCode, componentName }
```

Enforces design system standards and token-only policy. Checks:
- No hard-coded values (hex, px, ms, etc.)
- Design system prop contract
- React Aria integrity (no forks/patches)
- Slot discipline and surface inheritance
- State-based styling patterns

**When to use:** During code review or when refactoring components.

#### 3. Surface Agent
```
Prompt: "surface-agent"
Args: { componentCode, componentName }
```

Validates elevation system and surface stacking. Verifies:
- Surface context inheritance
- Elevation formula accuracy (two-shadow system)
- Dark mode treatment (white stroke, correct opacity)
- Media/transparency token usage

**When to use:** When working with layered components (cards, modals, popovers) or elevation.

#### 4. Design Guidance Agent
```
Prompt: "design-guidance-agent"
Args: { task, componentName?, platform? }
```

Provides comprehensive design system usage guidance. Offers:
- Direct answers to design system questions
- Code examples with correct token usage
- Component recommendations
- Best practices and common pitfalls
- Platform considerations

**When to use:** Anytime you need help understanding how to use the design system correctly.

## Installation

### Prerequisites
- Node.js 18+
- Claude Desktop app (or any MCP-compatible client)

### 1. Build the MCP Server

```bash
# From the monorepo root
cd packages/ds-mcp-server
npm run build
```

### 2. Configure Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "jio-design-system": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/JioDS_AI_Go/packages/ds-mcp-server/dist/index.js"
      ]
    }
  }
}
```

**Important:** Replace `/ABSOLUTE/PATH/TO/` with the actual path to your monorepo.

### 3. Restart Claude Desktop

Quit and reopen Claude Desktop. You should see "Jio Design System" in the MCP servers list.

### 4. Verify Installation

Ask Claude: "List the resources from the Jio Design System MCP server"

You should see all 34 components, token collections, and documentation.

## Remote Deployment (HTTP Transport)

The MCP server supports **Streamable HTTP transport** for remote deployment, allowing you to access it from anywhere.

### Quick Start (Local HTTP)

```bash
# Build and start HTTP server
cd packages/ds-mcp-server
npm run build
npm run start:http

# Server runs at http://localhost:3000/mcp
```

### Cloud Deployment

Deploy to any cloud platform:

| Platform | Scale-to-Zero | Command/Config |
|----------|---------------|----------------|
| **Railway** | Yes | `railway up` |
| **Render** | Yes | Connect repo |
| **Fly.io** | Yes | `fly deploy` |
| **Koyeb** | Yes | `koyeb deploy` |
| **Docker** | - | `docker run -p 3000:3000` |

### Client Configuration (Remote)

For HTTP transport, configure your client with:

```json
{
  "mcpServers": {
    "jio-design-system": {
      "type": "streamable-http",
      "url": "https://your-deployment.com/mcp"
    }
  }
}
```

Or use `mcp-remote` for clients that only support stdio:

```json
{
  "mcpServers": {
    "jio-design-system": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-deployment.com/mcp"]
    }
  }
}
```

### Health Check

```bash
curl https://your-deployment.com/health
```

For detailed deployment instructions, see [DEPLOYMENT.md](./DEPLOYMENT.md).

## Usage Examples

### Example 1: Get Component Schema

**You:** "Get the schema for the Button component"

Claude will read `jio-ds://components/Button/schema` and show you all available props with TypeScript types.

### Example 2: Resolve a Token

**You:** "What is the value of Surface/Bold/idle in light mode on desktop?"

Claude will use the `resolve-token` tool:
```
Token: Surface/Bold/idle
Context: Desktop (1440), Light, Default, Subtle
Value: oklch(0.95 0.02 264)
```

### Example 3: Validate Component Code

**You:** "Check this code for accessibility issues"
```tsx
<button onClick={handleClick}>
  <Icon name="close" />
</button>
```

Claude will use the `check-accessibility` tool and find:
- Missing accessible label (WCAG 2.4.6)
- Should use React Aria's useButton hook
- Suggestion: Add aria-label="Close" or visible text

### Example 4: Get Design Guidance

**You:** "How do I create a primary button that adapts to different surfaces?"

Claude will use the `design-guidance-agent` prompt and provide:
- Code example with proper imports
- Token usage for different surface levels
- Best practices for surface-aware components
- Accessibility considerations

### Example 5: Find Components for Mobile

**You:** "Which navigation components are available for React Native?"

Claude will read `jio-ds://registry/platform/native` and list:
- BottomNavigation (stable)
- HeaderNavigation (beta)
- BottomNavigationItem (stable)
- HeaderNavigationItem (beta)

## Architecture

### Resource Caching
- 5-minute TTL on loaded resources
- Lazy loading for schemas and specs
- Summary-first approach for tokens (10KB vs 500KB+)

### Token Resolution
- Reuses `@jio/ds-tokens` resolver
- Default context: Desktop, Light, Default, Subtle, Pack1
- Supports all 13 collections and multi-mode resolution

### Validation
- Regex-based scanning for hard-coded values
- WCAG 2.1 AA criteria checks
- React Aria hook detection
- Platform availability lookup

### Prompts
- Load agent definitions from `/docs/architecture/agents/`
- Include relevant documentation as context
- Structured response format for consistency

## Development

### Project Structure
```
packages/ds-mcp-server/
├── src/
│   ├── index.ts                  # MCP server entry point
│   ├── resources/                # Resource handlers
│   │   ├── index.ts              # Main resource router
│   │   ├── registry.ts           # Component catalog
│   │   ├── schemas.ts            # JSON schemas
│   │   ├── tokens.ts             # Design tokens
│   │   └── docs.ts               # Documentation
│   ├── tools/                    # Tool implementations
│   │   ├── index.ts              # Main tool router
│   │   ├── resolveToken.ts       # Token resolver
│   │   ├── validateTokenUsage.ts # No-literals checker
│   │   ├── checkAccessibility.ts # WCAG validator
│   │   └── checkPlatform.ts      # Platform checker
│   ├── prompts/                  # Sub-agent prompts
│   │   ├── index.ts              # Main prompt router
│   │   ├── accessibilityAgent.ts # A11y guidance
│   │   ├── codeQualityAgent.ts   # Standards enforcement
│   │   ├── surfaceAgent.ts       # Elevation validation
│   │   └── designGuidanceAgent.ts # General guidance
│   └── utils/
│       ├── fileLoader.ts         # File loading with cache
│       └── tokenResolver.ts      # Token resolution wrapper
├── dist/                         # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md
```

### Adding New Resources

1. Create handler in `src/resources/{name}.ts`
2. Export functions for loading data
3. Add routes in `src/resources/index.ts`
4. Update `handleListResources()` to expose new URIs

### Adding New Tools

1. Create tool in `src/tools/{name}.ts`
2. Export tool definition and handler
3. Add to `listTools()` and `handleToolCall()` in `src/tools/index.ts`

### Adding New Prompts

1. Create prompt in `src/prompts/{name}.ts`
2. Load relevant documentation/agent definitions
3. Add to `listPrompts()` and `handleGetPrompt()` in `src/prompts/index.ts`

### Testing

```bash
# Run tests
npm test

# Build
npm run build

# Development mode with watch
npm run dev

# Start server
npm start
```

## Troubleshooting

### Server Not Showing in Claude Desktop
1. Check the path in `claude_desktop_config.json` is absolute
2. Ensure the MCP server is built (`dist/index.js` exists)
3. Restart Claude Desktop completely (Cmd+Q, then reopen)
4. Check Claude Desktop logs: `~/Library/Logs/Claude/`

### Token Resolution Fails
- Verify `@jio/ds-tokens` package is built
- Check token name is correct (case-sensitive)
- Try with default context first
- Check `packages/ds-tokens/src/variables.json` exists

### Resource Not Found
- Verify the file path is correct relative to monorepo root
- Check file exists: `ls schemas/components/{ComponentName}.schema.json`
- Clear cache by restarting Claude Desktop
- Check for typos in component name (case-sensitive)

### Build Errors
```bash
# Clean and rebuild
rm -rf dist node_modules
npm install
npm run build
```

## Performance

### Resource Sizes
- Registry: ~21KB
- Token Summary: ~10KB (recommended default)
- Full Token Data: ~500KB (load on-demand)
- Component Schema: ~1-3KB each
- Component Spec: ~10-20KB each

### Cache Strategy
- Resources cached for 5 minutes
- Lazy loading for schemas/specs
- Summary-first for tokens
- No disk caching (memory only)

### Optimization Tips
- Use token summary instead of full data
- Request specific collections only
- Cache results client-side where possible
- Use glob resources for multiple components

## Contributing

### Guidelines
1. Follow existing code structure
2. Add TypeScript types for all new code
3. Update README for new features
4. Test with Claude Desktop before submitting
5. Keep prompts concise and actionable

### Adding Token Collections
Edit `src/resources/tokens.ts` to expose new collections.

### Adding Agent Definitions
1. Create markdown file in `/docs/architecture/agents/`
2. Add prompt handler in `src/prompts/`
3. Update prompt index

## License

MIT - See LICENSE file

## Support

For issues or questions:
- GitHub Issues: [marcelinodzn/jio-design-system](https://github.com/marcelinodzn/jio-design-system)
- Documentation: See `/docs/ai-guides/` in monorepo
- Examples: See Storybook stories in `/packages/ds-docs/`

---

**Built with ❤️ for AI-native design systems**