@atomixstudio/mcp 1.0.15 → 1.0.16

package/README.md

@@ -1,21 +1,6 @@
 # @atomixstudio/mcp
 
-MCP (Model Context Protocol) server and CLI for Atomix Design System. Query and sync design tokens directly from AI coding tools like Cursor, Claude Desktop, Windsurf, and more.
-
-## Quick Start (CLI)
-
-The easiest way to use Atomix is via the CLI:
-
-```bash
-# Sync tokens + AI rules (default behavior)
-npx heyatomix sync
-
-# Sync tokens only (skip AI rules)
-npx heyatomix sync --no-rules
-
-# Create config file
-npx heyatomix init
-```
+MCP (Model Context Protocol) server and CLI for Atomix Design System. Query and sync design tokens from AI coding tools (Cursor, Claude Desktop, Windsurf, etc.) or from the command line.
 
 ## Getting Your Credentials
 
@@ -24,79 +9,9 @@ npx heyatomix init
 3. Click **Publish** to make your DS available via API
 4. Your `ds-id` is in the URL: `atomixstudio.eu/ds/[ds-id]`
 
-## CLI Commands
-
-### `heyatomix sync`
-
-Sync design tokens and AI rules to your project. **Both tokens and AI guidance rules sync by default** since the rules reference tokens.
-
-```bash
-npx heyatomix sync                    # Sync tokens + AI rules
-npx heyatomix sync --no-rules         # Sync tokens only
-npx heyatomix sync -o src/tokens.css  # Custom output path
-npx heyatomix sync --format scss      # Output as SCSS
-npx heyatomix sync -y                 # Auto-confirm changes
-```
-
-**⚠️ Important: File Structure**
-
-The output file (e.g., `tokens.css`) is **completely rewritten** on each sync:
-
-- ✅ **Preserved**: CSS custom properties (variables) - both design system tokens and custom variables
-- ❌ **Lost**: Regular CSS rules (selectors, classes, media queries, etc.)
-
-**Best Practice**: Keep your tokens file separate from custom CSS. Use a separate file (e.g., `custom.css` or `styles.css`) for custom styles.
-
-### `heyatomix init`
-
-Create a `.atomixrc` config file:
-
-```bash
-npx heyatomix init
-```
-
-This creates:
-
-```json
-{
-  "dsId": "your-design-system-id",
-  "output": "./tokens.css",
-  "format": "css"
-}
-```
-
-### CLI Options
-
-| Option | Description |
-|--------|-------------|
-| `--ds-id` | Design system ID (or set in .atomixrc) |
-| `--api-key` | API key for private design systems |
-| `--output, -o` | Output file path [./tokens.css] |
-| `--format` | Output format (see below) |
-| `--no-rules` | Skip syncing AI rules (tokens + rules sync by default) |
-| `--rules-dir` | Directory for rules files [project root] |
-| `-y, --yes` | Auto-confirm changes |
-
-### Output Formats
-
-**Web:**
-- `css` — CSS custom properties (`:root { --var: value }`)
-- `scss` — CSS vars + SCSS variables (`$var: value`)
-- `less` — CSS vars + Less variables (`@var: value`)
-- `json` — Raw token JSON
-- `ts` — TypeScript with types
-- `js` — JavaScript module
-
-**Native:**
-- `swift` — Swift/SwiftUI for iOS
-- `kotlin` — Kotlin/Compose for Android
-- `dart` — Dart for Flutter
-
-All formats include **light and dark mode** values.
-
 ## MCP Server Setup
 
-For AI tools to query your design system directly:
+Connect your AI tool so it can query your design system directly.
 
 ### Cursor IDE
 
@@ -134,7 +49,7 @@ Create `.windsurf/mcp.json` in your project root (same format as Cursor).
 
 ## MCP Tools
 
-Once connected, AI tools can use these:
+Once connected, the AI can call these tools:
 
 | Tool | Description |
 |------|-------------|
@@ -146,55 +61,49 @@ Once connected, AI tools can use these:
 | `getAIToolRules(tool)` | Generate AI coding rules for your design system |
 | `exportMCPConfig(tool)` | Get MCP configuration for different tools |
 | `getSetupInstructions(tool)` | Get detailed setup guide |
-| `getDependencies(platform?, stack?)` | Get suggested dependencies (icons, fonts, SKILL.md, MCP config, tokens). Optional: `platform` (web, ios, android), `stack` (e.g. react, vue, next). Use with **--setup** prompt. |
+| `getDependencies(platform?, stack?)` | Get suggested dependencies (icons, fonts, SKILL.md, token files). Optional: `platform` (web, ios, android), `stack` (e.g. react, vue, next). Use with **/--getstarted** prompt. |
 
 ### getDependencies
 
