@atomixstudio/mcp 1.0.14 → 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,43 +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 **atomix/install**. |
+| `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.
-
-**Parameters (optional):**
+Returns DS-derived suggestions so the AI can build a "Suggested" vs "Already present" list and, after user approval, install or copy assets.
 
-| 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.
 
-## atomix/install
+## MCP Prompts
 
-The **install** 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.
+Run these prompts from your AI tool (e.g. **/--hello**, **/--getstarted**):
+
+| Prompt | Description |
+|--------|-------------|
+| **/--hello** | Get started — overview, tokens, and tools. Run this first. |
+| **/--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**. |
+
+## --getstarted (get started)
+
+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 install 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
 
@@ -196,9 +117,91 @@ The **install** 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)
+
+```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:
 
-By default, `sync` also updates AI rules files based on which AI tools you use:
+```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 |
 |------|---------|
@@ -209,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
 
@@ -237,6 +228,10 @@ npx heyatomix sync
 | `@atomixstudio/mcp` | Full MCP server + CLI |
 | `atomix-sync` | Legacy alias (deprecated) |
 
+## Troubleshooting
+
+**MCP shows old prompts or tools after updating:** Your IDE or npx may be using a cached version. Quit the IDE, clear the npx cache (`rm -rf ~/.npm/_npx` on macOS/Linux, or delete the `_npx` folder inside your [npm cache directory](https://docs.npmjs.com/cli/v10/commands/npm-cache)), then reopen the IDE and reconnect the MCP server.
+
 ## Links
 
 - [Atomix Studio](https://atomixstudio.eu)

package/dist/index.js

@@ -1345,7 +1345,7 @@ var TOKEN_CATEGORIES = ["colors", "typography", "spacing", "sizing", "shadows",
 var server = new Server(
   {
     name: "atomix-mcp-user",
-    version: "1.0.11"
+    version: "1.0.15"
   },
   {
     capabilities: {
@@ -1490,7 +1490,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "getDependencies",
-        description: "Get suggested dependencies for this design system (icon package, fonts, SKILL.md, token files). Use with atomix/setup. Optional platform and stack for tailored suggestions.",
+        description: "Get suggested dependencies for this design system (icon package, fonts, SKILL.md, token files). Use with atomix-setup prompt. Optional platform and stack for tailored suggestions.",
         inputSchema: {
           type: "object",
           properties: {
@@ -2159,23 +2159,8 @@ description: Use this design system when editing UI, design system files, or whe
 var AI_TOOLS = ["cursor", "copilot", "windsurf", "cline", "continue", "zed", "generic"];
 server.setRequestHandler(ListResourcesRequestSchema, async () => {
   try {
-    const data = await fetchDesignSystemForMCP();
-    const stats = getTokenStats(data);
-    const resources = [
-      {
-        uri: "atomix://hello",
-        name: `Welcome to ${data.meta.name}`,
-        description: `Design system overview with ${stats.total} tokens and ${stats.governanceRules} governance rules`,
-        mimeType: "text/markdown"
-      },
-      ...AI_TOOLS.map((tool) => ({
-        uri: `atomix://rules/${tool}`,
-        name: `${tool.charAt(0).toUpperCase() + tool.slice(1)} Rules`,
-        description: `Design system rules file for ${tool}`,
-        mimeType: "text/markdown"
-      }))
-    ];
-    return { resources };
+    await fetchDesignSystemForMCP();
+    return { resources: [] };
   } catch {
     return {
       resources: [
@@ -2254,75 +2239,31 @@ Get your DS ID from: https://atomixstudio.eu/ds/[your-ds-id]`
 });
 server.setRequestHandler(ListPromptsRequestSchema, async () => {
   const prompts = [
+    { name: "--hello", description: "Get started with this design system - overview, tokens, and tools. Run this first!" },
     {
-      name: "hello",
-      description: "Get started with this design system - shows overview, available tokens, and tools. Run this first!"
-    },
-    {
-      name: "design-system-rules",
-      description: "Get the design system governance rules for your AI coding tool",
+      name: "--setup",
+      description: "Setup design system in project. Three phases: scan, report and ask, then create only after you approve.",
       arguments: [
-        {
-          name: "tool",
-          description: "AI tool to generate rules for (cursor, copilot, windsurf, cline, continue, zed, generic)",
-          required: false
-        }
+        { name: "platform", description: "Target platform (web, ios, android). Optional.", required: false },
+        { name: "stack", description: "Stack or framework (e.g. react, vue, next, swift, kotlin). Optional.", required: false }
       ]
     },
     {
-      name: "spacing",
-      description: "List all spacing tokens with their values in a table format"
-    },
-    {
-      name: "radius",
-      description: "List all border radius tokens with their values in a table format"
-    },
-    {
-      name: "color",
-      description: "List all color tokens with light/dark mode values in a table format"
-    },
-    {
-      name: "typography",
-      description: "List all typography tokens with their values in a table format"
-    },
-    {
-      name: "shadow",
-      description: "List all shadow/elevation tokens with their values in a table format"
-    },
-    {
-      name: "border",
-      description: "List all border width tokens with their values in a table format"
-    },
-    {
-      name: "sizing",
-      description: "List all sizing tokens (height, icon) with their values in a table format"
-    },
-    {
-      name: "motion",
-      description: "List all motion tokens (duration, easing) with their values in a table format"
-    },
-    {
-      name: "sync",
-      description: "Sync design tokens (./tokens.css). Safe: Adds new tokens, updates existing values, marks deprecated tokens. Supports formats: css, scss, less, json, ts, js, swift, kotlin, dart. Use /refactor to migrate deprecated tokens."
-    },
-    {
-      name: "refactor",
-      description: "Migrate deprecated tokens in codebase. Scans for deprecated tokens marked by /sync and suggests replacements. Run after /sync to update code."
-    },
-    {
-      name: "setup",
-      description: "Suggest dependencies for this design system (icons, fonts, SKILL.md, tokens). Three phases: scan, report and ask, then create only after approval.",
+      name: "--rules",
+      description: "Get the design system governance rules for your AI coding tool",
       arguments: [
-        { name: "platform", description: "Target platform (web, ios, android). Optional; ask user if unknown.", required: false },
-        { name: "stack", description: "Stack or framework (e.g. react, vue, next, swift, kotlin). Optional.", required: false }
+        { name: "tool", description: "AI tool (cursor, copilot, windsurf, cline, continue, zed, generic). Optional.", required: false }
       ]
-    }
+    },
+    { name: "--sync", description: "Sync tokens to a local file. Safe: adds new, updates existing, marks deprecated. Use /--refactor to migrate." },
+    { name: "--refactor", description: "Migrate deprecated tokens in codebase. Run after /--sync." }
   ];
   return { prompts };
 });
 server.setRequestHandler(GetPromptRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
-  const shouldForceRefresh = name === "sync";
+  const canonicalName = name === "--hello" ? "hello" : name === "--setup" ? "atomix-setup" : name === "--rules" ? "design-system-rules" : name === "--sync" ? "sync" : name === "--refactor" ? "refactor" : name;
+  const shouldForceRefresh = canonicalName === "sync";
   let data = null;
   let stats = null;
   try {
@@ -2427,9 +2368,18 @@ Configure the MCP server in your Cursor settings, then restart Cursor.`
     lines.push(instructions);
     return lines.join("\n");
   };
-  switch (name) {
+  switch (canonicalName) {
     case "hello": {
       const welcome = generateWelcomeMessage(data, stats);
+      const helloInstruction = `You are showing the Atomix design system welcome. You MUST do the following in order:
+
+1. **First** \u2014 Copy and draw the ASCII art block exactly as it appears below (the code block with the arrow pattern). Output it verbatim before any other text. Do not summarize, skip, or replace it with a description.
+2. **Then** \u2014 Output the rest of the welcome message (markdown) exactly as given.
+
+Do not add any introduction or commentary before the ASCII art. The ASCII art must be the very first thing you output.
+
+---
+${welcome}`;
       return {
         description: `Hello \u2014 ${data.meta.name} Design System`,
         messages: [
@@ -2437,7 +2387,7 @@ Configure the MCP server in your Cursor settings, then restart Cursor.`
             role: "user",
             content: {
               type: "text",
-              text: welcome
+              text: helloInstruction
             }
           }
         ]
