Cisco-One-Design-Field-Kit-MCP-Server by copresto - MCP Server

Cisco One Design Field Kit MCP Server

An MCP (Model Context Protocol) server that provides design system guidance, validation, and code generation for AI agents working on Cisco web applications.

Overview

This MCP server exposes the Cisco One Design Field Kit as structured resources, validation tools, and guided workflows. It enables AI agents (like Claude) to:

Validate component code against Cisco design standards
Generate components following visual lever patterns
Suggest improvements based on design principles
Guide developers through design decisions
Enforce accessibility and performance best practices

🎉 Recent Updates

Phase 1 Complete - Production-Ready Foundation (November 2024)

✅ Added missing combined-levers.json - Complete pattern definitions for all priority levels
✅ Enhanced error handling - User-friendly error messages with helpful guidance
✅ Zod input validation - Runtime validation for all tool arguments
✅ Resource caching - 5-minute TTL cache for improved performance
✅ Test coverage - 35 passing unit and integration tests
✅ CI/CD pipeline - GitHub Actions workflow for automated testing

Build Status: ✅ All tests passing | Test Coverage: 35/35 tests | Build: Success

Features

🎨 Visual Lever Validation

Validates proper implementation of Cisco's three core visual levers:

Glass: Clarity and legibility through depth and transparency
Glow: Energy and attention through vibrant gradients
Sheen: Priority and context through subtle edge lighting

🎯 Design Token Compliance

Ensures consistent use of design tokens for:

Colors (Glass, Glow, Sheen palettes)
Spacing scale (4px, 8px, 16px, 24px, 32px, 48px)
Typography (font families, sizes, weights)
Border radii, shadows, and other design primitives

♿ Accessibility Validation

Comprehensive WCAG AA/AAA compliance checking specific to Cisco design system:

Contrast requirements for text on Glass backgrounds
Gradient text readability
Sheen border visibility for color-blind users
Keyboard navigation support
Screen reader compatibility
Motion sensitivity (prefers-reduced-motion)

🚀 Component Generation

Generate production-ready components with:

Appropriate visual levers based on component purpose
Design token usage throughout
Full accessibility features (ARIA, semantic HTML, keyboard nav)
TypeScript types and JSDoc documentation
Tests and Storybook stories

📐 Design Principles

Validates alignment with Cisco's three design principles:

Signal with Intent: Pair suggested actions with alerts
Inspire Confidence: Show AI reasoning and confidence
Design for Flex: Adapt to changing user context

Installation

Prerequisites

Node.js 18+ or compatible runtime
npm, yarn, or pnpm package manager
Claude Desktop or Claude Code MCP client

Quick Start (Recommended) ⚡

For the fastest setup, use the automated installation script:

# Clone or download the cisco-design-mcp directory
cd cisco-design-mcp

# Run the complete setup (installs dependencies, builds, and configures Claude)
npm run setup

This will automatically:

✅ Install all dependencies (npm install)
✅ Build the TypeScript project (npm run build)
✅ Configure Claude Code/Desktop (adds MCP server to config)
✅ Verify the installation works

Expected Output:

🚀 Cisco Design System MCP Server Setup v1.0.0

✅ MCP server found: /path/to/cisco-design-mcp/dist/index.js
📁 Claude config path: ~/Library/Application Support/Claude/claude_desktop_config.json
📝 Updating existing Claude configuration...
✅ Updated Claude config: ~/Library/Application Support/Claude/claude_desktop_config.json

🎉 Setup Complete!

Next steps:
1. Restart Claude Code/Desktop completely (Quit and reopen)
2. Verify tools are loaded by asking: "What MCP tools do you have available?"
3. Try the examples in README.md

After setup completes, restart Claude Code completely and verify the tools loaded.

Quick Test After Setup

Once restarted, paste this into Claude to verify everything works:

Can you validate this button component against Cisco design standards?

const Button = () => (
  <button style={{ background: '#ff0000', padding: '15px' }}>
    Click me
  </button>
);

