@spaced-out/ui-design-system 0.5.34-beta.2 → 0.5.35

package/mcp/README.md

@@ -1,526 +1,60 @@
-# Genesis UI Design System MCP Server
+# Genesis MCP Server
 
-A Model Context Protocol (MCP) server that provides AI assistants (Claude, Cursor, etc.) with access to the Genesis UI Design System.
+MCP server for AI assistants to access the Genesis UI Design System.
 
-## ✨ Features
+## Quick Setup
 
-- 📦 **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
+### Cursor / Claude Desktop
 
-## 🎯 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
-
-⚠️ **macOS Users**: Cursor may not find `npx` in its PATH. Use the full path instead.
-
-1. Find your `npx` path in terminal:
-
-```bash
-which npx
-```
-
-2. Add to your Cursor MCP settings with the **full path**:
-
-```json
-{
-  "mcpServers": {
-    "genesis-design-system": {
-      "command": "/opt/homebrew/bin/npx",
-      "args": ["-y", "@spaced-out/genesis-mcp-server@latest"]
-    }
-  }
-}
-```
-
-**Common npx locations:**
-
-- Apple Silicon Mac (Homebrew): `/opt/homebrew/bin/npx`
-- Intel Mac (Homebrew): `/usr/local/bin/npx`
-- nvm users: `/Users/YOUR_USERNAME/.nvm/versions/node/vX.X.X/bin/npx`
-
-**Windows/Linux users** can typically use `"command": "npx"` directly.
-
-### With Claude Desktop
-
-⚠️ **macOS Users**: Claude Desktop may not find `npx` in its PATH. Use the full path instead.
-
-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`
-
-1. Find your `npx` path in terminal:
+1. Find your `npx` path:
 
 ```bash
 which npx
 ```
 
-2. Use the **full path** in your config:
+2. Add to MCP settings:
 
 ```json
 {
   "mcpServers": {
     "genesis-design-system": {
       "command": "/opt/homebrew/bin/npx",
-      "args": ["-y", "@spaced-out/genesis-mcp-server@latest"]
+      "args": ["-y", "@spaced-out/genesis-mcp@latest"]
     }
   }
 }
 ```
 
-**Common npx locations:**
-
-- Apple Silicon Mac (Homebrew): `/opt/homebrew/bin/npx`
-- Intel Mac (Homebrew): `/usr/local/bin/npx`
-- nvm users: `/Users/YOUR_USERNAME/.nvm/versions/node/vX.X.X/bin/npx`
-
-**Windows/Linux users** can typically use `"command": "npx"` directly.
+> Replace `/opt/homebrew/bin/npx` with your actual path from step 1.
 
-Then restart Cursor or Claude Desktop.
+3. Restart the app.
 
-## 🔧 Development
+## Available Tools
 
-### Building the Data
+| Tool                             | Description                   |
+| -------------------------------- | ----------------------------- |
+| `list_components`                | List all components           |
+| `get_component`                  | Get component details & types |
+| `search_components`              | Search by name                |
+| `list_hooks`                     | List all hooks                |
+| `get_hook`                       | Get hook details              |
+| `get_design_tokens`              | Get design tokens             |
+| `get_component_template`         | New component template        |
+| `get_css_module_guidelines`      | CSS Module patterns           |
+| `analyze_component_dependencies` | Dependency analysis           |
 
-This server extracts design system metadata at build time. To build:
+## Development
 
 ```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
