@atlaskit/ads-mcp 0.20.2 → 0.20.4

package/dist/es2019/tools/migration-guides/migrations/onboarding-multi-step.js

@@ -0,0 +1,179 @@
+const additionalResources = 'Visit https://hello.atlassian.net/wiki/spaces/DST/pages/6069774593 or https://atlassian.design/components/spotlight for more context';
+export const onboardingMultiStep = {
+  id: 'multi-step',
+  title: 'Multi Step Spotlight Tour Migration',
+  description: 'Migrate a multi-step spotlight tour from @atlaskit/onboarding to @atlaskit/spotlight',
+  fromPackage: '@atlaskit/onboarding',
+  toPackage: '@atlaskit/spotlight',
+  examples: [{
+    title: 'Migrate multi step spotlight tour',
+    description: 'Replace the single SpotlightManager pattern with multiple PopoverProvider instances, one for each target in the tour',
+    before: `import React, { useState } from 'react';
+import Button, { IconButton } from '@atlaskit/button/new';
+import CommentAddIcon from '@atlaskit/icon/core/comment-add';
+import CopyIcon from '@atlaskit/icon/core/copy';
+import {
+  Spotlight,
+  SpotlightManager,
+  SpotlightTarget,
+  SpotlightTransition,
+} from '@atlaskit/onboarding';
+
+const OnboardingTour = () => {
+  const [activeSpotlight, setActiveSpotlight] = useState<null | number>(null);
+  const start = () => setActiveSpotlight(0);
+  const next = () => setActiveSpotlight((activeSpotlight || 0) + 1);
+  const back = () => setActiveSpotlight((activeSpotlight || 1) - 1);
+  const end = () => setActiveSpotlight(null);
+
+  const renderActiveSpotlight = () => {
+    const spotlights = [
+      <Spotlight
+        actions={[
+          { onClick: () => next(), text: 'Next' },
+          { onClick: () => end(), text: 'Dismiss', appearance: 'subtle' },
+        ]}
+        heading="Add a comment"
+        target="comment"
+        key="comment"
+      >
+        Quickly add a comment to the work item.
+      </Spotlight>,
+      <Spotlight
+        actions={[
+          { onClick: () => end(), text: 'Done' },
+          { onClick: () => back(), text: 'Back', appearance: 'subtle' },
+        ]}
+        heading="Copy code"
+        target="copy"
+        key="copy"
+      >
+        Click to copy the example code to your clipboard.
+      </Spotlight>,
+    ];
+
+    if (activeSpotlight === null) {
+      return null;
+    }
+    return spotlights[activeSpotlight];
+  };
+
+  return (
+    <SpotlightManager>
+      <SpotlightTarget name="comment">
+        <IconButton icon={CommentAddIcon} label="comment" />
+      </SpotlightTarget>
+      <SpotlightTarget name="copy">
+        <IconButton icon={CopyIcon} label="Copy" />
+      </SpotlightTarget>
+      <Button appearance="primary" onClick={start}>
+        Start tour
+      </Button>
+      <SpotlightTransition>{renderActiveSpotlight()}</SpotlightTransition>
+    </SpotlightManager>
+  );
+};`,
+    after: `import React, { useState } from 'react';
+import Button, { IconButton } from '@atlaskit/button/new';
+import CommentAddIcon from '@atlaskit/icon/core/comment-add';
+import CopyIcon from '@atlaskit/icon/core/copy';
+import { Text } from '@atlaskit/primitives/compiled';
+import {
+  PopoverContent,
+  PopoverProvider,
+  PopoverTarget,
+  SpotlightActions,
+  SpotlightBody,
+  SpotlightCard,
+  SpotlightControls,
+  SpotlightDismissControl,
+  SpotlightFooter,
+  SpotlightHeader,
+  SpotlightHeadline,
+  SpotlightPrimaryAction,
+  SpotlightSecondaryAction,
+  SpotlightStepCount,
+} from '@atlaskit/spotlight';
+
+const SpotlightTour = () => {
+  const [currentStep, setCurrentStep] = useState<number>(0);
+
+  const dismiss = () => setCurrentStep(0);
+  const back = () => setCurrentStep(Math.max(currentStep - 1, 1));
+  const next = () => setCurrentStep(Math.min(currentStep + 1, 2));
+  const done = () => setCurrentStep(0);
+
+  return (
+    <>
+      <PopoverProvider>
+        <PopoverTarget>
+          <IconButton icon={CommentAddIcon} label="comment" />
+        </PopoverTarget>
+        <PopoverContent dismiss={dismiss} placement="bottom-start" isVisible={currentStep === 1}>
+          <SpotlightCard>
+            <SpotlightHeader>
+              <SpotlightHeadline>Add a comment</SpotlightHeadline>
+              <SpotlightControls>
+                <SpotlightDismissControl onClick={dismiss} />
+              </SpotlightControls>
+            </SpotlightHeader>
+            <SpotlightBody>
+              <Text>Quickly add a comment to the work item.</Text>
+            </SpotlightBody>
+            <SpotlightFooter>
+              <SpotlightStepCount>1 of 2</SpotlightStepCount>
+              <SpotlightActions>
+                <SpotlightPrimaryAction onClick={next}>Next</SpotlightPrimaryAction>
+              </SpotlightActions>
+            </SpotlightFooter>
+          </SpotlightCard>
+        </PopoverContent>
+      </PopoverProvider>
+
+      <PopoverProvider>
+        <PopoverTarget>
+          <IconButton icon={CopyIcon} label="Copy" />
+        </PopoverTarget>
+        <PopoverContent dismiss={dismiss} placement="bottom-start" isVisible={currentStep === 2}>
+          <SpotlightCard>
+            <SpotlightHeader>
+              <SpotlightHeadline>Copy code</SpotlightHeadline>
+              <SpotlightControls>
+                <SpotlightDismissControl onClick={dismiss} />
+              </SpotlightControls>
+            </SpotlightHeader>
+            <SpotlightBody>
+              <Text>Click to copy the example code to your clipboard.</Text>
+            </SpotlightBody>
+            <SpotlightFooter>
+              <SpotlightStepCount>2 of 2</SpotlightStepCount>
+              <SpotlightActions>
+                <SpotlightSecondaryAction onClick={back}>Back</SpotlightSecondaryAction>
+                <SpotlightPrimaryAction onClick={done}>Done</SpotlightPrimaryAction>
+              </SpotlightActions>
+            </SpotlightFooter>
+          </SpotlightCard>
+        </PopoverContent>
+      </PopoverProvider>
+
+      <Button appearance="primary" onClick={() => setCurrentStep(1)}>
+        Start tour
+      </Button>
+    </>
+  );
+};`,
+    explanation: `Key changes when migrating a multi-step spotlight tour:
+- SpotlightManager coordinated multiple spotlights in a tour. PopoverProvider manages internal state for a single spotlight.
+- Each target gets its own PopoverProvider > PopoverTarget > PopoverContent structure
+- The spotlight array pattern is replaced with individual SpotlightCard components per target
+- Control visibility with isVisible={currentStep === n} on each PopoverContent
+- Add SpotlightStepCount component in SpotlightFooter to show progress (e.g., "1 of 3")
+- Use SpotlightSecondaryAction for "Back" buttons instead of appearance: 'subtle' in the actions array
+- Use SpotlightPrimaryAction for "Next" and "Done" buttons
+- The renderActiveSpotlight pattern is no longer needed - visibility is controlled declaratively
+- Navigation functions use Math.max/Math.min to bound the step range safely
+- All other migration changes from single step spotlight migration guide apply.`
+  }],
+  bestPractices: ['Use a numeric currentStep state where 0 = hidden, 1+ = active step number', 'Always include SpotlightStepCount in multi-step tours for user orientation', 'First step should only have "Next" action, middle steps have "Back" and "Next", last step has "Back" and "Done"', 'Use SpotlightSecondaryAction for back/dismiss actions and SpotlightPrimaryAction for next/done', 'Include SpotlightDismissControl with onClick={dismiss} so users can exit the tour at any point', 'Bound navigation functions with Math.max/Math.min to prevent invalid step values', 'Preference duplicating Spotlight code instead of trying to have a single `@atlaskit/spotlight` instance that conditionally renders content based on step.'],
+  additionalResources
+};

