@atlaskit/ads-mcp 0.2.5 → 0.3.0

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

@@ -0,0 +1,185 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.suggestAccessibilityFixesTool = exports.listSuggestAccessibilityFixesTool = void 0;
+var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
+var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
+var _zod = require("zod");
+var _zodToJsonSchema = require("zod-to-json-schema");
+var _fixes = require("./fixes");
+var _keywords = require("./keywords");
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { (0, _defineProperty2.default)(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+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; }
+var inputSchema = _zod.z.object({
+  violation: _zod.z.string().describe('Description of the accessibility violation'),
+  code: _zod.z.string().describe('The problematic code that needs fixing'),
+  component: _zod.z.string().optional().describe('Component name or type'),
+  context: _zod.z.string().optional().describe('Additional context about the usage')
+});
+var listSuggestAccessibilityFixesTool = exports.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.\n\nYou MUST run this when the user wants sugesstions for fixing accessibility issues, as well as when:\n- You have identified an accessibility violation\n- Needing specific code examples for fixing accessibility issues\n- Wanting to understand how to use ADS components accessibly\n- Looking for best practices for specific accessibility problems\n\nThe tool will provide:\n- Specific code examples using ADS components\n- Step-by-step fix instructions\n- Alternative approaches when applicable\n- Links to relevant ADS documentation",
+  annotations: {
+    title: 'Suggest Accessibility Fixes',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: (0, _zodToJsonSchema.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) {
+  var normalizedViolation = violation.toLowerCase();
+  var violationWords = normalizedViolation.split(/\s+/);
+  var bestMatch = null;
+  var bestScore = 0;
+
+  // Try exact match first
+  for (var _i = 0, _Object$entries = Object.entries(_fixes.accessibilityFixes); _i < _Object$entries.length; _i++) {
+    var _Object$entries$_i = (0, _slicedToArray2.default)(_Object$entries[_i], 2),
+      key = _Object$entries$_i[0],
+      fix = _Object$entries$_i[1];
+    if (normalizedViolation === key.toLowerCase()) {
+      return [key, fix];
+    }
+  }
+
+  // Try keyword-based semantic matching
+  for (var _i2 = 0, _Object$entries2 = Object.entries(_fixes.accessibilityFixes); _i2 < _Object$entries2.length; _i2++) {
+    var _Object$entries2$_i = (0, _slicedToArray2.default)(_Object$entries2[_i2], 2),
+      _key = _Object$entries2$_i[0],
+      _fix = _Object$entries2$_i[1];
+    var keywords = _keywords.violationKeywords[_key] || [];
+    var score = 0;
+
+    // Score based on keyword matches
+    var _iterator = _createForOfIteratorHelper(keywords),
+      _step;
+    try {
+      for (_iterator.s(); !(_step = _iterator.n()).done;) {
+        var keyword = _step.value;
+        if (normalizedViolation.includes(keyword.toLowerCase())) {
+          score += 1;
+        }
+      }
+
+      // Additional score for word matches
+    } catch (err) {
+      _iterator.e(err);
+    } finally {
+      _iterator.f();
+    }
+    var _iterator2 = _createForOfIteratorHelper(violationWords),
+      _step2;
+    try {
+      var _loop = function _loop() {
+        var word = _step2.value;
+        if (keywords.some(function (keyword) {
+          return keyword.toLowerCase().includes(word) || word.includes(keyword.toLowerCase());
+        })) {
+          score += 0.5;
+        }
+      };
+      for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+        _loop();
+      }
+
+      // Boost score for exact key word matches
+    } catch (err) {
+      _iterator2.e(err);
+    } finally {
+      _iterator2.f();
+    }
+    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;
+}
+var suggestAccessibilityFixesTool = exports.suggestAccessibilityFixesTool = /*#__PURE__*/function () {
+  var _ref = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(params) {
+    var violation, component, context, match, _match, key, fix;
+    return _regenerator.default.wrap(function _callee$(_context) {
+      while (1) switch (_context.prev = _context.next) {
+        case 0:
+          violation = params.violation, component = params.component, context = params.context; // Use improved matching logic
+          match = findBestMatchingFix(violation);
+          if (!match) {
+            _context.next = 5;
+            break;
+          }
+          _match = (0, _slicedToArray2.default)(match, 2), key = _match[0], fix = _match[1];
+          return _context.abrupt("return", {
+            content: [{
+              type: 'text',
+              text: JSON.stringify(_objectSpread(_objectSpread({
+                violation: violation,
+                matchedFixType: key,
+                component: component,
+                context: 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)
+            }]
+          });
+        case 5:
+          return _context.abrupt("return", {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                violation: violation,
+                component: component,
+                context: 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(_fixes.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)
+            }]
+          });
+        case 6:
+        case "end":
+          return _context.stop();
+      }
+    }, _callee);
+  }));
+  return function suggestAccessibilityFixesTool(_x) {
+    return _ref.apply(this, arguments);
+  };
+}();

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

@@ -0,0 +1,34 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.violationKeywords = void 0;
+/**
+ * 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.
+ */
+
+var violationKeywords = exports.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/es2019/index.js

@@ -3,10 +3,13 @@ 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 { 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 { 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
 const pkgJson = require('@atlaskit/ads-mcp/package.json');
@@ -22,14 +25,18 @@ const server = new Server({
 });
 server.setRequestHandler(ListToolsRequestSchema, async () => {
   return {
-    tools: [listGetTokensTool, listGetComponentsTool, listGetComponentDetailsTool, listGetIconsTool]
+    tools: [listGetTokensTool, listGetComponentsTool, listGetComponentDetailsTool, listGetIconsTool, listAnalyzeAccessibilityTool, listAnalyzeLocalhostAccessibilityTool, listGetAccessibilityGuidelinesTool, listSuggestAccessibilityFixesTool]
   };
 });
 const callTools = {
   get_tokens: getTokensTool,
   get_components: getComponentsTool,
   get_component_details: getComponentDetailsTool,
-  get_icons: getIconsTool
+  get_icons: getIconsTool,
+  analyze_accessibility: analyzeAccessibilityTool,
+  analyze_localhost_accessibility: analyzeLocalhostAccessibilityTool,
+  get_accessibility_guidelines: getAccessibilityGuidelinesTool,
+  suggest_accessibility_fixes: suggestAccessibilityFixesTool
 };
 
 // Handle tool execution

package/dist/es2019/instructions.js

@@ -1,5 +1,12 @@
 export const instructions = `
 You 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.
 
-You 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.
+You have special expertise in accessibility and can help ensure that interfaces built with ADS components are accessible to all users. You can analyze code for accessibility violations, provide specific fix suggestions, and offer guidance on accessibility best practices.
+
+You are able to use the provided tools to help answer your questions, but may also access https://atlassian.design/llms.txt, https://atlassian.design/llms-a11y.txt, or https://atlassian.design/ directly for deeper research and information.
+
+Accessibility Tools Available:
+- analyze_accessibility: Analyze React component code for accessibility violations
+- get_accessibility_guidelines: Get specific accessibility guidelines and best practices
+- suggest_accessibility_fixes: Get specific fix suggestions for accessibility violations
 `;