Aurora Design System MCP Server

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](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-