package/dist/es2019/tools/migration-guides/migrations/onboarding-single-step.js

@@ -0,0 +1,120 @@
+const additionalResources = 'Visit https://hello.atlassian.net/wiki/spaces/DST/pages/6069774593 or https://atlassian.design/components/spotlight for more context';
+export const onboardingSingleStep = {
+  id: 'single-step',
+  title: 'Single Step Spotlight Migration',
+  description: 'Use when code ONLY has `Spotlight` from `@atlaskit/onboarding` (no JiraSpotlight)',
+  fromPackage: '@atlaskit/onboarding',
+  toPackage: '@atlaskit/spotlight',
+  examples: [{
+    title: 'Migrate single step spotlight',
+    description: 'Replace SpotlightTarget, and Spotlight with the new compositional @atlaskit/spotlight components',
+    before: `
+// file1.tsx
+import React, { useState } from 'react';
+import Button from '@atlaskit/button/new';
+import { Spotlight } from '@atlaskit/onboarding';
+
+const OnboardingSpotlight = () => {
+  const [isSpotlightActive, setIsSpotlightActive] = useState(true);
+  const start = () => setIsSpotlightActive(true);
+  const end = () => setIsSpotlightActive(false);
+
+  return (
+		{isSpotlightActive && (
+			<Spotlight
+				dialogPlacement='bottom right'
+				actions={[
+					{
+						onClick: end,
+						text: 'Got it',
+					},
+				]}
+				heading="Feature Heading"
+				target="my-target"
+			>
+				This is the spotlight body content describing the feature.
+			</Spotlight>
+		)}
+  );
+};
+
+// file2.tsx
+import React from 'react';
+import Button from '@atlaskit/button/new';
+import { Spotlight } from '@atlaskit/onboarding';
+
+const SomeFeature = () => {
+
+  return (
+		<SpotlightTarget name="my-target">
+			<Button>Target Element</Button>
+		</SpotlightTarget>
+  );
+};
+`,
+    after: `
+// file2.tsx -- the Spotlight has been co-located to the targeted element.
+import React, { useState } from 'react';
+import Button from '@atlaskit/button/new';
+import { Text } from '@atlaskit/primitives/compiled';
+import {
+  PopoverContent,
+  PopoverProvider,
+  PopoverTarget,
+  SpotlightActions,
+  SpotlightBody,
+  SpotlightCard,
+  SpotlightControls,
+  SpotlightDismissControl,
+  SpotlightFooter,
+  SpotlightHeader,
+  SpotlightHeadline,
+  SpotlightPrimaryAction,
+} from '@atlaskit/spotlight';
+
+const Spotlight = () => {
+  const [isVisible, setIsVisible] = useState(false);
+  const dismiss = () => setIsVisible(false);
+  const done = () => setIsVisible(false);
+
+  return (
+    <PopoverProvider>
+      <PopoverTarget>
+        <Button onClick={() => setIsVisible(true)}>Target Element</Button>
+      </PopoverTarget>
+      <PopoverContent dismiss={dismiss} placement="bottom-start" isVisible={isVisible}>
+        <SpotlightCard>
+          <SpotlightHeader>
+            <SpotlightHeadline>Feature Heading</SpotlightHeadline>
+            <SpotlightControls>
+              <SpotlightDismissControl />
+            </SpotlightControls>
+          </SpotlightHeader>
+          <SpotlightBody>
+            <Text>This is the spotlight body content describing the feature.</Text>
+          </SpotlightBody>
+          <SpotlightFooter>
+            <SpotlightActions>
+              <SpotlightPrimaryAction onClick={done}>Got it</SpotlightPrimaryAction>
+            </SpotlightActions>
+          </SpotlightFooter>
+        </SpotlightCard>
+      </PopoverContent>
+    </PopoverProvider>
+  );
+};`,
+    explanation: `Key changes when migrating a single step spotlight:
+- Do not use this migration guide for JiraSpotlight. Use 'jira-spotlight' instead.
+- PopoverProvider maintains internal Spotlight state. SpotlightManager coordinated multiple @atlaskit/onboarding usages and is no longer needed.
+- Replace SpotlightTarget with PopoverTarget - wraps the element to highlight
+- Replace Spotlight with PopoverContent containing SpotlightCard - controls visibility and positioning
+- The 'heading' prop becomes SpotlightHeadline inside SpotlightHeader
+- The 'actions' array becomes SpotlightActions with SpotlightPrimaryAction (and optionally SpotlightSecondaryAction)
+- The children content moves into SpotlightBody wrapped with Text component
+- Add SpotlightDismissControl inside SpotlightControls for the close button
+- The 'target' and/or 'targetName' prop is replaced with PopoverTarget directly wrapping the target element
+- The 'dialogPlacement' prop becomes 'placement' on PopoverContent. Mapping: "top right" → "top-start", "top center" → "top", "top left" → "top-end", "right bottom" → "right-start", "right middle" → "right-start | right-end", "right top" → "right-end", "bottom left" → "bottom-end", "bottom center" → "bottom", "bottom right" → "bottom-start", "left top" → "left-end", "left middle" → "left-start | left-end", "left bottom" → "left-start"'`
+  }],
+  bestPractices: ['PopoverTarget should wrap exactly one child element that will be highlighted', 'Always include SpotlightDismissControl for accessibility - allows users to dismiss via close button', 'SpotlightPrimaryAction is required and wraps the main CTA button', 'Wrap body text content in the Text component from @atlaskit/primitives/compiled'],
+  additionalResources
+};

