Design System MCP Server

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.

🔗 Related Resources

• 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

⚡ Quickstart

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

1. Clone and setup:

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

2. Configure GitHub access:

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

3. Build and configure MCP:

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

4. Test the connection:

npm test

For detailed setup instructions, see the Installation section below.

Features

• 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 components within a category with source information
• Get detailed component information including guidance and code examples
• Search across all components by keyword with source filtering
• Source management: View source status and manually refresh content

Installation

Public Documentation Only

For access to public design system documentation only:

1. Clone this repository (or fork it to your own GitHub account)

2. Copy the environment file and configure it:

cp .env.example .env

3. Edit `.env` and update the values:

4. Install dependencies:

npm install

5. Build the server:

npm run build

Internal Documentation Access

For access to both public and internal documentation:

1. Follow the public documentation setup above

2. Configure internal documentation access in your `.env` file:

# 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

3. Ensure your internal repository follows the same structure as the public one:

Advanced Configuration

For detailed configuration options, see Configuration Guide.

Usage with Amazon Q (Appian-specific)

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.

What You'll Need

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

More on Node.js

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 the Node.js download page to 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, use `nvm` and `npm`.

Step 1: Install Amazon Q Chat

> [!IMPORTANT]

> During installation, sign in with the `Use with Pro license` option. You will need to locate the start URL from our internal documentation.

1. Visit the Amazon Q chat installation page: Amazon Q Developer (Command Line)

3. Click "Get Started" and follow the installation instructions for your operating system

4. Once installed, you can access Amazon Q through the terminal command line by typing `q chat`

Step 2: Download This Project

You have two options to get the project files:

Option A: Download ZIP (Easier)

1. Go to the project's GitHub page

2. Click the green "Code" button

3. Select "Download ZIP"

4. Extract the ZIP file to your Desktop or preferred location

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

1. Open Terminal (Mac) or Command Prompt (Windows)

2. Navigate to where you want the project, e.g., `~/repo/`

3. Run: `git clone [repository-url]`

Step 3: Install the Project

1. Open Terminal (Mac) or Command Prompt (Windows)

2. Navigate to the project folder, for example:

cd Desktop/aurora

3. Install the required dependencies:

npm install

4. Build the project:

npm run build

Step 4: Set Up GitHub Access

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)
• Copy the PAT to a `.env` file in the folder of your local copy of the `aurora-mcp` repo

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

Detailed Steps

1. Create a GitHub Personal Access Token:

1. Create a .env file:

cp .env.example .env

open -e .env

1. Rebuild the project:

npm run build

Step 5: Configure Amazon Q

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

1. Set up configuration file:

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

2. Get the full path to your project:

pwd

3. Edit the configuration file:

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

4. Save the file and restart Amazon Q

5. Confirm MCP configuration

Step 6: Set Up Your Working Project

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.

1. Create a new project folder:

1. Open your working folder in VS Code:

1. Understanding the workflow:

1. Organize your workspace:

Step 7: Test It Out

1. Open Amazon Q chat (type `q chat` in Terminal)

2. Try asking questions like:

Step 8: Internal Documentation Setup (Optional)

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

Prerequisites

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

Setup Steps

1. Get access to internal repository:

2. Create internal documentation token:

3. Update your .env file:

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

4. Rebuild and test:

npm run build

Test with Amazon Q:

Using Internal Documentation

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

Example queries:

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

Troubleshooting

If Amazon Q can't find the server:

• Double-check that the path in your config file is correct and absolute (starts with `/` on Mac or `C:\` on Windows)
• Make sure you ran `npm run build` successfully
• Restart Amazon Q completely

If npm commands don't work:

• Install Node.js from nodejs.org
• Restart your Terminal/Command Prompt after installation

If internal documentation isn't working:

• Verify `ENABLE_INTERNAL_DOCS=true` is set in your .env file
• Check that `INTERNAL_DOCS_TOKEN` has 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

Need help?

• Check the main README.md file for more detailed troubleshooting
• See Migration Guide for upgrading from single-source setup
• See Configuration Guide for advanced configuration options
• The configuration file path must be the complete, absolute path to work properly

What's Next?

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.

Usage with Claude Desktop

1. Make sure you have Claude Desktop installed and up to date

2. Edit the Claude Desktop configuration file:

MacOS:

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

Windows:

%AppData%\Claude\claude_desktop_config.json

3. Add the server configuration:

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

(Replace `/ABSOLUTE/PATH/TO` with the actual path to this directory)

4. Restart Claude Desktop

Troubleshooting

If you encounter issues:

1. Check Claude Desktop logs:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

2. Verify your server builds and runs without errors

3. Make sure the configuration path is absolute and correct

4. Restart Claude Desktop completely

Tools

The server provides the following tools with dual-source support:

Source Management

1. get-content-sources: View available documentation sources and their status

2. refresh-sources: Manually refresh documentation sources and clear cache

Content Access

3. list-categories: Lists all available design system categories

4. list-components: Lists all components in a specific category

5. get-component-details: Gets detailed information about a specific component with source attribution

6. search-design-system: Searches across all components by keyword with source filtering

For detailed API documentation, see API Guide.

Example Queries

Basic Usage (Public Documentation)

• "What design system categories are available?"
• "Show me all components in the 'layouts' category"
• "Get details about the 'cards' component"
• "Search the design system for 'navigation'"

Dual-Source Usage (Public + Internal)

• "Check the status of documentation sources"
• "Get details about the 'cards' component including internal documentation"
• "Search for 'internal' components in internal documentation only"
• "Show me all components, including internal ones"
• "Refresh the documentation sources"

Advanced Filtering

// Public users - default behavior
"Get details about the cards component"

// Internal users - access internal documentation
"Get details about the cards component with internal documentation included"

// Search only internal documentation
"Search for 'widget' in internal documentation only"

// Check what sources are available
"What documentation sources are available?"