Design System MCP Server

by pglevy

423 downloads
Not rated
GitHub

About

A proof-of-concept for publish design system guidance and code snippets as an MCP server for usage with LLMs

Details

Author
pglevy
Downloads
423
Categories
Developer Tools, Design, Knowledge Base, Other, Media

Jump to

- Browse design system categories (components, layouts, patterns)
- List components within a specific category
- Get detailed component information including guidance and code examples
- Search across all components by keyword

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name Design System MCP Server
    Command (node, npx, python, etc.)

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

Install dependencies with npm install, build with npm run build, then add the server to Claude Desktop’s configuration file (on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json or Windows: %AppData%\Claude\claude_desktop_config.json) with the absolute path to the built index.js and restart Claude Desktop.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "design system mcp server": {
            "design-system": {
                "command": "node",
                "args": [
                    "/ABSOLUTE/PATH/TO/design-system-server/build/index.js"
                ]
            }
        }
    }
}

McpServers

{
    "design-system": {
        "command": "node",
        "args": [
            "/ABSOLUTE/PATH/TO/design-system-server/build/index.js"
        ]
    }
}

An MCP server for accessing and managing design system documentation from a GitHub repository.

This is a Model Context Protocol (MCP) server that provides access to Appian's design system documentation through GitHub repositories. It supports both public and internal documentation sources, allowing LLMs like Claude to query and explore design system components, layouts, and patterns with appropriate access controls.

- Aurora Design System Documentation:appian-design/aurora- The source repository for design system documentation
- Live Documentation Site:https://appian-design.github.io/aurora/- Browse the design system online

For technical users who want to get up and running quickly:

git clone https://github.com/appian-design/aurora-mcp.git cd aurora-mcp npm install

cp .env.example .env # Edit .env with your GitHub token and repository details

npm run build # Add to ~/.aws/amazonq/mcp.json or Claude Desktop config

For detailed setup instructions, see theInstallationsection below.

- Multi-source support: Access both public and internal documentation repositories
- Source attribution: Clear indication of content source (public/internal)
- Priority-based merging: Internal documentation overrides public when both exist
- Access control: Configurable access to internal documentation
- Browse design system categories(components, layouts, patterns, branding, etc.)
- List componentswithin a category with source information
- Get detailed component informationincluding guidance and code examples
- Search across all componentsby keyword with source filtering
- Source management: View source status and manually refresh content

For access to public design system documentation only:
- Clone this repository (or fork it to your own GitHub account)
- Copy the environment file and configure it:

cp .env.example .env

