@atlaskit/ads-mcp 0.18.1 → 0.19.1

package/dist/esm/helpers/fuse-multi-term.js

@@ -0,0 +1,122 @@
+import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
+function _createForOfIteratorHelper(r, e) { var t = "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (!t) { if (Array.isArray(r) || (t = _unsupportedIterableToArray(r)) || e && r && "number" == typeof r.length) { t && (r = t); var _n = 0, F = function F() {}; return { s: F, n: function n() { return _n >= r.length ? { done: !0 } : { done: !1, value: r[_n++] }; }, e: function e(r) { throw r; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var o, a = !0, u = !1; return { s: function s() { t = t.call(r); }, n: function n() { var r = t.next(); return a = r.done, r; }, e: function e(r) { u = !0, o = r; }, f: function f() { try { a || null == t.return || t.return(); } finally { if (u) throw o; } } }; }
+function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0; } }
+function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
+/**
+ * Allocation for multi-query Fuse search: each term alone, plus one spaced combined query.
+ *
+ * `poolMax = limit * termCount`. From each term we take up to `perTermTake` hits; the rest of the
+ * pool is filled from the spaced combined query.
+ */
+export function computeMultiTermFuseAllocation(limit, termCount) {
+  if (termCount <= 1) return {
+    perTermTake: 1,
+    combinedTake: 0,
+    totalTake: 1
+  };
+  var perTermTake = Math.max(Math.round(limit / termCount), 1);
+  var combinedTake = Math.max(limit * termCount - termCount * perTermTake, 1);
+  var totalTake = Math.max(perTermTake * termCount + combinedTake, 1);
+  return {
+    perTermTake: perTermTake,
+    combinedTake: combinedTake,
+    totalTake: totalTake
+  };
+}
+/**
+ * Runs `search` for each term (top `perTermTake`) and for `terms.join(' ')` (top `combinedTake`),
+ * merges pools, sorts globally by Fuse score, then returns the first `limit` **distinct** keys
+ * (later duplicate keys are skipped).
+ *
+ * Default `tokenKey` uses `item.name` when present; pass an explicit `tokenKey` for types without
+ * `name` (e.g. icons keyed by `componentName`).
+ */
+export function mergeMultiTermFuseResults(_ref) {
+  var searchTerms = _ref.searchTerms,
+    limit = _ref.limit,
+    search = _ref.search,
+    _ref$tokenKey = _ref.tokenKey,
+    tokenKey = _ref$tokenKey === void 0 ? function (item) {
+      var _name;
+      return String((_name = item.name) !== null && _name !== void 0 ? _name : '');
+    } : _ref$tokenKey,
+    _ref$searchTermsJoin = _ref.searchTermsJoin,
+    searchTermsJoin = _ref$searchTermsJoin === void 0 ? ' ' : _ref$searchTermsJoin;
+  var n = searchTerms.length;
+  if (n === 0) {
+    return [];
+  }
+  if (n === 1) {
+    return takeFirstUniqueKeys(sortByScoreAsc(toScoredHits(search(searchTerms[0]), tokenKey)), limit);
+  }
+  var _computeMultiTermFuse = computeMultiTermFuseAllocation(limit, n),
+    perTermTake = _computeMultiTermFuse.perTermTake,
+    combinedTake = _computeMultiTermFuse.combinedTake,
+    totalTake = _computeMultiTermFuse.totalTake;
+  var termsCombined = searchTerms.join(searchTermsJoin);
+  var pool = [];
+  var _iterator = _createForOfIteratorHelper(searchTerms),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var term = _step.value;
+      pool.push.apply(pool, _toConsumableArray(topRankedFromQuery(search, term, tokenKey, perTermTake)));
+    }
+
+    // Combine the terms together and search as well.
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  pool.push.apply(pool, _toConsumableArray(topRankedFromQuery(search, termsCombined, tokenKey, combinedTake)));
+
+  // Grab the top combinations of all queries' results.
+  return takeFirstUniqueKeys(sortByScoreAsc(pool), totalTake);
+}
+
+/**
+ * Best `take` hits for one Fuse query (ranked by score, then slice).
+ */
+function topRankedFromQuery(search, query, tokenKey, take) {
+  return sortByScoreAsc(toScoredHits(search(query), tokenKey)).slice(0, take);
+}
+function toScoredHits(fuseHits, tokenKey) {
+  return fuseHits.map(function (hit) {
+    var _hit$score;
+    return {
+      item: hit.item,
+      score: (_hit$score = hit.score) !== null && _hit$score !== void 0 ? _hit$score : Number.POSITIVE_INFINITY,
+      key: tokenKey(hit.item)
+    };
+  });
+}
+function sortByScoreAsc(hits) {
+  return _toConsumableArray(hits).sort(function (a, b) {
+    return a.score - b.score;
+  });
+}
+function takeFirstUniqueKeys(sortedHits, limit) {
+  var seen = new Set();
+  var out = [];
+  var _iterator2 = _createForOfIteratorHelper(sortedHits),
+    _step2;
+  try {
+    for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+      var h = _step2.value;
+      if (seen.has(h.key)) {
+        continue;
+      }
+      seen.add(h.key);
+      out.push(h.item);
+      if (out.length >= limit) {
+        break;
+      }
+    }
+  } catch (err) {
+    _iterator2.e(err);
+  } finally {
+    _iterator2.f();
+  }
+  return out;
+}