+yarn build        # Generate design-system.json
+node index.js     # Test locally
 ```
 
-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
-```
-
-## 🐛 Troubleshooting
-
-### "spawn npx ENOENT" Error (macOS/Windows)
-
-**Symptoms:**
-
-- Cursor or Claude Desktop logs show `spawn npx ENOENT` error
-- MCP server fails to start with connection errors
-- Error message: `Server transport closed unexpectedly`
-
-**Cause:**
-GUI applications on macOS and Windows don't inherit your terminal's PATH environment variables, so they cannot find the `npx` command.
-
-**Solution:**
-
-1. Find your `npx` path in terminal:
-
-**macOS/Linux:**
-
-```bash
-which npx
-```
-
-**Windows (PowerShell):**
-
-```powershell
-where.exe npx
-```
-
-2. Use the **full path** in your MCP configuration instead of just `"command": "npx"`:
-
-**Example (macOS):**
-
-```json
-{
-  "mcpServers": {
-    "genesis-design-system": {
-      "command": "/opt/homebrew/bin/npx",
-      "args": ["-y", "@spaced-out/genesis-mcp-server@latest"]
-    }
-  }
-}
-```
-
-**Example (Windows):**
-
-```json
-{
-  "mcpServers": {
-    "genesis-design-system": {
-      "command": "C:\\Program Files\\nodejs\\npx.cmd",
-      "args": ["-y", "@spaced-out/genesis-mcp-server@latest"]
-    }
-  }
-}
-```
-
-**Common npx locations:**
-
-**macOS:**
-
-- Homebrew (Apple Silicon): `/opt/homebrew/bin/npx`
-- Homebrew (Intel): `/usr/local/bin/npx`
-- nvm: `/Users/YOUR_USERNAME/.nvm/versions/node/vX.X.X/bin/npx`
-
-**Windows:**
-
-- Default Node.js: `C:\Program Files\nodejs\npx.cmd`
-- nvm-windows: `C:\Users\YOUR_USERNAME\AppData\Roaming\nvm\vX.X.X\npx.cmd`
-
-**Linux:**
-
-- Most distributions: `/usr/bin/npx` or `/usr/local/bin/npx`
-
-3. Restart your AI assistant (Cursor or Claude Desktop)
-
-**Verify the fix:**
-After restarting, check the application logs. You should see successful initialization:
-
-```
-✅ Loaded Genesis design system data
-   Version: X.X.X
-   Components: XX
-   Hooks: XX
-```
-
-Instead of `ENOENT` errors.
-
-### MCP Inspector (Advanced Debugging)
-
-If you're still having issues, use the MCP Inspector to debug:
-
-```bash
-npx @modelcontextprotocol/inspector
-```
-
-Navigate to `http://127.0.0.1:6274` and configure:
-
-- **Transport type:** Stdio
-- **Command:** Your full npx path (e.g., `/opt/homebrew/bin/npx`)
-- **Arguments:** `-y @spaced-out/genesis-mcp-server@latest`
-
-Click **Connect** to test the connection. If it fails, check the terminal logs for detailed error messages.
-
-### Test the Server Directly
-
-Test if the server runs correctly in your terminal:
-
-```bash
-npx -y @spaced-out/genesis-mcp-server@latest
-```
-
-You should see:
-
-```
-✅ Loaded Genesis design system data
-   Version: X.X.X
-   Components: XX
-   Hooks: XX
-   Built: YYYY-MM-DD
-```
-
-If this fails, there may be an issue with the published package.
-
-### Package Not Found
-
-**Error:** `npm ERR! 404 '@spaced-out/genesis-mcp-server@latest' is not in this registry`
-
-**Solution:**
-
-- Verify the package is published: `npm view @spaced-out/genesis-mcp-server`
-- If using a private registry, ensure you're authenticated
-- Check your npm registry configuration: `npm config get registry`
-
-### Node.js Version
-
-**Error:** `The engine "node" is incompatible with this module`
-
-**Solution:**
-This server requires Node.js >= 18.0.0. Update your Node.js installation:
-
-```bash
-node --version  # Check current version
-```
-
-Use [nvm](https://github.com/nvm-sh/nvm) or download from [nodejs.org](https://nodejs.org/).
-
-## 🤝 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`)
-
-## 🎨 Integration with Figma MCP
-
-The Genesis MCP server works seamlessly alongside the Figma MCP server, enabling a powerful design-to-code workflow. By using both servers together, you can bridge design and implementation.
-
-### Why Use Both?
-
-**Figma MCP** provides:
-
-- Design screenshots and visual context
-- Component properties and variants from Figma
-- Design tokens and variables from Figma files
-- Layout measurements and spacing
-
-**Genesis MCP** provides:
-
-- Actual React component implementations
-- Design system tokens and guidelines
-- TypeScript types and APIs
-- CSS Module styling patterns
-
-Together, they create a complete workflow: **Design in Figma → Implement with Genesis**
-
-### Configuration Examples
-
-You can run multiple MCP servers simultaneously:
-
-**VS Code/Cursor:**
-
-```json
-{
-  "mcpServers": {
-    "genesis-design-system": {
-      "command": "/opt/homebrew/bin/npx",
-      "args": ["-y", "@spaced-out/genesis-mcp-server@latest"]
-    },
-    "figma-desktop": {
-      "command": "/opt/homebrew/bin/npx",
-      "args": ["-y", "@modelcontextprotocol/server-figma"]
-    }
-  }
-}
-```
-
-**Claude Desktop:**
-
-```json
-{
-  "mcpServers": {
-    "genesis-design-system": {
-      "command": "/opt/homebrew/bin/npx",
-      "args": ["-y", "@spaced-out/genesis-mcp-server@latest"]
-    },
-    "figma-desktop": {
-      "command": "/opt/homebrew/bin/npx",
-      "args": ["-y", "@modelcontextprotocol/server-figma"]
-    }
-  }
-}
-```
-
-### Workflow Examples
-
-**Design-to-Code:**
-
-```
-"Show me the current Figma selection"
-"Find the matching Genesis component for this design"
-"Implement this Figma button using Genesis Button component"
-```
-
-**Token Mapping:**
-
-```
-"Compare Figma colors with Genesis color tokens"
-"What Genesis spacing token matches this 16px gap?"
-"Map this Figma shadow to Genesis elevation tokens"
-```
-
-**Validation:**
-
-```
-"Does Genesis have a component matching this Figma design?"
-"Are these Figma colors available in Genesis palette?"
-"What Genesis components would I need for this Figma screen?"
-```
-
-### Requirements
-
-- **Figma MCP**: Figma Desktop app running with design files open
-- **Genesis MCP**: Node.js >= 18.0.0
-
-See [Figma MCP documentation](https://modelcontextprotocol.io/docs/tools/figma) for Figma setup details.
-
-## 📚 Additional Resources
-
-- [MCP Documentation](https://modelcontextprotocol.io)
-- [Figma MCP Documentation](https://modelcontextprotocol.io/docs/tools/figma)
-- [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
-- [Genesis Storybook MCP Guide](https://your-storybook-url.com/?path=/docs/model-context-protocol--docs)
-
-## 📄 License
+## Troubleshooting
 
-UNLICENSED - Internal use only
+**"spawn npx ENOENT"**: Use full path to `npx` (see setup above).
 
----
+**Package not found**: Run `npm view @spaced-out/genesis-mcp` to verify.
 
-**Built with ❤️ by the Central UI team**
+**Node version**: Requires Node.js >= 18.0.0