@atlaskit/ads-mcp 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @atlaskit/ads-mcp
 
+## 0.4.0
+
+### Minor Changes
+
+- [`b89521ec6e0ab`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/b89521ec6e0ab) -
+  Replaced deprecated token and icon tools with new `get_all_tokens`, `search_tokens`,
+  `get_all_icons`, and `search_icons` (supporting multiple search terms with improved search
+  accuracy and optimised results), updated dependencies and instructions, refactored related files,
+  and enhanced search functionality and result limits for both tokens and icons.
+
 ## 0.3.0
 
 ### Minor Changes

package/dist/cjs/index.js

@@ -9,10 +9,12 @@ var _types = require("@modelcontextprotocol/sdk/types.js");
 var _instructions = require("./instructions");
 var _analyzeAccessibility = require("./tools/analyze-accessibility");
 var _getAccessibilityGuidelines = require("./tools/get-accessibility-guidelines");
+var _getAllIcons = require("./tools/get-all-icons");
+var _getAllTokens = require("./tools/get-all-tokens");
 var _getComponentDetails = require("./tools/get-component-details");
 var _getComponents = require("./tools/get-components");
-var _getIcons = require("./tools/get-icons");
-var _getTokens = require("./tools/get-tokens");
+var _searchIcons = require("./tools/search-icons");
+var _searchTokens = require("./tools/search-tokens");
 var _suggestAccessibilityFixes = require("./tools/suggest-accessibility-fixes");
 /* eslint-disable import/extensions */
 
@@ -33,7 +35,7 @@ server.setRequestHandler(_types.ListToolsRequestSchema, /*#__PURE__*/(0, _asyncT
     while (1) switch (_context.prev = _context.next) {
       case 0:
         return _context.abrupt("return", {
-          tools: [_getTokens.listGetTokensTool, _getComponents.listGetComponentsTool, _getComponentDetails.listGetComponentDetailsTool, _getIcons.listGetIconsTool, _analyzeAccessibility.listAnalyzeAccessibilityTool, _analyzeAccessibility.listAnalyzeLocalhostAccessibilityTool, _getAccessibilityGuidelines.listGetAccessibilityGuidelinesTool, _suggestAccessibilityFixes.listSuggestAccessibilityFixesTool]
+          tools: [_getAllTokens.listGetAllTokensTool, _getComponents.listGetComponentsTool, _getComponentDetails.listGetComponentDetailsTool, _getAllIcons.listGetAllIconsTool, _searchIcons.listSearchIconsTool, _searchTokens.listSearchTokensTool, _analyzeAccessibility.listAnalyzeAccessibilityTool, _analyzeAccessibility.listAnalyzeLocalhostAccessibilityTool, _getAccessibilityGuidelines.listGetAccessibilityGuidelinesTool, _suggestAccessibilityFixes.listSuggestAccessibilityFixesTool]
         });
       case 1:
       case "end":
@@ -42,10 +44,12 @@ server.setRequestHandler(_types.ListToolsRequestSchema, /*#__PURE__*/(0, _asyncT
   }, _callee);
 })));
 var callTools = {
-  get_tokens: _getTokens.getTokensTool,
+  get_all_tokens: _getAllTokens.getAllTokensTool,
+  search_tokens: _searchTokens.searchTokensTool,
   get_components: _getComponents.getComponentsTool,
   get_component_details: _getComponentDetails.getComponentDetailsTool,
-  get_icons: _getIcons.getIconsTool,
+  get_all_icons: _getAllIcons.getAllIconsTool,
+  search_icons: _searchIcons.searchIconsTool,
   analyze_accessibility: _analyzeAccessibility.analyzeAccessibilityTool,
   analyze_localhost_accessibility: _analyzeAccessibility.analyzeLocalhostAccessibilityTool,
   get_accessibility_guidelines: _getAccessibilityGuidelines.getAccessibilityGuidelinesTool,

package/dist/cjs/instructions.js

@@ -4,4 +4,4 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.instructions = void 0;
-var instructions = exports.instructions = "\nYou are an expert in the Atlassian Design System (aka ADS). You are able to answer questions about the design system and provide guidance on what offerings to use when building user interfaces.\n\nYou have special expertise in accessibility and can help ensure that interfaces built with ADS components are accessible to all users. You can analyze code for accessibility violations, provide specific fix suggestions, and offer guidance on accessibility best practices.\n\nYou are able to use the provided tools to help answer your questions, but may also access https://atlassian.design/llms.txt, https://atlassian.design/llms-a11y.txt, or https://atlassian.design/ directly for deeper research and information.\n\nAccessibility Tools Available:\n- analyze_accessibility: Analyze React component code for accessibility violations\n- get_accessibility_guidelines: Get specific accessibility guidelines and best practices\n- suggest_accessibility_fixes: Get specific fix suggestions for accessibility violations\n";
+var instructions = exports.instructions = "\nYou are an expert in the Atlassian Design System (aka ADS). You are able to answer questions about the design system and provide guidance on what offerings to use when building user interfaces.\n\nYou have special expertise in accessibility and can help ensure that interfaces built with ADS components are accessible to all users. You can analyze code for accessibility violations, provide specific fix suggestions, and offer guidance on accessibility best practices.\n\nYou are able to use the provided tools to help answer your questions, but may also access https://atlassian.design/llms.txt, https://atlassian.design/llms-a11y.txt, or https://atlassian.design/ directly for deeper research and information.\n\nAccessibility Tools Available:\n- analyze_accessibility: Analyze React component code for accessibility violations\n- get_accessibility_guidelines: Get specific accessibility guidelines and best practices\n- suggest_accessibility_fixes: Get specific fix suggestions for accessibility violations\n- get_all_tokens: Get all tokens and their example values\n- search_tokens: Search for token(s) and their example value(s)\n- get_all_icons: Get all icons and their usage\n- search_icons: Search for icon(s) and their usage\n";

package/dist/cjs/tools/{get-icons → get-all-icons}/index.js

@@ -4,7 +4,7 @@ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefau
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.listGetIconsTool = exports.getIconsTool = void 0;
+exports.listGetAllIconsTool = exports.getAllIconsTool = void 0;
 var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
 var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
 var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
@@ -25,9 +25,9 @@ var icons = Object.entries(_metadata.coreIconMetadata).map(function (_ref) {
     shouldRecommendSmallIcon: icon.shouldRecommendSmallIcon
   };
 });
