# Clone repository
git clone <repo-url>
cd design-system-mcp

# Install dependencies
npm install

# Extract component metadata (first time)
npm run extract:all

# Build
npm run build

# Test
npm run test:production

{
  "mcpServers": {
    "design-system": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/path/to/design-system-mcp/dist/index.js"]
    }
  }
}

# Design System source path (for extraction)
export DS_PATH="/Users/YOUR_USERNAME/path/to/insider-design-system"

# Analytics FE path (for usage analysis)
export ANALYTICS_FE_PATH="/Users/YOUR_USERNAME/path/to/analytics-fe"

Design System Source Code (Vue files)
         ↓ AUTOMATED EXTRACTION
data/combined.json (209 KB)
         ↓ BUILD & COPY
dist/data/combined.json
         ↓ RUNTIME LOADING
MCP Server (in-memory, enum-resolved)
         ↓ FAST QUERIES
Claude Code

# Extract all data (run when Design System changes)
npm run extract:all

# Or run individually:
npm run extract:components  # Parse Vue components → data/components.json
npm run extract:storybook   # Extract examples → data/storybook.json
npm run extract:usage       # Analyze usage → data/usage.json
npm run extract:argtypes    # Sync possibleValues from storybook argTypes
npm run extract:merge       # Merge all → data/combined.json

# Rebuild MCP server
npm run build

# In Claude Code (works in ANY project with Design System MCP!)
User: "Use optimize-prompt to transform this request: I need a button that opens a dropdown menu"

# Original Prompt
I need a button that opens a dropdown menu

# Analysis
- Language: English
- Intent: implement
- Components: InButtonV2, InDropdownMenu
- Complexity: medium
- Estimated Token Savings: ~24,000 tokens

# Optimized Prompt
I need to implement InButtonV2 and InDropdownMenu components with proper integration.

Please use the Design System MCP to:

1. Get documentation for both components
   - Tool: mcp__design-system__get-component
   - Components: InButtonV2, InDropdownMenu
   - Note: Markdown format saves ~87% tokens on average

2. Generate implementation code
   - Tool: mcp__design-system__generate-code
   - Include integration between components

Requirements:
- Primary styling for main actions
- Dropdown opens below trigger element
- Proper state management between components

Show me:
✅ Which components you're using
✅ Token savings from Markdown format for each component
✅ The generated Vue code
✅ Integration example showing how components work together

User: "Now use the optimized prompt above to implement the button + dropdown"

<template>
  <div class="button-dropdown-container">
    <InButtonV2
      id="actions-button"
      :type="TYPES.PRIMARY"
      :styling="STYLES.SOLID"
      label-text="Actions"
      @click="toggleDropdown"
    />

    <InDropdownMenu
      v-if="isOpen"
      :items="menuItems"
      @item-click="handleItemClick"
      @close="isOpen = false"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { InButtonV2, InDropdownMenu } from '@useinsider/design-system-vue';
import '@useinsider/design-system-vue/dist/design-system-vue.css';

const isOpen = ref(false);

const menuItems = [
  { id: 'export', label: 'Export Data', icon: 'download' },
  { id: 'share', label: 'Share Report', icon: 'share' },
  { id: 'settings', label: 'Settings', icon: 'settings' },
];

const toggleDropdown = () => {
  isOpen.value = !isOpen.value;
};

const handleItemClick = (item: any) => {
  console.log('Clicked:', item.id);
  isOpen.value = false;
};
</script>

User: "I need a button"

User: "Use optimize-prompt: I need a button"

// Single component
mcp__design-system__optimize-prompt("I need a button")

// Multiple components
mcp__design-system__optimize-prompt("button and dropdown menu")

// Migration task
mcp__design-system__optimize-prompt("migrate InDatePicker from V1 to V2")

// Debug issue
mcp__design-system__optimize-prompt("InSelect not working, showing errors")

// Learning
mcp__design-system__optimize-prompt("how to use InTooltipV2?")

// Claude automatically calls:
mcp__design-system__get-component("InButtonV2")

// Returns in Markdown format (88% token savings):
# InButtonV2

**Version:** v2

## Props

### `styling`
**Type:** `String` | **Default:** `"STYLES.SOLID"`

**Allowed values:** `solid`, `ghost`, `text`

### `type`
**Type:** `String` | **Default:** `"TYPES.PRIMARY"`

...

## Examples

### Basic Primary Button
```vue
<InButtonV2
  id="primary-btn"
  styling="solid"
  type="primary"
  label-text="Click Me"
/>

### Search Components

```typescript
mcp__design-system__search-components("button")
// Returns: InButton, InButtonV2, InCreateButton...

