@atlaskit/ads-mcp 0.2.5 → 0.4.0

package/dist/es2019/tools/suggest-accessibility-fixes/index.js

@@ -0,0 +1,143 @@
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { accessibilityFixes } from './fixes';
+import { violationKeywords } from './keywords';
+const inputSchema = z.object({
+  violation: z.string().describe('Description of the accessibility violation'),
+  code: z.string().describe('The problematic code that needs fixing'),
+  component: z.string().optional().describe('Component name or type'),
+  context: z.string().optional().describe('Additional context about the usage')
+});
+export const listSuggestAccessibilityFixesTool = {
+  name: 'suggest_accessibility_fixes',
+  description: `Suggest specific accessibility fixes using Atlassian Design System components and patterns. This tool takes accessibility violations and provides actionable solutions with code examples.
+
+You MUST run this when the user wants sugesstions for fixing accessibility issues, as well as when:
+- You have identified an accessibility violation
+- Needing specific code examples for fixing accessibility issues
+- Wanting to understand how to use ADS components accessibly
+- Looking for best practices for specific accessibility problems
+
+The tool will provide:
+- Specific code examples using ADS components
+- Step-by-step fix instructions
+- Alternative approaches when applicable
+- Links to relevant ADS documentation`,
+  annotations: {
+    title: 'Suggest Accessibility Fixes',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: zodToJsonSchema(inputSchema)
+};
+
+// Keyword mappings for fuzzy matching - imported from keywords.ts
+// This allows flexible user input when describing accessibility violations
+
+// Improved fuzzy matching function
+function findBestMatchingFix(violation) {
+  const normalizedViolation = violation.toLowerCase();
+  const violationWords = normalizedViolation.split(/\s+/);
+  let bestMatch = null;
+  let bestScore = 0;
+
+  // Try exact match first
+  for (const [key, fix] of Object.entries(accessibilityFixes)) {
+    if (normalizedViolation === key.toLowerCase()) {
+      return [key, fix];
+    }
+  }
+
+  // Try keyword-based semantic matching
+  for (const [key, fix] of Object.entries(accessibilityFixes)) {
+    const keywords = violationKeywords[key] || [];
+    let score = 0;
+
+    // Score based on keyword matches
+    for (const keyword of keywords) {
+      if (normalizedViolation.includes(keyword.toLowerCase())) {
+        score += 1;
+      }
+    }
+
+    // Additional score for word matches
+    for (const word of violationWords) {
+      if (keywords.some(keyword => keyword.toLowerCase().includes(word) || word.includes(keyword.toLowerCase()))) {
+        score += 0.5;
+      }
+    }
+
+    // Boost score for exact key word matches
+    if (normalizedViolation.includes(key.toLowerCase()) || key.toLowerCase().includes(normalizedViolation)) {
+      score += 2;
+    }
+    if (score > bestScore) {
+      bestScore = score;
+      bestMatch = [key, fix];
+    }
+  }
+
+  // Return match if score is reasonable
+  return bestScore >= 1 ? bestMatch : null;
+}
+export const suggestAccessibilityFixesTool = async params => {
+  const {
+    violation,
+    component,
+    context
+  } = params;
+
+  // Use improved matching logic
+  const match = findBestMatchingFix(violation);
+  if (match) {
+    const [key, fix] = match;
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          violation,
+          matchedFixType: key,
+          component,
+          context,
+          ...fix,
+          additionalResources: ['https://atlassian.design/llms-a11y.txt - Complete ADS accessibility documentation', 'https://atlassian.design/foundations/accessibility - ADS accessibility foundation'],
+          nextSteps: ['Apply the suggested fixes to your code', 'Test the changes with screen readers', 'Test with keyboard navigation', 'Run automated accessibility tests']
+        }, null, 2)
+      }]
+    };
+  }
+
+  // Enhanced fallback with better suggestions
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        violation,
+        component,
+        context,
+        title: 'Accessibility Fix Suggestions',
+        description: "We couldn't find a specific match for your violation, but here are general recommendations",
+        searchedFor: violation,
+        generalFixes: [{
+          title: 'Use ADS Components',
+          description: 'Replace custom implementations with ADS components',
+          explanation: 'ADS components are built with accessibility in mind and handle most common issues automatically'
+        }, {
+          title: 'Add Proper Labels',
+          description: 'Ensure all interactive elements have accessible labels',
+          explanation: 'Use aria-label, VisuallyHidden, or proper label associations'
+        }, {
+          title: 'Test with Assistive Technologies',
+          description: 'Test with screen readers and keyboard navigation',
+          explanation: 'Manual testing is essential for accessibility validation'
+        }],
+        availableFixTypes: Object.keys(accessibilityFixes),
+        suggestions: ['Try describing the issue with keywords like: button, label, missing, text, color, contrast, focus, etc.', 'Use axe-core violation IDs or descriptions directly', 'Be more specific about the element type (button, input, image, etc.)'],
+        additionalResources: ['https://atlassian.design/llms-a11y.txt - Complete ADS accessibility documentation', 'https://atlassian.design/foundations/accessibility - ADS accessibility foundation'],
+        recommendation: 'Try the get_accessibility_guidelines tool for component-specific guidance'
+      }, null, 2)
+    }]
+  };
+};

package/dist/es2019/tools/suggest-accessibility-fixes/keywords.js

