@spaced-out/ui-design-system 0.5.18 → 0.5.20

package/mcp/README.md

@@ -0,0 +1,306 @@
+# Genesis UI Design System MCP Server
+
+A Model Context Protocol (MCP) server that provides AI assistants (Claude, Cursor, etc.) with access to the Genesis UI Design System.
+
+## ✨ Features
+
+- 📦 **Component Discovery**: List and search all available components
+- 🎨 **Design Tokens**: Access colors, spacing, typography, shadows, and more
+- 📚 **Documentation**: Browse component stories and TypeScript definitions
+- 🔍 **Dependency Analysis**: Understand component dependencies
+- 🚀 **Onboarding Templates**: Get starter templates for new components
+- 🪝 **Hooks Information**: Query available React hooks
+
+## 🎯 No Local Dependencies Required!
+
+Unlike traditional MCP servers that require a local copy of the design system, this server **bundles all data at build time**. Users only need to run `npx` - no cloning, no environment variables!
+
+## 📦 Installation for Users
+
+### With Cursor
+
+Add to your Cursor MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "genesis-design-system": {
+      "command": "npx",
+      "args": ["-y", "@spaced-out/genesis-mcp-server@latest"]
+    }
+  }
+}
+```
+
+### With Claude Desktop
+
+Add to your Claude config file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`  
+**Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "genesis-design-system": {
+      "command": "npx",
+      "args": ["-y", "@spaced-out/genesis-mcp-server@latest"]
+    }
+  }
+}
+```
+
+Then restart Cursor or Claude Desktop.
+
+## 💬 Usage Examples
+
+Once configured, you can ask:
+
+**Component Discovery:**
+
+```
+"List all components in Genesis"
+"Search for dropdown components"
+"Show me the Button component implementation"
+"What types does the Icon component export?"
+"Show me the Icon component with its exported types"
+```
+
+**Design Tokens:**
+
+```
+"Show me all color tokens"
+"What spacing tokens are available?"
+"List all shadow/elevation tokens"
+```
+
+**Component Onboarding:**
+
+```
+"I want to create a new Toast component, show me the template"
+"Help me onboard an Alert component"
+"What's the standard structure for a Genesis component?"
+```
+
+**Design Token Imports:**
+
+```
+"How do I import design tokens in CSS Module files?"
+"Show me the correct way to import color and spacing tokens"
+"What token files are available and how do I import them?"
+```
+
+**CSS Module Guidelines:**
+
+```
+"Show me CSS Module styling guidelines for Genesis"
+"What are the class naming conventions for CSS Modules?"
+"How should I style child elements in CSS Modules?"
+"What's the correct pattern for state-based styling in CSS?"
+"Show me common CSS mistakes to avoid"
+"How do I apply colors to child elements like text, icons, or buttons?"
+```
+
+**Dependencies:**
+
+```
+"What components does Modal depend on?"
+"Show me the dependencies of Dropdown"
+"What hooks does the Table component use?"
+```
+
+## 🔧 Development
+
+### Building the Data
+
+This server extracts design system metadata at build time. To build:
+
+```bash
+# Install dependencies
+yarn install
+
+# Build the data bundle
+yarn build
+```
+
+This creates `data/design-system.json` with all component, hook, and token information.
+
+### Testing Locally
+
+```bash
+# After building, test the server
+node index.js
+```
+
+Or test with MCP Inspector:
+
+```bash
+npx @modelcontextprotocol/inspector node index.js
+```
+
+### Publishing
+
+```bash
+# The prepublishOnly script runs yarn build automatically
+yarn publish
+```
+
+## 📊 How It Works
+
+### Build Time (CI/CD)
+
+1. `build-mcp-data.js` scans the design system:
+
+   - Reads all components from `src/components/`
+   - Reads all hooks from `src/hooks/`
+   - Reads all design tokens from `design-tokens/`
+
+2. Extracts file contents and metadata
+
+3. Bundles everything into `data/design-system.json`
+
+4. Package is published to npm with bundled data
+
+### Runtime (User's Machine)
+
+1. User runs `npx @spaced-out/genesis-mcp-server`
+
+2. Server loads pre-bundled `data/design-system.json`
+
+3. Serves data via MCP protocol (stdio)
+
+4. AI assistant queries the server for design system info
+
+**Result:** No local design system needed! ✨
+
+## 🏗️ Architecture
+
+```
+ui-design-system/
+├── src/
+│   ├── components/          # Source components
+│   └── hooks/               # Source hooks
+├── design-tokens/           # Source tokens
+└── mcp/                     # 👈 MCP Server
+    ├── index.js             # MCP server (reads from data/)
+    ├── build-mcp-data.js    # Build script (extracts from ../)
+    ├── data/
+    │   └── design-system.json  # Bundled data (git-ignored)
+    ├── package.json
+    └── README.md
+```
+
+## 📝 Available Tools
+
+The MCP server provides these tools to AI assistants:
+
+- `list_components` - List all available components
+- `get_component` - Get detailed component information **including exported types** (e.g., IconType, IconSize from Icon component)
+- `search_components` - Search components by name
+- `list_hooks` - List all available hooks
+- `get_hook` - Get detailed hook information
+- `get_design_tokens` - Get all or filtered design tokens
+- `get_component_template` - Get template for new components
+- `get_design_token_import_guidelines` - Get guidelines for importing design tokens in CSS Module files with correct paths and examples
+- `get_css_module_guidelines` - **NEW!** Get comprehensive CSS Module styling guidelines including class naming conventions (BEM patterns), token usage, icon color patterns, and common mistakes to avoid
+- `analyze_component_dependencies` - Analyze component dependencies
+
+## 🔄 CI/CD Integration
+
+### Automatic Publishing
+
+The MCP server is automatically published to npm via GitHub Actions (`.github/workflows/publish-mcp.yml`).
+
+**Triggers:**
+
+- Push to `master` branch when files change in:
+  - `src/**` (component/hook changes)
+  - `design-tokens/**` (token changes)
+  - `mcp/**` (MCP server changes)
+- Manual workflow dispatch
+
+**Process:**
+
+1. **Auto-version bump**: If `src/` or `design-tokens/` changed, automatically bumps patch version
+2. **Build**: Generates fresh MCP data bundle with latest design system changes
+3. **Commit**: Pushes version bump back to master (with `[skip ci]` to avoid loops)
+4. **Publish**: Publishes new version to npm
+
+**What this means for you:**
+
+✅ Update a component → Merge to master → New MCP version automatically published!
+
+No need to manually bump versions when changing design system files. The workflow handles it for you.
+
+### Version Management
+
+**Automatic (recommended):**
+
+- Changes to `src/` or `design-tokens/` → patch version bumped automatically
+- E.g., `1.0.5` → `1.0.6`
+
+**Manual (for major/minor releases):**
+
+```bash
+cd mcp
+yarn version --minor  # or --major
+git push --follow-tags
+```
+
+**Manual MCP-only changes:**
+
+- If you only change files in `mcp/`, manually bump the version to publish
+
+## 📈 Data Size
+
+The bundled JSON includes:
+
+- Full TypeScript component implementations
+- Storybook stories
+- CSS modules
+- Design tokens
+- Hook implementations
+
+Typical size: 5-15 MB (cached by npm, so only downloaded once)
+
+## 🔐 Private Packages
+
+If publishing to a private npm registry:
+
+```json
+{
+  "publishConfig": {
+    "registry": "https://your-private-registry.com"
+  }
+}
+```
+
+Users configure their registry:
+
+```bash
+npm config set @spaced-out:registry https://your-private-registry.com
+# or with yarn
+yarn config set registry https://your-private-registry.com
+```
+
+## 🤝 Contributing
+
+When updating the design system:
+
+1. Changes to components/hooks/tokens are automatically detected
+2. CI/CD runs `npm run build` to regenerate data
+3. New version is published to npm
+4. Users get updates on next `npx` run (or immediately with `@latest`)
+
+## 📚 Additional Resources
+
+- [MCP Documentation](https://modelcontextprotocol.io)
+
+## 📄 License
+
+UNLICENSED - Internal use only
+
+---
+
+**Built with ❤️ by the Central UI team**

package/mcp/build-mcp-data.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+
+/**
+ * Build script to extract design system metadata into JSON
+ * This runs before publishing to npm to bundle all component/token data
+ */
+
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync, mkdirSync } from 'fs';
+import { join, resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Design system is parent directory
+const DESIGN_SYSTEM_PATH = resolve(__dirname, '..');
+const OUTPUT_DIR = join(__dirname, 'data');
+const OUTPUT_FILE = join(OUTPUT_DIR, 'design-system.json');
+
+console.log('Building Genesis MCP data...\n');
+console.log(`Design System: ${DESIGN_SYSTEM_PATH}`);
+console.log(`Output: ${OUTPUT_FILE}\n`);
+
+function safeReadFile(filePath) {
+  try {
+    return readFileSync(filePath, 'utf-8');
+  } catch (error) {
+    return null;
+  }
+}
+
+function getDirectories(path) {
+  try {
+    return readdirSync(path).filter(f => {
+      const fullPath = join(path, f);
+      return statSync(fullPath).isDirectory() && !f.startsWith('.');
+    });
+  } catch (error) {
+    console.error(`❌ Error reading directories in ${path}:`, error.message);
+    return [];
+  }
+}
+
+/**
+ * Extract all components with their files
+ */
+function buildComponentsData() {
+  console.log('📦 Extracting components...');
+  const componentsPath = join(DESIGN_SYSTEM_PATH, 'src/components');
+  const components = {};
+  
+  if (!existsSync(componentsPath)) {
+    console.warn('⚠️  Components path not found');
+    return components;
+  }
+
+  const componentDirs = getDirectories(componentsPath).filter(name => name !== 'index.ts');
+  
+  for (const componentName of componentDirs) {
+    const componentDir = join(componentsPath, componentName);
+    
+    const mainTsx = join(componentDir, `${componentName}.tsx`);
+    const mainTs = join(componentDir, `${componentName}.ts`);
+    
+    const storyTsx = join(componentDir, `${componentName}.stories.tsx`);
+    const storyTs = join(componentDir, `${componentName}.stories.ts`);
+    
+    const cssFile = join(componentDir, `${componentName}.module.css`);
+    
+    const indexFile = join(componentDir, 'index.ts');
+    
+    const mainContent = safeReadFile(mainTsx) || safeReadFile(mainTs);
+    const storyContent = safeReadFile(storyTsx) || safeReadFile(storyTs);
+    const cssContent = safeReadFile(cssFile);
+    const indexContent = safeReadFile(indexFile);
+    
+    const allFiles = existsSync(componentDir) 
+      ? readdirSync(componentDir).filter(f => !f.startsWith('.'))
+      : [];
+    
+    components[componentName] = {
+      name: componentName,
+      path: `src/components/${componentName}`,
+      files: {
+        main: mainContent ? { path: `${componentName}.tsx`, content: mainContent } : null,
+        story: storyContent ? { path: `${componentName}.stories.tsx`, content: storyContent } : null,
+        css: cssContent ? { path: `${componentName}.module.css`, content: cssContent } : null,
+        index: indexContent ? { path: 'index.ts', content: indexContent } : null,
+      },
+      allFiles,
+    };
+  }
+  
+  console.log(`   ✅ Extracted ${Object.keys(components).length} components`);
+  return components;
+}
+
+/**
+ * Extract all hooks
+ */
+function buildHooksData() {
+  console.log('🪝 Extracting hooks...');
+  const hooksPath = join(DESIGN_SYSTEM_PATH, 'src/hooks');
+  const hooks = {};
+  
+  if (!existsSync(hooksPath)) {
+    console.warn('⚠️  Hooks path not found');
+    return hooks;
+  }
+
+  const hookDirs = getDirectories(hooksPath).filter(name => name !== 'index.ts');
+  
+  for (const hookName of hookDirs) {
+    const hookDir = join(hooksPath, hookName);
+    
+    // Read main hook file
+    const mainTs = join(hookDir, `${hookName}.ts`);
+    const mainTsx = join(hookDir, `${hookName}.tsx`);
+    
+    // Read story file
+    const storyTsx = join(hookDir, `${hookName}.stories.tsx`);
+    const storyTs = join(hookDir, `${hookName}.stories.ts`);
+    
+    // Read index file
+    const indexFile = join(hookDir, 'index.ts');
+    
+    const mainContent = safeReadFile(mainTs) || safeReadFile(mainTsx);
+    const storyContent = safeReadFile(storyTsx) || safeReadFile(storyTs);
+    const indexContent = safeReadFile(indexFile);
+    
+    const allFiles = existsSync(hookDir) 
+      ? readdirSync(hookDir).filter(f => !f.startsWith('.'))
+      : [];
+    
+    hooks[hookName] = {
+      name: hookName,
+      path: `src/hooks/${hookName}`,
+      files: {
+        main: mainContent ? { path: `${hookName}.ts`, content: mainContent } : null,
+        story: storyContent ? { path: `${hookName}.stories.tsx`, content: storyContent } : null,
+        index: indexContent ? { path: 'index.ts', content: indexContent } : null,
+      },
+      allFiles,
+    };
+  }
+  
+  console.log(`   ✅ Extracted ${Object.keys(hooks).length} hooks`);
+  return hooks;
+}
+
+/**
+ * Extract all design tokens
+ */
+function buildTokensData() {
+  console.log('🎨 Extracting design tokens...');
+  const tokensPath = join(DESIGN_SYSTEM_PATH, 'design-tokens');
+  const tokens = {};
+  
+  if (!existsSync(tokensPath)) {
+    console.warn('⚠️  Design tokens path not found');
+    return tokens;
+  }
+
+  const categories = getDirectories(tokensPath);
+  
+  for (const category of categories) {
+    tokens[category] = {};
+    const categoryPath = join(tokensPath, category);
+    
+    try {
+      const files = readdirSync(categoryPath).filter(f => f.endsWith('.json'));
+      
+      for (const file of files) {
+        const filePath = join(categoryPath, file);
+        try {
+          const content = readFileSync(filePath, 'utf-8');
+          const tokenData = JSON.parse(content);
+          tokens[category][file.replace('.json', '')] = tokenData;
+        } catch (error) {
+          console.warn(`   ⚠️  Error parsing ${file}:`, error.message);
+        }
+      }
+    } catch (error) {
+      console.warn(`   ⚠️  Error reading category ${category}:`, error.message);
+    }
+  }
+  
+  const tokenCount = Object.values(tokens).reduce((sum, cat) => sum + Object.keys(cat).length, 0);
+  console.log(`   ✅ Extracted ${tokenCount} token files across ${Object.keys(tokens).length} categories`);
+  return tokens;
+}
+
+/**
+ * Get package version
+ */
+function getVersion() {
+  try {
+    const pkgPath = join(DESIGN_SYSTEM_PATH, 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    return pkg.version || '0.0.0';
+  } catch (error) {
+    return '0.0.0';
+  }
+}
+
+/**
+ * Main build function
+ */
+function build() {
+  try {
+    const data = {
+      metadata: {
+        buildDate: new Date().toISOString(),
+        version: getVersion(),
+        designSystemPath: DESIGN_SYSTEM_PATH,
+      },
+      components: buildComponentsData(),
+      hooks: buildHooksData(),
+      tokens: buildTokensData(),
+    };
+
+    // Create output directory if it doesn't exist
+    if (!existsSync(OUTPUT_DIR)) {
+      mkdirSync(OUTPUT_DIR, { recursive: true });
+    }
+
+    // Write to JSON file
+    writeFileSync(OUTPUT_FILE, JSON.stringify(data, null, 2));
+
+    console.log('\n✨ Build complete!');
+    console.log(`📊 Summary:`);
+    console.log(`   - Components: ${Object.keys(data.components).length}`);
+    console.log(`   - Hooks: ${Object.keys(data.hooks).length}`);
+    console.log(`   - Token categories: ${Object.keys(data.tokens).length}`);
+    console.log(`   - Version: ${data.metadata.version}`);
+    console.log(`   - Output: ${OUTPUT_FILE}`);
+    console.log(`   - Size: ${(Buffer.byteLength(JSON.stringify(data)) / 1024 / 1024).toFixed(2)} MB\n`);
+
+  } catch (error) {
+    console.error('❌ Build failed:', error);
+    process.exit(1);
+  }
+}
+
+// Run the build
+build();
+