If successful, Claude will use the analyze-component tool and provide detailed feedback about Cisco design compliance.

Manual Installation

If you prefer manual setup or need custom configuration:

1. Install Dependencies

cd cisco-design-mcp
npm install

2. Build the Server

npm run build

3. Verify Build

# Check that the server starts correctly
node dist/index.js --version

You should see:

Starting Cisco Design System MCP Server...
Cisco Design System MCP Server running on stdio
Ready to provide design guidance and validation

4. Configure Claude Code/Desktop

For Claude Code: The configuration is automatically handled if you have Claude Desktop installed.

For Claude Desktop: Add to your claude_desktop_config.json file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "cisco-design-system": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/cisco-design-mcp/dist/index.js"
      ],
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}

⚠️ Important: Replace /ABSOLUTE/PATH/TO/ with your actual absolute path!

5. Restart Claude

Critical Step: You must fully restart Claude (not just reload) for the MCP server to load:

Quit Claude completely (Cmd+Q on macOS, Alt+F4 on Windows)
Reopen Claude

6. Verify Installation

After restarting Claude, test that the server loaded:

What MCP tools do you have available?

You should see the Cisco design tools including:

validate-visual-levers
validate-design-tokens
validate-accessibility
analyze-component
generate-cisco-component
suggest-design-improvements
validate-combined-levers

Configuration

The MCP server uses a flexible configuration system with environment variables and .env files.

Quick Configuration

Copy the sample configuration:
```
cp .env.sample .env
```

Edit .env to set your field kit path:

FIELD_KIT_PATH=/path/to/CISCO_ONE_DESIGN_FIELD_KIT.md
DATA_DIR=./data
LOG_LEVEL=info

Key Configuration Options

FIELD_KIT_PATH: Path to the main field kit markdown file (required)
- Supports: absolute paths, relative paths, home directory (~/), environment variables
- Default: ../CISCO_ONE_DESIGN_FIELD_KIT.md
DATA_DIR: Directory containing design system data files (required)
- Default: ./data
LOG_LEVEL: Logging verbosity (debug, info, warn, error)
- Default: info
ENABLE_CACHE: Enable resource caching for performance
- Default: true
CACHE_TTL: Cache time-to-live in milliseconds
- Default: 300000 (5 minutes)

Complete Configuration Guide

For detailed configuration options, troubleshooting, and advanced scenarios, see

The configuration guide covers:

Path resolution and validation
Environment-specific configurations
Error handling and troubleshooting
Performance tuning
Production deployment settings

Troubleshooting Installation

Tools Not Appearing in Claude

If Claude doesn't show the Cisco design tools after restart:

Verify config file syntax:

# macOS
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .

# Windows
type "%APPDATA%\Claude\claude_desktop_config.json"

Check the path is absolute and correct:

ls -la /your/path/to/cisco-design-mcp/dist/index.js

Test server manually:

cd cisco-design-mcp
node dist/index.js
# Should show startup messages

Check Claude logs:

