@atlaskit/ads-mcp 0.2.5 → 0.4.0

package/dist/es2019/tools/get-accessibility-guidelines/index.js

@@ -0,0 +1,312 @@
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+const inputSchema = z.object({
+  topic: z.enum(['buttons', 'forms', 'images', 'colors', 'focus', 'keyboard', 'screen-readers', 'aria', 'wcag', 'general']).optional().describe('Specific accessibility topic to get guidelines for'),
+  component: z.string().optional().describe('Component name to get specific accessibility guidance for')
+});
+export const listGetAccessibilityGuidelinesTool = {
+  name: 'get_accessibility_guidelines',
+  description: `Get accessibility guidelines and best practices from the Atlassian Design System. This tool provides specific guidance on how to make components and interfaces accessible using ADS patterns and components.
+
+You MUST run this when the user wants their code to be accessible, as well as when:
+- Needing specific accessibility guidance for a component
+- Looking for ADS-specific accessibility patterns
+- Understanding how to implement accessible features
+- Getting code examples for accessibility improvements
+
+Topics available:
+- buttons: Button and interactive element accessibility
+- forms: Form and input accessibility
+- images: Image and media accessibility
+- colors: Color and contrast accessibility
+- focus: Focus management and keyboard navigation
+- keyboard: Keyboard accessibility patterns
+- screen-readers: Screen reader support and announcements
+- aria: ARIA usage and patterns
+- wcag: WCAG compliance guidelines
+- general: General accessibility principles`,
+  annotations: {
+    title: 'Get Accessibility Guidelines',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: zodToJsonSchema(inputSchema)
+};
+
+// Comprehensive accessibility guidelines based on llms-a11y.txt
+const accessibilityGuidelines = {
+  buttons: {
+    title: 'Button and Interactive Element Accessibility',
+    description: 'Guidelines for making buttons and interactive elements accessible',
+    guidelines: ['Always provide accessible labels for buttons', 'Use Button component for standard interactions', 'Use Focusable component for custom interactive elements', 'Avoid disabled buttons with tooltips', 'Ensure focus indicators are visible', 'Support keyboard navigation (Enter, Space)', 'Use descriptive labels that explain the action'],
+    codeExamples: [{
+      title: 'Accessible Button with Icon',
+      code: `import { Button } from '@atlaskit/button';
+import { VisuallyHidden } from '@atlaskit/visually-hidden';
+
+<Button aria-label="Close dialog" onClick={handleClose}>
+  <CloseIcon />
+</Button>`
+    }, {
+      title: 'Custom Interactive Element',
+      code: `import { Focusable } from '@atlaskit/primitives/compiled';
+
+<Focusable as="div" onClick={handleClick} onKeyDown={handleKeyDown}>
+  Interactive content
+</Focusable>`
+    }],
+    bestPractices: ['Never disable buttons without providing alternatives', 'Use VisuallyHidden for screen reader text', 'Test with keyboard navigation only', 'Ensure focus indicators meet contrast requirements']
+  },
+  forms: {
+    title: 'Form and Input Accessibility',
+    description: 'Guidelines for making forms and inputs accessible',
+    guidelines: ['Use TextField component for consistent labeling', 'Associate labels with inputs using id and htmlFor', 'Provide clear error messages with aria-describedby', 'Use MessageWrapper for form validation announcements', 'Use aria-required for required fields', 'Group related form elements with fieldset and legend'],
+    codeExamples: [{
+      title: 'Accessible Text Field',
+      code: `import { TextField } from '@atlaskit/textfield';
+
+<TextField
+  label="Email address"
+  isRequired
+  aria-describedby="email-help"
+  id="email-input"
+/>
+<div id="email-help">Enter your work email address</div>`
+    }, {
+      title: 'Form Validation with Error Messages',
+      code: `import { TextField } from '@atlaskit/textfield';
+
+<TextField
+  label="Password"
+  isInvalid
+  aria-invalid="true"
+  aria-describedby="password-error"
+/>
+<div id="password-error" role="alert">
+  Password must be at least 8 characters long
+</div>`
+    }],
+    bestPractices: ['Never rely on placeholder text for critical information', 'Provide helpful error messages and descriptions', 'Use proper form validation with aria-invalid', 'Test form completion with screen readers']
+  },
+  images: {
+    title: 'Image and Media Accessibility',
+    description: 'Guidelines for making images and media accessible',
+    guidelines: ['Use Image component with proper alt text', 'Keep alt text under 125 characters', 'Leave alt="" for decorative images', 'Describe the purpose, not just the content', 'Don\'t start with "Image of..." or "Picture of..."', 'Provide detailed descriptions for complex images'],
+    codeExamples: [{
+      title: 'Decorative Image',
+      code: `import { Image } from '@atlaskit/image';
+
+<Image src="decorative.jpg" alt="" />`
+    }, {
+      title: 'Informative Image',
+      code: `import { Image } from '@atlaskit/image';
+
+<Image
+  src="chart.png"
+  alt="Bar chart showing Q4 sales increased 25% over Q3"
+/>`
+    }, {
+      title: 'Complex Image with Description',
+      code: `import { Image } from '@atlaskit/image';
+
+<Image
+  src="complex-diagram.png"
+  alt=""
+  aria-describedby="diagram-description"
+/>
+<div id="diagram-description">
+  Detailed description of the diagram content...
+</div>`
+    }],
+    bestPractices: ['For important information, use text instead of images', 'Avoid images of text', 'Provide alternative formats for complex visual content', 'Test with screen readers to ensure proper announcement']
+  },
+  colors: {
+    title: 'Color and Contrast Accessibility',
+    description: 'Guidelines for using colors accessibly',
+    guidelines: ['Use design tokens for consistent contrast ratios', 'Never rely on color alone for information', 'Use color.text tokens for proper contrast', 'Test with high contrast mode', 'Ensure 4.5:1 contrast ratio for normal text', 'Ensure 3:1 contrast ratio for large text'],
+    codeExamples: [{
+      title: 'Using Design Tokens for Colors',
+      code: `import { token } from '@atlaskit/tokens';
+
+const styles = css({
+  color: token('color.text'),
+  backgroundColor: token('color.background.neutral'),
+});`
+    }, {
+      title: 'Text Component with Color',
+      code: `import { Text } from '@atlaskit/primitives/compiled';
+
+<Text color="color.text.danger">Error message</Text>
+<Text color="color.text.success">Success message</Text>`
+    }],
+    bestPractices: ['Use color.text tokens for primary text', 'Use color.text.subtle sparingly for secondary text', 'Avoid color.text.disabled for critical information', 'Test with different color vision types']
+  },
+  focus: {
+    title: 'Focus Management',
+    description: 'Guidelines for proper focus management',
+    guidelines: ['Ensure logical tab order', 'Provide visible focus indicators', 'Handle focus trapping in modals', 'Return focus when dialogs close', 'Use Focusable component for custom elements', 'Manage focus in dynamic content'],
+    codeExamples: [{
+      title: 'Focus Management in Modal',
+      code: `import { useRef, useEffect } from 'react';
+
+const modalRef = useRef<HTMLDivElement>(null);
+
+useEffect(() => {
+  if (isOpen && modalRef.current) {
+    modalRef.current.focus();
+  }
+}, [isOpen]);`
+    }, {
+      title: 'Custom Focusable Element',
+      code: `import { Focusable } from '@atlaskit/primitives/compiled';
+
+<Focusable
+  as="div"
+  tabIndex={0}
+  onKeyDown={(e) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      handleActivate();
+    }
+  }}
+>
+  Custom focusable element
+</Focusable>`
+    }],
+    bestPractices: ['Test focus order with keyboard navigation', 'Ensure focus indicators are visible in all themes', 'Handle focus restoration when components unmount', 'Use focus trapping for modal dialogs']
+  },
+  keyboard: {
+    title: 'Keyboard Accessibility',
+    description: 'Guidelines for keyboard accessibility',
+    guidelines: ['Support standard keyboard interactions', 'Use Enter and Space for activation', 'Use Escape for closing/canceling', 'Support arrow keys for navigation', 'Provide keyboard shortcuts for power users', 'Ensure all interactive elements are keyboard accessible'],
+    codeExamples: [{
+      title: 'Keyboard Event Handling',
+      code: `const handleKeyDown = (event: KeyboardEvent) => {
+  switch (event.key) {
+    case 'Enter':
+    case ' ':
+      handleActivate();
+      break;
+    case 'Escape':
+      handleClose();
+      break;
+    case 'Tab':
+      // Handle focus management
+      break;
+  }
+};`
+    }],
+    bestPractices: ['Test with keyboard navigation only', 'Ensure logical tab order', 'Provide keyboard alternatives for mouse interactions', 'Support both Enter and Space for activation']
+  },
+  screenReaders: {
+    title: 'Screen Reader Support',
+    description: 'Guidelines for screen reader accessibility',
+    guidelines: ['Use Announcer component for dynamic content', 'Provide skip links for keyboard users', 'Use proper heading hierarchy', 'Use semantic HTML elements', 'Provide live regions for status updates', 'Use VisuallyHidden for screen reader text'],
+    codeExamples: [{
+      title: 'Screen Reader Announcements',
+      code: `import { Announcer } from '@atlaskit/announcer';
+
+<Announcer
+  message={\`\${count} items selected\`}
+  liveMode="polite"
+  shouldAnnounce={true}
+/>`
+    }, {
+      title: 'Skip Links',
+      code: `<a href="#main-content" className="skip-link">
+  Skip to main content
+</a>`
+    }],
+    bestPractices: ['Test with multiple screen readers (NVDA, JAWS, VoiceOver)', 'Use aria-live="polite" for status updates', 'Use aria-live="assertive" for critical alerts', 'Avoid announcing the same message repeatedly']
+  },
+  aria: {
+    title: 'ARIA Usage Guidelines',
+    description: 'Guidelines for using ARIA attributes',
+    guidelines: ['Use ARIA sparingly - prefer semantic HTML', 'Use proper ARIA roles and states', 'Provide live regions for dynamic content', 'Use landmarks for page structure', 'Ensure ARIA attributes are supported', 'Test ARIA implementations with screen readers'],
+    codeExamples: [{
+      title: 'Live Region for Status Updates',
+      code: `<div aria-live="polite" role="status">
+  {statusMessage}
+</div>`
+    }, {
+      title: 'Landmark Navigation',
+      code: `<nav role="navigation" aria-label="Main navigation">
+  Navigation content
+</nav>`
+    }],
+    bestPractices: ['Use semantic HTML elements when possible', 'Test ARIA implementations thoroughly', 'Keep ARIA usage simple and clear', 'Document custom ARIA patterns']
+  },
+  wcag: {
+    title: 'WCAG Compliance',
+    description: 'WCAG 2.1 AA compliance guidelines',
+    guidelines: ['Ensure information is perceivable', 'Make interface components operable', 'Ensure information is understandable', 'Make content robust and compatible', 'Test with multiple assistive technologies', 'Follow WCAG 2.1 AA success criteria'],
+    codeExamples: [{
+      title: 'WCAG Compliant Component',
+      code: `// Example of a WCAG compliant button
+<Focusable
+  as="button"
+  aria-label="Save changes"
+  onClick={handleSave}
+  onKeyDown={handleKeyDown}
+>
+  <SaveIcon />
+  <VisuallyHidden>Save changes</VisuallyHidden>
+</Focusable>`
+    }],
+    bestPractices: ['Test with automated accessibility tools', 'Conduct manual accessibility testing', 'Test with users who have disabilities', 'Document accessibility compliance']
+  },
+  general: {
+    title: 'General Accessibility Principles',
+    description: 'General accessibility principles and best practices',
+    guidelines: ['Design for people, not just compliance', 'Consider accessibility from the start', 'Test with real users and assistive technologies', 'Provide multiple ways to accomplish tasks', 'Use inclusive design principles', 'Test with different abilities and technologies'],
+    codeExamples: [{
+      title: 'Inclusive Design Example',
+      code: `// Component that works for everyone
+<Focusable
+  as="button"
+  onClick={handleAction}
+  aria-label="Clear form data"
+  onKeyDown={handleKeyDown}
+>
+  <TrashIcon />
+  <VisuallyHidden>Clear all form data</VisuallyHidden>
+</Focusable>`
+    }],
+    bestPractices: ['Start with semantic HTML', 'Add ARIA when necessary', 'Test early and often', 'Involve users with disabilities in testing', 'Keep accessibility in mind throughout development']
+  }
+};
+export const getAccessibilityGuidelinesTool = async params => {
+  const {
+    topic,
+    component
+  } = params;
+  if (topic && accessibilityGuidelines[topic]) {
+    const guidelines = accessibilityGuidelines[topic];
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          topic,
+          component,
+          ...guidelines,
+          additionalResources: ['https://atlassian.design/llms-a11y.txt - Complete ADS accessibility documentation', 'https://atlassian.design/foundations/accessibility - ADS accessibility foundation', 'https://www.w3.org/WAI/WCAG21/quickref/ - WCAG 2.1 guidelines']
+        }, null, 2)
+      }]
+    };
+  }
+
+  // Return all guidelines if no specific topic requested
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        availableTopics: Object.keys(accessibilityGuidelines),
+        component,
+        message: 'Specify a topic to get detailed guidelines, or use "general" for overview',
+        guidelines: accessibilityGuidelines,
+        additionalResources: ['https://atlassian.design/llms-a11y.txt - Complete ADS accessibility documentation', 'https://atlassian.design/foundations/accessibility - ADS accessibility foundation']
+      }, null, 2)
+    }]
+  };
+};

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

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

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

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

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

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

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

