@atlaskit/ads-mcp 1.7.4 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @atlaskit/ads-mcp
 
+## 1.8.0
+
+### Minor Changes
+
+- [`7b42e3dbea8db`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/7b42e3dbea8db) -
+  Add an opt-in `includeMetadata` option to ADS MCP token search so callers can retrieve token usage
+  guidelines while existing searches remain compact by default.
+
+  ```ts
+  import { searchTokensTool } from '@atlaskit/ads-mcp/tools/search-tokens';
+
+  await searchTokensTool({
+  	terms: ['border.width.focused'],
+  	includeMetadata: true,
+  });
+  ```
+
+  Metadata-inclusive results contain the existing `name` and `exampleValue` fields plus
+  `usageGuidelines`:
+
+  ```json
+  {
+  	"name": "border.width.focused",
+  	"exampleValue": "0.125rem",
+  	"usageGuidelines": {
+  		"usage": "Controls the thickness of borders/dividers. Use to standardize border widths throughout UI.",
+  		"cssProperties": ["border-width"]
+  	}
+  }
+  ```
+
 ## 1.7.4
 
 ### Patch Changes

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 JSON objects with **name** and **exampleValue** for each match (search also considers description, usage guidelines, and CSS property hints in metadata).\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 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

@@ -9,5 +9,6 @@ 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()
+  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()
 });

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

@@ -6,21 +6,22 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.searchTokensTool = void 0;
 var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
 var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
 var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
 var _fuse = _interopRequireDefault(require("fuse.js"));
 var _tokenMetadata = require("@atlaskit/tokens/token-metadata");
 var _helpers = require("../../helpers");
 var _cleanQuery = require("../../helpers/clean-query");
