Which integrations are available for this server?

Provides access to Appian's Aurora design system documentation, enabling users to explore components, layouts, and patterns from both public and internal sources. Integrates with GitHub repositories to fetch and search design system documentation, with support for private repository access through personal access tokens.

How do I use Design System MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Design System MCP Server show me the guidance and code examples for the card component" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Design System MCP Server

by appian-design

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

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.

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:

Clone and setup:

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

Configure GitHub access:

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

Build and configure MCP:

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

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:

Clone this repository (or fork it to your own GitHub account)
Copy the environment file and configure it:
```
cp .env.example .env
```
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")
Install dependencies:
```
npm install
```
Build the server:
```
npm run build
```

Internal Documentation Access

For access to both public and internal documentation:

Follow the public documentation setup above

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

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 theUse with Pro license option. You will need to locate the start URL from our internal documentation.

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.
Click "Get Started" and follow the installation instructions for your operating system
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)

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 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)

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

Step 3: Install the Project

Open Terminal (Mac) or Command Prompt (Windows)
Navigate to the project folder, for example:
```
cd Desktop/aurora
```
Install the required dependencies:
```
npm install
```
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

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.)
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
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.

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
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)
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"
            ]
        }
    }
}
```
Save the file and restart Amazon Q
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.

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

Open Amazon Q chat (type q chat in 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:

Prerequisites

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

Setup Steps

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
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)

Update your .env file:

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

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

Make sure you have Claude Desktop installed and up to date

Edit the Claude Desktop configuration file:

MacOS:

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

Windows:

%AppData%\Claude\claude_desktop_config.json

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)

Restart Claude Desktop

Troubleshooting

If you encounter issues:

Check Claude Desktop logs:

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

Verify your server builds and runs without errors
Make sure the configuration path is absolute and correct
Restart Claude Desktop completely

Tools

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

Source Management

get-content-sources: View available documentation sources and their status
refresh-sources: Manually refresh documentation sources and clear cache

Content Access

list-categories: Lists all available design system categories
list-components: Lists all components in a specific category
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")
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?"

Available Tools

7 tools

get-component-detailsC

Get detailed information about a specific component with source attribution

ParametersJSON Schema

Name	Required	Description
`category`	Yes	Design system category (components, layouts, patterns)
`componentName`	Yes	Name of the component, layout, or pattern
`includeInternal`	No	Include internal documentation if available (default: false)
`sourceOnly`	No	Filter by specific source
`includeSailGuidance`	No	Include SAIL coding guidance (default: true for components/patterns/layouts)

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It only states the tool returns detailed information with source attribution but does not mention potential side effects, authentication requirements, error handling (e.g., if component not found), or any limitations. The read-only nature is implied but not confirmed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no fluff. It is front-loaded with the core purpose. However, it could be slightly more informative without sacrificing conciseness, e.g., specifying that it returns a single component's metadata.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 5 parameters, no output schema, and no annotations. The description is too minimal to cover the complexity. It does not explain what 'source attribution' means, how parameters like 'includeInternal' affect results, or the relationship with sibling tools. An agent would have incomplete context to use it effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, so the schema already documents each parameter clearly. The description adds no extra meaning or context beyond what is in the schema. For example, it does not clarify how 'sourceOnly' interacts with 'includeInternal' or what 'source attribution' means. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves detailed information about a specific component with source attribution. The verb 'get' and resource 'component details' are specific, and it differentiates from sibling 'list-components' by focusing on a single component. However, it does not explicitly distinguish from 'get-content-sources' or 'get-sail-guidance', leaving some ambiguity about what 'detailed information' includes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus its siblings (e.g., list-components, get-sail-guidance). It does not indicate prerequisites, when not to use it, or how it fits with other tools. An agent would need to infer usage from the name and schema, which is not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-content-sourcesA

Get information about available documentation sources and their status

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It states 'Get information...' but does not specify whether results are cached, if authentication is needed, or any side effects. For a simple read operation, this is minimal but not misleading.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with core purpose. No wasted words, every part contributes to understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters, no output schema, and no annotations, the description is adequate for a simple retrieval tool. It lacks details on output format or structure, but for its complexity level, it provides sufficient context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters in input schema (100% coverage). Description adds meaning beyond schema by specifying the resource type and status aspect. Baseline 4 is appropriate as description compensates for absent parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool retrieves information about documentation sources and their status. The verb 'Get information' and resource 'documentation sources' are specific. It distinguishes from siblings like 'list-components' which focus on different resources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs siblings like 'refresh-sources' or 'list-categories'. The purpose implies simple retrieval, but alternatives are not mentioned. Usage is somewhat implied by the tool's clear function.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-sail-guidanceB

Get SAIL coding guidance and best practices

ParametersJSON Schema

Name	Required	Description	Default
`technology`	No	Technology or framework (e.g., 'sail', 'html', 'css')

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears the full burden of behavioral disclosure. It implies a read-only operation by stating 'Get', but it does not detail any behaviors like authentication needs, rate limits, or side effects. For a simple read, the minimal description is acceptable but could be improved.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that conveys the core purpose. It is front-loaded and contains no extraneous words. However, it could be slightly expanded to include more context without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the single parameter and lack of output schema, the description minimally covers what the tool does. It does not mention what form the guidance takes (e.g., list, text block) or any filtering behavior. It is adequate but leaves the agent without full context of the response.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description does not add further meaning to the 'technology' parameter beyond what is already in the schema. It provides no examples, defaults, or formatting hints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Get SAIL coding guidance and best practices'. It specifies a verb ('Get') and a resource ('SAIL coding guidance'), which differentiates it from sibling tools focused on components, content sources, and categories. However, it could be more specific about the scope (e.g., for a given technology).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or sibling tools. The agent receives no context about situations where this tool is preferred over others.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-categoriesA

List all design system categories

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It states 'list all' implying a safe read operation, but does not disclose any other behaviors (e.g., pagination, data format).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that conveys the tool's purpose with no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with no parameters and no output schema, the description is mostly complete. However, it does not describe what information is returned for each category, which would be helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters and 100% schema description coverage. With 0 params, baseline is 4; the description adds no extra parameter info because there are none.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('list') and the resource ('all design system categories'). It distinguishes from the sibling tool 'list-components' which lists components, not categories.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives. The context is implied but not explicit, and there are no exclusions or conditions provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-componentsB

List components in a specific category with source information

ParametersJSON Schema

Name	Required	Description
`category`	Yes	Design system category (components, layouts, patterns)
`includeInternal`	No	Include internal documentation components (default: false)
`sourceOnly`	No	Filter by specific source

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It mentions 'source information' but does not disclose behavior like pagination, rate limits, or side effects. For a list operation, it is likely read-only but not stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that efficiently states the purpose. It could be slightly more structured but avoids unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no annotations, the description is minimal. It fails to clarify what 'source information' means or whether the list is exhaustive. For a simple list tool, this is insufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds 'with source information' hinting at the sourceOnly parameter, but does not add significant meaning beyond the schema's own parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (list), resource (components), and constraints (specific category, with source information). It distinguishes from siblings like get-component-details and list-categories.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for listing components under a category but lacks explicit guidance on when to use this tool versus alternatives such as search-design-system. No when-not or exclusion criteria are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

refresh-sourcesA

Trigger manual refresh of documentation sources

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that it triggers a refresh, omitting details about side effects, required permissions, rate limits, or whether the operation is destructive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no unnecessary words. It conveys the core purpose efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and no output schema, the description provides the minimal information about its purpose. However, it lacks behavioral context such as expected execution time, whether it is asynchronous, or any side effects, making it less than fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so the input schema is fully covered. Per guidelines, the baseline score is 4 for zero parameters, and the description adds no additional parameter information because none is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Trigger manual refresh') and clearly identifies the resource ('documentation sources'). It effectively distinguishes the tool from its read-only siblings like 'get-component-details' and 'list-categories'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies that this tool is for manually refreshing sources, but it does not specify when to use it versus alternatives, nor does it mention any prerequisites or conditions for use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search-design-systemA

Search for components, layouts, or patterns by keyword with source filtering

ParametersJSON Schema

Name	Required	Description
`keyword`	Yes	Keyword to search for in titles and descriptions
`includeInternal`	No	Include internal documentation in search (default: false)
`sourceOnly`	No	Filter results by specific source

TDQS

A3.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It fails to disclose any behavioral traits such as pagination, rate limits, authentication requirements, or what happens with no results. Only states the basic search function.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single concise sentence that conveys the core functionality without any filler. Every word is meaningful and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description should hint at return values or structure. It does not. For a search tool with 3 parameters and one enum, additional context like search result format would improve completeness. Score reflects minimum viability.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters well. The description adds only a summary ('by keyword with source filtering') without enriching meaning beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches for components, layouts, or patterns by keyword with source filtering. It uses a specific verb and resource, and distinguishes itself from sibling tools like list-components (lists all) and get-component-details (specific item).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use when you need to find design system items by keyword and filter by source. However, it does not explicitly state when not to use it (e.g., when you already know the component name or want all items). Siblings provide context but are not mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

7 tool updatesv1.0.0Mar 21, 2026
- First observedget-component-details
- First observedget-content-sources
- First observedget-sail-guidance
- First observedlist-categories
- First observedlist-components
- First observedrefresh-sources
- First observedsearch-design-system

Deploy Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0

Scored 2026-05-02 02:50 across 7 tools

Disambiguation5/5

Each tool targets a distinct operation: component details, source info, guidance, categories, component listing, source refresh, and search. No two tools overlap in purpose.

Naming Consistency4/5

All tools follow a verb_noun pattern, but the verbs vary (get, list, refresh, search) without a strict convention. Minor deviation from full consistency.

Tool Count5/5

7 tools is well-scoped for a design system reference server. Each tool serves a clear purpose without bloat or deficiency.

Completeness4/5

Covers browsing, searching, and source management. Minor gaps: no tool for design tokens or component variants, but core functionality is present.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

smithery-ai-github
ai.smithery
Access the GitHub API, enabling file operations, repository management, search functionality, and…
Version Control Developer Tools CI/CD & DevOps
295
Github Public Repos Mcp
io.github.varvararatta
Dive into the world of open-source with the GitHub Repo Explorer! Utilize the powerful GitHub
Version Control Developer Tools
2
21st.dev AOAuth
dev.21st
Find UI components and themes, retrieve code, and generate with hosted 21st AI when enabled.
Design Tools Developer Tools AI & Machine Learning
2
searchcode A
com.searchcode
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Search Code Analysis Version Control
72

Design System MCP Server

🔗 Related Resources

⚡ Quickstart

Features

Installation

Public Documentation Only

Internal Documentation Access

Advanced Configuration

Usage with Amazon Q (Appian-specific)

What You'll Need

More on Node.js

Step 1: Install Amazon Q Chat

Step 2: Download This Project

Option A: Download ZIP (Easier)

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

Step 3: Install the Project

Step 4: Set Up GitHub Access

Public Documentation Only (Default Setup)

Internal Documentation Access (Optional)

Detailed Steps

Step 5: Configure Amazon Q

Step 6: Set Up Your Working Project

Step 7: Test It Out

Step 8: Internal Documentation Setup (Optional)

Prerequisites

Setup Steps

Using Internal Documentation

Troubleshooting

What's Next?

Usage with Claude Desktop

Troubleshooting

Tools

Source Management

Content Access

Example Queries

Basic Usage (Public Documentation)

Dual-Source Usage (Public + Internal)

Advanced Filtering

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors