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:
   • GITHUB_TOKEN: Your GitHub personal access token (generate at https://github.com/settings/tokens)
   • GITHUB_OWNER: Your GitHub username (the repository owner)
   • GITHUB_REPO: Your repository name (e.g., "aurora")
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:
   • Place documentation files in a /docs folder
   • Use the same category structure (components, layouts, patterns, etc.)

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)
   • We want to use the command line version (CLI) because it's more reliable and has access to the MCP tools.
2. Click "Get Started" and follow the installation instructions for your operating system
3. Once installed, you can access Amazon Q through the terminal command line by typing q chat
   • Once you start Q, we recommend switching the model to Claude 4 by typing /model and choosing that option.

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
   • It will download and extract as aurora-mcp-main. You can remove the -main or 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)

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)
  • Alternatively, you can fork your own copy of the repo and create a PAT for that one (more for development)
• 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:

   • Go to GitHub 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 to Public 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.)

2. Create a .env file:

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

     cp .env.example .env
     

   • Open the .env file in a text editor

     open -e .env
     

   • For public documentation only, update these values:

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

   • For internal documentation access, also add:

     • ENABLE_INTERNAL_DOCS=true
     • INTERNAL_DOCS_TOKEN=your_internal_docs_token_here

   • Save and close the file

3. 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:

   • 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
     

2. Get the full path to your project:

   • In Terminal/Command Prompt, while in the aurora-mcp project folder, run:

     pwd
     

   • Copy the full path that appears and paste it somewhere handy for now (it will look something like /Users/first.last/Desktop/aurora-mcp)

3. Edit the configuration file:

   • Open the mcp.json file in VS Code or any text editor (if it's not already open in TextEdit)
   • Add this configuration (replace YOUR_FULL_PATH_HERE with the path you copied and leave the /build/index.js after the path):

   {
       "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

   • 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 a design-system item listed

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:

   • Create a new folder on your Desktop called something like design-system-work or my-design-project
   • This folder will be separate from the MCP server folder you downloaded earlier

2. Open your working folder in VS Code:

   • 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

3. Understanding the workflow:

   • 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

4. Organize your workspace:

   • 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

Step 7: Test It Out

1. Open Amazon Q chat (type q chat in Terminal)
2. 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:

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:

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

2. Create internal documentation token:

   • Go to GitHub 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)

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:

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

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
   • includeInternal: Access internal documentation (default: false)
   • sourceOnly: Filter by specific source ("public", "internal", "all")
6. search-design-system: Searches across all components by keyword with source filtering
   • includeInternal: Include internal documentation in search
   • sourceOnly: Filter results by specific source

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?"