-Returns DS-derived suggestions so the client's AI can build a "Suggested" vs "Already present" list and, after user approval, install or copy assets.
+Returns DS-derived suggestions so the AI can build a "Suggested" vs "Already present" list and, after user approval, install or copy assets.
 
-**Parameters (optional):**
-
-| Parameter | Description |
-|-----------|-------------|
-| `platform` | `web`, `ios`, or `android` |
-| `stack` | e.g. `react`, `vue`, `next`, `swift`, `kotlin` |
+**Parameters (optional):** `platform` — `web`, `ios`, or `android`; `stack` — e.g. `react`, `vue`, `next`, `swift`, `kotlin`.
 
 **Returns (JSON):**
 
-- **iconLibrary** — `package`, `nativePackage`, and a **performance hint:** use individual SVG imports for tree-shaking; avoid loading entire icon libraries or icon fonts.
-- **fonts** — Font family names from typography tokens + **performance hint:** implement self-hosted fonts and local `@font-face`; avoid external CDN links; use `font-display: swap`.
+- **iconLibrary** — `package`, `nativePackage`, and a performance hint (use individual SVG imports for tree-shaking).
+- **fonts** — Font family names from typography tokens + performance hint (self-hosted `@font-face`, `font-display: swap`).
 - **skill** — `path` (e.g. `.cursor/skills/atomix-ds/SKILL.md`) and `content` (generic, platform-agnostic SKILL.md).
-- **mcpConfig** — Path and content for MCP configuration.
-- **tokenFiles** — e.g. `["tokens.css", "tokens.json"]` with short copy instructions.
+- **tokenFiles** — e.g. `["tokens.css", "tokens.json"]` with copy instructions.
 
-If the design system or MCP is not available (e.g. no `--ds-id`), the tool may fail; the client should tell the user to configure MCP with `--ds-id` and try again.
+If the design system is unavailable, the tool may fail; the client should tell the user the design system could not be reached.
 
 ## MCP Prompts
 
-Once connected, your AI tool can run these prompts (e.g. **/--hello**, **/--setup**):
+Run these prompts from your AI tool (e.g. **/--hello**, **/--getstarted**):
 
 | Prompt | Description |
 |--------|-------------|
 | **/--hello** | Get started — overview, tokens, and tools. Run this first. |
-| **/--setup** | Setup design system in project. Three phases; creates files only after you approve. |
+| **/--getstarted** | Get started with design system in project. Three phases; creates files only after you approve. |
 | **/--rules** | Governance rules for your AI tool (Cursor, Copilot, Windsurf, etc.). |
 | **/--sync** | Sync tokens to a local file. Use **/--refactor** to migrate deprecated tokens. |
 | **/--refactor** | Migrate deprecated tokens in codebase. Run after **/--sync**. |
 
-## --setup (design system setup)
+## --getstarted (get started)
 
-The **--setup** prompt suggests dependencies for your design system so you can get up and running quickly. It does **not** install anything by default; the client's AI presents a list and asks before making changes.
+The **/--getstarted** prompt suggests dependencies for your design system so you can get up and running quickly. It does **not** install anything by default; the AI presents a list and asks before making changes.
 
 **Flow (phased instructions):**
 
 1. **Resolve platform and stack** — Infer from the project (e.g. `package.json`, `build.gradle`) or **ask the user** if the project gives no hint (e.g. blank repo). Do not assume web or any default.
