@atlaskit/ads-mcp 0.0.1

package/CHANGELOG.md

@@ -0,0 +1 @@
+# @atlaskit/ads-mcp

package/LICENSE.md

@@ -0,0 +1,11 @@
+Copyright 2023 Atlassian Pty Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
+compliance with the License. You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is
+distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied. See the License for the specific language governing permissions and limitations under the
+License.

package/README.md

@@ -0,0 +1,29 @@
+# Atlassian Design System MCP Server
+
+Current state: Early Access
+
+The official Model Context Protocol (MCP) server for the Atlassian Design System. This server provides tools to access design tokens, icons, and components/primitives programmatically.
+
+This may expand to add accessibility, usage, and other guidance over time.
+
+## Usage
+
+Add an entry to your `mcp.json` (eg. `~/.cursor/mcp.json` or wherever your MCP config lives):
+```json
+{
+  "mcpServers": {
+		"ads": {
+      "command": "npx",
+      "args": ["-y", "@atlaskit/ads-mcp"]
+    }
+	}
+}
+```
+
+## Development
+
+Modify the usage instructions above, but replace `@atlaskit/ads-mcp` with a local path to the `index.js`:
+```json
+-"@atlaskit/ads-mcp"
++"~/git/atlassian/atlassian-frontend-monorepo/platform/packages/design-system/ads-mcp/index.js"
+```

package/build/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "extends": "../tsconfig",
+  "compilerOptions": {
+    "target": "es5",
+    "paths": {}
+  },
+  "include": [
+    "../src/**/*.ts",
+    "../src/**/*.tsx"
+  ],
+  "exclude": [
+    "../src/**/__tests__/*",
+    "../src/**/*.test.*",
+    "../src/**/test.*",
+    "../src/**/examples.*"
+  ]
+}

package/dist/cjs/index.js

@@ -0,0 +1,95 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
+var _index = require("@modelcontextprotocol/sdk/server/index.js");
+var _stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+var _types = require("@modelcontextprotocol/sdk/types.js");
+var _instructions = require("./instructions");
+var _getComponentDetails = require("./tools/get-component-details");
+var _getComponents = require("./tools/get-components");
+var _getIcons = require("./tools/get-icons");
+var _getTokens = require("./tools/get-tokens");
+/* eslint-disable import/extensions */
+
+// 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');
+var server = new _index.Server({
+  name: pkgJson.name || '@atlaskit/ads-mcp',
+  version: pkgJson.version || '0.0.0-unknown'
+}, {
+  instructions: _instructions.instructions,
+  capabilities: {
+    // Tools are defined in the handlers below.
+    tools: {}
+  }
+});
+server.setRequestHandler(_types.ListToolsRequestSchema, /*#__PURE__*/(0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee() {
+  return _regenerator.default.wrap(function _callee$(_context) {
+    while (1) switch (_context.prev = _context.next) {
+      case 0:
+        return _context.abrupt("return", {
+          tools: [_getTokens.listGetTokensTool, _getComponents.listGetComponentsTool, _getComponentDetails.listGetComponentDetailsTool, _getIcons.listGetIconsTool]
+        });
+      case 1:
+      case "end":
+        return _context.stop();
+    }
+  }, _callee);
+})));
+var callTools = {
+  get_tokens: _getTokens.getTokensTool,
+  get_components: _getComponents.getComponentsTool,
+  get_component_details: _getComponentDetails.getComponentDetailsTool,
+  get_icons: _getIcons.getIconsTool
+};
+
+// Handle tool execution
+server.setRequestHandler(_types.CallToolRequestSchema, /*#__PURE__*/function () {
+  var _ref2 = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee2(request) {
+    var tool;
+    return _regenerator.default.wrap(function _callee2$(_context2) {
+      while (1) switch (_context2.prev = _context2.next) {
+        case 0:
+          tool = callTools[request.params.name];
+          if (!tool) {
+            _context2.next = 3;
+            break;
+          }
+          return _context2.abrupt("return", tool(request.params.arguments));
+        case 3:
+          throw new Error("Tool '".concat(request.params.name, "' not found, only the following tools are available: ").concat(Object.keys(callTools).join(', ')));
+        case 4:
+        case "end":
+          return _context2.stop();
+      }
+    }, _callee2);
+  }));
+  return function (_x) {
+    return _ref2.apply(this, arguments);
+  };
+}());
+function runServer() {
+  return _runServer.apply(this, arguments);
+}
+function _runServer() {
+  _runServer = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee3() {
+    var transport;
+    return _regenerator.default.wrap(function _callee3$(_context3) {
+      while (1) switch (_context3.prev = _context3.next) {
+        case 0:
+          transport = new _stdio.StdioServerTransport();
+          _context3.next = 3;
+          return server.connect(transport);
+        case 3:
+        case "end":
+          return _context3.stop();
+      }
+    }, _callee3);
+  }));
+  return _runServer.apply(this, arguments);
+}
+runServer().catch(function (error) {
+  throw new Error("Invalid input to ads-mcp: ".concat(JSON.stringify(error.errors)));
+});