# macOS
tail -f ~/Library/Logs/Claude/*.log

# Windows
# Check Event Viewer or Claude installation directory logs

Build Failures

If npm run build fails:

# Clean and rebuild
rm -rf node_modules dist
npm install
npm run build

# Check TypeScript version
npx tsc --version
# Should be 4.9+ or 5.0+

Permission Issues

If you get permission errors:

# Fix npm permissions (macOS/Linux)
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

# Or use a Node version manager like nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install node

Getting Started

First Steps After Installation

Once you've restarted Claude and verified the tools are available, try these examples:

1. Quick Component Validation

Ask Claude to validate this button component:

Can you validate this button component against Cisco design standards?

const Button = () => (
  <button style={{ background: '#ff0000', padding: '15px' }}>
    Click me
  </button>
);

Expected Result: Claude will use the analyze-component tool and report:

❌ Hardcoded color violation → Use var(--glow-pink)
❌ Non-standard spacing → Use var(--space-md)
❌ Missing ARIA label for accessibility
❌ No visual levers applied
📊 Compliance score and actionable recommendations

2. Generate a Compliant Component

Try generating a component from scratch:

Generate a SecurityAlert component using Cisco design standards with Glass and Sheen visual levers.

Expected Result: Claude will use the generate-cisco-component tool to create:

✅ Complete React component with proper visual levers
✅ Design tokens used throughout (no hardcoded values)
✅ Full accessibility features (ARIA labels, semantic HTML)
✅ TypeScript types and JSDoc documentation
✅ Jest tests and Storybook stories

3. Get Design Guidance

Ask for architectural advice:

I'm building a dashboard card to show network security metrics. Which visual levers should I use and why?

Expected Result: Claude will provide:

🎯 Lever recommendations based on content priority
📋 Implementation guidance with code examples
🔍 Rationale based on Cisco design principles
🎨 Color palette and spacing recommendations

Common Workflows

Design Review Workflow

For systematic component review:

Please run a comprehensive design review on this component:

[paste your component code]

Use the design-review-workflow prompt for a systematic analysis.

Component Creation Workflow

For guided component creation:

I need to create a new AlertCard component. Can you guide me through the component-creation-workflow?

Migration Workflow

For updating existing components:

I have this legacy component that needs to be migrated to Cisco design standards:

[paste legacy code]

Please use the migration-guide workflow.

Usage

Available Tools

1. `validate-visual-levers`

Validate Glass, Glow, and Sheen implementation.

// Input
{
  code: "const Alert = () => <div className='glass-card'>...</div>",
  language: "jsx",
  strictMode: false
}

// Output
{
  valid: true,
  complianceScore: 95,
  violations: [],
  summary: "Visual lever validation passed"
}

2. `validate-design-tokens`

Check for hardcoded values that should use design tokens.

// Input
{
  code: "color: #ff6b9d; padding: 15px;",
  language: "css"
}

// Output
{
  valid: false,
  violations: [
    {
      rule: "use-spacing-tokens",
      severity: "warning",
      message: "Spacing value '15px' should use design token",
      suggestion: "Use var(--space-md)"
    }
  ]
}

3. `validate-accessibility`

WCAG compliance validation specific to Cisco design system.

// Input
{
  code: "<button onClick={handleClick}>Submit</button>",
  componentType: "Button",
  wcagLevel: "AA",
  checkMotion: true
}

// Output
{
  valid: false,
  violations: [
    {
      rule: "wcag-aria-labels",
      severity: "error",
      message: "Interactive elements should have aria-label"
    }
  ]
}

4. `analyze-component`

Comprehensive analysis against all design system standards.

// Input
{
  code: "/* full component code */",
  componentType: "AlertCard",
  framework: "react",
  includePerformanceAnalysis: true
}

// Output
{
  valid: true,
  complianceScore: 88,
  violations: [/* detailed violations */],
  summary: "Compliance: 88%. 0 errors, 3 warnings, 2 suggestions"
}

5. `generate-cisco-component`

Generate compliant component code.

// Input
{
  componentName: "SecurityAlert",
  componentType: "alert",
  visualLevers: {
    glass: true,
    glow: false,
    sheen: true
  },
  framework: "react",
  includeTests: true,
  includeStorybook: true
}

// Output
{
  code: "/* full React component */",
  tests: "/* Jest tests */",
  storybook: "/* Storybook story */",
  documentation: "/* component docs */"
}

6. `suggest-design-improvements`

Analyze code and get prioritized improvement suggestions.

// Input
{
  code: "/* existing component code */",
  componentType: "Button",
  priorityLevel: "high"
}

// Output
{
  improvements: [
    {
      priority: "high",
      category: "design-tokens",
      title: "Replace Hardcoded Colors",
      currentCode: "color: #ff0000;",
      improvedCode: "color: var(--glow-pink);",
      effort: "low"
    }
  ],
  totalImprovements: 5,
  estimatedEffort: "Low (< 2 hours)"
}