-var listGetIconsTool = exports.listGetIconsTool = {
-  name: 'get_icons',
-  description: "You MUST use this to fetch all Atlassian Design System icons and parse their names, package, and understand how they're used (provided in JSON format) before working with iconography.\nThese are the only icons to be used in modern code, though other legacy icons may still be found, these are not to be used by you, but you can keep them if you see them in existing code.\nThe resulting icon name and package is often like this:\n```tsx\nimport AddIcon from '@atlaskit/icon/core/add';\n\n// Usage in isolation\n<AddIcon label=\"Add\" />\n\n// Usage with a button\nimport Button from '@atlaskit/button/new';\n<Button iconAfter={AddIcon}>Create</Button>\n```\n",
+var listGetAllIconsTool = exports.listGetAllIconsTool = {
+  name: 'get_all_icons',
+  description: "You SHOULD call this when you need complete guidance on what icons to use, but you SHOULD use the `search_icons` tool to find specific icons instead.\nThese are the only icons to be used in modern code, though other legacy icons may still be found, these are not to be used by you, but you can keep them if you see them in existing code.\nThe resulting icon name and package is often like this:\n```tsx\nimport AddIcon from '@atlaskit/icon/core/add';\n\n// Usage in isolation\n<AddIcon label=\"Add\" />\n\n// Usage with a button\nimport Button from '@atlaskit/button/new';\n<Button iconAfter={AddIcon}>Create</Button>\n```\n",
   annotations: {
     title: 'Get ADS icons',
     readOnlyHint: true,
@@ -37,7 +37,7 @@ var listGetIconsTool = exports.listGetIconsTool = {
   },
   inputSchema: _schema.emptyInputSchema
 };
-var getIconsTool = exports.getIconsTool = /*#__PURE__*/function () {
+var getAllIconsTool = exports.getAllIconsTool = /*#__PURE__*/function () {
   var _ref3 = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee() {
     return _regenerator.default.wrap(function _callee$(_context) {
       while (1) switch (_context.prev = _context.next) {
@@ -58,7 +58,7 @@ var getIconsTool = exports.getIconsTool = /*#__PURE__*/function () {
       }
     }, _callee);
   }));
-  return function getIconsTool() {
+  return function getAllIconsTool() {
     return _ref3.apply(this, arguments);
   };
 }();

package/dist/cjs/tools/{get-tokens → get-all-tokens}/index.js

@@ -4,18 +4,18 @@ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefau
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.listGetTokensTool = exports.getTokensTool = void 0;
+exports.listGetAllTokensTool = exports.getAllTokensTool = void 0;
 var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
 var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
 var _zod = require("zod");
 var _zodToJsonSchema = require("zod-to-json-schema");
 var _tokenMetadata = require("@atlaskit/tokens/token-metadata");
 var inputSchema = _zod.z.object({});
-var listGetTokensTool = exports.listGetTokensTool = {
-  name: 'get_tokens',
-  description: "You MUST use this to fetch all Atlassian Design System tokens and parse their names and descriptions (provided in JSON format) before working with tokens.\nThese tokens are used in place of hardcoded values; you should never use a hardcoded value where a token value is appropriate.\nThe resulting token name is used inside of the `token()` function, eg.:\n```tsx\nimport { token } from '@atlaskit/tokens';\nconst styles = css({ color: token('color.text') });\n```\n",
+var listGetAllTokensTool = exports.listGetAllTokensTool = {
+  name: 'get_all_tokens',
+  description: "You SHOULD call this when you need complete guidance on what tokens to use, but you SHOULD use the `search_tokens` tool to find specific tokens instead.\n\tThese tokens are used in place of hardcoded values; you should never use a hardcoded value where a token value is appropriate.\n\tThe resulting token name is used inside of the `token()` function, eg.:\n\t```tsx\n\timport { token } from '@atlaskit/tokens';\n\tconst styles = css({ color: token('color.text') });\n\t```\n\t",
   annotations: {
-    title: 'Get ADS tokens',
+    title: 'Get all ADS tokens',
     readOnlyHint: true,
     destructiveHint: false,
     idempotentHint: true,
@@ -23,7 +23,7 @@ var listGetTokensTool = exports.listGetTokensTool = {
   },
   inputSchema: (0, _zodToJsonSchema.zodToJsonSchema)(inputSchema)
 };
-var getTokensTool = exports.getTokensTool = /*#__PURE__*/function () {
+var getAllTokensTool = exports.getAllTokensTool = /*#__PURE__*/function () {
   var _ref = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee() {
     return _regenerator.default.wrap(function _callee$(_context) {
       while (1) switch (_context.prev = _context.next) {
@@ -36,7 +36,6 @@ var getTokensTool = exports.getTokensTool = /*#__PURE__*/function () {
                 type: 'text',
                 text: JSON.stringify({
                   name: token.name,
-                  description: token.description,
                   exampleValue: token.exampleValue
                 }, null, 2)
               };
@@ -48,7 +47,7 @@ var getTokensTool = exports.getTokensTool = /*#__PURE__*/function () {
       }
     }, _callee);
   }));
-  return function getTokensTool() {
+  return function getAllTokensTool() {
     return _ref.apply(this, arguments);
   };
 }();

package/dist/cjs/tools/search-icons/index.js

@@ -0,0 +1,138 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.searchIconsTool = exports.listSearchIconsTool = void 0;
+var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
+var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
+var _fuse = _interopRequireDefault(require("fuse.js"));
+var _zod = require("zod");
+var _zodToJsonSchema = require("zod-to-json-schema");
+var _metadata = require("@atlaskit/icon/metadata");
+var inputSchema = _zod.z.object({
+  terms: _zod.z.array(_zod.z.string()).describe('Search term(s) to find icons by name, keywords, or categorization'),
+  limit: _zod.z.number().optional().default(1).describe('Maximum number of results per term to return (default: 1)'),
+  exactName: _zod.z.boolean().optional().default(false).describe('Whether to search for exact match only for the icon name')
+});
+var icons = Object.entries(_metadata.coreIconMetadata).map(function (_ref) {
+  var _ref2 = (0, _slicedToArray2.default)(_ref, 2),
+    _key = _ref2[0],
+    icon = _ref2[1];
+  return {
+    componentName: icon.componentName,
+    package: icon.package,
+    categorization: icon.categorization,
+    keywords: icon.keywords,
+    status: icon.status,
+    usage: icon.usage,
+    type: icon.type,
+    shouldRecommendSmallIcon: icon.shouldRecommendSmallIcon
+  };
+}).filter(function (icon) {
+  return icon.status === 'published';
+});
+var listSearchIconsTool = exports.listSearchIconsTool = {
+  name: 'search_icons',
+  description: "You SHOULD Search for Atlassian Design System icons based on multiple query strings (if there's multiple candidates of icon names, categorization or keywords, you SHOULD pass them in a single call). You SHOULD use default `limit` value of 1 first and only set a higher limit like 5 or 10 if you can't find the icon you need). Fallback to `get_all_icons` if nothing is found). This tool searches through component names, icon names, keywords, categorization, type and usage to find the most relevant design icons.\n\n\tThe search will match against:\n\t- Icon component names (e.g., \"AddIcon\", \"DeleteIcon\", \"EditIcon\")\n\t- Icon keywords (descriptive terms associated with icons)\n\t- Icon categorization (e.g., \"single-purpose\", \"multi-purpose\", \"utility\")\n\t- Icon usage descriptions (usage guidelines for the icon)\n\n\tThe results include the icon's component name, package path, and usage guidelines.\n\n\tUsage pattern for found icons:\n\t```tsx\n\timport AddIcon from '@atlaskit/icon/core/add';\n\n\t// Usage in isolation\n\t<AddIcon label=\"Add\" size=\"small\" />\n\n\t// Usage with a button\n\timport Button from '@atlaskit/button/new';\n\t<Button iconAfter={AddIcon}>Create</Button>\n\t```\n\n\tYou SHOULD check proper usage (props, example usage, etc.) of the icon component using `get_component_details` tool before using this tool.\n\t",
+  annotations: {
+    title: 'Search ADS icons',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: (0, _zodToJsonSchema.zodToJsonSchema)(inputSchema)
+};
+var cleanQuery = function cleanQuery(query) {
+  return query.trim().toLowerCase().replace(/\s+/g, '');
+};
+var searchIconsTool = exports.searchIconsTool = /*#__PURE__*/function () {
+  var _ref3 = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(params) {
+    var terms, _params$limit, limit, _params$exactName, exactName, searchTerms, exactNameMatches, fuse, results, matchedIcons;
+    return _regenerator.default.wrap(function _callee$(_context) {
+      while (1) switch (_context.prev = _context.next) {
+        case 0:
+          terms = params.terms, _params$limit = params.limit, limit = _params$limit === void 0 ? 1 : _params$limit, _params$exactName = params.exactName, exactName = _params$exactName === void 0 ? false : _params$exactName;
+          searchTerms = terms.filter(Boolean).map(cleanQuery);
+          if (!exactName) {
+            _context.next = 6;
+            break;
+          }
+          // for each search term, search for the exact match
+          exactNameMatches = searchTerms.map(function (term) {
+            return icons.find(function (icon) {
+              return icon.componentName.toLowerCase() === term.toLowerCase();
+            });
+          }).filter(Boolean);
+          if (!(exactNameMatches.length > 0)) {
+            _context.next = 6;
+            break;
+          }
+          return _context.abrupt("return", {
+            content: [{
+              type: 'text',
+              text: JSON.stringify(exactNameMatches)
+            }]
+          });
+        case 6:
+          // use Fuse.js to fuzzy-search through the icons
+          fuse = new _fuse.default(icons, {
+            keys: [{
+              name: 'componentName',
+              weight: 3
+            }, {
+              name: 'iconName',
+              weight: 3
+            }, {
+              name: 'keywords',
+              weight: 2
+            }, {
+              name: 'categorization',
+              weight: 1
+            }, {
+              name: 'type',
+              weight: 1
+            }, {
+              name: 'usage',
+              weight: 1
+            }],
+            threshold: 0.4
+          }); // every search term, search for the results
+          results = searchTerms.map(function (term) {
+            // always search exact match from the icons
+            var exactNameMatch = icons.find(function (icon) {
+              return icon.componentName.toLowerCase() === term.toLowerCase();
+            });
+            if (exactNameMatch) {
+              return [{
+                item: exactNameMatch
+              }];
+            }
+            return fuse.search(term).slice(0, limit);
+          }).flat();
+          matchedIcons = results.map(function (result) {
+            return {
+              componentName: result.item.componentName,
+              package: result.item.package,
+              usage: result.item.usage
+            };
+          });
+          return _context.abrupt("return", {
+            content: [{
+              type: 'text',
+              text: JSON.stringify(matchedIcons)
+            }]
+          });
+        case 10:
+        case "end":
+          return _context.stop();
+      }
+    }, _callee);
+  }));
+  return function searchIconsTool(_x) {
+    return _ref3.apply(this, arguments);
+  };
+}();

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

@@ -0,0 +1,106 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.searchTokensTool = exports.listSearchTokensTool = void 0;
+var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
+var _fuse = _interopRequireDefault(require("fuse.js"));
+var _zod = require("zod");
+var _zodToJsonSchema = require("zod-to-json-schema");
+var _tokenMetadata = require("@atlaskit/tokens/token-metadata");
+var inputSchema = _zod.z.object({
+  terms: _zod.z.array(_zod.z.string()).describe('Search term(s) to find tokens by name or description'),
+  limit: _zod.z.number().optional().default(1).describe('Maximum number of results per term to return (default: 1)'),
+  exactName: _zod.z.boolean().optional().default(false).describe('Whether to search for exact match only for the token name')
+});
+var cleanQuery = function cleanQuery(query) {
+  return query.trim().toLowerCase().replace(/\s+/g, '');
+};
+var listSearchTokensTool = exports.listSearchTokensTool = {
+  name: 'search_tokens',
+  description: "You SHOULD Search for Atlassian Design System tokens based on multiple query strings (if there's multiple candidates of token names, descriptions or example values, you SHOULD pass them in a single call). You SHOULD use default `limit` value of 1 first and only set a higher limit like 5 or 10 if you can't find the token you need). Fallback to `get_all_tokens` if nothing is found). This tool searches through token names, descriptions, and example values to find the most relevant design tokens.\n\nThe search will match against:\n- Token names (e.g., \"color.text\", \"space.100\", \"border.radius\")\n- Token descriptions\n- Token example values (eg. \"#2898BD\" -> \"color.icon.accent.teal\")\n\nThe results include the token's name and example value.\n\nUsage pattern for found tokens:\n```tsx\nimport { token } from '@atlaskit/tokens';\n\nconst styles = css({\ncolor: token('color.text'),\npadding: token('space.100'),\nborderRadius: token('border.radius'),\n});\n```\n",
+  annotations: {
+    title: 'Search ADS tokens',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: (0, _zodToJsonSchema.zodToJsonSchema)(inputSchema)
+};
+var searchTokensTool = exports.searchTokensTool = /*#__PURE__*/function () {
+  var _ref = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(params) {
+    var terms, _params$limit, limit, _params$exactName, exactName, searchTerms, exactNameMatches, fuse, results, matchedTokens;
+    return _regenerator.default.wrap(function _callee$(_context) {
+      while (1) switch (_context.prev = _context.next) {
+        case 0:
+          terms = params.terms, _params$limit = params.limit, limit = _params$limit === void 0 ? 1 : _params$limit, _params$exactName = params.exactName, exactName = _params$exactName === void 0 ? false : _params$exactName;
+          searchTerms = terms.filter(Boolean).map(cleanQuery);
+          if (!exactName) {
+            _context.next = 6;
+            break;
+          }
+          // for each search term, search for the exact match
+          exactNameMatches = searchTerms.map(function (term) {
+            return _tokenMetadata.tokens.find(function (token) {
+              return token.name.toLowerCase() === term.toLowerCase();
+            });
+          }).filter(Boolean);
+          if (!(exactNameMatches.length > 0)) {
+            _context.next = 6;
+            break;
+          }
+          return _context.abrupt("return", {
+            content: [{
+              type: 'text',
+              text: JSON.stringify(exactNameMatches.map(function (token) {
+                return {
+                  name: token.name,
+                  exampleValue: token.exampleValue
+                };
+              }))
+            }]
+          });
+        case 6:
+          // use Fuse.js to fuzzy-search for the tokens
+          fuse = new _fuse.default(_tokenMetadata.tokens, {
+            keys: [{
+              name: 'name',
+              weight: 3
+            }, {
+              name: 'description',
+              weight: 2
+            }, {
+              name: 'exampleValue',
+              weight: 1
+            }],
+            threshold: 0.4
+          });
+          results = searchTerms.map(function (term) {
+            return fuse.search(term).slice(0, limit);
+          }).flat();
+          matchedTokens = results.map(function (result) {
+            return {
+              name: result.item.name,
+              exampleValue: result.item.exampleValue
+            };
+          });
+          return _context.abrupt("return", {
+            content: [{
+              type: 'text',
+              text: JSON.stringify(matchedTokens)
+            }]
+          });
+        case 10:
+        case "end":
+          return _context.stop();
+      }
+    }, _callee);
+  }));
+  return function searchTokensTool(_x) {
+    return _ref.apply(this, arguments);
+  };
+}();

package/dist/cjs/tools/suggest-accessibility-fixes/fixes.js

@@ -254,7 +254,7 @@ var accessibilityFixes = exports.accessibilityFixes = {
       description: 'Provide table caption for complex tables',
       before: "<table>\n  <thead>...</thead>\n</table>",
       after: "<table>\n  <caption>User account information by department</caption>\n  <thead>...</thead>\n</table>",
-      explanation: 'Captions provide context about the table\'s purpose and structure.'
+      explanation: "Captions provide context about the table's purpose and structure."
     }],
     bestPractices: ['Use th elements for headers', 'Add scope attributes (col, row)', 'Provide table captions when helpful', 'Use thead, tbody, tfoot for structure']
   },

package/dist/es2019/index.js

@@ -5,10 +5,12 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprot
 import { instructions } from './instructions';
 import { analyzeAccessibilityTool, analyzeLocalhostAccessibilityTool, listAnalyzeAccessibilityTool, listAnalyzeLocalhostAccessibilityTool } from './tools/analyze-accessibility';
 import { getAccessibilityGuidelinesTool, listGetAccessibilityGuidelinesTool } from './tools/get-accessibility-guidelines';
+import { getAllIconsTool, listGetAllIconsTool } from './tools/get-all-icons';
+import { getAllTokensTool, listGetAllTokensTool } from './tools/get-all-tokens';
 import { getComponentDetailsTool, listGetComponentDetailsTool } from './tools/get-component-details';
 import { getComponentsTool, listGetComponentsTool } from './tools/get-components';
-import { getIconsTool, listGetIconsTool } from './tools/get-icons';
-import { getTokensTool, listGetTokensTool } from './tools/get-tokens';
+import { listSearchIconsTool, searchIconsTool } from './tools/search-icons';
+import { listSearchTokensTool, searchTokensTool } from './tools/search-tokens';
 import { listSuggestAccessibilityFixesTool, suggestAccessibilityFixesTool } from './tools/suggest-accessibility-fixes';
 
 // eslint-disable-next-line import/no-extraneous-dependencies -- this uses require because not all node versions this package supports use the same import assertions/attributes
@@ -25,14 +27,16 @@ const server = new Server({
 });
 server.setRequestHandler(ListToolsRequestSchema, async () => {
   return {
-    tools: [listGetTokensTool, listGetComponentsTool, listGetComponentDetailsTool, listGetIconsTool, listAnalyzeAccessibilityTool, listAnalyzeLocalhostAccessibilityTool, listGetAccessibilityGuidelinesTool, listSuggestAccessibilityFixesTool]
+    tools: [listGetAllTokensTool, listGetComponentsTool, listGetComponentDetailsTool, listGetAllIconsTool, listSearchIconsTool, listSearchTokensTool, listAnalyzeAccessibilityTool, listAnalyzeLocalhostAccessibilityTool, listGetAccessibilityGuidelinesTool, listSuggestAccessibilityFixesTool]
   };
 });
 const callTools = {
-  get_tokens: getTokensTool,
+  get_all_tokens: getAllTokensTool,
+  search_tokens: searchTokensTool,
   get_components: getComponentsTool,
   get_component_details: getComponentDetailsTool,
-  get_icons: getIconsTool,
+  get_all_icons: getAllIconsTool,
+  search_icons: searchIconsTool,
   analyze_accessibility: analyzeAccessibilityTool,
   analyze_localhost_accessibility: analyzeLocalhostAccessibilityTool,
   get_accessibility_guidelines: getAccessibilityGuidelinesTool,

package/dist/es2019/instructions.js

@@ -9,4 +9,8 @@ Accessibility Tools Available:
 - analyze_accessibility: Analyze React component code for accessibility violations
 - get_accessibility_guidelines: Get specific accessibility guidelines and best practices
 - suggest_accessibility_fixes: Get specific fix suggestions for accessibility violations
+- get_all_tokens: Get all tokens and their example values
+- search_tokens: Search for token(s) and their example value(s)
+- get_all_icons: Get all icons and their usage
+- search_icons: Search for icon(s) and their usage
 `;

package/dist/es2019/tools/{get-icons → get-all-icons}/index.js

@@ -10,9 +10,9 @@ const icons = Object.entries(coreIconMetadata).map(([_key, icon]) => ({
   type: icon.type,
   shouldRecommendSmallIcon: icon.shouldRecommendSmallIcon
 }));
-export const listGetIconsTool = {
-  name: 'get_icons',
-  description: `You MUST use this to fetch all Atlassian Design System icons and parse their names, package, and understand how they're used (provided in JSON format) before working with iconography.
+export const listGetAllIconsTool = {
+  name: 'get_all_icons',
+  description: `You SHOULD call this when you need complete guidance on what icons to use, but you SHOULD use the \`search_icons\` tool to find specific icons instead.
 These are the only icons to be used in modern code, though other legacy icons may still be found, these are not to be used by you, but you can keep them if you see them in existing code.
 The resulting icon name and package is often like this:
 \`\`\`tsx
@@ -35,7 +35,7 @@ import Button from '@atlaskit/button/new';
   },
   inputSchema: emptyInputSchema
 };
-export const getIconsTool = async () => ({
+export const getAllIconsTool = async () => ({
   content: icons.map(icon => ({
     // NOTE: Ideally one day the MCP would support structured content…
     // eg. `type: 'object', data: icon`

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

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { tokens } from '@atlaskit/tokens/token-metadata';
+const inputSchema = z.object({});
+export const listGetAllTokensTool = {
+  name: 'get_all_tokens',
+  description: `You SHOULD call this when you need complete guidance on what tokens to use, but you SHOULD use the \`search_tokens\` tool to find specific tokens instead.
+	These tokens are used in place of hardcoded values; you should never use a hardcoded value where a token value is appropriate.
+	The resulting token name is used inside of the \`token()\` function, eg.:
+	\`\`\`tsx
+	import { token } from '@atlaskit/tokens';
+	const styles = css({ color: token('color.text') });
+	\`\`\`
+	`,
+  annotations: {
+    title: 'Get all ADS tokens',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: zodToJsonSchema(inputSchema)
+};
+export const getAllTokensTool = async () => ({
+  content: tokens.map(token => ({
+    // NOTE: Ideally one day the MCP would support structured content…
+    // eg. `type: 'object', data: token`
+    type: 'text',
+    text: JSON.stringify({
+      name: token.name,
+      exampleValue: token.exampleValue
+    }, null, 2)
+  }))
+});

package/dist/es2019/tools/search-icons/index.js

@@ -0,0 +1,126 @@
+import Fuse from 'fuse.js';
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { coreIconMetadata } from '@atlaskit/icon/metadata';
+const inputSchema = z.object({
+  terms: z.array(z.string()).describe('Search term(s) to find icons by name, keywords, or categorization'),
+  limit: z.number().optional().default(1).describe('Maximum number of results per term to return (default: 1)'),
+  exactName: z.boolean().optional().default(false).describe('Whether to search for exact match only for the icon name')
+});
+const icons = Object.entries(coreIconMetadata).map(([_key, icon]) => ({
+  componentName: icon.componentName,
+  package: icon.package,
+  categorization: icon.categorization,
+  keywords: icon.keywords,
+  status: icon.status,
+  usage: icon.usage,
+  type: icon.type,
+  shouldRecommendSmallIcon: icon.shouldRecommendSmallIcon
+})).filter(icon => icon.status === 'published');
+export const listSearchIconsTool = {
+  name: 'search_icons',
+  description: `You SHOULD Search for Atlassian Design System icons based on multiple query strings (if there's multiple candidates of icon names, categorization or keywords, you SHOULD pass them in a single call). You SHOULD use default \`limit\` value of 1 first and only set a higher limit like 5 or 10 if you can't find the icon you need). Fallback to \`get_all_icons\` if nothing is found). This tool searches through component names, icon names, keywords, categorization, type and usage to find the most relevant design icons.
+
+	The search will match against:
+	- Icon component names (e.g., "AddIcon", "DeleteIcon", "EditIcon")
+	- Icon keywords (descriptive terms associated with icons)
+	- Icon categorization (e.g., "single-purpose", "multi-purpose", "utility")
+	- Icon usage descriptions (usage guidelines for the icon)
+
+	The results include the icon's component name, package path, and usage guidelines.
+
+	Usage pattern for found icons:
+	\`\`\`tsx
+	import AddIcon from '@atlaskit/icon/core/add';
+
+	// Usage in isolation
+	<AddIcon label="Add" size="small" />
+
+	// Usage with a button
+	import Button from '@atlaskit/button/new';
+	<Button iconAfter={AddIcon}>Create</Button>
+	\`\`\`
+
+	You SHOULD check proper usage (props, example usage, etc.) of the icon component using \`get_component_details\` tool before using this tool.
+	`,
+  annotations: {
+    title: 'Search ADS icons',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: zodToJsonSchema(inputSchema)
+};
+const cleanQuery = query => query.trim().toLowerCase().replace(/\s+/g, '');
+export const searchIconsTool = async params => {
+  const {
+    terms,
+    limit = 1,
+    exactName = false
+  } = params;
+  const searchTerms = terms.filter(Boolean).map(cleanQuery);
+  if (exactName) {
+    // for each search term, search for the exact match
+    const exactNameMatches = searchTerms.map(term => {
+      return icons.find(icon => icon.componentName.toLowerCase() === term.toLowerCase());
+    }).filter(Boolean);
+    if (exactNameMatches.length > 0) {
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(exactNameMatches)
+        }]
+      };
+    }
+  }
+
+  // use Fuse.js to fuzzy-search through the icons
+  const fuse = new Fuse(icons, {
+    keys: [{
+      name: 'componentName',
+      weight: 3
+    }, {
+      name: 'iconName',
+      weight: 3
+    }, {
+      name: 'keywords',
+      weight: 2
+    }, {
+      name: 'categorization',
+      weight: 1
+    }, {
+      name: 'type',
+      weight: 1
+    }, {
+      name: 'usage',
+      weight: 1
+    }],
+    threshold: 0.4
+  });
+
+  // every search term, search for the results
+  const results = searchTerms.map(term => {
+    // always search exact match from the icons
+    const exactNameMatch = icons.find(icon => icon.componentName.toLowerCase() === term.toLowerCase());
+    if (exactNameMatch) {
+      return [{
+        item: exactNameMatch
+      }];
+    }
+    return fuse.search(term).slice(0, limit);
+  }).flat();
+  const matchedIcons = results.map(result => {
+    return {
+      componentName: result.item.componentName,
+      package: result.item.package,
+      usage: result.item.usage
+    };
+  });
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify(matchedIcons)
+    }]
+  };
+};