package/dist/cjs/instructions.js

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

package/dist/cjs/schema.js

@@ -0,0 +1,11 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.releasePhase = exports.emptyInputSchema = void 0;
+var _zod = require("zod");
+var _zodToJsonSchema = _interopRequireDefault(require("zod-to-json-schema"));
+var releasePhase = exports.releasePhase = _zod.z.enum(['early_access', 'beta', 'general_availability', 'intent_to_deprecate', 'deprecated']).default('general_availability').describe("\nThe release phase or status of the offering, providing guidance on what you can expect at each phase and who can use them.\nYou should typically only use `general_availability` or `beta` components. If a release phase or status is not defined, you should assume it is `general_availability`.\n\n- `early_access`: New experimental feature. There may be breaking changes in minor releases at versions `0.x`. We don't recommend using this unless you are part of an early access pilot group, as support is otherwise not available.\n- `beta`: New and ready to use. The feature is supported and stable at versions `1.0`+. We are working on improvements based on customer feedback. This may include expanding feature sets, and evolving tooling, guidance, and self-service. Breaking changes will only be made in major releases, and should be infrequent.\n- `general_availability`: Fully stable and ready to use.\n- `intent_to_deprecate` aka Caution: This feature is being considered for deprecation. There may be some issues with this feature that need to be resolved. If you are not already using the feature, use the recommended alternative instead.\n- `deprecated`: This feature is no longer supported and will be removed after the deprecation period ends. We have provided a recommended solution to replace it and communicated how to move to it.\n");
+var emptyInputSchema = exports.emptyInputSchema = (0, _zodToJsonSchema.default)(_zod.z.object({}));

package/dist/cjs/tools/get-component-details/index.js

@@ -0,0 +1,88 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.listGetComponentDetailsTool = exports.getComponentDetailsTool = void 0;
+var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
+var _zod = require("zod");
+var _zodToJsonSchema = require("zod-to-json-schema");
+var _components = require("../get-components/components");
+var inputSchema = _zod.z.object({
+  names: _zod.z.array(_zod.z.string()).describe('The name of the component(s) to get full details about')
+});
+var listGetComponentDetailsTool = exports.listGetComponentDetailsTool = {
+  name: 'get_component_details',
+  description: "You MUST use this to fetch detailed information about a specific Atlassian Design System component(s) including code examples, props, accessibility guidelines, and other usage guidance.\nIf you're not sure how to query this, you should use the `get_components` tool to get a list of all components and their names before using this tool.\n",
+  annotations: {
+    title: 'Get ADS component details',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: (0, _zodToJsonSchema.zodToJsonSchema)(inputSchema)
+};
+var cleanName = function cleanName(name) {
+  return name.trim().toLowerCase().replace(/\s+/g, '');
+};
+var getComponentDetailsTool = exports.getComponentDetailsTool = /*#__PURE__*/function () {
+  var _ref = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(params) {
+    var names, filteredComponents;
+    return _regenerator.default.wrap(function _callee$(_context) {
+      while (1) switch (_context.prev = _context.next) {
+        case 0:
+          names = params.names.filter(Boolean).map(cleanName);
+          if (names.length) {
+            _context.next = 3;
+            break;
+          }
+          return _context.abrupt("return", {
+            isError: true,
+            content: [{
+              type: 'text',
+              text: "Error: Required parameter 'names' is missing. Available components: ".concat(_components.components.map(function (c) {
+                return c.name;
+              }).join(', '))
+            }]
+          });
+        case 3:
+          filteredComponents = _components.components.filter(function (c) {
+            return names.includes(cleanName(c.name));
+          });
+          if (filteredComponents.length) {
+            _context.next = 6;
+            break;
+          }
+          return _context.abrupt("return", {
+            isError: true,
+            content: [{
+              type: 'text',
+              text: "Error: Component not found for '".concat(names.join(', '), "'. Available components: ").concat(_components.components.map(function (c) {
+                return c.name;
+              }).join(', '))
+            }]
+          });
+        case 6:
+          return _context.abrupt("return", {
+            content: filteredComponents.map(function (component) {
+              return {
+                // NOTE: Ideally one day the MCP would support structured content…
+                // eg. `type: 'object', data: component`
+                type: 'text',
+                text: JSON.stringify(component, null, 2)
+              };
+            })
+          });
+        case 7:
+        case "end":
+          return _context.stop();
+      }
+    }, _callee);
+  }));
+  return function getComponentDetailsTool(_x) {
+    return _ref.apply(this, arguments);
+  };
+}();