@atlaskit/ads-mcp 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @atlaskit/ads-mcp
 
+## 0.5.0
+
+### Minor Changes
+
+- [`0276dc4a39d9d`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/0276dc4a39d9d) -
+  Renamed `get_component_details` to `search_components` tool and adjusted related references in the
+  codebase and improved querying of components.
+
+## 0.4.1
+
+### Patch Changes
+
+- [`217beed112e9f`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/217beed112e9f) -
+  fix broken import
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -12,10 +12,39 @@ to help ensure your interfaces are accessible to all users.
 
 ### Design System Tools
 
-- `get_tokens` - Get design tokens for colors, spacing, typography, etc.
-- `get_components` - Get a list of available components
-- `get_component_details` - Get detailed information about a specific component
-- `get_icons` - Get a list of available icons
+- `get_all_tokens` - Get all available design tokens for colors, spacing, typography, etc.
+- `search_tokens` - Search for specific design tokens by name, description, or example values
+- `get_components` - Get a list of all available components with basic information
+- `search_components` - Search for components by name, description, category, or package name
+- `get_all_icons` - Get all available icons from the design system
+- `search_icons` - Search for specific icons by name, keywords, or categorization
+
+#### Design System Tools Usage
+
+```typescript
+// Search for components (recommended approach)
+const buttonComponents = await search_components({
+  terms: ['button', 'click'],
+  limit: 3
+});
+
+// Search for specific tokens
+const colorTokens = await search_tokens({
+  terms: ['color.text', 'primary'],
+  limit: 5
+});
+
+// Search for icons
+const addIcons = await search_icons({
+  terms: ['add', 'plus', 'create'],
+  limit: 2
+});
+
+// Get all available items (fallback when search doesn't find what you need)
+const allComponents = await get_components();
+const allTokens = await get_all_tokens();
+const allIcons = await get_all_icons();
+```
 
 ### Accessibility Tools
 

package/dist/cjs/helpers/index.js

@@ -0,0 +1,9 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.cleanQuery = void 0;
+var cleanQuery = exports.cleanQuery = function cleanQuery(query) {
+  return query.trim().toLowerCase().replace(/\s+/g, '');
+};

package/dist/cjs/index.js

@@ -11,8 +11,8 @@ 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 _searchComponents = require("./tools/search-components");
 var _searchIcons = require("./tools/search-icons");
 var _searchTokens = require("./tools/search-tokens");
 var _suggestAccessibilityFixes = require("./tools/suggest-accessibility-fixes");