-/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
-
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { (0, _defineProperty2.default)(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; } /* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
 var searchTokensTool = exports.searchTokensTool = /*#__PURE__*/function () {
   var _ref2 = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(_ref) {
-    var terms, _ref$limit, limit, searchTerms, fuse, matchedItems, matchedTokens;
+    var terms, _ref$limit, limit, _ref$includeMetadata, includeMetadata, searchTerms, fuse, matchedItems, matchedTokens;
     return _regenerator.default.wrap(function (_context) {
       while (1) switch (_context.prev = _context.next) {
         case 0:
-          terms = _ref.terms, _ref$limit = _ref.limit, limit = _ref$limit === void 0 ? 2 : _ref$limit;
+          terms = _ref.terms, _ref$limit = _ref.limit, limit = _ref$limit === void 0 ? 2 : _ref$limit, _ref$includeMetadata = _ref.includeMetadata, includeMetadata = _ref$includeMetadata === void 0 ? false : _ref$includeMetadata;
           // Unique cleaned terms (order preserved) so duplicates don't concatenate into a bogus query.
           searchTerms = (0, _toConsumableArray2.default)(new Set(terms.filter(Boolean).map(_cleanQuery.cleanQuery)));
           if (searchTerms.length) {
@@ -71,10 +72,12 @@ var searchTokensTool = exports.searchTokensTool = /*#__PURE__*/function () {
             searchTermsJoin: '.'
           });
           matchedTokens = matchedItems.map(function (item) {
-            return {
+            return _objectSpread({
               name: item.name,
               exampleValue: item.exampleValue
-            };
+            }, includeMetadata ? {
+              usageGuidelines: item.usageGuidelines
+            } : {});
           });
           if (matchedTokens.length) {
             _context.next = 2;

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 JSON objects with **name** and **exampleValue** for each match (search also considers description, usage guidelines, and CSS property hints in metadata).
+  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.
 
 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

@@ -2,5 +2,6 @@
 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()
+  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()
 });

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

@@ -6,7 +6,8 @@ import { mergeMultiTermFuseResults } from '../../helpers';
 import { cleanQuery } from '../../helpers/clean-query';
 export const searchTokensTool = async ({
   terms,
-  limit = 2
+  limit = 2,
+  includeMetadata = false
 }) => {
   // Unique cleaned terms (order preserved) so duplicates don't concatenate into a bogus query.
   const searchTerms = [...new Set(terms.filter(Boolean).map(cleanQuery))];
@@ -54,7 +55,10 @@ export const searchTokensTool = async ({
   });
   const matchedTokens = matchedItems.map(item => ({
     name: item.name,
-    exampleValue: item.exampleValue
+    exampleValue: item.exampleValue,
+    ...(includeMetadata ? {
+      usageGuidelines: item.usageGuidelines
+    } : {})
   }));
   if (!matchedTokens.length) {
     return {

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 JSON objects with **name** and **exampleValue** for each match (search also considers description, usage guidelines, and CSS property hints in metadata).\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 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

@@ -2,5 +2,6 @@
 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()
+  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()
 });

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

@@ -1,6 +1,9 @@
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
 import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
 import _asyncToGenerator from "@babel/runtime/helpers/asyncToGenerator";
 import _regeneratorRuntime from "@babel/runtime/regenerator";
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
 /* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
 
 import Fuse from 'fuse.js';
@@ -9,11 +12,11 @@ import { mergeMultiTermFuseResults } from '../../helpers';
 import { cleanQuery } from '../../helpers/clean-query';
 export var searchTokensTool = /*#__PURE__*/function () {
   var _ref2 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee(_ref) {
-    var terms, _ref$limit, limit, searchTerms, fuse, matchedItems, matchedTokens;
+    var terms, _ref$limit, limit, _ref$includeMetadata, includeMetadata, searchTerms, fuse, matchedItems, matchedTokens;
     return _regeneratorRuntime.wrap(function (_context) {
       while (1) switch (_context.prev = _context.next) {
         case 0:
-          terms = _ref.terms, _ref$limit = _ref.limit, limit = _ref$limit === void 0 ? 2 : _ref$limit;
+          terms = _ref.terms, _ref$limit = _ref.limit, limit = _ref$limit === void 0 ? 2 : _ref$limit, _ref$includeMetadata = _ref.includeMetadata, includeMetadata = _ref$includeMetadata === void 0 ? false : _ref$includeMetadata;
           // Unique cleaned terms (order preserved) so duplicates don't concatenate into a bogus query.
           searchTerms = _toConsumableArray(new Set(terms.filter(Boolean).map(cleanQuery)));
           if (searchTerms.length) {
@@ -64,10 +67,12 @@ export var searchTokensTool = /*#__PURE__*/function () {
             searchTermsJoin: '.'
           });
           matchedTokens = matchedItems.map(function (item) {
-            return {
+            return _objectSpread({
               name: item.name,
               exampleValue: item.exampleValue
-            };
+            }, includeMetadata ? {
+              usageGuidelines: item.usageGuidelines
+            } : {});
           });
           if (matchedTokens.length) {
             _context.next = 2;

package/dist/types/tools/search-tokens/search-tokens-input-schema.d.ts

@@ -2,10 +2,13 @@ import { z } from 'zod';
 export declare const searchTokensInputSchema: z.ZodObject<{
     terms: z.ZodArray<z.ZodString, 'many'>;
     limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    includeMetadata: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
 }, 'strip', z.ZodTypeAny, {
     terms: string[];
     limit?: number | undefined;
+    includeMetadata?: boolean | undefined;
 }, {
     terms: string[];
     limit?: number | undefined;
+    includeMetadata?: boolean | undefined;
 }>;

package/dist/types/tools/search-tokens/search-tokens-tool.d.ts

@@ -1,4 +1,4 @@
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import { type z } from 'zod';
 import { type searchTokensInputSchema } from './search-tokens-input-schema';
-export declare const searchTokensTool: ({ terms, limit, }: z.infer<typeof searchTokensInputSchema>) => Promise<CallToolResult>;
+export declare const searchTokensTool: ({ terms, limit, includeMetadata, }: z.infer<typeof searchTokensInputSchema>) => Promise<CallToolResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/ads-mcp",
-	"version": "1.7.4",
+	"version": "1.8.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",
@@ -24,7 +24,7 @@
 		"@atlaskit/icon": "^37.3.0",
 		"@atlaskit/icon-lab": "^7.5.0",
 		"@atlaskit/platform-feature-flags": "^2.1.0",
-		"@atlaskit/tokens": "^16.5.0",
+		"@atlaskit/tokens": "^16.6.0",
 		"@axe-core/playwright": "^4.11.1",
 		"@axe-core/puppeteer": "^4.11.1",
 		"@babel/runtime": "^7.0.0",