@@ -2743,8 +2693,16 @@ Use \`/color\`, \`/spacing\`, \`/radius\`, \`/typography\`, \`/shadow\`, \`/bord
         ]
       };
     }
-    case "setup": {
-      const setupInstructions = `You are running **atomix/setup**. Three phases only. Do not create, write, or modify any file until Phase 3 and only after the user has approved.
+    case "atomix-setup": {
+      const setupInstructions = `You are running **atomix-setup** (design system setup). Three phases only.
+
+**Rule:** Do not create, write, or modify any file until Phase 3 and only after the user has explicitly approved (e.g. replied "Yes", "Yes for all", "Go ahead"). Creating or modifying files before the user approves is a rule violation.
+
+## Todo list (required)
+
+- **Create a todo list** at the start with items for Phase 1, Phase 2, and Phase 3 (e.g. "Phase 1: Scan", "Phase 2: Report and ask", "Phase 3: Create after approval").
+- Work **step by step**: complete Phase 1, then Phase 2; do not run Phase 3 until the user has replied with approval.
+- Mark todo items completed as you finish each phase. Use this pattern so the user and you can track progress.
 
 ## Phase 1 \u2013 Scan
 
@@ -2776,9 +2734,9 @@ Use \`/color\`, \`/spacing\`, \`/radius\`, \`/typography\`, \`/shadow\`, \`/bord
 
 ---
 
-Execute Phase 1 now (resolve platform/stack, call getDependencies, scan, build lists). Then Phase 2 (report lists and ask). Do not perform Phase 3 until the user replies.`;
+Create your todo list first, then execute Phase 1 (resolve platform/stack, call getDependencies, scan, build lists). Then Phase 2 (report lists and ask). Do not perform Phase 3 until the user replies.`;
       return {
-        description: "Setup design system in project (atomix/setup). Phase 1 scan, Phase 2 report and ask, Phase 3 create only after user approval.",
+        description: "Setup design system in project (atomix-setup). Create todo list; Phase 1 scan, Phase 2 report and ask, Phase 3 create only after user approval.",
         messages: [
           {
             role: "user",
@@ -2848,25 +2806,13 @@ ${tokenSummary}
 
 | Command | What to expect |
 |---------|----------------|
-| **setup** | Scans your repo to set up global styles (if none), icons and fonts. Safe: Won't add anything until you confirm. |
-| **sync** | Syncs tokens to a local file. Adds new, updates existing, marks deprecated. Safe: No changes until you confirm. |
-| **refactor** | Scans codebase for deprecated tokens (after sync), suggests replacements. Run after sync to migrate code. |
-
-## Helper commands
+| **/--hello** | Get started - overview, tokens, and tools. Run this first! |
+| **/--setup** | Setup 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. Safe: adds new, updates existing, marks deprecated. |
+| **/--refactor** | Migrate deprecated tokens in codebase. Run after /--sync. |
 
-| Command | What to expect |
-|---------|----------------|
-| **design-system-rules** | Returns governance rules for your AI tools. |
-| **spacing** | Table of all spacing tokens and values. |
-| **color** | Table of color tokens with light/dark values. |
-| **typography** | Table of typography tokens and values. |
-| **radius** | Table of border radius tokens. |
-| **shadow** | Table of shadow/elevation tokens. |
-| **border** | Table of border width tokens. |
-| **sizing** | Table of height and icon size tokens. |
-| **motion** | Table of duration and easing tokens. |
-
-**Suggested next step:** Run **setup** to set up global styles, icons, fonts, and token files; the AI will list options and ask before adding anything.
+**Suggested next step:** Run **/--setup** to set up global styles, icons, fonts, and token files; the AI will list options and ask before adding anything.
 
 ---