@@ -35,7 +35,7 @@ server.setRequestHandler(_types.ListToolsRequestSchema, /*#__PURE__*/(0, _asyncT
     while (1) switch (_context.prev = _context.next) {
       case 0:
         return _context.abrupt("return", {
-          tools: [_getAllTokens.listGetAllTokensTool, _getComponents.listGetComponentsTool, _getComponentDetails.listGetComponentDetailsTool, _getAllIcons.listGetAllIconsTool, _searchIcons.listSearchIconsTool, _searchTokens.listSearchTokensTool, _analyzeAccessibility.listAnalyzeAccessibilityTool, _analyzeAccessibility.listAnalyzeLocalhostAccessibilityTool, _getAccessibilityGuidelines.listGetAccessibilityGuidelinesTool, _suggestAccessibilityFixes.listSuggestAccessibilityFixesTool]
+          tools: [_getAllTokens.listGetAllTokensTool, _getComponents.listGetComponentsTool, _searchComponents.listSearchComponentsTool, _getAllIcons.listGetAllIconsTool, _searchIcons.listSearchIconsTool, _searchTokens.listSearchTokensTool, _analyzeAccessibility.listAnalyzeAccessibilityTool, _analyzeAccessibility.listAnalyzeLocalhostAccessibilityTool, _getAccessibilityGuidelines.listGetAccessibilityGuidelinesTool, _suggestAccessibilityFixes.listSuggestAccessibilityFixesTool]
         });
       case 1:
       case "end":
@@ -47,7 +47,7 @@ var callTools = {
   get_all_tokens: _getAllTokens.getAllTokensTool,
   search_tokens: _searchTokens.searchTokensTool,
   get_components: _getComponents.getComponentsTool,
-  get_component_details: _getComponentDetails.getComponentDetailsTool,
+  search_components: _searchComponents.searchComponentsTool,
   get_all_icons: _getAllIcons.getAllIconsTool,
   search_icons: _searchIcons.searchIconsTool,
   analyze_accessibility: _analyzeAccessibility.analyzeAccessibilityTool,

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- 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";
+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";

package/dist/cjs/tools/get-components/index.js

@@ -19,7 +19,7 @@ var componentsList = _components.components.map(function (c) {
 });
 var listGetComponentsTool = exports.listGetComponentsTool = {
   name: 'get_components',
-  description: "You MUST use this to fetch all Atlassian Design System components and parse their names, descriptions, and understand how they might be used (provided in JSON format) before working with components.\nYou should never use a custom component not provided via this API where appropriate, or the custom component is a necessary wrapper around an ADS component.\n\nFor a full example, guidelines, list of props, and more information, you should use the `get_component_details` tool passing one or many component names as the 'names' tool parameter.\n",
+  description: "You MUST use this to fetch all Atlassian Design System components and parse their names, descriptions, and understand how they might be used (provided in JSON format) before working with components.\nYou should never use a custom component not provided via this API where appropriate, or the custom component is a necessary wrapper around an ADS component.\n\nFor a full example, guidelines, list of props, and more information, you should use the `search_components` tool passing one or many component names as the 'terms' tool parameter.\n",
   annotations: {
     title: 'Get ADS components',
     readOnlyHint: true,

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

@@ -0,0 +1,146 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.searchComponentsTool = exports.listSearchComponentsTool = 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 _helpers = require("../../helpers");
+var _components = require("../get-components/components");
+var inputSchema = _zod.z.object({
+  terms: _zod.z.array(_zod.z.string()).describe('Search term(s) to find components by name, package name, description, or example'),
+  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 component name')
+});
+var listSearchComponentsTool = exports.listSearchComponentsTool = {
+  name: 'search_components',
+  description: "You SHOULD use this to search for Atlassian Design System components based on multiple query strings (if there are multiple candidates of component names, descriptions, categories, or package names, 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 component you need. Fallback to `get_components` if nothing is found. This tool searches through component names, descriptions, categories, and package names to find the most relevant design system components.\n\nThe search will match against:\n- Component names (e.g., \"Button\", \"TextField\", \"Avatar\")\n- Package names (e.g., \"@atlaskit/button\", \"@atlaskit/textfield\")\n- Component descriptions (descriptive text about what the component does)\n- Component categories (e.g., \"Forms and Input\", \"Navigation\", \"Data Display\")\n\nThe results include the component's name, package name, example, and props.\n\nUsage pattern for found components:\n```tsx\nimport Button from '@atlaskit/button/new';\nimport CopyIcon from '@atlaskit/icon/core/copy';\n\n<Button appearance=\"primary\" iconBefore={CopyIcon}>Copy text</Button>\n```\n",
+  annotations: {
+    title: 'Search ADS components',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: (0, _zodToJsonSchema.zodToJsonSchema)(inputSchema)
+};
+
+// Clean component result to only return name, package name, example, and props
+var cleanComponentResult = function cleanComponentResult(result) {
+  return {
+    name: result.name,
+    packageName: result.packageName,
+    example: result.example,
+    props: result.props
+  };
+};
+var searchComponentsTool = exports.searchComponentsTool = /*#__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;
+    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(_helpers.cleanQuery);
+          if (searchTerms.length) {
+            _context.next = 4;
+            break;
+          }
+          return _context.abrupt("return", {
+            isError: true,
+            content: [{
+              type: 'text',
+              text: "Error: Required parameter 'terms' is missing or empty"
+            }]
+          });
+        case 4:
+          if (!exactName) {
+            _context.next = 8;
+            break;
+          }
+          // for each search term, search for the exact match
+          exactNameMatches = searchTerms.map(function (term) {
+            return _components.components.find(function (component) {
+              return component.name.toLowerCase() === term.toLowerCase();
+            });
+          }).filter(Boolean);
+          if (!(exactNameMatches.length > 0)) {
+            _context.next = 8;
+            break;
+          }
+          return _context.abrupt("return", {
+            content: [{
+              type: 'text',
+              text: JSON.stringify(exactNameMatches.map(cleanComponentResult))
+            }]
+          });
+        case 8:
+          // use Fuse.js to fuzzy-search through the components
+          fuse = new _fuse.default(_components.components, {
+            keys: [{
+              name: 'name',
+              weight: 3
+            }, {
+              name: 'packageName',
+              weight: 3
+            }, {
+              name: 'category',
+              weight: 2
+            }, {
+              name: 'description',
+              weight: 2
+            }, {
+              name: 'example',
+              weight: 1
+            }],
+            threshold: 0.4
+          }); // every search term, search for the results
+          results = searchTerms.map(function (term) {
+            // always search exact match from the components first
+            var exactNameMatch = _components.components.find(function (component) {
+              return component.name.toLowerCase() === term.toLowerCase();
+            });
+            if (exactNameMatch) {
+              return [{
+                item: exactNameMatch
+              }];
+            }
+            return fuse.search(term).slice(0, limit);
+          }).flat();
+          if (results.length) {
+            _context.next = 12;
+            break;
+          }
+          return _context.abrupt("return", {
+            isError: true,
+            content: [{
+              type: 'text',
+              text: "Error: No components found for '".concat(terms.join(', '), "'. Available components: ").concat(_components.components.map(function (c) {
+                return c.name;
+              }).join(', '))
+            }]
+          });
+        case 12:
+          return _context.abrupt("return", {
+            content: [{
+              type: 'text',
+              text: JSON.stringify(results.map(function (result) {
+                return result.item;
+              }).map(cleanComponentResult))
+            }]
+          });
+        case 13:
+        case "end":
+          return _context.stop();
+      }
+    }, _callee);
+  }));
+  return function searchComponentsTool(_x) {
+    return _ref.apply(this, arguments);
+  };
+}();

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

@@ -12,6 +12,7 @@ var _fuse = _interopRequireDefault(require("fuse.js"));
 var _zod = require("zod");
 var _zodToJsonSchema = require("zod-to-json-schema");
 var _metadata = require("@atlaskit/icon/metadata");
+var _helpers = require("../../helpers");
 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)'),
@@ -36,7 +37,7 @@ var icons = Object.entries(_metadata.coreIconMetadata).map(function (_ref) {
 });
 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",
+  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 `search_components` tool.\n\t",
   annotations: {
     title: 'Search ADS icons',
     readOnlyHint: true,
@@ -46,9 +47,6 @@ var listSearchIconsTool = exports.listSearchIconsTool = {
   },
   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;
@@ -56,9 +54,21 @@ var searchIconsTool = exports.searchIconsTool = /*#__PURE__*/function () {
       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);
+          searchTerms = terms.filter(Boolean).map(_helpers.cleanQuery);
+          if (searchTerms.length) {
+            _context.next = 4;
+            break;
+          }
+          return _context.abrupt("return", {
+            isError: true,
+            content: [{
+              type: 'text',
+              text: "Error: Required parameter 'terms' is missing or empty"
+            }]
+          });
+        case 4:
           if (!exactName) {
-            _context.next = 6;
+            _context.next = 8;
             break;
           }
           // for each search term, search for the exact match
@@ -68,7 +78,7 @@ var searchIconsTool = exports.searchIconsTool = /*#__PURE__*/function () {
             });
           }).filter(Boolean);
           if (!(exactNameMatches.length > 0)) {
-            _context.next = 6;
+            _context.next = 8;
             break;
           }
           return _context.abrupt("return", {
@@ -77,7 +87,7 @@ var searchIconsTool = exports.searchIconsTool = /*#__PURE__*/function () {
               text: JSON.stringify(exactNameMatches)
             }]
           });
-        case 6:
+        case 8:
           // use Fuse.js to fuzzy-search through the icons
           fuse = new _fuse.default(icons, {
             keys: [{
@@ -113,6 +123,20 @@ var searchIconsTool = exports.searchIconsTool = /*#__PURE__*/function () {
             }
             return fuse.search(term).slice(0, limit);
           }).flat();
+          if (results.length) {
+            _context.next = 12;
+            break;
+          }
+          return _context.abrupt("return", {
+            isError: true,
+            content: [{
+              type: 'text',
+              text: "Error: No icons found for '".concat(terms.join(', '), "'. Available icons: ").concat(icons.map(function (i) {
+                return i.componentName;
+              }).join(', '))
+            }]
+          });
+        case 12:
           matchedIcons = results.map(function (result) {
             return {
               componentName: result.item.componentName,
@@ -126,7 +150,7 @@ var searchIconsTool = exports.searchIconsTool = /*#__PURE__*/function () {
               text: JSON.stringify(matchedIcons)
             }]
           });
-        case 10:
+        case 14:
         case "end":
           return _context.stop();
       }

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

@@ -11,14 +11,12 @@ 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 _helpers = require("../../helpers");
 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",
@@ -38,7 +36,7 @@ var searchTokensTool = exports.searchTokensTool = /*#__PURE__*/function () {
       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);
+          searchTerms = terms.filter(Boolean).map(_helpers.cleanQuery);
           if (!exactName) {
             _context.next = 6;
             break;

package/dist/es2019/helpers/index.js

@@ -0,0 +1 @@
+export const cleanQuery = query => query.trim().toLowerCase().replace(/\s+/g, '');

package/dist/es2019/index.js

@@ -7,8 +7,8 @@ import { analyzeAccessibilityTool, analyzeLocalhostAccessibilityTool, listAnalyz
 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 { listSearchComponentsTool, searchComponentsTool } from './tools/search-components';
 import { listSearchIconsTool, searchIconsTool } from './tools/search-icons';
 import { listSearchTokensTool, searchTokensTool } from './tools/search-tokens';
 import { listSuggestAccessibilityFixesTool, suggestAccessibilityFixesTool } from './tools/suggest-accessibility-fixes';
@@ -27,14 +27,14 @@ const server = new Server({
 });
 server.setRequestHandler(ListToolsRequestSchema, async () => {
   return {
-    tools: [listGetAllTokensTool, listGetComponentsTool, listGetComponentDetailsTool, listGetAllIconsTool, listSearchIconsTool, listSearchTokensTool, listAnalyzeAccessibilityTool, listAnalyzeLocalhostAccessibilityTool, listGetAccessibilityGuidelinesTool, listSuggestAccessibilityFixesTool]
+    tools: [listGetAllTokensTool, listGetComponentsTool, listSearchComponentsTool, listGetAllIconsTool, listSearchIconsTool, listSearchTokensTool, listAnalyzeAccessibilityTool, listAnalyzeLocalhostAccessibilityTool, listGetAccessibilityGuidelinesTool, listSuggestAccessibilityFixesTool]
   };
 });
 const callTools = {
   get_all_tokens: getAllTokensTool,
   search_tokens: searchTokensTool,
   get_components: getComponentsTool,
-  get_component_details: getComponentDetailsTool,
+  search_components: searchComponentsTool,
   get_all_icons: getAllIconsTool,
   search_icons: searchIconsTool,
   analyze_accessibility: analyzeAccessibilityTool,

package/dist/es2019/instructions.js

@@ -4,13 +4,4 @@ You are an expert in the Atlassian Design System (aka ADS). You are able to answ
 You 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.
 
 You 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.
-
-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-components/index.js

@@ -11,7 +11,7 @@ export const listGetComponentsTool = {
   description: `You MUST use this to fetch all Atlassian Design System components and parse their names, descriptions, and understand how they might be used (provided in JSON format) before working with components.
 You should never use a custom component not provided via this API where appropriate, or the custom component is a necessary wrapper around an ADS component.
 
-For a full example, guidelines, list of props, and more information, you should use the \`get_component_details\` tool passing one or many component names as the 'names' tool parameter.
+For a full example, guidelines, list of props, and more information, you should use the \`search_components\` tool passing one or many component names as the 'terms' tool parameter.
 `,
   annotations: {
     title: 'Get ADS components',

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

@@ -0,0 +1,128 @@
+import Fuse from 'fuse.js';
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { cleanQuery } from '../../helpers';
+import { components } from '../get-components/components';
+const inputSchema = z.object({
+  terms: z.array(z.string()).describe('Search term(s) to find components by name, package name, description, or example'),
+  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 component name')
+});
+export const listSearchComponentsTool = {
+  name: 'search_components',
+  description: `You SHOULD use this to search for Atlassian Design System components based on multiple query strings (if there are multiple candidates of component names, descriptions, categories, or package names, 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 component you need. Fallback to \`get_components\` if nothing is found. This tool searches through component names, descriptions, categories, and package names to find the most relevant design system components.
+
+The search will match against:
+- Component names (e.g., "Button", "TextField", "Avatar")
+- Package names (e.g., "@atlaskit/button", "@atlaskit/textfield")
+- Component descriptions (descriptive text about what the component does)
+- Component categories (e.g., "Forms and Input", "Navigation", "Data Display")
+
+The results include the component's name, package name, example, and props.
+
+Usage pattern for found components:
+\`\`\`tsx
+import Button from '@atlaskit/button/new';
+import CopyIcon from '@atlaskit/icon/core/copy';
+
+<Button appearance="primary" iconBefore={CopyIcon}>Copy text</Button>
+\`\`\`
+`,
+  annotations: {
+    title: 'Search ADS components',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: zodToJsonSchema(inputSchema)
+};
+
+// Clean component result to only return name, package name, example, and props
+const cleanComponentResult = result => {
+  return {
+    name: result.name,
+    packageName: result.packageName,
+    example: result.example,
+    props: result.props
+  };
+};
+export const searchComponentsTool = async params => {
+  const {
+    terms,
+    limit = 1,
+    exactName = false
+  } = params;
+  const searchTerms = terms.filter(Boolean).map(cleanQuery);
+  if (!searchTerms.length) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: `Error: Required parameter 'terms' is missing or empty`
+      }]
+    };
+  }
+  if (exactName) {
+    // for each search term, search for the exact match
+    const exactNameMatches = searchTerms.map(term => {
+      return components.find(component => component.name.toLowerCase() === term.toLowerCase());
+    }).filter(Boolean);
+    if (exactNameMatches.length > 0) {
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(exactNameMatches.map(cleanComponentResult))
+        }]
+      };
+    }
+  }
+
+  // use Fuse.js to fuzzy-search through the components
+  const fuse = new Fuse(components, {
+    keys: [{
+      name: 'name',
+      weight: 3
+    }, {
+      name: 'packageName',
+      weight: 3
+    }, {
+      name: 'category',
+      weight: 2
+    }, {
+      name: 'description',
+      weight: 2
+    }, {
+      name: 'example',
+      weight: 1
+    }],
+    threshold: 0.4
+  });
+
+  // every search term, search for the results
+  const results = searchTerms.map(term => {
+    // always search exact match from the components first
+    const exactNameMatch = components.find(component => component.name.toLowerCase() === term.toLowerCase());
+    if (exactNameMatch) {
+      return [{
+        item: exactNameMatch
+      }];
+    }
+    return fuse.search(term).slice(0, limit);
+  }).flat();
+  if (!results.length) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: `Error: No components found for '${terms.join(', ')}'. Available components: ${components.map(c => c.name).join(', ')}`
+      }]
+    };
+  }
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify(results.map(result => result.item).map(cleanComponentResult))
+    }]
+  };
+};

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

