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

{
  "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

{
  "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

{
  "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

{
  "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

# 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:

{
  "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)

# 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:

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

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

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

Health Check

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

For detailed deployment instructions, see 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"

<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

# 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

# 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
• Documentation: See /docs/ai-guides/ in monorepo
• Examples: See Storybook stories in /packages/ds-docs/

Built with ❤️ for AI-native design systems