@atomixstudio/mcp 1.0.5 → 1.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +115 -23
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,23 +1,93 @@
1
1
  # @atomixstudio/mcp
2
2
 
3
- 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.
3
+ 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.
4
4
 
5
- ## Installation
5
+ ## Quick Start (CLI)
6
+
7
+ The easiest way to use Atomix is via the CLI:
6
8
 
7
9
  ```bash
8
- npm install -g @atomixstudio/mcp
9
- # or use directly with npx
10
- npx @atomixstudio/mcp --ds-id <your-ds-id> --api-key <your-api-key>
10
+ # Sync design tokens to your project
11
+ npx heyatomix sync
12
+
13
+ # Sync tokens + AI rules files (.cursorrules, etc.)
14
+ npx heyatomix sync --rules
15
+
16
+ # Create config file
17
+ npx heyatomix init
11
18
  ```
12
19
 
13
20
  ## Getting Your Credentials
14
21
 
15
22
  1. Go to [Atomix Studio](https://atomixstudio.eu)
16
- 2. Sign in and access your design system
17
- 3. Click **Export** → Generate API Key
23
+ 2. Sign in and create/access your design system
24
+ 3. Click **Publish** to make your DS available via API
18
25
  4. Your `ds-id` is in the URL: `atomixstudio.eu/ds/[ds-id]`
19
26
 
20
- ## Quick Setup
27
+ ## CLI Commands
28
+
29
+ ### `heyatomix sync`
30
+
31
+ Sync design tokens to a local file in your project.
32
+
33
+ ```bash
34
+ npx heyatomix sync # Sync to ./tokens.css
35
+ npx heyatomix sync -o src/tokens.css # Custom output path
36
+ npx heyatomix sync --format scss # Output as SCSS
37
+ npx heyatomix sync --rules # Also sync AI rules files
38
+ npx heyatomix sync -y # Auto-confirm changes
39
+ ```
40
+
41
+ ### `heyatomix init`
42
+
43
+ Create a `.atomixrc` config file:
44
+
45
+ ```bash
46
+ npx heyatomix init
47
+ ```
48
+
49
+ This creates:
50
+
51
+ ```json
52
+ {
53
+ "dsId": "your-design-system-id",
54
+ "output": "./tokens.css",
55
+ "format": "css"
56
+ }
57
+ ```
58
+
59
+ ### CLI Options
60
+
61
+ | Option | Description |
62
+ |--------|-------------|
63
+ | `--ds-id` | Design system ID (or set in .atomixrc) |
64
+ | `--api-key` | API key for private design systems |
65
+ | `--output, -o` | Output file path [./tokens.css] |
66
+ | `--format` | Output format (see below) |
67
+ | `--rules, -r` | Also sync AI rules files |
68
+ | `--rules-dir` | Directory for rules files [project root] |
69
+ | `-y, --yes` | Auto-confirm changes |
70
+
71
+ ### Output Formats
72
+
73
+ **Web:**
74
+ - `css` — CSS custom properties (`:root { --var: value }`)
75
+ - `scss` — CSS vars + SCSS variables (`$var: value`)
76
+ - `less` — CSS vars + Less variables (`@var: value`)
77
+ - `json` — Raw token JSON
78
+ - `ts` — TypeScript with types
79
+ - `js` — JavaScript module
80
+
81
+ **Native:**
82
+ - `swift` — Swift/SwiftUI for iOS
83
+ - `kotlin` — Kotlin/Compose for Android
84
+ - `dart` — Dart for Flutter
85
+
86
+ All formats include **light and dark mode** values.
87
+
88
+ ## MCP Server Setup
89
+
90
+ For AI tools to query your design system directly:
21
91
 
22
92
  ### Cursor IDE
23
93
 
@@ -28,7 +98,7 @@ Create `.cursor/mcp.json` in your project root:
28
98
  "mcpServers": {
29
99
  "my-design-system": {
30
100
  "command": "npx",
31
- "args": ["@atomixstudio/mcp@latest", "--ds-id", "<your-ds-id>", "--api-key", "<your-api-key>"]
101
+ "args": ["@atomixstudio/mcp@latest", "--ds-id", "<your-ds-id>"]
32
102
  }
33
103
  }
34
104
  }