@@ -2,6 +2,7 @@ import Fuse from 'fuse.js';
 import { z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import { coreIconMetadata } from '@atlaskit/icon/metadata';
+import { cleanQuery } from '../../helpers';
 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)'),
@@ -41,7 +42,7 @@ export const listSearchIconsTool = {
 	<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.
+	You SHOULD check proper usage (props, example usage, etc.) of the icon component using \`search_components\` tool.
 	`,
   annotations: {
     title: 'Search ADS icons',
@@ -52,7 +53,6 @@ export const listSearchIconsTool = {
   },
   inputSchema: zodToJsonSchema(inputSchema)
 };
-const cleanQuery = query => query.trim().toLowerCase().replace(/\s+/g, '');
 export const searchIconsTool = async params => {
   const {
     terms,
@@ -60,6 +60,15 @@ export const searchIconsTool = async params => {
     exactName = false
   } = params;
   const searchTerms = terms.filter(Boolean).map(cleanQuery);
+  if (!searchTerms.length) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: `Error: Required parameter 'terms' is missing or empty`
+      }]
+    };
+  }
   if (exactName) {
     // for each search term, search for the exact match
     const exactNameMatches = searchTerms.map(term => {
@@ -110,6 +119,15 @@ export const searchIconsTool = async params => {
     }
     return fuse.search(term).slice(0, limit);
   }).flat();
+  if (!results.length) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: `Error: No icons found for '${terms.join(', ')}'. Available icons: ${icons.map(i => i.componentName).join(', ')}`
+      }]
+    };
+  }
   const matchedIcons = results.map(result => {
     return {
       componentName: result.item.componentName,