@atomixstudio/mcp 0.1.0

package/README.md

@@ -0,0 +1,325 @@
+# @atomixstudio/mcp
+
+MCP (Model Context Protocol) server for the Atomix Design System.
+
+Enables AI coding tools to consume and query design tokens — works with **Cursor, GitHub Copilot, Windsurf, Cline, Claude, Zed**, and more.
+
+## Supported AI Coding Tools
+
+| Tool | Rules File | MCP Support |
+|------|-----------|-------------|
+| Cursor | `.cursorrules` | Native |
+| GitHub Copilot | `.github/copilot-instructions.md` | Via MCP extension |
+| Windsurf | `.windsurfrules` | Native |
+| Cline | `.clinerules` | Native |
+| Continue | `.continuerules` | Native |
+| Zed | `.zed/assistant/rules.md` | Native |
+| Claude Desktop | MCP config | Native |
+| VS Code + Extensions | Various | Via MCP |
+| Amazon Q IDE | MCP config | Native |
+| Warp | MCP config | Native |
+| ChatGPT | MCP config | Native |
+
+## Quick Start
+
+```bash
+# Install dependencies
+cd packages/atomix-mcp
+npm install
+
+# Build the server
+npm run build
+
+# Test locally
+npm start
+```
+
+## AI Tool Integration
+
+### Cursor Integration
+
+The server is pre-configured in `.cursor/mcp.json`. After building, restart Cursor to enable the MCP server.
+
+### Other Tools
+
+Generate rules for any supported tool:
+
+```
+# Generate rules for a specific tool
+getAIToolRules({ tool: "copilot", projectName: "My App", strict: true })
+
+# Generate rules for ALL tools at once
+getAIToolRules({ tool: "all", projectName: "My App" })
+
+# Get a setup guide
+getAIToolSetupGuide({ projectName: "My App" })
+```
+
+## Available Tools
+
+### `getToken`
+
+Get a specific token by its path.
+
+```
+getToken("colors.static.brand.primary")
+→ { 
+    path, 
+    value, 
+    cssVariable, 
+    tier: "primitive" | "semantic",
+    mutable: boolean,
+    guidance: "...",
+    usage 
+  }
+```
+
+### `listTokens`
+
+List all tokens in a category (filters by tier).
+
+```
+listTokens("colors")
+listTokens("colors", { tier: "semantic" })
+listTokens("spacing", { subcategory: "scale" })
+```
+
+### `getComponentTokens`
+
+Get tokens for a specific component.
+
+```
+getComponentTokens("button")
+getComponentTokens("button", { variant: "primary", size: "md" })
+```
+
+### `validateUsage`
+
+Check if a value follows the design system.
+
+```
+validateUsage("#ff0000")
+→ { valid: false, issue: "Hardcoded hex color", suggestion: "Use token..." }
+```
+
+### `searchTokens`
+
+Search for tokens by name or value.
+
+```
+searchTokens("brand")
+→ Matches: colors.static.brand.primary, colors.static.brand.primaryLight, ...
+```
+
+### `getAIToolRules` ⭐ NEW
+
+Generate design system rules for any supported AI coding tool.
+
+```
+getAIToolRules({ tool: "cursor", projectName: "My App", strict: true })
+getAIToolRules({ tool: "copilot", projectName: "My App" })
+getAIToolRules({ tool: "all", projectName: "My App" })  // All tools at once
+```
+
+### `listAITools`
+
+List all supported AI coding tools.
+
+```
+listAITools()
+→ { count: 7, tools: [{ id, name, rulesFile, description }, ...] }
+```
+
+### `getAIToolSetupGuide`
+
+Get a complete setup guide for integrating Atomix with AI tools.
+
+```
+getAIToolSetupGuide({ projectName: "My App" })
+→ Full markdown setup guide
+```
+
+### `exportMCPConfig` ⭐ NEW
+
+Generate MCP configuration files for AI tools.
+
+```
+exportMCPConfig({ tool: "cursor" })
+→ { path: ".cursor/mcp.json", content: "...", instructions: "..." }
+
+exportMCPConfig({ tool: "claude-desktop" })
+→ { path: "~/Library/Application Support/Claude/claude_desktop_config.json", ... }
+
+exportMCPConfig({ tool: "all" })
+→ Configs for all 5 supported MCP tools
+```
+
+**Supported MCP tools**: cursor, claude-desktop, windsurf, continue, vscode
+
+### `getSetupInstructions` ⭐ NEW
+
+Get detailed step-by-step setup instructions for a specific AI tool.
+
+```
+getSetupInstructions({ tool: "cursor" })
+→ Complete setup guide with MCP config, verification steps, etc.
+
+getSetupInstructions({ tool: "copilot" })
+→ Instructions for GitHub Copilot (uses rules file, not MCP)
+```
+
+### `generateCursorRules` (deprecated)
+
+Use `getAIToolRules({ tool: "cursor" })` instead.
+
+## Token Tier System
+
+Atomix uses a 3-tier token hierarchy:
+
+| Tier | Mutable | Purpose | AI Usage |
+|------|---------|---------|----------|
+| **Primitive** | No | Raw values (hex colors, px values) | Read-only reference |
+| **Semantic** | Yes | Purpose-driven tokens | Primary API for styling |
+| **Component** | Yes | Component-specific assignments | Via Designer UI |
+
+**Rule**: AI tools should use **semantic tokens** (Tier 2) in generated code, never primitives directly.
+
+## Resources
+
+The server exposes token data as MCP resources:
+
+- `atomix://tokens/all` — Complete token reference
+- `atomix://tokens/colors` — Color tokens
+- `atomix://tokens/typography` — Typography tokens
+- `atomix://tokens/spacing` — Spacing tokens
+- `atomix://components` — Component token mappings
+
+## Development
+
+```bash
+# Watch mode
+npm run dev
+
+# Build
+npm run build
+
+# Sync component tokens from Atomix Lab
+npm run sync
+
+# Run tests
+npm test
+
+# Run stress tests (all 10 scenarios)
+npm run test:stress
+
+# Run specific stress test scenario
+npm run test:scenario -- 5
+```
+
+## Stress Test Scenarios
+
+The stress test suite validates multi-tenant scenarios and the build/sync pipeline:
+
+| # | Scenario | What It Tests |
+|---|----------|---------------|
+| 1 | Brand Color Override Storm | Rapid consecutive saves, tenant-specific tokens |
+| 2 | New Variant Hot-Add | Dynamic variant discovery without code changes |
+| 3 | Size Matrix Explosion | Token lookup performance at scale (1000 lookups) |
+| 4 | Cross-Component Cascade | Shared base components, typography inheritance |
+| 5 | Concurrent Multi-Tenant Saves | Race conditions, tenant isolation (gap identified) |
+| 6 | Primitive Token Drift | Invalid/renamed token detection |
+| 7 | Breaking Change Detection | Variant removal warnings (gap identified) |
+| 8 | Locked Token Enforcement | Token mutability rules (gap identified) |
+| 9 | AI Tool Rules Generation | Rules generator performance for 350 projects |
+| 10 | Hot Reload Chain Reaction | Rapid saves, final state consistency |
+
+### Known Gaps (Identified by Tests)
+
+| Gap | Priority | Description |
+|-----|----------|-------------|
+| Multi-tenant isolation | P1 | Separate storage per tenant not yet implemented |
+| Breaking change detection | P2 | No diff comparison when variants are removed |
+| Locked token enforcement | P2 | No API validation for immutable tokens |
+
+## Architecture
+
+```
+packages/atomix-mcp/
+├── src/
+│   ├── index.ts              # MCP server entry point
+│   ├── tokens.ts             # Re-exports @atomix/tokens
+│   ├── utils.ts              # Token traversal utilities
+│   ├── component-tokens.ts   # Component → token mappings (auto-generated)
+│   ├── ai-rules-generator.ts # AI tool rules & MCP config generator
+│   └── tenant-store.ts       # Multi-tenant storage
+├── scripts/
+│   └── sync-component-tokens.cjs  # Sync from Atomix Lab
+├── data/
+│   ├── tenants/              # Per-tenant configurations
+│   └── component-tokens-snapshot.json  # Breaking change detection
+├── tests/
+│   └── stress-test.cjs       # Multi-tenant stress tests
+├── package.json
+└── tsconfig.json
+```
+
+## How It Works
+
+1. AI tool spawns the MCP server as a subprocess (via stdio)
+2. When you ask about design tokens, the AI queries the MCP server
+3. The server reads from `@atomix/tokens` primitives and `token-map.json`
+4. Responses include token values, CSS variable names, tier info, and usage examples
+5. Rules files (`.cursorrules`, etc.) provide project-level guidance
+
+## Token Path Format
+
+Tokens use dot notation:
+
+| Path | Tier | Description |
+|------|------|-------------|
+| `colors.scales.green.500` | Primitive | Raw green color |
+| `colors.modes.light.bgSurface` | Semantic | Light mode surface background |
+| `spacing.scale.md` | Primitive | Medium spacing value |
+| `typography.fontSize.sm` | Primitive | Small font size |
+| `radius.semantic.button` | Semantic | Button border radius |
+
+## CSS Variable Mapping
+
+Token paths map to CSS variables:
+
+```
+colors.static.brand.primary → --atomix-colors-static-brand-primary
+spacing.scale.md → --atomix-spacing-scale-md
+```
+
+Semantic aliases are also available:
+
+```
+--atomix-brand (alias for colors.static.brand.primary)
+--atomix-bg-surface (alias for colors.modes.{mode}.bgSurface)
+```
+
+## Multi-Tenant Support (Future)
+
+The MCP server is prepared for multi-tenant operation:
+
+```bash
+# Use tenant-specific tokens
+ATOMIX_TENANT_ID=my-company npm start
+
+# Connect to Atomix Cloud (future)
+ATOMIX_CLOUD_API=https://cloud.atomix.design npm start
+```
+
+## Changelog
+
+### v0.2.0
+- Added multi-tool support (`getAIToolRules`, `listAITools`, `getAIToolSetupGuide`)
+- Added token tier system (primitive vs semantic)
+- Added `tier` and `mutable` metadata to token responses
+- Prepared for multi-tenant support
+
+### v0.1.0
+- Initial MCP server with token querying
+- Component token mappings
+- `.cursorrules` generation