@@ -43,7 +113,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
43
113
  "mcpServers": {
44
114
  "my-design-system": {
45
115
  "command": "npx",
46
- "args": ["@atomixstudio/mcp@latest", "--ds-id", "<your-ds-id>", "--api-key", "<your-api-key>"]
116
+ "args": ["@atomixstudio/mcp@latest", "--ds-id", "<your-ds-id>"]
47
117
  }
48
118
  }
49
119
  }
@@ -53,9 +123,9 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
53
123
 
54
124
  Create `.windsurf/mcp.json` in your project root (same format as Cursor).
55
125
 
56
- ## Available Tools
126
+ ## MCP Tools
57
127
 
58
- Once connected, AI tools can use these MCP tools:
128
+ Once connected, AI tools can use these:
59
129
 
60
130
  | Tool | Description |
61
131
  |------|-------------|
@@ -63,13 +133,14 @@ Once connected, AI tools can use these MCP tools:
63
133
  | `listTokens(category)` | List all tokens in a category |
64
134
  | `searchTokens(query)` | Search tokens by name or value |
65
135
  | `validateUsage(value)` | Check if a hardcoded value should use a token |
136
+ | `syncTokens(options)` | Sync tokens to a local file |
66
137
  | `getAIToolRules(tool)` | Generate AI coding rules for your design system |
67
138
  | `exportMCPConfig(tool)` | Get MCP configuration for different tools |
68
139
  | `getSetupInstructions(tool)` | Get detailed setup guide |
69
140
 
70
141
  ## Token Categories
71
142
 
72
- - **colors** — Brand, background, text, icon, border, action, feedback colors
143
+ - **colors** — Brand, background, text, icon, border, action, feedback (light + dark)
73
144
  - **typography** — Font families, sizes, weights, line heights
74
145
  - **spacing** — Scale tokens (xs, sm, md, lg, xl, etc.)
75
146
  - **sizing** — Component heights, icon sizes
@@ -79,31 +150,52 @@ Once connected, AI tools can use these MCP tools:
79
150
  - **motion** — Duration and easing tokens
80
151
  - **zIndex** — Layer tokens
81
152
 
153
+ ## AI Rules Files
154
+
155
+ When using `--rules`, these files are synced based on which AI tools you use:
156
+
157
+ | File | AI Tool |
158
+ |------|---------|
159
+ | `.cursorrules` | Cursor |
160
+ | `.windsurfrules` | Windsurf |
161
+ | `.clinerules` | Cline |
162
+ | `.continuerules` | Continue |
163
+ | `.github/copilot-instructions.md` | GitHub Copilot |
164
+ | `AI_GUIDELINES.md` | Generic |
165
+
166
+ The rules include your design system's governance guidelines and token usage instructions.
167
+
82
168
  ## Example Usage
83
169
 
84
- After setup, ask your AI tool:
170
+ **CLI:**
171
+
172
+ ```bash
173
+ npx heyatomix sync --rules
174
+ ```
175
+
176
+ **Natural language (via MCP):**
177
+
178
+ > "Sync my design tokens to tokens.css"
85
179
 
86
- > "What color tokens are available in my design system?"
180
+ > "What color tokens are available?"
87
181
 
88
182
  > "Use the correct spacing token for 16px padding"
89
183
 
90
184
  > "Validate this: style={{ backgroundColor: '#007061' }}"
91
185
 
92
- ## CLI Options
186
+ ## Package Aliases
93
187
 
94
- | Option | Description |
95
- |--------|-------------|
96
- | `--ds-id` | Your design system ID (required) |
97
- | `--api-key` | Your API key for authentication |
98
- | `--api-base` | API base URL (default: https://atomixstudio.eu) |
188
+ | Package | Description |
189
+ |---------|-------------|
190
+ | `heyatomix` | Recommended CLI (e.g., `npx heyatomix sync`) |
191
+ | `@atomixstudio/mcp` | Full MCP server + CLI |
192
+ | `atomix-sync` | Legacy alias (deprecated) |
99
193
 
100
194
  ## Links
101
195
 
102
196
  - [Atomix Studio](https://atomixstudio.eu)
103
- - [Documentation](https://atomixstudio.eu/docs)
104
197
  - [MCP Protocol](https://modelcontextprotocol.io)
105
198
 
106
199
  ## License
107
200
 
108
201
  MIT
109
-
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atomixstudio/mcp",
3
- "version": "1.0.5",
3
+ "version": "1.0.6",
4
4
  "description": "MCP server for Atomix Design System - query your design tokens from AI coding tools",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",