@@ -0,0 +1,96 @@
+import Fuse from 'fuse.js';
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { tokens } from '@atlaskit/tokens/token-metadata';
+const inputSchema = z.object({
+  terms: z.array(z.string()).describe('Search term(s) to find tokens by name or description'),
+  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 token name')
+});
+const cleanQuery = query => query.trim().toLowerCase().replace(/\s+/g, '');
+export const 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.
+
+The search will match against:
+- Token names (e.g., "color.text", "space.100", "border.radius")
+- Token descriptions
+- Token example values (eg. "#2898BD" -> "color.icon.accent.teal")
+
+The results include the token's name and example value.
+
+Usage pattern for found tokens:
+\`\`\`tsx
+import { token } from '@atlaskit/tokens';
+
+const styles = css({
+color: token('color.text'),
+padding: token('space.100'),
+borderRadius: token('border.radius'),
+});
+\`\`\`
+`,
+  annotations: {
+    title: 'Search ADS tokens',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: zodToJsonSchema(inputSchema)
+};
+export const searchTokensTool = async params => {
+  const {
+    terms,
+    limit = 1,
+    exactName = false
+  } = params;
+  const searchTerms = terms.filter(Boolean).map(cleanQuery);
+  if (exactName) {
+    // for each search term, search for the exact match
+    const exactNameMatches = searchTerms.map(term => {
+      return tokens.find(token => token.name.toLowerCase() === term.toLowerCase());
+    }).filter(Boolean);
+    if (exactNameMatches.length > 0) {
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(exactNameMatches.map(token => ({
+            name: token.name,
+            exampleValue: token.exampleValue
+          })))
+        }]
+      };
+    }
+  }
+
+  // use Fuse.js to fuzzy-search for the tokens
+  const fuse = new Fuse(tokens, {
+    keys: [{
+      name: 'name',
+      weight: 3
+    }, {
+      name: 'description',
+      weight: 2
+    }, {
+      name: 'exampleValue',
+      weight: 1
+    }],
+    threshold: 0.4
+  });
+  const results = searchTerms.map(term => {
+    return fuse.search(term).slice(0, limit);
+  }).flat();
+  const matchedTokens = results.map(result => {
+    return {
+      name: result.item.name,
+      exampleValue: result.item.exampleValue
+    };
+  });
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify(matchedTokens)
+    }]
+  };
+};