@atomixstudio/mcp 0.1.0 → 1.0.0

package/README.md

@@ -1,325 +1,109 @@
 # @atomixstudio/mcp
 
-MCP (Model Context Protocol) server for the Atomix Design System.
+MCP (Model Context Protocol) server for Atomix Design System. Query your design tokens directly from AI coding tools like Cursor, Claude Desktop, Windsurf, and more.
 
-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
+## Installation
 
 ```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:
-
+npm install -g @atomixstudio/mcp
+# or use directly with npx
+npx @atomixstudio/mcp --ds-id <your-ds-id> --api-key <your-api-key>
 ```
-# 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" })
+## Getting Your Credentials
 
-# Get a setup guide
-getAIToolSetupGuide({ projectName: "My App" })
-```
+1. Go to [Atomix Studio](https://atomixstudio.eu)
+2. Sign in and access your design system
+3. Click **Export** → Generate API Key
+4. Your `ds-id` is in the URL: `atomixstudio.eu/ds/[ds-id]`
 
-## Available Tools
+## Quick Setup
 
-### `getToken`
+### Cursor IDE
 
-Get a specific token by its path.
+Create `.cursor/mcp.json` in your project root:
 
-```
-getToken("colors.static.brand.primary")
-→ { 
-    path, 
-    value, 
-    cssVariable, 
-    tier: "primitive" | "semantic",
-    mutable: boolean,
-    guidance: "...",
-    usage 
+```json
+{
+  "mcpServers": {
+    "my-design-system": {
+      "command": "npx",
+      "args": ["@atomixstudio/mcp@latest", "--ds-id", "<your-ds-id>", "--api-key", "<your-api-key>"]
+    }
   }
+}
 ```
 
-### `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" })
-```
+### Claude Desktop
 
-### `validateUsage`
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
-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
+```json
+{
+  "mcpServers": {
+    "my-design-system": {
+      "command": "npx",
+      "args": ["@atomixstudio/mcp@latest", "--ds-id", "<your-ds-id>", "--api-key", "<your-api-key>"]
+    }
+  }
+}
 ```
 
-## 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)
+### Windsurf
 
-| 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 |
+Create `.windsurf/mcp.json` in your project root (same format as Cursor).
 
-## Architecture
+## Available Tools
 
-```
-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
-```
+Once connected, AI tools can use these MCP tools:
 
-## How It Works
+| Tool | Description |
+|------|-------------|
+| `getToken(path)` | Get a specific token by path (e.g., `colors.brand.primary`) |
+| `listTokens(category)` | List all tokens in a category |
+| `searchTokens(query)` | Search tokens by name or value |
+| `validateUsage(value)` | Check if a hardcoded value should use a token |
+| `getAIToolRules(tool)` | Generate AI coding rules for your design system |
+| `exportMCPConfig(tool)` | Get MCP configuration for different tools |
+| `getSetupInstructions(tool)` | Get detailed setup guide |
 
-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 Categories
 
-## Token Path Format
+- **colors** — Brand, background, text, icon, border, action, feedback colors
+- **typography** — Font families, sizes, weights, line heights
+- **spacing** — Scale tokens (xs, sm, md, lg, xl, etc.)
+- **sizing** — Component heights, icon sizes
+- **shadows** — Elevation scale
+- **radius** — Border radius scale
+- **borders** — Border width tokens
+- **motion** — Duration and easing tokens
+- **zIndex** — Layer tokens
 
-Tokens use dot notation:
+## Example Usage
 
-| 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 |
+After setup, ask your AI tool:
 
-## CSS Variable Mapping
+> "What color tokens are available in my design system?"
 
-Token paths map to CSS variables:
+> "Use the correct spacing token for 16px padding"
 
-```
-colors.static.brand.primary → --atomix-colors-static-brand-primary
-spacing.scale.md → --atomix-spacing-scale-md
-```
+> "Validate this: style={{ backgroundColor: '#007061' }}"
 
-Semantic aliases are also available:
+## CLI Options
 
-```
---atomix-brand (alias for colors.static.brand.primary)
---atomix-bg-surface (alias for colors.modes.{mode}.bgSurface)
-```
-
-## Multi-Tenant Support (Future)
+| Option | Description |
+|--------|-------------|
+| `--ds-id` | Your design system ID (required) |
+| `--api-key` | Your API key for authentication |
+| `--api-base` | API base URL (default: https://atomixstudio.eu) |
 
-The MCP server is prepared for multi-tenant operation:
+## Links
 
-```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
-```
+- [Atomix Studio](https://atomixstudio.eu)
+- [Documentation](https://atomixstudio.eu/docs)
+- [MCP Protocol](https://modelcontextprotocol.io)
 
-## Changelog
+## License
 
-### 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
+MIT
 
-### v0.1.0
-- Initial MCP server with token querying
-- Component token mappings
-- `.cursorrules` generation

package/dist/index.d.ts

@@ -1,202 +1,2 @@
-/**
- * User Tokens Fetcher
- * -------------------
- * Fetches user-specific design system tokens from Atomix API.
- *
- * Used when MCP server is run with --ds-id flag to serve a user's
- * custom design system instead of Atomix's internal tokens.
- */
-interface UserDesignSystem {
-    id: string;
-    name: string;
-    tokens: Record<string, unknown>;
-    governance?: {
-        rules: string[];
-        categories?: Record<string, string[]>;
-    };
-}
-interface FetchUserDSOptions {
-    /** User's design system ID */
-    dsId: string;
-    /** API key for authentication */
-    apiKey?: string;
-    /** Base URL for the Atomix API (default: https://atomix.design) */
-    baseUrl?: string;
-}
-interface UserDSMeta {
-    id: string;
-    name: string;
-    publishedAt?: number;
-    updatedAt?: number;
-    version?: number;
-}
-interface UserDSResponse {
-    success: boolean;
-    tokens?: Record<string, unknown>;
-    governance?: UserDesignSystem['governance'];
-    meta?: UserDSMeta;
-    error?: string;
-}
-/**
- * Fetch user's design system tokens from Atomix API
- *
- * @param options - Fetch options including dsId and apiKey
- * @returns User's tokens and governance rules
- *
- * @example
- * ```ts
- * const { tokens, governance } = await fetchUserDesignSystem({
- *   dsId: 'abc123',
- *   apiKey: 'user-api-key'
- * });
- * ```
- */
-declare function fetchUserDesignSystem(options: FetchUserDSOptions): Promise<UserDSResponse>;
-interface CLIArgs {
-    /** User's design system ID */
-    dsId?: string;
-    /** API key for authentication */
-    apiKey?: string;
-    /** Tenant ID (legacy, mapped to dsId) */
-    tenant?: string;
-    /** Base URL for the Atomix API */
-    baseUrl?: string;
-}
-/**
- * Parse command line arguments for user DS mode
- *
- * Supported args:
- * - --ds-id <id>: User's design system ID
- * - --api-key <key>: API key for authentication
- * - --tenant <id>: Legacy tenant ID (mapped to dsId)
- * - --base-url <url>: Custom API base URL
- *
- * @param argv - Command line arguments (default: process.argv)
- * @returns Parsed CLI arguments
- */
-declare function parseCLIArgs(argv?: string[]): CLIArgs;
-/**
- * Check if CLI args indicate user DS mode
- */
-declare function isUserDSMode(args: CLIArgs): boolean;
-/**
- * Transform user DS tokens to match the structure expected by MCP server.
- *
- * User DS tokens come in the StoredDesignSystem format from InstantDB.
- * This transforms them to the flat primitives structure used by MCP tools.
- *
- * @param userTokens - User's tokens from InstantDB
- * @returns Tokens in MCP-compatible format
- */
-declare function transformUserTokens(userTokens: Record<string, unknown>): Record<string, unknown>;
 
-/**
- * AI Rules Generator
- *
- * Generates project-specific rules and MCP configurations for AI coding tools
- * using the Atomix design system.
- *
- * SUPPORTED MCP CLIENTS (from modelcontextprotocol.io/clients):
- *
- * IDE/Editors:
- * - Cursor (.cursorrules)
- * - VS Code + GitHub Copilot (.github/copilot-instructions.md)
- * - Windsurf (.windsurfrules)
- * - Zed (MCP native)
- * - Continue (.continuerules)
- * - Cline (.clinerules)
- * - CodeGPT (MCP native)
- * - Amazon Q IDE (MCP native)
- * - Augment Code (MCP native)
- * - VT Code (MCP native)
- *
- * Desktop Apps:
- * - Claude Desktop (MCP native)
- * - BoltAI (MCP native)
- * - Chatbox (MCP native)
- * - ChatGPT (MCP native)
- *
- * CLI/Terminal:
- * - Warp (.warp/workflows or MCP)
- * - Amazon Q CLI (MCP native)
- * - goose (MCP native)
- *
- * Frameworks/Libraries:
- * - Genkit (MCP native)
- * - LangChain (MCP native)
- * - fast-agent (MCP native)
- */
-type AIToolId = "cursor" | "copilot" | "windsurf" | "cline" | "continue" | "zed" | "claude-desktop" | "generic";
-interface AIToolConfig {
-    id: AIToolId;
-    name: string;
-    rulesFilename: string;
-    rulesPath: string;
-    mcpConfigPath?: string;
-    supportsMarkdown: boolean;
-    supportsMCP: boolean;
-    description: string;
-}
-/**
- * Registry of supported AI coding tools and their rules file conventions
- */
-declare const AI_TOOLS: Record<AIToolId, AIToolConfig>;
-type MCPConfigToolId = "cursor" | "claude-desktop" | "windsurf" | "continue" | "vscode";
-interface MCPConfigOptions {
-    /** Path to the MCP server (default: npx @atomixstudio/mcp) */
-    serverPath?: string;
-    /** Use npx to run the server */
-    useNpx?: boolean;
-    /** Design system ID for per-user MCP mode */
-    dsId?: string;
-    /** API key for authentication (required for per-user mode) */
-    apiKey?: string;
-    /** @deprecated Use dsId instead. Tenant ID for backwards compatibility */
-    tenantId?: string;
-    /** Project name for identification */
-    projectName?: string;
-}
-interface MCPConfig {
-    tool: MCPConfigToolId;
-    filename: string;
-    path: string;
-    content: string;
-    instructions: string;
-}
-/**
- * Generate MCP configuration file for a specific AI tool
- */
-declare function generateMCPConfig(tool: MCPConfigToolId, options?: MCPConfigOptions): MCPConfig;
-/**
- * Generate MCP configs for all supported tools
- */
-declare function generateAllMCPConfigs(options?: MCPConfigOptions): MCPConfig[];
-/**
- * Get detailed setup instructions for a specific AI tool
- */
-declare function getSetupInstructions(toolId: AIToolId): string;
-declare function generateCursorRules(projectName: string, strict: boolean): string;
-interface GeneratedRulesFile {
-    tool: AIToolConfig;
-    filename: string;
-    path: string;
-    content: string;
-}
-/**
- * Generate rules for a specific AI tool
- */
-declare function generateRulesForTool(toolId: AIToolId, projectName: string, strict: boolean): GeneratedRulesFile;
-/**
- * Generate rules for ALL supported AI tools at once
- */
-declare function generateRulesForAllTools(projectName: string, strict: boolean): GeneratedRulesFile[];
-/**
- * Get list of all supported AI tools
- */
-declare function getSupportedAITools(): AIToolConfig[];
-/**
- * Generate a summary of which files to create for full AI tool support
- */
-declare function generateToolSetupGuide(projectName: string): string;
-
-export { type AIToolId, AI_TOOLS, type MCPConfigToolId, fetchUserDesignSystem, generateAllMCPConfigs, generateCursorRules, generateMCPConfig, generateRulesForAllTools, generateRulesForTool, generateToolSetupGuide, getSetupInstructions, getSupportedAITools, isUserDSMode, parseCLIArgs, transformUserTokens };
+export {  }