-2. **Get suggested dependencies** — Call `getDependencies(platform, stack)`. If the call fails (e.g. MCP not connected or no ds-id), tell the user: "Atomix MCP is not connected or design system ID is missing. Configure MCP with --ds-id and try again."
+2. **Get suggested dependencies** — Call `getDependencies(platform, stack)`. If the call fails, tell the user the design system could not be reached and stop.
 3. **Scan codebase and build suggestion list** — Scan for `package.json` (or equivalent), existing skill path, token files, font/icon usage. Build **Suggested dependencies** (from getDependencies minus what's present) and **Already present**. Do not install or copy anything in this phase.
 4. **Present list and ask before install** — Reply with "Suggested dependencies: …" and "Already present: …" and state: "Do not install or copy anything until you confirm. Would you like me to install or add these?" Only perform steps the user approves.
 5. **Optional: suggest global styles** — If the project has no global styles that use the design system tokens, ask verbatim: "Your project doesn't appear to have global styles that use the design system tokens (e.g. semantic typography scale or semantic color classes). Would you like me to suggest or generate a minimal set (e.g. typography scale + semantic utilities) so you can develop consistently with the DS?"
-6. **Report what was created** — After any install/copy steps, list what was created or updated (e.g. "Installed: lucide-react. Added: .cursor/skills/atomix-ds/SKILL.md. Updated: .cursor/mcp.json. Copied: tokens.css.").
+6. **Report what was created** — After any install/copy steps, list what was created or updated (e.g. "Installed: lucide-react. Added: .cursor/skills/atomix-ds/SKILL.md. Synced: tokens.css.").
 
-**Single SKILL.md:** The setup flow suggests adding a generic, coding-platform agnostic SKILL at `.cursor/skills/atomix-ds/SKILL.md`. It instructs the AI to call `getAIToolRules({ tool: "<tool>" })` where `<tool>` matches the current environment (cursor, windsurf, copilot, cline, continue, zed, generic).
+**Single SKILL.md:** The getstarted flow suggests adding a generic, coding-platform agnostic SKILL at `.cursor/skills/atomix-ds/SKILL.md`. It instructs the AI to call `getAIToolRules({ tool: "<tool>" })` where `<tool>` matches the current environment (cursor, windsurf, copilot, cline, continue, zed, generic).
 
 ## Token Categories
 
@@ -208,9 +117,91 @@ The **--setup** prompt suggests dependencies for your design system so you can g
 - **motion** — Duration and easing tokens
 - **zIndex** — Layer tokens
 
-## AI Rules Files
+## Example Usage (MCP)
+
+Once MCP is connected, you can say:
+
+> "Sync my design tokens to tokens.css"
+
+> "What color tokens are available?"
+
+> "Use the correct spacing token for 16px padding"
+
+> "Validate this: style={{ backgroundColor: '#007061' }}"
+
+---
+
+## CLI
+
+Use the CLI when you prefer commands over the AI, or in scripts/CI.
+
+### Quick Start (CLI)
 
-By default, `sync` also updates AI rules files based on which AI tools you use:
+```bash
+# Sync tokens + AI rules (default behavior)
+npx heyatomix sync
+
+# Sync tokens only (skip AI rules)
+npx heyatomix sync --no-rules
+
+# Create config file
+npx heyatomix init
+```
+
+### `heyatomix sync`
+
+Sync design tokens and AI rules to your project. **Both tokens and AI guidance rules sync by default** since the rules reference tokens.
+
+```bash
+npx heyatomix sync                    # Sync tokens + AI rules
+npx heyatomix sync --no-rules         # Sync tokens only
+npx heyatomix sync -o src/tokens.css  # Custom output path
+npx heyatomix sync --format scss     # Output as SCSS
+npx heyatomix sync -y                 # Auto-confirm changes
+```
+
+**File structure:** The output file (e.g., `tokens.css`) is **completely rewritten** on each sync. Preserved: CSS custom properties (variables). Lost: regular CSS rules (selectors, classes, media queries). Keep your tokens file separate from custom CSS (e.g. use `custom.css` for custom styles).
+
+### `heyatomix init`
+
+Create a `.atomixrc` config file:
+
+```bash
+npx heyatomix init
+```
+
+Creates:
+
+```json
+{
+  "dsId": "your-design-system-id",
+  "output": "./tokens.css",
+  "format": "css"
+}
+```
+
+### CLI Options
+
+| Option | Description |
+|--------|-------------|
+| `--ds-id` | Design system ID (or set in .atomixrc) |
+| `--api-key` | API key for private design systems |
+| `--output, -o` | Output file path [./tokens.css] |
+| `--format` | Output format (see below) |
+| `--no-rules` | Skip syncing AI rules (tokens + rules sync by default) |
+| `--rules-dir` | Directory for rules files [project root] |
+| `-y, --yes` | Auto-confirm changes |
+
+### Output Formats
+
+**Web:** `css`, `scss`, `less`, `json`, `ts`, `js`  
+**Native:** `swift`, `kotlin`, `dart`
+
+All formats include **light and dark mode** values.
+
+### AI Rules Files (CLI)
+
+By default, `sync` also updates AI rules files:
 
 | File | AI Tool |
 |------|---------|
@@ -221,25 +212,13 @@ By default, `sync` also updates AI rules files based on which AI tools you use:
 | `.github/copilot-instructions.md` | Copilot |
 | `AI_GUIDELINES.md` | Generic |
 
-The rules include your design system's governance guidelines and token usage instructions.
-
-## Example Usage
-
-**CLI:**
+### Example Usage (CLI)
 
 ```bash
 npx heyatomix sync
 ```
 
-**Natural language (via MCP):**
-
-> "Sync my design tokens to tokens.css"
-
-> "What color tokens are available?"
-
-> "Use the correct spacing token for 16px padding"
-
-> "Validate this: style={{ backgroundColor: '#007061' }}"
+---
 
 ## Package Aliases
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atomixstudio/mcp",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "description": "MCP server for Atomix Design System - query your design foundation and tokens for AI coding tools",
   "type": "module",
   "main": "dist/index.js",