@atlaskit/ads-mcp 1.10.12 → 1.11.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @atlaskit/ads-mcp
 
+## 1.11.0
+
+### Minor Changes
+
+- [`9b565c62c7a8d`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/9b565c62c7a8d) -
+  Return the canonical per-token description from the tokens package in detailed token searches and
+  CLI JSON output. Show that description as the CLI's token guidance instead of generic category
+  guidance, while retaining CSS property hints and compact search results.
+
+### Patch Changes
+
+- Updated dependencies
+
 ## 1.10.12
 
 ### Patch Changes

package/dist/cjs/tools/get-all-tokens/get-all-tokens-tool.js

@@ -21,6 +21,7 @@ var getAllTokensTool = exports.getAllTokensTool = /*#__PURE__*/function () {
                 type: 'text',
                 text: JSON.stringify({
                   name: token.name,
+                  description: token.description,
                   exampleValue: token.exampleValue,
                   usageGuidelines: token.usageGuidelines
                 }, null, 2)

package/dist/cjs/tools/get-all-tokens/list-get-all-tokens-tool.js

@@ -11,7 +11,7 @@ var _zodToJsonSchema = require("../../helpers/zod-to-json-schema");
 var inputSchema = _zod.z.object({});
 var listGetAllTokensTool = exports.listGetAllTokensTool = {
   name: 'ads_get_all_tokens',
-  description: "Returns **every** ADS design token from bundled metadata (name, example value, usage guidelines)\u2014one JSON object per token, **very large** output.\n\nWHEN TO USE:\nLast resort when `ads_plan` / `ads_search_tokens` cannot answer the question and you need the full list (e.g. exhaustive audit). Prefer targeted search for normal development.\n\nNo parameters.",
+  description: "Returns **every** ADS design token from bundled metadata (name, canonical token description, example value, shared usage guidelines)\u2014one JSON object per token, **very large** output.\n\nWHEN TO USE:\nLast resort when `ads_plan` / `ads_search_tokens` cannot answer the question and you need the full list (e.g. exhaustive audit). Prefer targeted search for normal development.\n\nNo parameters.",
   annotations: {
     title: 'Get all ADS tokens',
     readOnlyHint: true,

package/dist/cjs/tools/search-tokens/list-search-tokens-tool.js

@@ -10,7 +10,7 @@ var _searchTokensInputSchema = require("./search-tokens-input-schema");
 
 var listSearchTokensTool = exports.listSearchTokensTool = {
   name: 'ads_search_tokens',
-  description: "Searches Atlassian Design System **design tokens** from bundled metadata. Returns compact JSON objects with **name** and **exampleValue** for each match by default (search also considers description, usage guidelines, and CSS property hints in metadata). Set **includeMetadata** to include usage guidelines in each result.\n\nWHEN TO USE:\n**Styling or theming in code**\u2014you need the right `token('\u2026')` names for colors, space, typography, etc. Use during layout and visual work when tokens must match ADS. Prefer `ads_plan` when you also need icons and components in the same step.\n\nExample:\n```tsx\nimport { token } from '@atlaskit/tokens';\nconst styles = css({ color: token('color.text'), padding: token('space.100') });\n```",
+  description: "Searches Atlassian Design System **design tokens** from bundled metadata. Returns compact JSON objects with **name** and **exampleValue** for each match by default (search also considers description, usage guidelines, and CSS property hints in metadata). Set **includeMetadata** to include the canonical token description from the tokens package and shared usage guidelines in each result.\n\nWHEN TO USE:\n**Styling or theming in code**\u2014you need the right `token('\u2026')` names for colors, space, typography, etc. Use during layout and visual work when tokens must match ADS. Prefer `ads_plan` when you also need icons and components in the same step.\n\nExample:\n```tsx\nimport { token } from '@atlaskit/tokens';\nconst styles = css({ color: token('color.text'), padding: token('space.100') });\n```",
   annotations: {
     title: 'Search ADS tokens',
     readOnlyHint: true,

package/dist/cjs/tools/search-tokens/search-tokens-input-schema.js

@@ -10,5 +10,5 @@ var _zod = require("zod");
 var searchTokensInputSchema = exports.searchTokensInputSchema = _zod.z.object({
   terms: _zod.z.array(_zod.z.string()).describe('Required: one or more terms; fuzzy match on token **name**, **description**, **exampleValue**, **usageGuidelines.usage**, and **usageGuidelines.cssProperties**. Example: `["spacing", "color.text", "background"]`.'),
   limit: _zod.z.number().default(2).describe('Max matches **per term** (default 2).').optional(),
-  includeMetadata: _zod.z.boolean().default(false).describe('Include usage guidelines in each result (default false).').optional()
+  includeMetadata: _zod.z.boolean().default(false).describe('Include the token description and usage guidelines in each result (default false).').optional()
 });

package/dist/cjs/tools/search-tokens/search-tokens-tool.js

@@ -76,6 +76,7 @@ var searchTokensTool = exports.searchTokensTool = /*#__PURE__*/function () {
               name: item.name,
               exampleValue: item.exampleValue
             }, includeMetadata ? {
+              description: item.description,
               usageGuidelines: item.usageGuidelines
             } : {});
           });

package/dist/es2019/tools/get-all-tokens/get-all-tokens-tool.js

@@ -6,6 +6,7 @@ export const getAllTokensTool = async () => ({
     type: 'text',
     text: JSON.stringify({
       name: token.name,
+      description: token.description,
       exampleValue: token.exampleValue,
       usageGuidelines: token.usageGuidelines
     }, null, 2)

package/dist/es2019/tools/get-all-tokens/list-get-all-tokens-tool.js

@@ -5,7 +5,7 @@ import { zodToJsonSchema } from '../../helpers/zod-to-json-schema';
 const inputSchema = z.object({});
 export const listGetAllTokensTool = {
   name: 'ads_get_all_tokens',
-  description: `Returns **every** ADS design token from bundled metadata (name, example value, usage guidelines)—one JSON object per token, **very large** output.
+  description: `Returns **every** ADS design token from bundled metadata (name, canonical token description, example value, shared usage guidelines)—one JSON object per token, **very large** output.
 
 WHEN TO USE:
 Last resort when \`ads_plan\` / \`ads_search_tokens\` cannot answer the question and you need the full list (e.g. exhaustive audit). Prefer targeted search for normal development.

package/dist/es2019/tools/search-tokens/list-search-tokens-tool.js

@@ -4,7 +4,7 @@ import { zodToJsonSchema } from '../../helpers/zod-to-json-schema';
 import { searchTokensInputSchema } from './search-tokens-input-schema';
 export const listSearchTokensTool = {
   name: 'ads_search_tokens',
-  description: `Searches Atlassian Design System **design tokens** from bundled metadata. Returns compact JSON objects with **name** and **exampleValue** for each match by default (search also considers description, usage guidelines, and CSS property hints in metadata). Set **includeMetadata** to include usage guidelines in each result.
+  description: `Searches Atlassian Design System **design tokens** from bundled metadata. Returns compact JSON objects with **name** and **exampleValue** for each match by default (search also considers description, usage guidelines, and CSS property hints in metadata). Set **includeMetadata** to include the canonical token description from the tokens package and shared usage guidelines in each result.
 
 WHEN TO USE:
 **Styling or theming in code**—you need the right \`token('…')\` names for colors, space, typography, etc. Use during layout and visual work when tokens must match ADS. Prefer \`ads_plan\` when you also need icons and components in the same step.

package/dist/es2019/tools/search-tokens/search-tokens-input-schema.js

@@ -4,5 +4,5 @@ import { z } from 'zod';
 export const searchTokensInputSchema = z.object({
   terms: z.array(z.string()).describe('Required: one or more terms; fuzzy match on token **name**, **description**, **exampleValue**, **usageGuidelines.usage**, and **usageGuidelines.cssProperties**. Example: `["spacing", "color.text", "background"]`.'),
   limit: z.number().default(2).describe('Max matches **per term** (default 2).').optional(),
-  includeMetadata: z.boolean().default(false).describe('Include usage guidelines in each result (default false).').optional()
+  includeMetadata: z.boolean().default(false).describe('Include the token description and usage guidelines in each result (default false).').optional()
 });

package/dist/es2019/tools/search-tokens/search-tokens-tool.js

@@ -57,6 +57,7 @@ export const searchTokensTool = async ({
     name: item.name,
     exampleValue: item.exampleValue,
     ...(includeMetadata ? {
+      description: item.description,
       usageGuidelines: item.usageGuidelines
     } : {})
   }));

package/dist/esm/tools/get-all-tokens/get-all-tokens-tool.js

@@ -14,6 +14,7 @@ export var getAllTokensTool = /*#__PURE__*/function () {
                 type: 'text',
                 text: JSON.stringify({
                   name: token.name,
+                  description: token.description,
                   exampleValue: token.exampleValue,
                   usageGuidelines: token.usageGuidelines
                 }, null, 2)

package/dist/esm/tools/get-all-tokens/list-get-all-tokens-tool.js

@@ -5,7 +5,7 @@ import { zodToJsonSchema } from '../../helpers/zod-to-json-schema';
 var inputSchema = z.object({});
 export var listGetAllTokensTool = {
   name: 'ads_get_all_tokens',
-  description: "Returns **every** ADS design token from bundled metadata (name, example value, usage guidelines)\u2014one JSON object per token, **very large** output.\n\nWHEN TO USE:\nLast resort when `ads_plan` / `ads_search_tokens` cannot answer the question and you need the full list (e.g. exhaustive audit). Prefer targeted search for normal development.\n\nNo parameters.",
+  description: "Returns **every** ADS design token from bundled metadata (name, canonical token description, example value, shared usage guidelines)\u2014one JSON object per token, **very large** output.\n\nWHEN TO USE:\nLast resort when `ads_plan` / `ads_search_tokens` cannot answer the question and you need the full list (e.g. exhaustive audit). Prefer targeted search for normal development.\n\nNo parameters.",
   annotations: {
     title: 'Get all ADS tokens',
     readOnlyHint: true,

package/dist/esm/tools/search-tokens/list-search-tokens-tool.js

@@ -4,7 +4,7 @@ import { zodToJsonSchema } from '../../helpers/zod-to-json-schema';
 import { searchTokensInputSchema } from './search-tokens-input-schema';
 export var listSearchTokensTool = {
   name: 'ads_search_tokens',
-  description: "Searches Atlassian Design System **design tokens** from bundled metadata. Returns compact JSON objects with **name** and **exampleValue** for each match by default (search also considers description, usage guidelines, and CSS property hints in metadata). Set **includeMetadata** to include usage guidelines in each result.\n\nWHEN TO USE:\n**Styling or theming in code**\u2014you need the right `token('\u2026')` names for colors, space, typography, etc. Use during layout and visual work when tokens must match ADS. Prefer `ads_plan` when you also need icons and components in the same step.\n\nExample:\n```tsx\nimport { token } from '@atlaskit/tokens';\nconst styles = css({ color: token('color.text'), padding: token('space.100') });\n```",
+  description: "Searches Atlassian Design System **design tokens** from bundled metadata. Returns compact JSON objects with **name** and **exampleValue** for each match by default (search also considers description, usage guidelines, and CSS property hints in metadata). Set **includeMetadata** to include the canonical token description from the tokens package and shared usage guidelines in each result.\n\nWHEN TO USE:\n**Styling or theming in code**\u2014you need the right `token('\u2026')` names for colors, space, typography, etc. Use during layout and visual work when tokens must match ADS. Prefer `ads_plan` when you also need icons and components in the same step.\n\nExample:\n```tsx\nimport { token } from '@atlaskit/tokens';\nconst styles = css({ color: token('color.text'), padding: token('space.100') });\n```",
   annotations: {
     title: 'Search ADS tokens',
     readOnlyHint: true,

package/dist/esm/tools/search-tokens/search-tokens-input-schema.js

@@ -4,5 +4,5 @@ import { z } from 'zod';
 export var searchTokensInputSchema = z.object({
   terms: z.array(z.string()).describe('Required: one or more terms; fuzzy match on token **name**, **description**, **exampleValue**, **usageGuidelines.usage**, and **usageGuidelines.cssProperties**. Example: `["spacing", "color.text", "background"]`.'),
   limit: z.number().default(2).describe('Max matches **per term** (default 2).').optional(),
-  includeMetadata: z.boolean().default(false).describe('Include usage guidelines in each result (default false).').optional()
+  includeMetadata: z.boolean().default(false).describe('Include the token description and usage guidelines in each result (default false).').optional()
 });

package/dist/esm/tools/search-tokens/search-tokens-tool.js

@@ -71,6 +71,7 @@ export var searchTokensTool = /*#__PURE__*/function () {
               name: item.name,
               exampleValue: item.exampleValue
             }, includeMetadata ? {
+              description: item.description,
               usageGuidelines: item.usageGuidelines
             } : {});
           });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/ads-mcp",
-	"version": "1.10.12",
+	"version": "1.11.0",
 	"description": "The official Atlassian Design System MCP server to develop apps and user interfaces matching the Atlassian style.",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",