@atomixstudio/mcp 1.0.14 → 1.0.15

package/README.md

@@ -146,7 +146,7 @@ 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, MCP config, tokens). Optional: `platform` (web, ios, android), `stack` (e.g. react, vue, next). Use with **--setup** prompt. |
 
 ### getDependencies
 
@@ -169,9 +169,21 @@ Returns DS-derived suggestions so the client's AI can build a "Suggested" vs "Al
 
 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.
 
-## 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.
+Once connected, your AI tool can run these prompts (e.g. **/--hello**, **/--setup**):
+
+| 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. |
+| **/--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)
+
+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.
 
 **Flow (phased instructions):**
 
@@ -182,7 +194,7 @@ The **install** prompt suggests dependencies for your design system so you can g
 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.").
 
-**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 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).
 
 ## Token Categories
 
@@ -237,6 +249,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.
 
 ---