- GITHUB_TOKEN: Your GitHub personal access token (generate athttps://github.com/settings/tokens)
- GITHUB_OWNER: Your GitHub username (the repository owner)
- GITHUB_REPO: Your repository name (e.g., "aurora")

For access to both public and internal documentation:
- Follow the public documentation setup above
- Configure internal documentation access in your.envfile:

# Enable internal documentation ENABLE_INTERNAL_DOCS=true # GitHub token for internal repository (must have access to private repo) INTERNAL_DOCS_TOKEN=your_github_token_for_private_repo # Optional: Internal repository owner (defaults to GITHUB_OWNER) INTERNAL_GITHUB_OWNER=your_internal_repo_owner # Optional: Internal repository name (defaults to design-system-docs-internal) INTERNAL_GITHUB_REPO=your_internal_repo_name

- Place documentation files in a/docsfolder
- Use the same category structure (components, layouts, patterns, etc.)

For detailed configuration options, seeConfiguration Guide.

This section will help you set up the Design System MCP Server to work with Amazon Q chat. This tool allows you to query design system components, patterns, and layouts directly through conversational AI, with support for both public and internal documentation sources.

- Access to our AWS account
- VS Code (recommended)
- Node.js installed on your machine

Check if it's installed by opening the Terminal app and running this command to see the version:node -v.

If you get a "command not found" message, go to theNode.js download pageto get it. You can use the selection tool to run the installation from the command line or the download the binary and run it from your machine.

Pick the current LTS (long-term support) version of Node.

The command line tool will have you pick a node version manager and node package manager. Unless you have a preference for something else, usenvmandnpm.
- Visit the Amazon Q chat installation page:Amazon Q Developer(Command Line)

- We want to use the command line version (CLI) because it's more reliable and has access to the MCP tools.

- Once you start Q, we recommend switching the model to Claude 4 by typing/modeland choosing that option.

You have two options to get the project files:
- Go to the project's GitHub page
- Click the green "Code" button
- Select "Download ZIP"
- Extract the ZIP file to your Desktop or preferred location

- It will download and extract asaurora-mcp-main. You can remove the-mainor leave as is but the rest of the instructions assume it's not there.

Option B: Clone with Git (If you're comfortable with Git)

- Open Terminal (Mac) or Command Prompt (Windows) - Navigate to where you want the project, e.g.,~/repo/ - Run:git clone [repository-url] - Open Terminal (Mac) or Command Prompt (Windows) - Navigate to the project folder, for example: 
cd Desktop/aurora

The MCP server needs API access to GitHub to fetch the design system documentation. You can set up access for public documentation only, or for both public and internal documentation.

Public Documentation Only (Default Setup)

At a high level, here's what you need to do:

- Create a Personal Access Token (PAT) to allow API access to all public repositories (easier)

- Alternatively, you can fork your own copy of the repo and create a PAT for that one (more for development)

Internal Documentation Access (Optional)

If you need access to internal documentation, you'll also need:

- Access to the internal documentation repository
- A separate GitHub token for the private repository
- Additional environment configuration

- Go toGitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens
- Click "Generate new token"
- Give it a descriptive name like "Appian Aurora Docs Access"
- Set expiration to your preference
- Under Repository Access, confirm it's set toPublic repositories
- Click "Generate token"
- Important:Copy the token immediately - you won't be able to see it again! (You may want to paste it in a temporary location until setup is complete.)

-

In the aurora-mcp folder on your machine, run this command in Terminal to copy the example environment file:

For public documentation only, update these values:

- GITHUB_TOKEN: Replace with your actual token from previous step
- GITHUB_OWNER: Should be set toappian-design(unless you created a fork)
- GITHUB_REPO: Should be set toaurora(unless you renamed your fork)

For internal documentation access, also add:

- ENABLE_INTERNAL_DOCS=true
- INTERNAL_DOCS_TOKEN=your_internal_docs_token_here

Now you need to tell Amazon Q where to find this design system server.

- Run this command in Terminal to create the empty file in the right place and open it with TextEdit:

mkdir -p ~/.aws/amazonq && touch ~/.aws/amazonq/mcp.json && open -e ~/.aws/amazonq/mcp.json

- In Terminal/Command Prompt, while in theaurora-mcpproject folder, run:

pwd

- Open themcp.jsonfile in VS Code or any text editor (if it's not already open in TextEdit)
- Add this configuration (replaceYOUR_FULL_PATH_HEREwith the path you copied and leave the/build/index.jsafter the path):

{ "mcpServers": { "design-system": { "command": "node", "args": [ "YOUR_FULL_PATH_HERE/build/index.js" ] } } }

- In a new Terminal window, type this command:qchat mcp list
- You should see a reference to the file you just edited (under global:) with adesign-systemitem listed

Now that the MCP server is configured, you'll want to create a separate workspace for your design system work. This is where you'll generate and organize files before copying them into Interface Designer.

- Create a new folder on your Desktop called something likedesign-system-workormy-design-project
- This folder will be separate from the MCP server folder you downloaded earlier

- Launch VS Code
- Go to File → Open Folder
- Select your new working project folder
- This gives you a clean workspace for your design system files

- You'll use Amazon Q chat to query the design system and generate component code
- Amazon Q will provide you with SAIL code snippets
- You can save these snippets as files in your VS Code project for reference
- When ready, you'll copy and paste the final code into Interface Designer

- Consider creating folders like:

- components/- for individual component files
- layouts/- for layout patterns
- examples/- for code examples and variations
- notes/- for design decisions and documentation
- Open Amazon Q chat (typeq chatin Terminal)
- Try asking questions like:

- "What design system categories are available?"
- "Show me all components in the components category"
- "Search the design system for cards"
- "Check the status of documentation sources" (to see if internal docs are enabled)
- "Get details about the cards component including internal documentation" (if you have internal access)

Step 8: Internal Documentation Setup (Optional)

If you need access to internal documentation, follow these additional steps:

- Access to the internal documentation repository
- Permission to create GitHub Personal Access Tokens for private repositories

- Contact your team lead to get access to the internal documentation repository
- The repository is typically named something likeaurora-internal

- Go toGitHub Settings > Personal access tokens > Fine-grained tokens
- Create a new token with access to the internal repository
- Set the same permissions as your public token (Contents: Read, Metadata: Read)

# Add these lines to your existing .env file ENABLE_INTERNAL_DOCS=true INTERNAL_DOCS_TOKEN=your_internal_token_here

- "Check the status of documentation sources"
- You should see both PUBLIC and INTERNAL sources listed

Once set up, you can access internal documentation by:

- Adding "including internal documentation" to your queries
- Using specific internal component names
- Searching within internal documentation only

- "Get details about the admin-panel component including internal documentation"
- "Search for 'internal' components in internal documentation only"

- Double-check that the path in your config file is correct and absolute (starts with/on Mac orC:\on Windows)
- Make sure you rannpm run buildsuccessfully
- Restart Amazon Q completely

- Install Node.js fromnodejs.org
- Restart your Terminal/Command Prompt after installation

If internal documentation isn't working:

- VerifyENABLE_INTERNAL_DOCS=trueis set in your .env file
- Check thatINTERNAL_DOCS_TOKENhas the correct permissions
- Test the token manually by visiting the repository in your browser
- Use "Check the status of documentation sources" to verify both sources are enabled

If you see "Authentication required" errors:

- Your internal documentation token may have expired
- Verify the token has access to the correct repository
- Try regenerating the token with the same permissions

- Check the main README.md file for more detailed troubleshooting
- SeeMigration Guidefor upgrading from single-source setup
- SeeConfiguration Guidefor advanced configuration options
- The configuration file path must be the complete, absolute path to work properly

Once set up, you can use Amazon Q to explore your design system by asking natural language questions about components, patterns, and layouts. The AI will help you find what you need without having to manually browse through documentation.
-

Make sure you have Claude Desktop installed and up to date

Edit the Claude Desktop configuration file:

~/Library/Application Support/Claude/claude_desktop_config.json

%AppData%\Claude\claude_desktop_config.json

{ "mcpServers": { "design-system": { "command": "node", "args": [ "/ABSOLUTE/PATH/TO/aurora-mcp/build/index.js" ] } } }

(Replace/ABSOLUTE/PATH/TOwith the actual path to this directory)
- Check Claude Desktop logs:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Install

Add to Claude Desktop or Cursor

{
    "mcpServers": {
        "design system mcp server": {
            "design-system": {
                "command": "node",
                "args": [
                    "/ABSOLUTE/PATH/TO/design-system-server/build/index.js"
                ]
            }
        }
    }
}

More like this

Similar MCP servers you might find useful

Browse category

Memory

Memory is an MCP server that provides persistent memory using a local knowledge graph. It lets AI assistants like Claude remember information about the user…

88.1k
Knowledge Base

Git

A Model Context Protocol (MCP) server that provides tools for LLMs to read, search, and manipulate Git repositories. It enables automated repository…

88.1k
Developer Tools