7. `validate-combined-levers`

Validate proper combination of multiple visual levers.

// Input
{
  code: "/* component with Glass + Glow + Sheen */",
  priorityLevel: "critical"
}

// Output
{
  valid: true,
  message: "Critical priority correctly uses all three levers"
}

Available Resources

Access design system documentation:

cisco://design/levers/glass - Glass specifications
cisco://design/levers/glow - Glow specifications
cisco://design/levers/sheen - Sheen specifications
cisco://design/principles/signal-with-intent - Signal with Intent principle
cisco://design/principles/inspire-confidence - Inspire Confidence principle
cisco://design/principles/design-for-flex - Design for Flex principle
cisco://design/tokens/colors - Color design tokens
cisco://design/tokens/spacing - Spacing design tokens
cisco://design/tokens/typography - Typography design tokens
cisco://design/components/alert-card - Alert card component pattern
cisco://design/components/ai-assistant - AI assistant interface pattern
cisco://design/patterns/combined-levers - Combined lever patterns
cisco://design/field-kit/complete - Complete field kit documentation

Available Prompts

Guided workflows for common tasks:

`design-review-workflow`

Systematic design review process.

Arguments:
- componentType: Type of component being reviewed
- reviewLevel: quick | standard | comprehensive

`component-creation-workflow`

Step-by-step component creation guide.

Arguments:
- componentName: Name of component to create
- framework: react | vue | angular

`accessibility-checklist`

WCAG compliance checklist specific to Cisco design.

Arguments:
- wcagLevel: A | AA | AAA

`visual-lever-selection`

Interactive guide for selecting appropriate visual levers.

Arguments:
- componentType: Type of component
- priorityLevel: critical | high | medium | low

`migration-guide`

Guide for migrating to Cisco design system.

Arguments:
- migrationScope: single-component | feature | application-wide

Examples

Example 1: Validate a Button Component

const buttonCode = `
export const PrimaryButton = ({ children, onClick }) => {
  return (
    <button
      className="glow-element sheen-cyan-dark"
      onClick={onClick}
    >
      {children}
    </button>
  );
};
`;

// Use validate-visual-levers tool
// Result: Validation passes with suggestions for ARIA labels

Example 2: Generate an Alert Card

// Use generate-cisco-component tool
{
  componentName: "CriticalAlert",
  componentType: "alert",
  visualLevers: { glass: true, glow: true, sheen: true },
  designPrinciple: "signal-with-intent"
}

// Generates: Complete AlertCard with all three levers,
// action buttons, accessibility features, tests, and docs

Example 3: Get Improvement Suggestions

const oldCode = `
const Card = () => (
  <div style={{
    background: '#1a1a1a',
    padding: '20px',
    color: '#ff0000'
  }}>
    Content
  </div>
);
`;

// Use suggest-design-improvements tool
// Result: Recommendations to use Glass, design tokens, and proper spacing

Example 4: Real-World Dashboard Component

// Ask Claude:
// "Please analyze this dashboard metrics card and make it compliant with Cisco design standards"

const MetricsCard = () => (
  <div className="metrics-card" style={{
    background: 'linear-gradient(135deg, #1e1e2e 0%, #2a2d3a 100%)',
    border: '2px solid #444',
    borderRadius: '12px',
    padding: '24px',
    margin: '16px',
    boxShadow: '0 8px 24px rgba(0,0,0,0.3)',
  }}>
    <h3 style={{ color: '#ff6b9d', fontSize: '18px', fontWeight: 600 }}>
      Network Security Status
    </h3>
    <div style={{ color: '#fff', fontSize: '32px', fontWeight: 700 }}>
      99.2%
    </div>
    <div style={{ color: '#888', fontSize: '14px' }}>
      Systems Protected
    </div>
  </div>
);