package/dist/esm/helpers/index.js

@@ -1,6 +1,7 @@
 /* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
 
 import { zodToJsonSchema as zodToJsonSchemaHelper } from 'zod-to-json-schema';
+export { computeMultiTermFuseAllocation, mergeMultiTermFuseResults } from './fuse-multi-term';
 export var cleanQuery = function cleanQuery(query) {
   return query.trim().toLowerCase().replace(/\s+/g, '');
 };

package/dist/esm/index.js

@@ -10,14 +10,17 @@ import { validateToolArguments } from './helpers/validation';
 import { instructions } from './instructions';
 import { analyzeA11yInputSchema, analyzeA11yLocalhostInputSchema, analyzeA11yTool, analyzeLocalhostA11yTool, listAnalyzeA11yTool, listAnalyzeLocalhostA11yTool } from './tools/analyze-a11y';
 import { getA11yGuidelinesInputSchema, getA11yGuidelinesTool, listGetA11yGuidelinesTool } from './tools/get-a11y-guidelines';
+import { getAllComponentsTool, listGetAllComponentsTool } from './tools/get-all-components';
 import { getAllIconsTool, listGetAllIconsTool } from './tools/get-all-icons';
 import { getAllTokensTool, listGetAllTokensTool } from './tools/get-all-tokens';
-import { getComponentsTool, listGetComponentsTool } from './tools/get-components';
 import { getGuidelinesInputSchema, getGuidelinesTool, listGetGuidelinesTool } from './tools/get-guidelines';
 import { getLintRulesInputSchema, getLintRulesTool, listGetLintRulesTool } from './tools/get-lint-rules';
 import { i18nConversionInputSchema, i18nConversionTool, listI18nConversionTool } from './tools/i18n-conversion';
 import { listMigrationGuidesTool, migrationGuidesInputSchema, migrationGuidesTool } from './tools/migration-guides';
 import { listPlanTool, planInputSchema, planTool } from './tools/plan';
+import { listSearchComponentsTool, searchComponentsInputSchema, searchComponentsTool } from './tools/search-components';
+import { listSearchIconsTool, searchIconsInputSchema, searchIconsTool } from './tools/search-icons';
+import { listSearchTokensTool, searchTokensInputSchema, searchTokensTool } from './tools/search-tokens';
 import { listSuggestA11yFixesTool, suggestA11yFixesInputSchema, suggestA11yFixesTool } from './tools/suggest-a11y-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
@@ -55,8 +58,8 @@ var generateLogger = function generateLogger(level) {
   };
 };
 export var getToolRegistry = function getToolRegistry() {
-  var _baseTools;
-  var baseTools = (_baseTools = {}, _defineProperty(_defineProperty(_defineProperty(_defineProperty(_defineProperty(_defineProperty(_defineProperty(_defineProperty(_defineProperty(_defineProperty(_baseTools, listAnalyzeA11yTool.name, {
+  var _ref;
+  return _ref = {}, _defineProperty(_defineProperty(_defineProperty(_defineProperty(_defineProperty(_defineProperty(_defineProperty(_defineProperty(_defineProperty(_defineProperty(_ref, listAnalyzeA11yTool.name, {
     handler: analyzeA11yTool,
     inputSchema: analyzeA11yInputSchema,
     tool: listAnalyzeA11yTool
@@ -68,14 +71,26 @@ export var getToolRegistry = function getToolRegistry() {
     handler: getA11yGuidelinesTool,
     inputSchema: getA11yGuidelinesInputSchema,
     tool: listGetA11yGuidelinesTool
-  }), listGetComponentsTool.name, {
-    handler: getComponentsTool,
+  }), listGetAllComponentsTool.name, {
+    handler: getAllComponentsTool,
     inputSchema: null,
-    tool: listGetComponentsTool
+    tool: listGetAllComponentsTool
   }), listPlanTool.name, {
     handler: planTool,
     inputSchema: planInputSchema,
     tool: listPlanTool
+  }), listSearchComponentsTool.name, {
+    handler: searchComponentsTool,
+    inputSchema: searchComponentsInputSchema,
+    tool: listSearchComponentsTool
+  }), listSearchIconsTool.name, {
+    handler: searchIconsTool,
+    inputSchema: searchIconsInputSchema,
+    tool: listSearchIconsTool
+  }), listSearchTokensTool.name, {
+    handler: searchTokensTool,
+    inputSchema: searchTokensInputSchema,
+    tool: listSearchTokensTool
   }), listSuggestA11yFixesTool.name, {
     handler: suggestA11yFixesTool,
     inputSchema: suggestA11yFixesInputSchema,
@@ -84,7 +99,7 @@ export var getToolRegistry = function getToolRegistry() {
     handler: migrationGuidesTool,
     inputSchema: migrationGuidesInputSchema,
     tool: listMigrationGuidesTool
-  }), listI18nConversionTool.name, {
+  }), _defineProperty(_defineProperty(_defineProperty(_defineProperty(_defineProperty(_ref, listI18nConversionTool.name, {
     handler: i18nConversionTool,
     inputSchema: i18nConversionInputSchema,
     tool: listI18nConversionTool
@@ -96,7 +111,7 @@ export var getToolRegistry = function getToolRegistry() {
     handler: getAllTokensTool,
     inputSchema: null,
     tool: listGetAllTokensTool
-  }), _defineProperty(_defineProperty(_baseTools, listGetAllIconsTool.name, {
+  }), listGetAllIconsTool.name, {
     handler: getAllIconsTool,
     inputSchema: null,
     tool: listGetAllIconsTool
@@ -104,11 +119,10 @@ export var getToolRegistry = function getToolRegistry() {
     handler: getLintRulesTool,
     inputSchema: getLintRulesInputSchema,
     tool: listGetLintRulesTool
-  }));
-  return baseTools;
+  });
 };
 server.setRequestHandler(ListToolsRequestSchema, /*#__PURE__*/function () {
-  var _ref = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee(request, extra) {
+  var _ref2 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee(request, extra) {
     var toolRegistry, tools;
     return _regeneratorRuntime.wrap(function _callee$(_context) {
       while (1) switch (_context.prev = _context.next) {
@@ -137,13 +151,13 @@ server.setRequestHandler(ListToolsRequestSchema, /*#__PURE__*/function () {
     }, _callee);
   }));
   return function (_x, _x2) {
-    return _ref.apply(this, arguments);
+    return _ref2.apply(this, arguments);
   };
 }());
 
 // Handle tool execution
 server.setRequestHandler(CallToolRequestSchema, /*#__PURE__*/function () {
-  var _ref2 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee2(request, extra) {
+  var _ref3 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee2(request, extra) {
     var toolRegistry, toolName, toolConfig, actionSubject, toolArguments, inputValidation, result, toolRegistryForError;
     return _regeneratorRuntime.wrap(function _callee2$(_context2) {
       while (1) switch (_context2.prev = _context2.next) {
@@ -251,7 +265,7 @@ server.setRequestHandler(CallToolRequestSchema, /*#__PURE__*/function () {
     }, _callee2, null, [[6, 20]]);
   }));
   return function (_x3, _x4) {
-    return _ref2.apply(this, arguments);
+    return _ref3.apply(this, arguments);
   };
 }());
 function runServer() {

package/dist/esm/instructions.js

@@ -1 +1 @@
-export var instructions = "\nYou are an expert in the Atlassian Design System (ADS).\nYou can search for tokens, icons, and components and return guidance on how to build user interfaces.\nYou have special accessibility knowledge and can ensure interfaces built with ADS components are accessible to all users.\nYou can analyze code for accessibility violations, provide specific fix suggestions, and offer guidance on accessibility best practices.\nThese tools will support you, but for deep research, you may also want to to fetch https://atlassian.design/llms.txt, https://atlassian.design/llms-a11y.txt, or https://atlassian.design/ directly.\n";
+export var instructions = "\nYou are an expert in the Atlassian Design System (ADS).\nYou can search for tokens, icons, and components and return guidance on how to build user interfaces.\nYou have special accessibility knowledge and can ensure interfaces built with ADS components are accessible to all users.\nYou can analyze code for accessibility violations, provide specific fix suggestions, and offer guidance on accessibility best practices.\nFor org-wide standards alongside ADS tools: pair Context Engine `get_accessibility_docs` with `ads_get_a11y_guidelines`, `get_content_standards_docs` with `ads_get_guidelines`, and `get_i18n_docs` with `ads_i18n_conversion_guide` (Traduki/i18n policy plus the bundled formatMessage refactor guide).\nThese tools will support you, but for deep research you may also fetch https://atlassian.design/llms.txt, https://atlassian.design/llms-a11y.txt, or https://atlassian.design/ directly.\n";

package/dist/esm/tools/analyze-a11y/index.js

@@ -12,16 +12,16 @@ import puppeteer from 'puppeteer';
 import { z } from 'zod';
 import { zodToJsonSchema } from '../../helpers';
 export var analyzeA11yInputSchema = z.object({
-  code: z.string().describe('React component code to analyze for accessibility'),
-  componentName: z.string().describe('Name of the component being analyzed').optional(),
-  context: z.string().describe('Additional context about the component usage').optional(),
-  includePatternAnalysis: z.boolean().default(true).describe('Include pattern-based analysis in addition to axe-core').optional()
+  code: z.string().describe('Source code of a React component or JSX snippet to analyze (string content only—no file path).'),
+  componentName: z.string().optional().describe('Optional label for the component under review (for summaries and reports).'),
+  context: z.string().optional().describe('Optional: how the component is used (e.g. in a form, modal) to improve suggestions.'),
+  includePatternAnalysis: z.boolean().default(true).describe('When true (default), runs regex-based heuristics on the code string (e.g. unlabeled buttons, missing alt) in addition to other analysis.').optional()
 });
 export var listAnalyzeA11yTool = {
   name: 'ads_analyze_a11y',
-  description: 'Analyze React component code for accessibility violations using axe-core and generate ADS-specific suggestions.',
+  description: "Analyzes a **string of React/JSX** code for likely accessibility issues (heuristics and/or axe-related paths) and returns hints that often **point to** `ads_suggest_a11y_fixes` or generic axe/WCAG-style context\u2014not every finding maps to a specific ADS component fix.\n\nWHEN TO USE:\nYou have component source as text and want automated checks or heuristics before or during a code review.\n\nLIMITATIONS:\n- Does not replace testing in a real browser with assistive technologies or full keyboard traversal.\n- For rendered UI, `ads_analyze_localhost_a11y` (live URL + axe) is preferable when available\u2014it is **only exposed when this MCP runs locally**, not in the remote MCP deployment.",
   annotations: {
-    title: 'Analyze Accessibility',
+    title: 'Analyze accessibility (code string)',
     readOnlyHint: true,
     destructiveHint: false,
     idempotentHint: true,
@@ -30,16 +30,16 @@ export var listAnalyzeA11yTool = {
   inputSchema: zodToJsonSchema(analyzeA11yInputSchema)
 };
 export var analyzeA11yLocalhostInputSchema = z.object({
-  url: z.string().describe('The URL to analyze for accessibility (e.g. `http://localhost:9000`)'),
-  componentName: z.string().optional().describe('Name of the component being analyzed'),
-  context: z.string().optional().describe('Additional context about the component usage'),
-  selector: z.string().optional().describe('CSS selector to target a specific element for analysis (e.g. `#my-form` or `[data-role="button"]`)')
+  url: z.string().describe('Fully qualified page URL to load (e.g. `http://localhost:9000` or a dev URL). Must be reachable from this MCP process.'),
+  componentName: z.string().optional().describe('Optional label for reporting (e.g. feature or component under test).'),
+  context: z.string().optional().describe('Optional: route, user flow, or feature context for the analyzed page.'),
+  selector: z.string().optional().describe('Optional CSS selector to scope axe analysis to a subtree (e.g. `#my-form`, `[data-testid="panel"]`). Omit to analyze the whole document.')
 });
 export var listAnalyzeLocalhostA11yTool = {
   name: 'ads_analyze_localhost_a11y',
-  description: "Analyze a live web page for accessibility violations using axe-core and generate ADS-specific suggestions.",
+  description: "Loads a **live URL** in a headless browser, runs **axe-core**, and returns violations with follow-up hints (often suggesting `ads_suggest_a11y_fixes`). Output is anchored in **axe** rule text; remediation may be generic or ADS-biased depending on the violation.\n\n**Availability:** This tool is only registered when the ADS MCP runs **on your machine** (local MCP). It is **not** available in the **remote** MCP offering\u2014use `ads_analyze_a11y` on source text there instead.\n\nWHEN TO USE:\nYou have a running app or storybook page and need automated accessibility results on **rendered** UI\u2014especially local or staging URLs.\n\nLIMITATIONS:\n- Does not replace manual testing with assistive technologies or keyboard-only navigation.\n- Requires network access to the URL from the environment running the MCP.",
   annotations: {
-    title: 'Analyze Localhost Accessibility',
+    title: 'Analyze accessibility (live URL)',
     readOnlyHint: true,
     destructiveHint: false,
     idempotentHint: true,

package/dist/esm/tools/get-a11y-guidelines/index.js

@@ -10,13 +10,13 @@ import { zodToJsonSchema } from '../../helpers';
 import { accessibilityGuidelines } from './guidelines';
 var topics = Object.keys(accessibilityGuidelines);
 export var getA11yGuidelinesInputSchema = z.object({
-  topic: z.string().optional().describe('Select the topic to get the accessibility guidelines for: ' + topics.join(', '))
+  topic: z.string().optional().describe('ADS accessibility topic key. Omit to receive all topics and the full guideline bundle. Pass a valid key (see response \`availableTopics\`) or \`general\` for a focused overview when supported. Known topics: ' + topics.join(', ') + '.')
 });
 export var listGetA11yGuidelinesTool = {
   name: 'ads_get_a11y_guidelines',
-  description: 'Get accessibility guidelines and best practices from the Atlassian Design System.',
+  description: "Returns Atlassian Design System (ADS) accessibility guidance: best practices and patterns for buttons, interactions, color contrast, forms, and other design-system topics shipped in this tool.\n\nUse this alongside the Context Engine MCP tool `get_accessibility_docs` for Atlassian-wide accessibility standards (e.g. A11YKB); this tool supplies ADS-specific component and pattern guidance.\n\nWHEN TO USE:\nYou MUST call this when generating or substantially changing a new interactive or visual user interface built with ADS, or when you need topic-specific ADS guidance (e.g. focus, forms, motion).\n\nDO NOT rely on generic web accessibility advice alone\u2014ADS conventions may differ. Use `get_accessibility_docs` for org-wide standards and this tool for ADS-topic guidance.",
   annotations: {
-    title: 'Get Accessibility Guidelines',
+    title: 'Get ADS accessibility guidelines',
     readOnlyHint: true,
     destructiveHint: false,
     idempotentHint: true,

package/dist/esm/tools/{get-components → get-all-components}/index.js

@@ -5,9 +5,9 @@ import _regeneratorRuntime from "@babel/runtime/regenerator";
 import { z } from 'zod';
 import { zodToJsonSchema } from '../../helpers';
 import { loadAllComponents } from './load-all-components';
-export var listGetComponentsTool = {
-  name: 'ads_get_components',
-  description: "Fetch all Atlassian Design System components. Only use when `ads_search_components` does not return what you're looking for.",
+export var listGetAllComponentsTool = {
+  name: 'ads_get_all_components',
+  description: "Returns **every** Atlassian Design System component record as separate JSON text chunks (full catalog; large payload).\n\nWHEN TO USE:\nLast resort when `ads_plan` / `ads_search_components` is insufficient and you must enumerate all components. Prefer search for normal component picking.\n\nNo parameters.",
   annotations: {
     title: 'Get all ADS components',
     readOnlyHint: true,
@@ -17,7 +17,7 @@ export var listGetComponentsTool = {
   },
   inputSchema: zodToJsonSchema(z.object({}))
 };
-export var getComponentsTool = /*#__PURE__*/function () {
+export var getAllComponentsTool = /*#__PURE__*/function () {
   var _ref = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee() {
     return _regeneratorRuntime.wrap(function _callee$(_context) {
       while (1) switch (_context.prev = _context.next) {
@@ -38,7 +38,7 @@ export var getComponentsTool = /*#__PURE__*/function () {
       }
     }, _callee);
   }));
-  return function getComponentsTool() {
+  return function getAllComponentsTool() {
     return _ref.apply(this, arguments);
   };
 }();

package/dist/esm/tools/get-all-icons/index.js

@@ -7,7 +7,7 @@ import { zodToJsonSchema } from '../../helpers';
 import { icons } from './icons';
 export var listGetAllIconsTool = {
   name: 'ads_get_all_icons',
-  description: "Fetch all Atlassian Design System icons. Only use when `ads_search_icons` does not return what you're looking for.",
+  description: "Returns **every** ADS icon record as separate JSON text chunks (full catalog; large payload).\n\nWHEN TO USE:\nLast resort when `ads_plan` / `ads_search_icons` is insufficient and you must enumerate all icons. Prefer search for normal icon picking.\n\nNo parameters.",
   annotations: {
     title: 'Get all ADS icons',
     readOnlyHint: true,

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

@@ -8,7 +8,7 @@ import { zodToJsonSchema } from '../../helpers';
 var inputSchema = z.object({});
 export var listGetAllTokensTool = {
   name: 'ads_get_all_tokens',
-  description: "Fetch all Atlassian Design System tokens. Only use when `ads_search_tokens` does not return what you're looking for.",
+  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.",
   annotations: {
     title: 'Get all ADS tokens',
     readOnlyHint: true,

package/dist/esm/tools/get-guidelines/index.js

@@ -7,14 +7,14 @@ import { z } from 'zod';
 import { cleanQuery, zodToJsonSchema } from '../../helpers';
 import { guidelinesStructuredContent } from './guidelines-structured-content.codegen';
 export var getGuidelinesInputSchema = z.object({
-  terms: z.array(z.string()).default([]).describe('An array of search terms to find content guidelines by keywords or content, eg. `["messages", "empty state", "voice tone"]`. If empty or not provided, returns all guidelines.').optional(),
-  limit: z.number().default(1).describe('Maximum number of results per search term in the array (default: 1)').optional()
+  terms: z.array(z.string()).default([]).describe('Search terms matched against guideline keywords and body (fuzzy). Examples: `["empty state", "voice tone"]`, `["color tokens", "spacing"]`, `["elevation", "grid"]`. Omit or use an empty array to return **all** guidelines as Markdown.').optional(),
+  limit: z.number().default(1).describe('Max matches **per term** when `terms` is non-empty (default 1). Ignored when returning all guidelines.').optional()
 });
 export var listGetGuidelinesTool = {
   name: 'ads_get_guidelines',
-  description: "Get Atlassian Design System content guidelines (foundations content) with optional search functionality.\n\n- If search parameters are provided, searches for guidelines matching the criteria by keywords or content.\n- If no search parameters are provided, returns all guidelines.\n\nExample: use this tool to look up content guidance for designing messages, voice and tone, date and time, inclusive writing, or language and grammar.",
+  description: "Returns Atlassian Design System (ADS) **foundations** guidelines as Markdown: the bundled design-system-docs foundations set (not component API docs).\n\nTOPIC COVERAGE:\n- **Content & UX writing**: messaging types (empty state, error, success, warning, info, feature discovery), voice and tone, inclusive language, grammar and style, date/time copy handoff, vocabulary pointers.\n- **Visual foundations**: color (roles, accents, palette, charts, pickers), borders and radius, elevation and z-index, spacing and layout primitives (box/inline/stack), grid, iconography, logos.\n- **Design tokens**: concepts, themes, migration, using tokens in code and in Figma.\n- **Typography**: typefaces, scale, applying text styles and tokens.\n- **Accessibility overview**: building accessible apps and related foundations pages bundled here.\n\nWhen working with content, use this tool alongside the Context Engine MCP tool `get_content_standards_docs` for Atlassian-wide content standards (CDSTD/BAIT-style org guidance); this tool supplies ADS-specific foundations.\n\nWHAT YOU GET:\n- With `terms`: fuzzy search over keywords and content; concatenated Markdown for matches.\n- Without `terms` (or empty): the full guideline set as Markdown.\n\nWHEN TO USE:\nUse this when you are **building or updating a visual interface**, **writing or reviewing user-facing copy**, or need to **answer foundations questions** about ADS: content patterns, visual appearance, design tokens, typography, spacing, color, grid, motion, and related topics shipped in this bundle.\n\nIt is **not** for picking a component\u2019s props or package (use `ads_plan` / `ads_search_components`) or for interactive accessibility rules and patterns (use `ads_get_a11y_guidelines`, with Context Engine `get_accessibility_docs` for org-wide a11y standards).",
   annotations: {
-    title: 'Get ADS guidelines',
+    title: 'Get ADS guidelines (content, a11y, visual design, design tokens, typography)',
     readOnlyHint: true,
     destructiveHint: false,
     idempotentHint: true,

package/dist/esm/tools/get-lint-rules/index.js

@@ -7,15 +7,15 @@ import { z } from 'zod';
 import { cleanQuery, zodToJsonSchema } from '../../helpers';
 import { lintRulesMcpStructuredContent } from './lint-rules-structured-content.codegen';
 export var getLintRulesInputSchema = z.object({
-  terms: z.array(z.string()).default([]).describe('An array of search terms to find lint rules by name or description, eg. `["icon-label", "xcss", "design token"]`. If empty or not provided, returns all lint rules.').optional(),
-  limit: z.number().default(1).describe('Maximum number of results per search term in the array (default: 1)').optional(),
-  exactName: z.boolean().default(false).describe('Enable to explicitly search lint rules by the exact rule name match (when you know the rule name, but need more details)').optional()
+  terms: z.array(z.string()).default([]).describe('Search terms matched against rule name, description, and docs body (fuzzy unless \`exactName\` is true). Example: `["icon-label", "xcss", "design token"]`. Omit or empty: return **all** rules as JSON.').optional(),
+  limit: z.number().default(1).describe('Max matches **per term** when searching (default 1). Not used when returning all rules.').optional(),
+  exactName: z.boolean().default(false).describe('If true, resolve each term by **exact** ESLint rule name (case-insensitive). If false, fuzzy search across name, description, and content.').optional()
 });
 export var listGetLintRulesTool = {
   name: 'ads_get_lint_rules',
-  description: "Get Atlassian Design System ESLint rule documentation (constellation) with optional search functionality.\n\n- If search parameters are provided, searches for lint rules matching the criteria.\n- If no search parameters are provided, returns all lint rules.\n\nExample: use this tool to look up documentation for rules like icon-label, ensure-proper-xcss-usage, or no-deprecated-apis.",
+  description: "Returns documentation for **Constellation** (Atlassian Design System) ESLint rules shipped with this MCP\u2014rule purpose, examples, and fixes where available.\n\nWHAT YOU GET:\n- No `terms`: JSON array of all rule payloads.\n- With `terms`: fuzzy search (or exact rule name when `exactName` is true); JSON for one or more matching rules.\n\nWHEN TO USE:\nExplaining or fixing an ESLint message from ADS rules (e.g. `icon-label`, `ensure-proper-xcss-usage`, `no-deprecated-apis`), or browsing rule docs without opening the repo. Prefer this over guessing from rule id alone.\n\nThis tool does not run ESLint; it only returns bundled documentation.",
   annotations: {
-    title: 'Get ADS lint rules',
+    title: 'Get ADS ESLint rule docs',
     readOnlyHint: true,
     destructiveHint: false,
     idempotentHint: true,

package/dist/esm/tools/i18n-conversion/index.js

@@ -6,13 +6,13 @@ import { z } from 'zod';
 import { zodToJsonSchema } from '../../helpers';
 import { i18nConversionGuide } from './guide';
 export var i18nConversionInputSchema = z.object({
-  guide: z.enum(['hardcoded-string-to-formatmessage']).describe('The i18n conversion guide to retrieve.')
+  guide: z.enum(['hardcoded-string-to-formatmessage']).describe('Which bundled guide to return. Currently only `hardcoded-string-to-formatmessage` (JSX literals → `formatMessage` / intl patterns).')
 });
 export var listI18nConversionTool = {
   name: 'ads_i18n_conversion_guide',
-  description: "Provides comprehensive guide for converting hardcoded strings to use formatMessage from @atlassian/jira-intl or react-intl-next.\n\n**TRIGGER**: Use this tool when you encounter:\n- \"fix hardcoded string\" / \"fix hardcoded strings\" / \"fix hardcoded string in [file]\"\n- \"convert hardcoded string\" / \"convert to i18n\" / \"convert to formatMessage\"\n- \"translate string\" / \"internationalize string\" / \"i18n this string\"\n- \"use formatMessage\" / \"use FormattedMessage\" / \"wrap in formatMessage\"\n- \"literal string\" / \"fix literal string\" / \"convert literal string\"\n- ESLint errors: \"Literal string in JSX content should be internationalized. Use FormattedMessage or intl.formatMessage()\"\n- ESLint errors: \"@atlassian/i18n/no-literal-string-in-jsx\"\n- Requests to convert hardcoded strings to i18n messages\n\nThis tool helps LLM agents systematically convert hardcoded strings while respecting scope limitations and following best practices for message constants, placeholders, and descriptions.",
+  description: "Returns a **bundled** step-by-step guide for replacing hardcoded UI strings with `formatMessage` (and related patterns) using @atlassian/jira-intl or react-intl-next: message constants, placeholders, descriptions, and scope/limitations for systematic refactors.\n\nWhen working with i18n or hardcoded UI strings, use this tool alongside the Context Engine MCP tool `get_i18n_docs` for Atlassian-wide Traduki / i18n standards (message definition, extraction, pluralisation, formatting, workflow); this tool supplies the concrete hardcoded-string \u2192 `formatMessage` playbook bundled in ADS MCP.\n\nWHEN TO USE / TYPICAL TRIGGERS:\n- Refactoring JSX or TS literals to i18n; \"fix hardcoded string(s)\", \"convert hardcoded string in [file]\", \"literal string in JSX\".\n- \"Convert to i18n\", \"convert to formatMessage\", \"translate this string\", \"internationalize this string\", \"i18n this string\".\n- \"Use formatMessage\", \"use FormattedMessage\", \"wrap in formatMessage\", \"fix literal string\".\n- ESLint: `Literal string in JSX content should be internationalized. Use FormattedMessage or intl.formatMessage()`.\n- ESLint: `@atlassian/i18n/no-literal-string-in-jsx`.",
   annotations: {
-    title: 'i18n Conversion Guide',
+    title: 'i18n conversion guide',
     readOnlyHint: true,
     destructiveHint: false,
     idempotentHint: true,

package/dist/esm/tools/migration-guides/index.js

@@ -10,12 +10,12 @@ import { getAvailableMigrationIds, getAvailableMigrationsDescription, migrationR
 var migrationIds = getAvailableMigrationIds();
 var migrationDescriptions = getAvailableMigrationsDescription();
 export var migrationGuidesInputSchema = z.object({
-  migration: z.enum(migrationIds).describe("The specific migration to perform.\n"),
-  description: z.enum(migrationDescriptions).describe("Description of the migration type.\n")
+  migration: z.enum(migrationIds).describe('Migration id from the registry. Must match the guide you want (see tool description list).'),
+  description: z.enum(migrationDescriptions).describe('Human-readable migration label that pairs with `migration` in the schema—choose the entry that matches the selected id.')
 });
 export var listMigrationGuidesTool = {
   name: 'ads_migration_guides',
-  description: "Migration guides for Atlassian Design System components.\n\n\tAvailable migrations:\n".concat(getAvailableMigrationsDescription()),
+  description: "Returns a structured Atlassian Design System (ADS) **migration guide** for a known package or API migration (before/after examples, best practices, links).\n\nWHEN TO USE:\nYou are upgrading or refactoring code between ADS packages or APIs and need the official migration pattern for a specific id listed below.\n\nPass **both** `migration` and `description` using a **matching pair** from the enum (schema enforces valid combinations).\n\nAvailable migrations:\n".concat(getAvailableMigrationsDescription()),
   annotations: {
     title: 'ADS Migration Guides',
     readOnlyHint: true,

package/dist/esm/tools/plan/index.js

@@ -11,17 +11,16 @@ import { searchComponentsTool } from '../search-components';
 import { searchIconsTool } from '../search-icons';
 import { searchTokensTool } from '../search-tokens';
 export var planInputSchema = z.object({
-  tokens: z.array(z.string()).describe('Array of terms to search for tokens, eg. `["spacing", "inverted text", "background primary"]`. Provide a minimum of 2 terms when known.'),
-  icons: z.array(z.string()).describe('Array of terms to search for icons, eg. `["search", "folder", "user"]`. Provide a minimum of 2 terms when known.'),
-  components: z.array(z.string()).describe('Array of terms to search for components, eg. `["button", "input", "select"]`. Provide a minimum of 2 terms when known.'),
-  limit: z.number().default(1).describe('Maximum number of results per search term in the provided arrays (default: 1)').optional(),
-  exactName: z.boolean().default(false).describe('Search tokens, icons, and components by their exact name match (use when you explicitly know the name and need more details)').optional()
+  tokens: z.array(z.string()).describe('Search terms for ADS design tokens (fuzzy by default). Use `[]` if you only need icons or components. Prefer **at least two** terms per non-empty list when you know what you need.'),
+  icons: z.array(z.string()).describe('Search terms for ADS icons. Use `[]` if you only need tokens or components. Prefer **at least two** terms per non-empty list when known.'),
+  components: z.array(z.string()).describe('Search terms for ADS components. Use `[]` if you only need tokens or icons. Prefer **at least two** terms per non-empty list when known.'),
+  limit: z.number().default(2).describe('Max matches **per term** for each non-empty list (default 2). Same limit applies to tokens, icons, and components searches.').optional()
 });
 export var listPlanTool = {
   name: 'ads_plan',
-  description: "Search how to use the Atlassian Design System offerings and get guidance on `tokens`, `icons`, and `components`.\n\nYOU MUST ALWAYS call this tool with known parameters and include a minimum of 2 search terms per parameter when known, eg.\n```json\n{\n\t\"tokens\": [\"spacing\", \"inverted text\", \"background primary\", \"animation\"],\n\t\"icons\": [\"search\", \"folder\", \"user\"],\n\t\"components\": [\"button\", \"input\", \"select\", \"heading\"]\n}\n```\n\nPlease note, there may not be results for everything as there are minor gaps in offerings or how we describe them.\n\nExample token usage:\n```tsx\nimport { token } from '@atlaskit/tokens';\nconst styles = css({ color: token('color.text'), padding: token('space.100') });\n```\n\nExample icon usage:\n```tsx\nimport AddIcon from '@atlaskit/icon/core/add';\n<AddIcon label=\"Add work item\" size=\"small\" />\n```",
+  description: "Runs **ads_search_tokens**, **ads_search_icons**, and **ads_search_components** in one call and returns a single JSON payload (each section only if that list was non-empty). Use this as the default way to discover ADS **tokens**, **icons**, and **components** for a UI task.\n\nWHEN TO USE:\n**Implementing or iterating on a UI**\u2014new screen, feature, or polish\u2014and you need candidate **token** names, **icon** imports, and **component** packages/props in one pass. Also use when exploring ADS building blocks before you write code.\n\nAt least one of `tokens`, `icons`, or `components` must contain search terms (use `[]` for lists you do not need).\n\nPrefer supplying **multiple** terms per non-empty array when you know them\u2014broader queries improve recall. Some queries return no rows where metadata is thin; try alternate wording.\n\nThis is equivalent to calling the individual search tools; there are no extra merge semantics beyond concatenating results.\n\nExample request:\n```json\n{\n\t\"tokens\": [\"spacing\", \"inverted text\", \"background primary\", \"animation\"],\n\t\"icons\": [\"search\", \"folder\", \"user\"],\n\t\"components\": [\"button\", \"input\", \"select\", \"heading\"]\n}\n```\n\nExample token usage:\n```tsx\nimport { token } from '@atlaskit/tokens';\nconst styles = css({ color: token('color.text'), padding: token('space.100') });\n```\n\nExample icon usage:\n```tsx\nimport AddIcon from '@atlaskit/icon/core/add';\n<AddIcon label=\"Add work item\" size=\"small\" />\n```",
   annotations: {
-    title: 'Plan ADS resources',
+    title: 'Search ADS tokens, icons, and components to plan what to build',
     readOnlyHint: true,
     destructiveHint: false,
     idempotentHint: true,
@@ -30,12 +29,12 @@ export var listPlanTool = {
   inputSchema: zodToJsonSchema(planInputSchema)
 };
 export var planTool = /*#__PURE__*/function () {
-  var _ref = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee(params) {
-    var tokens_search, icons_search, components_search, _params$limit, limit, _params$exactName, exactName, results, searchPromises, getResultCount, consolidatedResult;
+  var _ref2 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee(_ref) {
+    var tokens_search, icons_search, components_search, limit, results, searchPromises, getResultCount, consolidatedResult;
     return _regeneratorRuntime.wrap(function _callee$(_context) {
       while (1) switch (_context.prev = _context.next) {
         case 0:
-          tokens_search = params.tokens, icons_search = params.icons, components_search = params.components, _params$limit = params.limit, limit = _params$limit === void 0 ? 1 : _params$limit, _params$exactName = params.exactName, exactName = _params$exactName === void 0 ? false : _params$exactName; // Validate that at least one search type is provided
+          tokens_search = _ref.tokens, icons_search = _ref.icons, components_search = _ref.components, limit = _ref.limit;
           if (!(!(tokens_search !== null && tokens_search !== void 0 && tokens_search.length) && !(icons_search !== null && icons_search !== void 0 && icons_search.length) && !(components_search !== null && components_search !== void 0 && components_search.length))) {
             _context.next = 3;
             break;
@@ -53,8 +52,7 @@ export var planTool = /*#__PURE__*/function () {
           if (tokens_search !== null && tokens_search !== void 0 && tokens_search.length) {
             searchPromises.push(searchTokensTool({
               terms: tokens_search,
-              limit: limit,
-              exactName: exactName
+              limit: limit
             }).then(function (result) {
               results.tokens = result;
             }));
@@ -62,8 +60,7 @@ export var planTool = /*#__PURE__*/function () {
           if (icons_search !== null && icons_search !== void 0 && icons_search.length) {
             searchPromises.push(searchIconsTool({
               terms: icons_search,
-              limit: limit,
-              exactName: exactName
+              limit: limit
             }).then(function (result) {
               results.icons = result;
             }));
@@ -71,8 +68,7 @@ export var planTool = /*#__PURE__*/function () {
           if (components_search !== null && components_search !== void 0 && components_search.length) {
             searchPromises.push(searchComponentsTool({
               terms: components_search,
-              limit: limit,
-              exactName: exactName
+              limit: limit
             }).then(function (result) {
               results.components = result;
             }));
@@ -126,6 +122,6 @@ export var planTool = /*#__PURE__*/function () {
     }, _callee);
   }));
   return function planTool(_x) {
-    return _ref.apply(this, arguments);
+    return _ref2.apply(this, arguments);
   };
 }();