package/dist/es2019/tools/migration-guides/migrations/onboarding-with-motion.js

@@ -0,0 +1,120 @@
+const additionalResources = 'Visit https://hello.atlassian.net/wiki/spaces/DST/pages/6069774593 or https://atlassian.design/components/spotlight for more context';
+export const onboardingWithMotion = {
+  id: 'motion',
+  title: 'Single Step Spotlight with Motion Migration',
+  description: 'Migrate a single step spotlight with entrance animation from @atlaskit/onboarding to @atlaskit/spotlight using @atlaskit/motion',
+  fromPackage: '@atlaskit/onboarding',
+  toPackage: '@atlaskit/spotlight',
+  examples: [{
+    title: 'Migrate spotlight with transition animation',
+    description: 'Replace SpotlightTransition with FadeIn from @atlaskit/motion wrapped around the SpotlightCard',
+    before: `import React, { useState } from 'react';
+import Button from '@atlaskit/button/new';
+import {
+  Spotlight,
+  SpotlightManager,
+  SpotlightTarget,
+  SpotlightTransition,
+} from '@atlaskit/onboarding';
+
+const OnboardingSpotlightWithTransition = () => {
+  const [isSpotlightActive, setIsSpotlightActive] = useState(false);
+  const start = () => setIsSpotlightActive(true);
+  const end = () => setIsSpotlightActive(false);
+
+  return (
+    <SpotlightManager>
+      <SpotlightTarget name="my-target">
+        <Button>Target Element</Button>
+      </SpotlightTarget>
+      <div>
+        <Button appearance="primary" onClick={start}>
+          Show spotlight
+        </Button>
+      </div>
+      <SpotlightTransition>
+        {isSpotlightActive && (
+          <Spotlight
+            actions={[
+              {
+                onClick: end,
+                text: 'Got it',
+              },
+            ]}
+            heading="Feature Heading"
+            target="my-target"
+            key="my-target"
+          >
+            This is the spotlight body content describing the feature.
+          </Spotlight>
+        )}
+      </SpotlightTransition>
+    </SpotlightManager>
+  );
+};`,
+    after: `import React, { useState } from 'react';
+import Button from '@atlaskit/button/new';
+import { FadeIn } from '@atlaskit/motion';
+import { Text } from '@atlaskit/primitives/compiled';
+import {
+  PopoverContent,
+  PopoverProvider,
+  PopoverTarget,
+  SpotlightActions,
+  SpotlightBody,
+  SpotlightCard,
+  SpotlightControls,
+  SpotlightDismissControl,
+  SpotlightFooter,
+  SpotlightHeader,
+  SpotlightHeadline,
+  SpotlightPrimaryAction,
+} from '@atlaskit/spotlight';
+
+const SpotlightWithMotion = () => {
+  const [isVisible, setIsVisible] = useState(false);
+  const dismiss = () => setIsVisible(false);
+  const done = () => setIsVisible(false);
+
+  return (
+    <PopoverProvider>
+      <PopoverTarget>
+        <Button onClick={() => setIsVisible(true)}>Target Element</Button>
+      </PopoverTarget>
+      <PopoverContent done={done} dismiss={dismiss} placement="bottom-start" isVisible={isVisible}>
+        <FadeIn entranceDirection="left">
+          {(props) => (
+            <div {...props}>
+              <SpotlightCard>
+                <SpotlightHeader>
+                  <SpotlightHeadline>Feature Heading</SpotlightHeadline>
+                  <SpotlightControls>
+                    <SpotlightDismissControl />
+                  </SpotlightControls>
+                </SpotlightHeader>
+                <SpotlightBody>
+                  <Text>This is the spotlight body content describing the feature.</Text>
+                </SpotlightBody>
+                <SpotlightFooter>
+                  <SpotlightActions>
+                    <SpotlightPrimaryAction onClick={done}>Got it</SpotlightPrimaryAction>
+                  </SpotlightActions>
+                </SpotlightFooter>
+              </SpotlightCard>
+            </div>
+          )}
+        </FadeIn>
+      </PopoverContent>
+    </PopoverProvider>
+  );
+};`,
+    explanation: `Key changes when migrating a spotlight with transition animation:
+- Replace SpotlightTransition with FadeIn from @atlaskit/motion
+- Import FadeIn from '@atlaskit/motion' instead of SpotlightTransition from '@atlaskit/onboarding'
+- FadeIn uses a render props pattern - wrap content in {(props) => <div {...props}>...</div>}
+- The entranceDirection prop controls animation direction: 'left', 'right', 'top', or 'bottom'
+- All other migration changes from single step spotlight apply (PopoverProvider, compositional components, etc.)`
+  }],
+  bestPractices: ['Choose entranceDirection based on spotlight placement (e.g., "left" for right-placed spotlights)', 'Motion is optional - only add if the original onboarding spotlight used SpotlightTransition for entrance effects'],
+  additionalResources
+};