// Expected improvements from Claude:
// 1. Replace hardcoded colors with design tokens
// 2. Apply Glass visual lever for dashboard context
// 3. Add Glow accent for the critical metric
// 4. Improve accessibility with proper ARIA labels
// 5. Use consistent spacing tokens
// 6. Add semantic HTML structure

Example 5: AI Assistant Interface Component

// Ask Claude:
// "Generate an AI assistant chat interface component following Cisco design principles"

// Claude will generate a component that:
// - Uses Glass for the chat container (clarity/transparency)
// - Applies Glow for user messages (energy/interaction)
// - Uses Sheen for system responses (authority/confidence)
// - Implements "Design for Flex" with responsive layout
// - Follows "Signal with Intent" with clear action buttons
// - Ensures "Inspire Confidence" with loading states

Example 6: Form Validation Component

// Real scenario: Legacy form needs Cisco design compliance
const LegacyForm = () => (
  <form style={{ padding: '20px', background: '#f5f5f5' }}>
    <input
      type="email"
      placeholder="Email"
      style={{ border: '1px solid #ccc', padding: '10px', marginBottom: '10px' }}
    />
    <button
      type="submit"
      style={{ background: '#007ACC', color: 'white', padding: '12px 20px' }}
    >
      Submit
    </button>
    <div style={{ color: '#red', fontSize: '12px' }}>
      Email is required
    </div>
  </form>
);

// Ask Claude: "Please migrate this form to Cisco design standards with proper error handling"
// Results in: Glass form container, Glow error states, Sheen success states, full accessibility

Development

Run in Development Mode

npm run dev

Run Tests

npm test

Test with MCP Inspector

npm run inspector

Opens interactive UI for testing server tools and resources.

Architecture

cisco-design-mcp/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── resources/            # Design documentation
│   │   └── index.ts         # Resource registration
│   ├── tools/               # Validation & generation
│   │   ├── index.ts        # Tool registration
│   │   ├── validators.ts   # Validation logic
│   │   ├── generator.ts    # Component generation
│   │   └── advisor.ts      # Improvement suggestions
│   ├── prompts/            # Guided workflows
│   │   └── index.ts       # Prompt registration
│   └── config/            # Configuration
├── data/                  # Extracted design system data
│   ├── levers/           # Glass, Glow, Sheen specs
│   ├── principles/       # Design principles
│   ├── components/       # Component patterns
│   └── tokens/           # Design tokens
├── tests/                # Test files
└── docker/               # Container configuration

Design System Content

The server exposes the complete Cisco One Design Field Kit including:

3 Visual Levers: Glass, Glow, Sheen
3 Design Principles: Signal with Intent, Inspire Confidence, Design for Flex
Complete Component Library: Alert cards, buttons, modals, AI assistants, etc.
Advanced Patterns: Combined lever applications, progressive disclosure, etc.
Design Tokens: Colors, spacing, typography, borders, shadows
Accessibility Guidelines: WCAG compliance specific to visual levers
Implementation Examples: React, Vue, Angular patterns

Roadmap

Phase 1: Foundation ✅

Phase 2: Team Infrastructure (In Progress)

HTTP server deployment
Docker containerization
CI/CD integration
Team configuration system

Phase 3: Enterprise Platform

Phase 4: Advanced Features

AI-enhanced code generation
Design evolution tracking
Performance impact analysis
Predictive design guidance

Contributing

Internal Cisco Contributors

Fork the repository
Create a feature branch
Make your changes
Run tests and validation
Submit a pull request

Reporting Issues

Report issues through Cisco internal channels:

Jira: DESIGN project
Slack: #design-systems

Support

Documentation: See docs/ directory
Examples: See examples/ directory
FAQs: See docs/FAQ.md
Team Contact: design-systems@cisco.com

License

Proprietary - Cisco Internal Use Only

Version: 1.0.0 Last Updated: 2025-11-10 Maintained By: Cisco Design Systems Team

copresto/Cisco-One-Design-Field-Kit-MCP-Server