mcp__design-system__generate-code({
  component: "InButtonV2",
  props: { styling: "solid", type: "primary" }
})

// Returns:
// <InButtonV2
//   id="button-1"
//   styling="solid"
//   type="primary"
//   label-text="Button"
// />

# Test combined dataset
npm run test:data

# Test production build
npm run test:production

# Run unit tests
npm test

# Coverage
npm run test:coverage

design-system-mcp/
├── 📄 README.md                      # This file
├── 📄 COMPLETION_REPORT.md           # Full project report
├── 📄 HOW_IT_WORKS.md                # Architecture deep dive
├── 📄 CLEANUP_SUMMARY.md             # Cleanup history
├── 📦 package.json                   # Dependencies & scripts
├── 🔧 tsup.config.ts                 # Build configuration
│
├── 📂 src/                           # Source code
│   ├── index.ts                      # Entry point
│   ├── server.ts                     # MCP server
│   ├── tools/index.ts                # MCP tools
│   ├── resources/index.ts            # MCP resources
│   ├── types/index.ts                # TypeScript types
│   └── registry/
│       ├── combined-loader.ts        # ⭐ Dataset loader (NEW)
│       ├── enrichments/              # Manual enrichments
│       │   ├── InButtonV2.json
│       │   ├── InDatePickerV2.json
│       │   └── InSelect.json
│       └── migrations/               # V1→V2 guides
│           └── InDatePicker-to-V2.json
│
├── 📂 scripts/                       # Extraction scripts
│   ├── extract-components.ts         # Vue component parser
│   ├── extract-storybook.ts          # Example extractor
│   ├── extract-usage.ts              # Usage analyzer
│   └── merge-datasets.ts             # Dataset combiner
│
├── 📂 data/                          # Extracted data
│   ├── components.json               # 148 KB - Parsed components
│   ├── storybook.json                # 1.6 KB - Examples
│   ├── usage.json                    # Real usage data
│   └── combined.json                 # 209 KB - ⭐ FINAL DATASET
│
└── 📂 dist/                          # Build output
    ├── index.js                      # Bundled MCP server
    └── data/combined.json            # Runtime dataset

# 1. Pull latest Design System
cd /path/to/insider-design-system
git pull

# 2. Re-extract metadata
cd /path/to/design-system-mcp
npm run extract:all          # ~5 minutes

# 3. Rebuild MCP server
npm run build

# 4. Test
npm run test:production

# 5. Commit (optional)
git add data/combined.json
git commit -m "chore: update component metadata"
git push

# Claude Desktop will auto-reload! ✅

// Source: const STYLES = { SOLID: 'solid', GHOST: 'ghost' }
// Extracted: enums: [{ name: "STYLES", values: {...} }]
// Runtime: validValues: ["solid", "ghost", "text"] ✅

{
  "mistake": "Using number for iconSize",
  "occurrences": 12,
  "fix": "Use string: icon-size=\"24\"",
  "severity": "critical"
}

Auto-extracted (100% coverage)
    +
Manual enrichments (critical details)
    =
Best of both worlds! ✅

Components: 62 (100% coverage)
Props: 1,087 (with types, defaults, validators)
Enums: 30 (automatically detected)
Emits: 170
Manual Enrichments: 3 (InButtonV2, InDatePickerV2, InSelect)
Migration Guides: 1
File Size: 209 KB (combined.json)

# Build
npm run build              # Build for production
npm run dev                # Watch mode

# Extraction
npm run extract:components # Extract component metadata
npm run extract:storybook  # Extract examples
npm run extract:usage      # Analyze real usage
npm run extract:merge      # Merge all datasets
npm run extract:all        # Run all extractions

# Testing
npm test                   # Run unit tests
npm run test:coverage      # Coverage report
npm run test:data          # Test dataset validity
npm run test:production    # Test production build

# Code Quality
npm run lint               # Run ESLint
npm run lint:fix           # Fix linting issues
npm run typecheck          # TypeScript check

# Let AI generate enrichment for you
# In Claude Code: "Use enrichment-maker agent to create enrichment for InTooltipV2"

# Agent analyzes component and creates:
# - valueFormat for complex props
# - commonMistakes documentation
# - Real-world examples
# - Helper functions

# Then merge and build:
npm run extract:merge
npm run build

# 1. Create enrichment file
touch src/registry/enrichments/InTooltipV2.json

# 2. Add detailed metadata
# (See existing enrichments: InButtonV2, InDatePickerV2, InSelect)

# 3. Rebuild
npm run extract:merge
npm run build