package/dist/es2019/tools/plan/list-plan-tool.js

@@ -0,0 +1,47 @@
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+
+import { zodToJsonSchema } from '../../helpers/zod-to-json-schema';
+import { planInputSchema } from './plan-input-schema';
+export const listPlanTool = {
+  name: 'ads_plan',
+  description: `Runs **ads_search_tokens**, **ads_search_icons**, **ads_search_components**, and **ads_search_atlaskit_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** (including legacy/broader Atlaskit) for a UI task.
+
+WHEN TO USE:
+**Implementing or iterating on a UI**—new screen, feature, or polish—and 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.
+
+At least one of \`tokens\`, \`icons\`, \`components\`, or \`atlaskitComponents\` must contain search terms (use \`[]\` for lists you do not need).
+
+Prefer supplying **multiple** terms per non-empty array when you know them—broader queries improve recall. Some queries return no rows where metadata is thin; try alternate wording.
+
+This is equivalent to calling the individual search tools; there are no extra merge semantics beyond concatenating results.
+
+Example request:
+\`\`\`json
+{
+	"tokens": ["spacing", "inverted text", "background primary", "animation"],
+	"icons": ["search", "folder", "user"],
+	"components": ["button", "input", "select", "heading"],
+	"atlaskitComponents": ["inline-dialog", "onboarding", "page-layout"]
+}
+\`\`\`
+
+Example token usage:
+\`\`\`tsx
+import { token } from '@atlaskit/tokens';
+const styles = css({ color: token('color.text'), padding: token('space.100') });
+\`\`\`
+
+Example icon usage:
+\`\`\`tsx
+import AddIcon from '@atlaskit/icon/core/add';
+<AddIcon label="Add work item" size="small" />
+\`\`\``,
+  annotations: {
+    title: 'Search ADS tokens, icons, and components to plan what to build',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: zodToJsonSchema(planInputSchema)
+};

package/dist/es2019/tools/plan/plan-input-schema.js

@@ -0,0 +1,9 @@
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+import { z } from 'zod';
+export const planInputSchema = z.object({
+  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.'),
+  atlaskitComponents: z.array(z.string()).describe('Search terms for Atlaskit components. Use `[]` if you only need core ADS components. 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 both ADS and atlaskit component searches.').optional()
+});

package/dist/es2019/tools/plan/plan-tool.js

@@ -0,0 +1,111 @@
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+
+import { searchAtlaskitComponentsTool } from '../search-atlaskit-components/search-atlaskit-components-tool';
+import { searchComponentsTool } from '../search-components/search-components-tool';
+import { searchIconsTool } from '../search-icons/search-icons-tool';
+import { searchTokensTool } from '../search-tokens/search-tokens-tool';
+export const planTool = async ({
+  tokens: tokens_search,
+  icons: icons_search,
+  components: components_search,
+  atlaskitComponents: atlaskit_components_search,
+  limit
+}) => {
+  // Validate that at least one search type is provided
+  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) && !(atlaskit_components_search !== null && atlaskit_components_search !== void 0 && atlaskit_components_search.length)) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: 'Error: At least one search type (tokens_search, icons_search, components_search, or atlaskit_components_search) must be provided with search terms'
+      }]
+    };
+  }
+  const results = {};
+
+  // Execute searches in parallel
+  const searchPromises = [];
+  if (tokens_search !== null && tokens_search !== void 0 && tokens_search.length) {
+    searchPromises.push(searchTokensTool({
+      terms: tokens_search,
+      limit
+    }).then(result => {
+      results.tokens = result;
+    }));
+  }
+  if (icons_search !== null && icons_search !== void 0 && icons_search.length) {
+    searchPromises.push(searchIconsTool({
+      terms: icons_search,
+      limit
+    }).then(result => {
+      results.icons = result;
+    }));
+  }
+  if (components_search !== null && components_search !== void 0 && components_search.length) {
+    searchPromises.push(searchComponentsTool({
+      terms: components_search,
+      limit
+    }).then(result => {
+      results.components = result;
+    }));
+  }
+  if (atlaskit_components_search !== null && atlaskit_components_search !== void 0 && atlaskit_components_search.length) {
+    searchPromises.push(searchAtlaskitComponentsTool({
+      terms: atlaskit_components_search,
+      limit
+    }).then(result => {
+      results.atlaskitComponents = result;
+    }));
+  }
+
+  // Wait for all searches to complete
+  await Promise.all(searchPromises);
+
+  // Helper function to safely count results
+  const getResultCount = result => {
+    var _result$content;
+    if (!result || result.isError || !((_result$content = result.content) !== null && _result$content !== void 0 && _result$content[0])) {
+      return 0;
+    }
+    const firstContent = result.content[0];
+    if (firstContent.type !== 'text') {
+      return 0;
+    }
+    try {
+      const parsed = JSON.parse(firstContent.text);
+      return Array.isArray(parsed) ? parsed.length : 0;
+    } catch {
+      return 0;
+    }
+  };
+
+  // Format the consolidated results
+  const consolidatedResult = {
+    searchResults: {
+      ...(results.tokens && {
+        tokens: results.tokens
+      }),
+      ...(results.icons && {
+        icons: results.icons
+      }),
+      ...(results.components && {
+        components: results.components
+      }),
+      ...(results.atlaskitComponents && {
+        atlaskitComponents: results.atlaskitComponents
+      })
+    },
+    summary: {
+      tokensFound: getResultCount(results.tokens),
+      iconsFound: getResultCount(results.icons),
+      componentsFound: getResultCount(results.components),
+      atlaskitComponentsFound: getResultCount(results.atlaskitComponents)
+    }
+  };
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify(consolidatedResult, null, 2)
+    }]
+  };
+};

