@adobe/spectrum-design-data-mcp 1.0.12 → 1.1.0

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,37 @@
1
1
  # [**@adobe/spectrum-design-data-mcp**](https://github.com/adobe/spectrum-design-data-mcp)
2
2
 
3
+ ## 1.1.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#706](https://github.com/adobe/spectrum-design-data/pull/706) [`c051815`](https://github.com/adobe/spectrum-design-data/commit/c05181505730ec911196c4b6d37d106bccd742e5) Thanks [@GarthDB](https://github.com/GarthDB)! - Fix data loader to use getTokensByFile/getAllTokens from @adobe/spectrum-tokens.
8
+ Add query-tokens-by-value tool (search by direct or resolved alias value).
9
+
10
+ ### Patch Changes
11
+
12
+ - Updated dependencies [[`c051815`](https://github.com/adobe/spectrum-design-data/commit/c05181505730ec911196c4b6d37d106bccd742e5)]:
13
+ - @adobe/spectrum-tokens@14.2.0
14
+
15
+ ## 1.0.13
16
+
17
+ ### Patch Changes
18
+
19
+ - [#669](https://github.com/adobe/spectrum-design-data/pull/669) [`ae68c41`](https://github.com/adobe/spectrum-design-data/commit/ae68c412101b32b114d0d56893d1214f5225210a) Thanks [@GarthDB](https://github.com/GarthDB)! - feat(tooling): add renamed property support to token processing tools
20
+
21
+ Updated token processing tools to extract and display the new `renamed` property:
22
+ - **MCP Token Processor**: Extracts `renamed`, `deprecated`, and `deprecated_comment`
23
+ properties in token results
24
+ - **CSV Generator**: Added `renamed`, `deprecated`, and `deprecated_comment` columns
25
+ to CSV export
26
+ - **Diff Generator**: Updated documentation - tool automatically tracks `renamed`
27
+ property changes
28
+
29
+ These updates support the new `renamed` property added to the token schema for
30
+ tracking 1:1 token replacements.
31
+
32
+ - Updated dependencies [[`ae68c41`](https://github.com/adobe/spectrum-design-data/commit/ae68c412101b32b114d0d56893d1214f5225210a)]:
33
+ - @adobe/spectrum-tokens@14.1.0
34
+
3
35
  ## 1.0.12
4
36
 
5
37
  ### Patch Changes
package/README.md CHANGED
@@ -54,20 +54,17 @@ The server runs locally and communicates via stdio with MCP-compatible AI client
54
54
 
55
55
  #### Token Tools
56
56
 
57
- * **`query-tokens`**: Search and retrieve design tokens by name, type, or category
58
- * **`find-tokens-by-use-case`** ⭐: Find appropriate tokens for specific component use cases (e.g., "button background", "text color", "error state")
59
- * **`get-component-tokens`** ⭐: Get all tokens related to a specific component type
60
- * **`get-design-recommendations`** ⭐: Get token recommendations for design decisions and component states
61
- * **`get-token-categories`**: List all available token categories
57
+ * **`query-tokens`**: Search Spectrum tokens by name, type, or category
58
+ * **`query-tokens-by-value`**: Find tokens by direct or resolved value (follows aliases)
62
59
  * **`get-token-details`**: Get detailed information about a specific token
60
+ * **`get-component-tokens`**: Get all tokens for a component name
63
61
 
64
62
  #### Schema Tools
65
63
 
66
- * **`query-component-schemas`**: Search component API schemas
67
- * **`get-component-schema`**: Get the complete schema for a specific component
68
- * **`list-components`**: List all available components with schemas
69
- * **`validate-component-props`**: Validate component properties against schemas
70
- * **`get-type-schemas`**: Get type definitions used in schemas
64
+ * **`list-components`**: List available components (no schema payload)
65
+ * **`get-component-schema`**: Full schema for one component
66
+ * **`validate-component-props`**: Validate props against schema
67
+ * **`search-components-by-feature`**: Find components by property name
71
68
 
72
69
  ## Configuration
73
70
 
@@ -82,7 +79,7 @@ Add to your MCP configuration (e.g., `.cursor/mcp.json` for Cursor IDE):
82
79
  "mcpServers": {
83
80
  "spectrum-design-data": {
84
81
  "command": "npx",
85
- "args": ["@adobe/spectrum-design-data-mcp"]
82
+ "args": ["-y", "@adobe/spectrum-design-data-mcp"]
86
83
  }
87
84
  }
88
85
  }
@@ -138,55 +135,38 @@ The server uses stdio transport and follows the MCP specification. Refer to your
138
135
 
139
136
  ## Examples
140
137
 
141
- ### Component Building Workflow ⭐
138
+ ### Component Building Workflow
142
139
 
143
- #### Finding Tokens for Component Use Cases
144
-
145
- ```
146
- Human: I'm building a primary action button. What design tokens should I use for the background color?
147
-
148
- AI: I'll help you find the appropriate tokens for a primary button background.
149
-
150
- [Uses find-tokens-by-use-case with useCase="button background" and componentType="button"]
151
-
152
- For a primary action button background, I recommend these Spectrum tokens:
153
- - accent-color-100: Primary accent color for default state
154
- - accent-color-200: For hover states
155
- - accent-color-300: For pressed/active states
156
- - floating-action-button-drop-shadow-color: For drop shadows
157
- ```
158
-
159
- #### Design Intent Recommendations
140
+ #### Component-Specific Token Discovery
160
141
 
161
142
  ```
162
- Human: What tokens should I use for error messaging in my form validation?
143
+ Human: Show me all available button-related design tokens.
163
144
 
164
- AI: I'll find tokens for error state messaging.
145
+ AI: I'll gather all button-related tokens from the Spectrum system.
165
146
 
166
- [Uses get-design-recommendations with intent="negative" and context="text"]
147
+ [Uses get-component-tokens with componentName="button"]
167
148
 
168
- For error messaging, use these Spectrum tokens:
169
- - negative-color-100: Primary error text color
170
- - negative-background-color-default: Error background areas
171
- - negative-border-color: Error state borders
149
+ Found button-related tokens across categories:
150
+ - Color tokens: floating-action-button colors
151
+ - Layout tokens: button sizing, padding, spacing
152
+ - Examples: radio-button-control-size-small, action-button-edge-to-hold-icon...
172
153
  ```
173
154
 
174
- #### Component-Specific Token Discovery
155
+ #### Finding Tokens by Value
175
156
 
176
157
  ```
177
- Human: Show me all available button-related design tokens.
158
+ Human: Which tokens resolve to 1px?
178
159
 
179
- AI: I'll gather all button-related tokens from the Spectrum system.
160
+ AI: I'll search for tokens whose value is 1px (direct or alias).
180
161
 
181
- [Uses get-component-tokens with componentName="button"]
162
+ [Uses query-tokens-by-value with value="1px"]
182
163
 
183
- Found 57 button-related tokens across categories:
184
- - Color tokens (2): floating-action-button colors
185
- - Layout tokens (55): button sizing, padding, spacing
186
- - Examples: radio-button-control-size-small, action-button-edge-to-hold-icon...
164
+ Tokens with value 1px:
165
+ - border-width-100 (direct)
166
+ - picker-border-width (alias to border-width-100)
187
167
  ```
188
168
 
189
- ### Traditional Token Queries
169
+ ### Token Queries
190
170
 
191
171
  #### Querying Color Tokens
192
172
 
@@ -291,7 +271,7 @@ src/
291
271
 
292
272
  * Always verify package integrity using `npm audit signatures`
293
273
  * Keep the package updated to the latest version
294
- * Use npx for the most secure and up-to-date execution
274
+ * Use `npx -y` for the most secure and up-to-date execution
295
275
  * Report security issues through the [GitHub security advisory](https://github.com/adobe/spectrum-design-data/security/advisories)
296
276
 
297
277
  ## License
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adobe/spectrum-design-data-mcp",
3
- "version": "1.0.12",
3
+ "version": "1.1.0",
4
4
  "description": "Model Context Protocol server for Spectrum design data including tokens, schemas, and component anatomy",
5
5
  "keywords": [
6
6
  "mcp",
@@ -48,7 +48,7 @@
48
48
  "dependencies": {
49
49
  "@modelcontextprotocol/sdk": "^0.5.0",
50
50
  "commander": "^13.1.0",
51
- "@adobe/spectrum-tokens": "14.0.0",
51
+ "@adobe/spectrum-tokens": "14.2.0",
52
52
  "@adobe/spectrum-component-api-schemas": "6.0.0"
53
53
  },
54
54
  "devDependencies": {
@@ -10,86 +10,15 @@ OF ANY KIND, either express or implied. See the License for the specific languag
10
10
  governing permissions and limitations under the License.
11
11
  */
12
12
 
13
- import { readFileSync } from "fs";
14
- import { join, dirname } from "path";
15
- import { fileURLToPath } from "url";
13
+ import { getTokensByFile, getAllTokens } from "@adobe/spectrum-tokens";
16
14
 
17
- const __filename = fileURLToPath(import.meta.url);
18
- const __dirname = dirname(__filename);
15
+ export const getTokenData = getTokensByFile;
19
16
 
20
- /**
21
- * Get token data from the spectrum-tokens package
22
- * @returns {Promise<Object>} Token data organized by category
23
- */
24
- export async function getTokenData() {
25
- try {
26
- // Try to import from the workspace package first
27
- const spectrumTokens = await import("@adobe/spectrum-tokens");
28
-
29
- // If the package exports token data directly, use it
30
- if (spectrumTokens.default || spectrumTokens.tokens) {
31
- return spectrumTokens.default || spectrumTokens.tokens;
32
- }
33
-
34
- // Otherwise, read the token files directly from the package
35
- return await loadTokenFilesFromPackage();
36
- } catch (error) {
37
- console.error(
38
- "Failed to load token data from package, trying direct file access:",
39
- error,
40
- );
41
- return await loadTokenFilesDirectly();
42
- }
43
- }
44
-
45
- /**
46
- * Load token files from the spectrum-tokens package structure
47
- * @returns {Promise<Object>} Token data
48
- */
49
- async function loadTokenFilesFromPackage() {
50
- // This would be the ideal approach - loading from the actual package
51
- // For now, we'll fall back to direct file access
52
- return await loadTokenFilesDirectly();
53
- }
54
-
55
- /**
56
- * Load token files directly from the repository structure
57
- * @returns {Promise<Object>} Token data
58
- */
59
- async function loadTokenFilesDirectly() {
60
- const tokenData = {};
61
-
62
- // Path to the tokens source directory
63
- const tokensPath = join(__dirname, "../../../../packages/tokens/src");
64
-
65
- // List of token files to load
66
- const tokenFiles = [
67
- "color-aliases.json",
68
- "color-component.json",
69
- "color-palette.json",
70
- "icons.json",
71
- "layout-component.json",
72
- "layout.json",
73
- "semantic-color-palette.json",
74
- "typography.json",
75
- ];
76
-
77
- for (const fileName of tokenFiles) {
78
- try {
79
- const filePath = join(tokensPath, fileName);
80
- const fileContent = readFileSync(filePath, "utf8");
81
- tokenData[fileName] = JSON.parse(fileContent);
82
- } catch (error) {
83
- console.error(`Failed to load token file ${fileName}:`, error);
84
- // Continue loading other files even if one fails
85
- }
86
- }
87
-
88
- return tokenData;
89
- }
17
+ /** Flat { tokenName: tokenData } map — used for alias resolution */
18
+ export const getFlatTokenMap = getAllTokens;
90
19
 
91
20
  /**
92
- * Get available token categories
21
+ * Get available token categories (filenames without .json)
93
22
  * @returns {Promise<Array<string>>} List of token categories
94
23
  */
95
24
  export async function getTokenCategories() {
package/src/index.js CHANGED
@@ -66,10 +66,7 @@ export function createMCPServer() {
66
66
  content: [
67
67
  {
68
68
  type: "text",
69
- text:
70
- typeof result === "string"
71
- ? result
72
- : JSON.stringify(result, null, 2),
69
+ text: typeof result === "string" ? result : JSON.stringify(result),
73
70
  },
74
71
  ],
75
72
  };
@@ -18,81 +18,15 @@ import { getSchemaData } from "../data/schemas.js";
18
18
  */
19
19
  export function createSchemaTools() {
20
20
  return [
21
- {
22
- name: "query-component-schemas",
23
- description: "Search and retrieve Spectrum component API schemas",
24
- inputSchema: {
25
- type: "object",
26
- properties: {
27
- component: {
28
- type: "string",
29
- description:
30
- 'Component name to search for (e.g., "button", "action-button")',
31
- },
32
- query: {
33
- type: "string",
34
- description:
35
- "Search query to filter schemas (searches component names, descriptions)",
36
- },
37
- limit: {
38
- type: "number",
39
- description: "Maximum number of schemas to return (default: 20)",
40
- default: 20,
41
- },
42
- },
43
- },
44
- handler: async (args) => {
45
- const { component, query, limit = 20 } = args;
46
- const schemaData = await getSchemaData();
47
-
48
- let results = [];
49
-
50
- // Search through component schemas
51
- for (const [fileName, schema] of Object.entries(
52
- schemaData.components,
53
- )) {
54
- const componentName = fileName.replace(".json", "");
55
-
56
- // Apply component filter
57
- if (component && !componentName.includes(component.toLowerCase())) {
58
- continue;
59
- }
60
-
61
- // Apply query filter
62
- if (query && !matchesSchemaQuery(componentName, schema, query)) {
63
- continue;
64
- }
65
-
66
- results.push({
67
- component: componentName,
68
- fileName,
69
- title: schema.title,
70
- description: schema.description,
71
- properties: Object.keys(schema.properties || {}),
72
- required: schema.required || [],
73
- schema,
74
- });
75
- }
76
-
77
- // Apply limit
78
- results = results.slice(0, limit);
79
-
80
- return {
81
- total: results.length,
82
- schemas: results,
83
- query: { component, query, limit },
84
- };
85
- },
86
- },
87
21
  {
88
22
  name: "get-component-schema",
89
- description: "Get the complete schema for a specific component",
23
+ description: "Get full JSON schema for one component.",
90
24
  inputSchema: {
91
25
  type: "object",
92
26
  properties: {
93
27
  component: {
94
28
  type: "string",
95
- description: 'Component name (e.g., "action-button")',
29
+ description: "Component name",
96
30
  required: true,
97
31
  },
98
32
  },
@@ -123,29 +57,23 @@ export function createSchemaTools() {
123
57
  },
124
58
  {
125
59
  name: "list-components",
126
- description: "List all available Spectrum components with schemas",
127
- inputSchema: {
128
- type: "object",
129
- properties: {},
130
- },
60
+ description: "List all components (names and summary, no full schema).",
61
+ inputSchema: { type: "object", properties: {} },
131
62
  handler: async () => {
132
63
  const schemaData = await getSchemaData();
133
-
134
64
  const components = Object.keys(schemaData.components).map(
135
65
  (fileName) => {
136
66
  const componentName = fileName.replace(".json", "");
137
67
  const schema = schemaData.components[fileName];
138
-
139
- return {
68
+ const entry = {
140
69
  name: componentName,
141
- title: schema.title,
142
- description: schema.description,
143
70
  propertyCount: Object.keys(schema.properties || {}).length,
144
- hasRequired: (schema.required || []).length > 0,
145
71
  };
72
+ if (schema.title) entry.title = schema.title;
73
+ if (schema.description) entry.description = schema.description;
74
+ return entry;
146
75
  },
147
76
  );
148
-
149
77
  return {
150
78
  total: components.length,
151
79
  components: components.sort((a, b) => a.name.localeCompare(b.name)),
@@ -154,18 +82,18 @@ export function createSchemaTools() {
154
82
  },
155
83
  {
156
84
  name: "validate-component-props",
157
- description: "Validate component properties against their schema",
85
+ description: "Validate props against a component schema.",
158
86
  inputSchema: {
159
87
  type: "object",
160
88
  properties: {
161
89
  component: {
162
90
  type: "string",
163
- description: "Component name to validate against",
91
+ description: "Component name",
164
92
  required: true,
165
93
  },
166
94
  props: {
167
95
  type: "object",
168
- description: "Component properties to validate",
96
+ description: "Props to validate",
169
97
  required: true,
170
98
  },
171
99
  },
@@ -194,149 +122,16 @@ export function createSchemaTools() {
194
122
  };
195
123
  },
196
124
  },
197
- {
198
- name: "get-type-schemas",
199
- description: "Get type definitions used in component schemas",
200
- inputSchema: {
201
- type: "object",
202
- properties: {
203
- type: {
204
- type: "string",
205
- description: 'Specific type to retrieve (e.g., "hex-color")',
206
- },
207
- },
208
- },
209
- handler: async (args) => {
210
- const { type } = args;
211
- const schemaData = await getSchemaData();
212
-
213
- if (type) {
214
- const typeSchema = schemaData.types[`${type}.json`];
215
- if (!typeSchema) {
216
- throw new Error(`Type schema not found: ${type}`);
217
- }
218
-
219
- return {
220
- type,
221
- schema: typeSchema,
222
- };
223
- }
224
-
225
- // Return all types
226
- const types = Object.keys(schemaData.types).map((fileName) => {
227
- const typeName = fileName.replace(".json", "");
228
- const typeSchema = schemaData.types[fileName];
229
-
230
- return {
231
- name: typeName,
232
- title: typeSchema.title,
233
- description: typeSchema.description,
234
- type: typeSchema.type,
235
- };
236
- });
237
-
238
- return {
239
- total: types.length,
240
- types: types.sort((a, b) => a.name.localeCompare(b.name)),
241
- };
242
- },
243
- },
244
- {
245
- name: "get-component-options",
246
- description:
247
- "Get all available options/properties for a component in a user-friendly format - perfect for discovering what options a component supports",
248
- inputSchema: {
249
- type: "object",
250
- properties: {
251
- component: {
252
- type: "string",
253
- description:
254
- 'Component name (e.g., "action-button", "text-field", "menu")',
255
- required: true,
256
- },
257
- detailed: {
258
- type: "boolean",
259
- description:
260
- "Include detailed property information like enums, default values, etc.",
261
- default: false,
262
- },
263
- },
264
- required: ["component"],
265
- },
266
- handler: async (args) => {
267
- const { component, detailed = false } = args;
268
- const schemaData = await getSchemaData();
269
-
270
- const fileName = `${component}.json`;
271
- const schema = schemaData.components[fileName];
272
-
273
- if (!schema) {
274
- throw new Error(
275
- `Component not found: ${component}. Use list-components to see available components.`,
276
- );
277
- }
278
-
279
- const componentInfo = {
280
- name: component,
281
- title: schema.title || component,
282
- description: schema.description,
283
- totalProperties: 0,
284
- properties: [],
285
- };
286
-
287
- if (schema.properties) {
288
- componentInfo.totalProperties = Object.keys(schema.properties).length;
289
-
290
- Object.entries(schema.properties).forEach(([propName, propDef]) => {
291
- const propInfo = {
292
- name: propName,
293
- type: propDef.type || "object",
294
- required: schema.required
295
- ? schema.required.includes(propName)
296
- : false,
297
- description: propDef.description,
298
- };
299
-
300
- if (detailed) {
301
- // Add detailed information
302
- if (propDef.enum) {
303
- propInfo.possibleValues = propDef.enum;
304
- }
305
- if (propDef.default !== undefined) {
306
- propInfo.defaultValue = propDef.default;
307
- }
308
- if (propDef.properties) {
309
- propInfo.nestedProperties = Object.keys(propDef.properties);
310
- }
311
- if (propDef.$ref) {
312
- propInfo.reference = propDef.$ref;
313
- }
314
- }
315
-
316
- componentInfo.properties.push(propInfo);
317
- });
318
-
319
- // Sort properties: required first, then alphabetical
320
- componentInfo.properties.sort((a, b) => {
321
- if (a.required !== b.required) return a.required ? -1 : 1;
322
- return a.name.localeCompare(b.name);
323
- });
324
- }
325
-
326
- return componentInfo;
327
- },
328
- },
329
125
  {
330
126
  name: "search-components-by-feature",
331
127
  description:
332
- 'Find components that have specific features or properties (e.g., "size", "disabled", "selected")',
128
+ "Find components that have a property matching a name (e.g. size, disabled).",
333
129
  inputSchema: {
334
130
  type: "object",
335
131
  properties: {
336
132
  feature: {
337
133
  type: "string",
338
- description:
339
- 'The feature/property to search for (e.g., "size", "disabled", "icon", "label")',
134
+ description: "Property name substring",
340
135
  required: true,
341
136
  },
342
137
  },
@@ -349,30 +144,27 @@ export function createSchemaTools() {
349
144
 
350
145
  Object.entries(schemaData.components).forEach(([fileName, schema]) => {
351
146
  const componentName = fileName.replace(".json", "");
352
-
353
147
  if (schema.properties) {
354
148
  const hasFeature = Object.keys(schema.properties).some((prop) =>
355
149
  prop.toLowerCase().includes(feature.toLowerCase()),
356
150
  );
357
-
358
151
  if (hasFeature) {
359
152
  const matchingProps = Object.keys(schema.properties).filter(
360
153
  (prop) => prop.toLowerCase().includes(feature.toLowerCase()),
361
154
  );
362
-
363
- matchingComponents.push({
155
+ const entry = {
364
156
  name: componentName,
365
- title: schema.title || componentName,
366
- description: schema.description,
367
157
  matchingProperties: matchingProps,
368
158
  totalProperties: Object.keys(schema.properties).length,
369
- });
159
+ };
160
+ if (schema.title) entry.title = schema.title;
161
+ if (schema.description) entry.description = schema.description;
162
+ matchingComponents.push(entry);
370
163
  }
371
164
  }
372
165
  });
373
166
 
374
167
  return {
375
- feature,
376
168
  totalMatches: matchingComponents.length,
377
169
  components: matchingComponents.sort((a, b) =>
378
170
  a.name.localeCompare(b.name),
@@ -10,7 +10,7 @@ OF ANY KIND, either express or implied. See the License for the specific languag
10
10
  governing permissions and limitations under the License.
11
11
  */
12
12
 
13
- import { getTokenData } from "../data/tokens.js";
13
+ import { getTokenData, getFlatTokenMap } from "../data/tokens.js";
14
14
 
15
15
  /**
16
16
  * Create token-related MCP tools
@@ -21,27 +21,19 @@ export function createTokenTools() {
21
21
  {
22
22
  name: "query-tokens",
23
23
  description:
24
- "Search and retrieve Spectrum design tokens by name, type, or category",
24
+ "Search Spectrum tokens by name, type, or category. Categories: color-aliases, color-component, color-palette, icons, layout, layout-component, semantic-color-palette, typography.",
25
25
  inputSchema: {
26
26
  type: "object",
27
27
  properties: {
28
28
  query: {
29
29
  type: "string",
30
- description:
31
- "Search query to filter tokens (searches names, types, categories)",
32
- },
33
- category: {
34
- type: "string",
35
- description:
36
- 'Filter by token category (e.g., "color", "layout", "typography")',
37
- },
38
- type: {
39
- type: "string",
40
- description: 'Filter by token type (e.g., "alias", "component")',
30
+ description: "Filter by name, type, or description",
41
31
  },
32
+ category: { type: "string", description: "Filter by category" },
33
+ type: { type: "string", description: "Filter by token type" },
42
34
  limit: {
43
35
  type: "number",
44
- description: "Maximum number of tokens to return (default: 50)",
36
+ description: "Max results (default: 50)",
45
37
  default: 50,
46
38
  },
47
39
  },
@@ -49,71 +41,120 @@ export function createTokenTools() {
49
41
  handler: async (args) => {
50
42
  const { query, category, type, limit = 50 } = args;
51
43
  const tokenData = await getTokenData();
52
-
53
44
  let results = [];
54
-
55
- // Search through all token files
56
45
  for (const [fileName, tokens] of Object.entries(tokenData)) {
57
- // Skip if category filter doesn't match
58
46
  if (
59
47
  category &&
60
48
  !fileName.toLowerCase().includes(category.toLowerCase())
61
49
  ) {
62
50
  continue;
63
51
  }
64
-
65
- // Process tokens based on their structure
66
52
  const processedTokens = processTokens(tokens, fileName, query, type);
67
53
  results.push(...processedTokens);
68
54
  }
69
-
70
- // Apply limit
71
55
  results = results.slice(0, limit);
72
-
73
- return {
74
- total: results.length,
75
- tokens: results,
76
- query: { query, category, type, limit },
77
- };
56
+ return { total: results.length, tokens: results };
78
57
  },
79
58
  },
80
59
  {
81
- name: "get-token-categories",
82
- description:
83
- "Get all available token categories in the Spectrum design system",
60
+ name: "query-tokens-by-value",
61
+ description: "Find tokens by direct or resolved value (follows aliases).",
84
62
  inputSchema: {
85
63
  type: "object",
86
- properties: {},
64
+ properties: {
65
+ value: {
66
+ type: "string",
67
+ description: "Value to match (e.g. 1px, #000)",
68
+ },
69
+ exact: {
70
+ type: "boolean",
71
+ description: "Exact match (default: true)",
72
+ default: true,
73
+ },
74
+ limit: {
75
+ type: "number",
76
+ description: "Max results (default: 50)",
77
+ default: 50,
78
+ },
79
+ },
80
+ required: ["value"],
87
81
  },
88
- handler: async () => {
89
- const tokenData = await getTokenData();
90
- const categories = Object.keys(tokenData).map((fileName) => {
91
- // Extract category from filename (e.g., "color-palette.json" -> "color-palette")
92
- return fileName.replace(".json", "");
93
- });
94
-
95
- return {
96
- categories,
97
- total: categories.length,
82
+ handler: async (args) => {
83
+ const { value: searchValue, exact = true, limit = 50 } = args;
84
+ const [tokenData, flatMap] = await Promise.all([
85
+ getTokenData(),
86
+ getFlatTokenMap(),
87
+ ]);
88
+ const results = [];
89
+ const norm = (v) =>
90
+ v === null || v === undefined ? "" : String(v).toLowerCase();
91
+ const s = norm(searchValue);
92
+
93
+ const resolvedValuesToCheck = (resolved) => {
94
+ if (resolved === null || resolved === undefined) return [];
95
+ if (typeof resolved === "object" && !Array.isArray(resolved)) {
96
+ return Object.values(resolved).flatMap(resolvedValuesToCheck);
97
+ }
98
+ return [resolved];
98
99
  };
100
+
101
+ for (const [fileName, tokens] of Object.entries(tokenData)) {
102
+ const category = fileName.replace(".json", "");
103
+ if (!tokens || typeof tokens !== "object") continue;
104
+
105
+ for (const [name, token] of Object.entries(tokens)) {
106
+ if (!token || typeof token !== "object") continue;
107
+ const directValue = token.value;
108
+ const resolved = resolveTokenValue(token, flatMap, new Set(), name);
109
+ const toCheck = [directValue, ...resolvedValuesToCheck(resolved)];
110
+ const matched = toCheck.some((v) => {
111
+ const n = norm(v);
112
+ return exact ? n === s : n.includes(s);
113
+ });
114
+ if (!matched) continue;
115
+
116
+ const resolvedDisplay =
117
+ typeof resolved === "object" && resolved !== null
118
+ ? Object.entries(resolved)
119
+ .map(([k, v]) => `${k}: ${v}`)
120
+ .join(", ")
121
+ : resolved;
122
+ const directMatches =
123
+ directValue !== undefined &&
124
+ matchesValue(directValue, searchValue, exact);
125
+ const matchType = directMatches ? "direct" : "alias";
126
+
127
+ results.push({
128
+ name,
129
+ category,
130
+ directValue:
131
+ directValue !== undefined
132
+ ? directValue
133
+ : token.sets
134
+ ? JSON.stringify(token.sets)
135
+ : undefined,
136
+ resolvedValue: resolvedDisplay ?? directValue,
137
+ matchType,
138
+ });
139
+ }
140
+ }
141
+
142
+ const sliced = results.slice(0, limit);
143
+ return { total: sliced.length, tokens: sliced };
99
144
  },
100
145
  },
101
146
  {
102
147
  name: "get-token-details",
103
- description:
104
- "Get detailed information about a specific token by its path",
148
+ description: "Get full token data by path (flat token name).",
105
149
  inputSchema: {
106
150
  type: "object",
107
151
  properties: {
108
152
  tokenPath: {
109
153
  type: "string",
110
- description: 'The full path to the token (e.g., "color.blue.100")',
154
+ description: "Token path/name",
111
155
  required: true,
112
156
  },
113
- category: {
114
- type: "string",
115
- description: 'Token category to search in (e.g., "color-palette")',
116
- },
157
+ category: { type: "string", description: "Category to search in" },
117
158
  },
118
159
  required: ["tokenPath"],
119
160
  },
@@ -143,133 +184,16 @@ export function createTokenTools() {
143
184
  throw new Error(`Token not found: ${tokenPath}`);
144
185
  },
145
186
  },
146
- {
147
- name: "find-tokens-by-use-case",
148
- description:
149
- 'Find appropriate design tokens for specific component use cases (e.g., "button background", "text color", "border", "spacing")',
150
- inputSchema: {
151
- type: "object",
152
- properties: {
153
- useCase: {
154
- type: "string",
155
- description:
156
- 'The use case or purpose (e.g., "button background", "text color", "border", "spacing", "error state")',
157
- },
158
- componentType: {
159
- type: "string",
160
- description:
161
- 'Optional: Type of component being built (e.g., "button", "input", "card")',
162
- },
163
- },
164
- required: ["useCase"],
165
- },
166
- handler: async ({ useCase, componentType }) => {
167
- const data = await getTokenData();
168
- const recommendations = [];
169
-
170
- // Smart token recommendations based on use case
171
- const useCaseLower = useCase.toLowerCase();
172
- const compTypeLower = (componentType || "").toLowerCase();
173
-
174
- // Define use case mappings
175
- const useCasePatterns = {
176
- background: [
177
- "color-component",
178
- "semantic-color-palette",
179
- "color-palette",
180
- ],
181
- text: ["color-component", "semantic-color-palette", "typography"],
182
- border: ["color-component", "semantic-color-palette"],
183
- spacing: ["layout", "layout-component"],
184
- padding: ["layout", "layout-component"],
185
- margin: ["layout", "layout-component"],
186
- font: ["typography"],
187
- icon: ["icons", "layout"],
188
- error: ["semantic-color-palette", "color-component"],
189
- success: ["semantic-color-palette", "color-component"],
190
- warning: ["semantic-color-palette", "color-component"],
191
- accent: ["semantic-color-palette", "color-component"],
192
- button: ["color-component", "layout-component"],
193
- input: ["color-component", "layout-component"],
194
- card: ["color-component", "layout-component"],
195
- };
196
-
197
- // Find relevant categories
198
- const relevantCategories = [];
199
- for (const [pattern, categories] of Object.entries(useCasePatterns)) {
200
- if (
201
- useCaseLower.includes(pattern) ||
202
- compTypeLower.includes(pattern)
203
- ) {
204
- relevantCategories.push(...categories);
205
- }
206
- }
207
-
208
- // If no specific patterns match, search all categories
209
- const categoriesToSearch =
210
- relevantCategories.length > 0
211
- ? [...new Set(relevantCategories)]
212
- : Object.keys(data);
213
-
214
- // Search within relevant categories
215
- for (const category of categoriesToSearch) {
216
- const filename = category.includes(".json")
217
- ? category
218
- : `${category}.json`;
219
- const tokens = data[filename];
220
- if (!tokens) continue;
221
-
222
- Object.entries(tokens).forEach(([name, token]) => {
223
- const nameMatch =
224
- name.toLowerCase().includes(useCaseLower) ||
225
- (componentType && name.toLowerCase().includes(compTypeLower));
226
- const descMatch =
227
- token.description &&
228
- token.description.toLowerCase().includes(useCaseLower);
229
-
230
- if (nameMatch || descMatch) {
231
- recommendations.push({
232
- name,
233
- category: filename,
234
- value: token.value,
235
- description: token.description,
236
- schema: token.$schema,
237
- uuid: token.uuid,
238
- private: token.private || false,
239
- relevanceReason: nameMatch ? "name match" : "description match",
240
- });
241
- }
242
- });
243
- }
244
-
245
- // Sort by relevance (non-private first, then by name match)
246
- recommendations.sort((a, b) => {
247
- if (a.private !== b.private) return a.private ? 1 : -1;
248
- if (a.relevanceReason !== b.relevanceReason) {
249
- return a.relevanceReason === "name match" ? -1 : 1;
250
- }
251
- return a.name.localeCompare(b.name);
252
- });
253
-
254
- return {
255
- useCase,
256
- componentType,
257
- recommendations: recommendations.slice(0, 20), // Limit to top 20
258
- totalFound: recommendations.length,
259
- searchedCategories: categoriesToSearch,
260
- };
261
- },
262
- },
263
187
  {
264
188
  name: "get-component-tokens",
265
- description: "Get all tokens related to a specific component type",
189
+ description:
190
+ "Get tokens whose name contains a component (e.g. button, input).",
266
191
  inputSchema: {
267
192
  type: "object",
268
193
  properties: {
269
194
  componentName: {
270
195
  type: "string",
271
- description:
272
- 'Name of the component (e.g., "button", "input", "card", "modal")',
196
+ description: "Component name substring",
273
197
  },
274
198
  },
275
199
  required: ["componentName"],
@@ -279,26 +203,19 @@ export function createTokenTools() {
279
203
  const componentTokens = [];
280
204
  const componentLower = componentName.toLowerCase();
281
205
 
282
- // Search through all token categories for component-specific tokens
283
206
  Object.entries(data).forEach(([category, tokens]) => {
284
207
  if (!tokens) return;
285
-
286
208
  Object.entries(tokens).forEach(([name, token]) => {
287
209
  if (name.toLowerCase().includes(componentLower)) {
288
- componentTokens.push({
289
- name,
290
- category,
291
- value: token.value,
292
- description: token.description,
293
- schema: token.$schema,
294
- uuid: token.uuid,
295
- private: token.private || false,
296
- });
210
+ const entry = { name, category, value: token.value };
211
+ if (token.description) entry.description = token.description;
212
+ if (token.deprecated) entry.deprecated = true;
213
+ if (token.private) entry.private = true;
214
+ componentTokens.push(entry);
297
215
  }
298
216
  });
299
217
  });
300
218
 
301
- // Group by category for better organization
302
219
  const groupedTokens = componentTokens.reduce((acc, token) => {
303
220
  if (!acc[token.category]) acc[token.category] = [];
304
221
  acc[token.category].push(token);
@@ -306,175 +223,11 @@ export function createTokenTools() {
306
223
  }, {});
307
224
 
308
225
  return {
309
- componentName,
310
226
  tokensByCategory: groupedTokens,
311
227
  totalTokens: componentTokens.length,
312
228
  };
313
229
  },
314
230
  },
315
- {
316
- name: "get-design-recommendations",
317
- description:
318
- "Get design token recommendations for common design decisions and component states",
319
- inputSchema: {
320
- type: "object",
321
- properties: {
322
- intent: {
323
- type: "string",
324
- description:
325
- 'Design intent (e.g., "primary", "secondary", "accent", "negative", "notice", "positive", "informative")',
326
- },
327
- state: {
328
- type: "string",
329
- description:
330
- 'Component state (e.g., "default", "hover", "focus", "active", "disabled", "selected")',
331
- },
332
- context: {
333
- type: "string",
334
- description:
335
- 'Usage context (e.g., "button", "input", "text", "background", "border", "icon")',
336
- },
337
- },
338
- required: ["intent"],
339
- },
340
- handler: async ({ intent, state, context }) => {
341
- const data = await getTokenData();
342
- const recommendations = {
343
- colors: [],
344
- layout: [],
345
- typography: [],
346
- };
347
-
348
- const intentLower = intent.toLowerCase();
349
- const stateLower = (state || "").toLowerCase();
350
- const contextLower = (context || "").toLowerCase();
351
-
352
- // Search semantic colors first (these are typically the best recommendations)
353
- const semanticColors = data["semantic-color-palette.json"] || {};
354
- Object.entries(semanticColors).forEach(([name, token]) => {
355
- const nameLower = name.toLowerCase();
356
-
357
- // Intent matching
358
- const intentMatch =
359
- nameLower.includes(intentLower) ||
360
- (intentLower === "error" && nameLower.includes("negative")) ||
361
- (intentLower === "success" && nameLower.includes("positive")) ||
362
- (intentLower === "warning" && nameLower.includes("notice"));
363
-
364
- // State matching
365
- const stateMatch = !state || nameLower.includes(stateLower);
366
-
367
- // Context matching
368
- const contextMatch = !context || nameLower.includes(contextLower);
369
-
370
- if (intentMatch && stateMatch && contextMatch) {
371
- recommendations.colors.push({
372
- name,
373
- value: token.value,
374
- category: "semantic-color-palette",
375
- type: "semantic",
376
- confidence: "high",
377
- });
378
- }
379
- });
380
-
381
- // Search component colors if semantic colors don't provide enough options
382
- if (recommendations.colors.length < 3) {
383
- const componentColors = data["color-component.json"] || {};
384
- Object.entries(componentColors).forEach(([name, token]) => {
385
- const nameLower = name.toLowerCase();
386
-
387
- // Intent and context matching for component colors
388
- const intentMatch = nameLower.includes(intentLower);
389
- const contextMatch = !context || nameLower.includes(contextLower);
390
- const stateMatch = !state || nameLower.includes(stateLower);
391
-
392
- if ((intentMatch || contextMatch) && stateMatch) {
393
- recommendations.colors.push({
394
- name,
395
- value: token.value,
396
- category: "color-component",
397
- type: "component",
398
- confidence: "medium",
399
- });
400
- }
401
- });
402
- }
403
-
404
- // Layout recommendations if context suggests spacing/sizing
405
- if (
406
- context &&
407
- ["button", "input", "spacing", "padding", "margin"].some((c) =>
408
- contextLower.includes(c),
409
- )
410
- ) {
411
- const layoutComponent = data["layout-component.json"] || {};
412
- Object.entries(layoutComponent).forEach(([name, token]) => {
413
- const nameLower = name.toLowerCase();
414
-
415
- if (
416
- contextLower &&
417
- nameLower.includes(contextLower) &&
418
- nameLower.includes(stateLower || "size")
419
- ) {
420
- recommendations.layout.push({
421
- name,
422
- value: token.value,
423
- category: "layout-component",
424
- type: "spacing",
425
- confidence: "high",
426
- });
427
- }
428
- });
429
- }
430
-
431
- // Typography recommendations for text contexts
432
- if (
433
- context &&
434
- ["text", "label", "heading", "body"].some((c) =>
435
- contextLower.includes(c),
436
- )
437
- ) {
438
- const typography = data["typography.json"] || {};
439
- Object.entries(typography).forEach(([name, token]) => {
440
- const nameLower = name.toLowerCase();
441
-
442
- if (nameLower.includes(contextLower)) {
443
- recommendations.typography.push({
444
- name,
445
- value: token.value,
446
- category: "typography",
447
- type: "text",
448
- confidence: "high",
449
- });
450
- }
451
- });
452
- }
453
-
454
- // Sort by confidence and limit results
455
- ["colors", "layout", "typography"].forEach((category) => {
456
- recommendations[category] = recommendations[category]
457
- .sort((a, b) => {
458
- const confidenceOrder = { high: 0, medium: 1, low: 2 };
459
- return (
460
- confidenceOrder[a.confidence] - confidenceOrder[b.confidence]
461
- );
462
- })
463
- .slice(0, 10);
464
- });
465
-
466
- return {
467
- intent,
468
- state,
469
- context,
470
- recommendations,
471
- totalFound:
472
- recommendations.colors.length +
473
- recommendations.layout.length +
474
- recommendations.typography.length,
475
- };
476
- },
477
- },
478
231
  ];
479
232
  }
480
233
 
@@ -509,15 +262,19 @@ function processTokens(tokens, fileName, query, type) {
509
262
  continue;
510
263
  }
511
264
 
512
- results.push({
265
+ const entry = {
513
266
  name: key,
514
- path: currentPath,
515
267
  category,
516
- type: tokenType,
517
268
  value: value.$value || value.value,
518
- description: value.$description || value.description,
519
- extensions: value.$extensions || value.extensions,
520
- });
269
+ };
270
+ if (value.$description || value.description)
271
+ entry.description = value.$description || value.description;
272
+ if (value.deprecated) entry.deprecated = true;
273
+ if (value.private) entry.private = true;
274
+ if (value.deprecated_comment)
275
+ entry.deprecated_comment = value.deprecated_comment;
276
+ if (value.renamed) entry.renamed = value.renamed;
277
+ results.push(entry);
521
278
  } else {
522
279
  // Recurse into nested objects
523
280
  traverse(value, currentPath);
@@ -579,3 +336,66 @@ function matchesQuery(path, token, query) {
579
336
 
580
337
  return false;
581
338
  }
339
+
340
+ /**
341
+ * Extract token name from alias reference value {token-name}
342
+ * @param {string} value - Raw value
343
+ * @returns {string|null} Token name or null if not a reference
344
+ */
345
+ function extractReference(value) {
346
+ if (typeof value !== "string") return null;
347
+ const m = value.match(/^\{([^}]+)\}$/);
348
+ return m ? m[1] : null;
349
+ }
350
+
351
+ /**
352
+ * Resolve a token's value (follow alias chains, handle sets). Detects cycles.
353
+ * @param {Object} token - Token object
354
+ * @param {Object} flatMap - Flat map of tokenName -> token
355
+ * @param {Set<string>} visited - Token names already visited (cycle detection)
356
+ * @param {string} currentName - Current token name (for visited set)
357
+ * @returns {string|number|Object|null} Resolved value; for sets, object of setKey -> resolved value
358
+ */
359
+ function resolveTokenValue(token, flatMap, visited, currentName) {
360
+ if (!token || typeof token !== "object") return null;
361
+ if (visited.has(currentName)) return null;
362
+ visited.add(currentName);
363
+
364
+ if (token.sets && typeof token.sets === "object") {
365
+ const out = {};
366
+ for (const [setKey, setToken] of Object.entries(token.sets)) {
367
+ const resolved = resolveTokenValue(
368
+ setToken,
369
+ flatMap,
370
+ new Set(visited),
371
+ `${currentName}.${setKey}`,
372
+ );
373
+ out[setKey] = resolved;
374
+ }
375
+ return out;
376
+ }
377
+
378
+ const raw = token.value;
379
+ if (raw === undefined) return null;
380
+ const ref = extractReference(raw);
381
+ if (ref) {
382
+ const refToken = flatMap[ref];
383
+ if (!refToken) return null;
384
+ return resolveTokenValue(refToken, flatMap, visited, ref);
385
+ }
386
+ return raw;
387
+ }
388
+
389
+ /**
390
+ * Check if a value matches the search string (exact or contains)
391
+ * @param {string|number} value - Token value
392
+ * @param {string} searchValue - Search string
393
+ * @param {boolean} exact - Whether to require exact match
394
+ * @returns {boolean}
395
+ */
396
+ function matchesValue(value, searchValue, exact) {
397
+ const n =
398
+ value === null || value === undefined ? "" : String(value).toLowerCase();
399
+ const s = String(searchValue).toLowerCase();
400
+ return exact ? n === s : n.includes(s);
401
+ }