@@ -0,0 +1,28 @@
+/**
+ * Violation keywords mapping for fuzzy matching accessibility violations
+ *
+ * This file contains keyword synonyms and variations that users might use
+ * when describing accessibility violations. The keys should match the exact
+ * violation types defined in fixes.ts
+ *
+ * Each violation type has an array of keywords that help identify when a user
+ * is describing that particular type of accessibility issue, even if they
+ * don't use the exact technical terminology.
+ */
+
+export const violationKeywords = {
+  'button missing label': ['button', 'missing', 'label', 'text', 'name', 'accessible', 'empty', 'discernible', 'aria-label', 'screen reader', 'button-name'],
+  'image missing alt': ['image', 'img', 'alt', 'alternative', 'text', 'missing', 'empty', 'accessibility', 'screen reader', 'image-alt'],
+  'clickable div': ['div', 'clickable', 'interactive', 'onclick', 'click', 'handler', 'button', 'focusable', 'keyboard', 'role'],
+  'input missing label': ['input', 'form', 'field', 'label', 'missing', 'accessibility', 'screen reader', 'associated', 'htmlfor', 'aria-label'],
+  'form missing label': ['form', 'label', 'missing', 'field', 'input', 'accessibility', 'screen reader', 'associated', 'htmlfor'],
+  'hardcoded colors': ['color', 'hardcoded', 'hex', 'rgb', 'design', 'token', 'theme', 'css', 'style', 'contrast'],
+  'color contrast': ['contrast', 'color', 'ratio', 'accessibility', 'wcag', 'aa', 'visibility', 'readability', 'low contrast'],
+  'focus management': ['focus', 'keyboard', 'navigation', 'tab', 'outline', 'indicator', 'visible', 'management', 'trap'],
+  'heading structure': ['heading', 'h1', 'h2', 'h3', 'hierarchy', 'structure', 'semantic', 'outline', 'skip', 'level'],
+  'link accessibility': ['link', 'anchor', 'href', 'accessible', 'name', 'text', 'descriptive', 'context', 'purpose'],
+  'keyboard navigation': ['keyboard', 'navigation', 'tab', 'arrow', 'enter', 'space', 'accessible', 'focus', 'trap'],
+  'live regions': ['live', 'region', 'aria-live', 'announcement', 'screen reader', 'dynamic', 'content', 'update'],
+  'skip navigation': ['skip', 'navigation', 'link', 'bypass', 'main', 'content', 'keyboard', 'users'],
+  'table accessibility': ['table', 'header', 'th', 'scope', 'caption', 'summary', 'accessibility', 'screen reader']
+};

package/dist/esm/index.js

@@ -5,10 +5,15 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { instructions } from './instructions';
+import { analyzeAccessibilityTool, analyzeLocalhostAccessibilityTool, listAnalyzeAccessibilityTool, listAnalyzeLocalhostAccessibilityTool } from './tools/analyze-accessibility';
+import { getAccessibilityGuidelinesTool, listGetAccessibilityGuidelinesTool } from './tools/get-accessibility-guidelines';
+import { getAllIconsTool, listGetAllIconsTool } from './tools/get-all-icons';
+import { getAllTokensTool, listGetAllTokensTool } from './tools/get-all-tokens';
 import { getComponentDetailsTool, listGetComponentDetailsTool } from './tools/get-component-details';
 import { getComponentsTool, listGetComponentsTool } from './tools/get-components';
-import { getIconsTool, listGetIconsTool } from './tools/get-icons';
-import { getTokensTool, listGetTokensTool } from './tools/get-tokens';
+import { listSearchIconsTool, searchIconsTool } from './tools/search-icons';
+import { listSearchTokensTool, searchTokensTool } from './tools/search-tokens';
+import { listSuggestAccessibilityFixesTool, suggestAccessibilityFixesTool } from './tools/suggest-accessibility-fixes';
 
 // eslint-disable-next-line import/no-extraneous-dependencies -- this uses require because not all node versions this package supports use the same import assertions/attributes
 var pkgJson = require('@atlaskit/ads-mcp/package.json');
@@ -27,7 +32,7 @@ server.setRequestHandler(ListToolsRequestSchema, /*#__PURE__*/_asyncToGenerator(
     while (1) switch (_context.prev = _context.next) {
       case 0:
         return _context.abrupt("return", {
-          tools: [listGetTokensTool, listGetComponentsTool, listGetComponentDetailsTool, listGetIconsTool]
+          tools: [listGetAllTokensTool, listGetComponentsTool, listGetComponentDetailsTool, listGetAllIconsTool, listSearchIconsTool, listSearchTokensTool, listAnalyzeAccessibilityTool, listAnalyzeLocalhostAccessibilityTool, listGetAccessibilityGuidelinesTool, listSuggestAccessibilityFixesTool]
         });
       case 1:
       case "end":
@@ -36,10 +41,16 @@ server.setRequestHandler(ListToolsRequestSchema, /*#__PURE__*/_asyncToGenerator(
   }, _callee);
 })));
 var callTools = {
-  get_tokens: getTokensTool,
+  get_all_tokens: getAllTokensTool,
+  search_tokens: searchTokensTool,
   get_components: getComponentsTool,
   get_component_details: getComponentDetailsTool,
-  get_icons: getIconsTool
+  get_all_icons: getAllIconsTool,
+  search_icons: searchIconsTool,
+  analyze_accessibility: analyzeAccessibilityTool,
+  analyze_localhost_accessibility: analyzeLocalhostAccessibilityTool,
+  get_accessibility_guidelines: getAccessibilityGuidelinesTool,
+  suggest_accessibility_fixes: suggestAccessibilityFixesTool
 };
 
 // Handle tool execution

package/dist/esm/instructions.js

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