package/dist/es2019/tools/search-atlaskit-components/list-search-atlaskit-components-tool.js

@@ -0,0 +1,19 @@
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+
+import { zodToJsonSchema } from '../../helpers/zod-to-json-schema';
+import { searchAtlaskitComponentsInputSchema } from './search-atlaskit-components-input-schema';
+export const listSearchAtlaskitComponentsTool = {
+  name: 'atlaskit_search_components',
+  description: `Searches the bundled Atlaskit component catalog. Returns JSON objects with **name**, **package**, **examples**, and **props** for each match (trimmed payload).
+
+WHEN TO USE:
+**Selecting which Atlaskit component to use**—package name, examples, and props—before implementation. Use when searching for specific Atlaskit components that might not be in the core ADS catalog.`,
+  annotations: {
+    title: 'Search Atlaskit components',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: zodToJsonSchema(searchAtlaskitComponentsInputSchema)
+};

package/dist/es2019/tools/search-atlaskit-components/search-atlaskit-components-input-schema.js

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+export const searchAtlaskitComponentsInputSchema = z.object({
+  terms: z.array(z.string()).describe('Required: one or more search terms (fuzzy over name, package, category, description, keywords, examples). Example: `["button", "modal", "select"]`.'),
+  limit: z.number().default(2).describe('Max matches **per term** (default 2).').optional()
+});