使用说明

设计系统MCP服务器

这是一个模型上下文协议（MCP）服务器，它通过GitHub仓库提供对Appian设计系统文档的访问。该服务器支持公共和内部文档来源，允许像Claude这样的大型语言模型（LLM）在适当的访问控制下查询和探索设计系统的组件、布局和模式。

🔗 相关资源

Aurora 设计系统文档： Appian设计/Aurora（或“奥罗拉设计”） - 设计系统文档的源代码仓库
实时文档网站: https://appian-design.github.io/aurora/（该网址可翻译为：“https://appian-design在GitHub上的aurora项目页面”，但通常网址本身不直接翻译，这里仅对网址的组成部分进行意译说明，实际使用时直接保留原网址即可。） - 在线浏览设计系统

⚡ 快速入门

对于希望快速上手的技术用户：

克隆并设置：

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

配置GitHub访问权限：

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

构建并配置MCP:

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

测试连接:
```
npm test
```

如需详细的设置说明，请参阅安装以下部分。

特点/功能

多源支持访问公共和内部文档存储库
来源归因明确显示内容来源（公开/内部）
基于优先级的合并当内部文档和公开文档同时存在时，以内部文档为准
访问控制可配置的内部文档访问权限
浏览设计系统类别 （组件、布局、模式、品牌标识等）
列出组件 在一个包含源信息的类别中
获取详细的组件信息 包括指导和代码示例
在所有组件中搜索 通过关键词并进行来源过滤
源管理查看源状态并手动刷新内容

安装

仅限公开文档

仅用于访问公共设计系统文档：

克隆这个仓库（或者将其分叉到你自己的GitHub账户）
复制环境文件并进行配置：
```
cp .env.example .env
```
编辑 .env 并更新这些值：
- GITHUB_TOKEN您的GitHub个人访问令牌（在https://github.com/settings/tokens生成）
- GITHUB_OWNER你的GitHub用户名（仓库所有者）
- GITHUB_REPO你的仓库名称（例如，“aurora”）
安装依赖项：
```
npm install
```
构建服务器：
```
npm run build
```

内部文档访问

要访问公共和内部文档，请：

按照上述公开文档的设置进行操作

在您的（系统/环境中）配置内部文档访问权限 .env 文件：

# 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

确保您的内部仓库与公共仓库遵循相同的结构：
- 将文档文件放置在 /docs 文件夹
- 使用相同的分类结构（组件、布局、模式等）

高级配置

如需详细的配置选项，请参阅配置指南。

与 Amazon Q 的使用（Appian 特定）

本节将指导您设置设计系统MCP服务器，以便与Amazon Q聊天功能协同工作。此工具允许您直接通过对话式人工智能查询设计系统的组件、模式和布局，并支持公开和内部文档资源。

您将需要的物品

访问我们的AWS账户
VS Code（推荐）
您的机器上已安装Node.js

步骤1：安装Amazon Q聊天应用

[!重要] 在安装过程中，请使用（账号）登录 Use with Pro license 选项。您需要从我们的内部文档中找到起始URL。

访问 Amazon Q 聊天安装页面： Amazon Q 开发者（或：亚马逊Q开发者工具） (命令行)
- 我们希望使用命令行版本（CLI），因为它更可靠，并且可以访问MCP工具。
点击“开始”，然后按照您操作系统的安装说明进行操作
安装完成后，您可以通过终端命令行输入来访问 Amazon Q： q chat
- 一旦你启动了Q，我们建议通过输入来切换模型到Claude 4 /model 并选择那个选项。

步骤2：下载此项目

您有两种方式获取项目文件：

选项A：下载ZIP文件（更简单）

前往该项目的GitHub页面
点击绿色的“代码”按钮
选择“下载ZIP文件”
将ZIP文件解压到您的桌面或您选择的位置
- 它将下载并解压为 aurora-mcp-main你可以移除 -main 或者保持原样，但其余的说明均假设它不存在。

选项B：使用Git进行克隆（如果你对Git熟悉的话）

打开终端（Mac）或命令提示符（Windows）
导航到你想要存放项目的目录，例如。， ~/repo/
运行： git clone [repository-url]

步骤3：安装项目

打开终端（Mac）或命令提示符（Windows）
导航到项目文件夹，例如：
```
cd Desktop/aurora
```
安装所需的依赖项：
```
npm install
```
构建项目：
```
npm run build
```

步骤4：设置GitHub访问权限

MCP服务器需要通过GitHub的API访问来获取设计系统文档。您可以设置仅访问公开文档，或同时访问公开和内部文档。

仅公开文档（默认设置）

概括来说，你需要做的是：

创建一个个人访问令牌（PAT）以允许API访问所有公共仓库（更简单）
- 或者，你可以克隆一个自己的仓库副本，并为这个副本创建一个个人访问令牌（PAT）（更多用于开发）
将PAT复制到一个（地方/设备/文件等，具体根据上下文确定） .env 在你本地副本的文件夹中找到文件 aurora-mcp 仓库

内部文档访问（可选）

如果您需要访问内部文档，您还需要：

访问内部文档存储库
为私有仓库单独设置一个GitHub令牌
额外的环境配置

详细步骤

创建一个GitHub个人访问令牌：
- 首选 GitHub 设置 > 开发者设置 > 个人访问令牌 > 精细粒度令牌
- 点击“生成新令牌”
- 给它起一个描述性的名字，比如“Appian Aurora 文档访问”
- 根据您的喜好设置过期时间
- 在“仓库访问”下，确认它已设置为 Public repositories
- 点击“生成令牌”
- 重要提示： 立即复制令牌——之后将无法再次查看！（您可能需要在设置完成前，先将其粘贴到一个临时位置。）
创建一个 .env 文件：
- 在您的机器上的aurora-mcp文件夹中，打开终端并运行以下命令以复制示例环境文件：
```
cp .env.example .env
```
- 打开 .env 在文本编辑器中打开文件
```
open -e .env
```
- 仅供公开文档使用更新这些值：
  - GITHUB_TOKEN用上一步中获取的实际令牌替换
  - GITHUB_OWNER应设置为 appian-design （除非你创建了一个分支）
  - GITHUB_REPO应设置为 aurora （除非你更改了你的分支名称）
- 用于访问内部文档，并补充：
  - ENABLE_INTERNAL_DOCS=true
  - INTERNAL_DOCS_TOKEN=your_internal_docs_token_here
- 保存并关闭文件
重新构建项目：
```
npm run build
```

第五步：配置Amazon Q

现在，您需要告诉 Amazon Q 在哪里可以找到这个设计系统服务器。

设置配置文件：
- 在终端中运行此命令，以在正确的位置创建一个空文件并用TextEdit打开它：
```
mkdir -p ~/.aws/amazonq && touch ~/.aws/amazonq/mcp.json && open -e ~/.aws/amazonq/mcp.json
```
获取项目的完整路径：
- 在终端/命令提示符中，当位于 aurora-mcp 项目文件夹，运行：
```
pwd
```
- 复制显示的完整路径，并粘贴到一个方便的地方（它看起来会像这样： /Users/first.last/Desktop/aurora-mcp)
编辑配置文件：
- 打开 mcp.json 在 VS Code 或任何文本编辑器中打开文件（如果它尚未在 TextEdit 中打开）
- 添加此配置（替换 YOUR_FULL_PATH_HERE （将路径）复制到你粘贴的地方，并留出（空间/位置） /build/index.js （路径之后）：
```
{
    "mcpServers": {
        "design-system": {
            "command": "node",
            "args": [
                "YOUR_FULL_PATH_HERE/build/index.js"
            ]
        }
    }
}
```
保存文件并重新启动Amazon Q
确认MCP配置
- 在新的终端窗口中，输入以下命令： qchat mcp list
- 你应该能看到对你刚刚编辑的文件的引用（在“全局:”下），并且有一个 design-system 列出的项目

步骤6：设置您的工作项目

既然MCP服务器已经配置完毕，您接下来应该为设计系统工作创建一个独立的工作区。您将在该工作区中生成和整理文件，然后再将它们复制到Interface Designer中。

创建一个新项目文件夹：
- 在你的桌面上创建一个新文件夹，命名为类似 design-system-work 或者 my-design-project
- 这个文件夹将与您之前下载的MCP服务器文件夹分开
在VS Code中打开你的工作文件夹：
- 启动 VS Code
- 转到“文件”→“打开文件夹”
- 选择您的新工作项目文件夹
- 这为您提供了用于设计系统文件的干净工作空间
了解工作流程：
- 你将使用 Amazon Q 聊天来查询设计系统并生成组件代码
- Amazon Q 将为您提供 SAIL 代码片段
- 你可以将这些代码片段保存为VS Code项目中的文件以供参考
- 准备就绪后，您将把最终代码复制并粘贴到界面设计器中
整理你的工作空间：
- 考虑创建以下文件夹：
  - components/ - 对于单个组件文件
  - layouts/ - 用于布局图案
  - examples/ - 用于代码示例和变体
  - notes/ - 用于设计决策和文档记录

步骤7：进行测试

打开Amazon Q聊天（输入 q chat 在终端（里）
试着问一些这样的问题：
- “有哪些可用的设计系统类别？”
- “显示组件类别中的所有组件”
- “在设计系统中搜索卡片”
- “检查文档源的状态”（以查看内部文档是否已启用）
- “获取卡片组件的详细信息，包括内部文档”（如果您有内部访问权限）

步骤8：设置内部文档（可选）

如果您需要访问内部文档，请按照以下额外步骤操作：

先决条件

访问内部文档存储库
为私有仓库创建GitHub个人访问令牌的权限

设置步骤

访问内部仓库：
- 联系您的团队负责人以获取访问内部文档存储库的权限
- 该存储库通常命名为类似 aurora-internal
创建内部文档令牌：
- 首选 GitHub 设置 > 个人访问令牌 > 精细粒度令牌
- 创建一个具有访问内部仓库权限的新令牌
- 设置与您的公开令牌相同的权限（内容：读取，元数据：读取）

更新你的 .env 文件：

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

重建并测试：
```
npm run build
```
使用 Amazon Q 进行测试：
- “检查文档来源的状态”
- 你应该能看到列出的PUBLIC（公开）和INTERNAL（内部）两种来源

使用内部文件

一旦设置完成，您可以通过以下方式访问内部文档：

在你的查询中加上“包括内部文档”
使用特定的内部组件名称
仅在内部文档中搜索

示例查询：

“获取关于管理面板组件的详细信息，包括内部文档”
“仅在内部文档中搜索‘内部’组件”

故障排除

如果Amazon Q无法找到服务器：

再次检查你的配置文件中的路径是否正确且为绝对路径（以 / 在Mac上或 C:\ （在Windows上）
确保你已经运行了 npm run build 成功地
完全重启 Amazon Q

如果npm命令不起作用：

从（指定来源）安装 Node.js nodejs.org
安装后重启您的终端/命令提示符

如果内部文档不起作用：

验证 ENABLE_INTERNAL_DOCS=true 设置在你的 .env 文件中
检查一下 INTERNAL_DOCS_TOKEN 具有正确的权限
通过在浏览器中访问仓库来手动测试令牌
使用“检查文档源的状态”来验证两个源是否都已启用

如果你看到“需要身份验证”的错误：

您的内部文档令牌可能已过期
验证令牌是否具有对正确存储库的访问权限
尝试使用相同的权限重新生成令牌

需要帮助吗？

请查看主 README.md 文件以获取更详细的故障排除信息
看见迁移指南用于从单一来源配置升级
见配置指南用于高级配置选项
配置文件路径必须是完整的绝对路径才能正常工作

接下来怎么办？

一旦设置好，您就可以使用Amazon Q，通过用自然语言提问组件、模式和布局相关的问题来探索您的设计系统。人工智能将帮助您找到所需内容，无需手动浏览文档。

与Claude桌面版的使用

确保您已安装Claude Desktop并且版本是最新的
编辑Claude桌面配置文件：

MacOS：（可译为“苹果操作系统”或保持原样，根据上下文决定是否需要具体翻译）
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
Windows：
```
%AppData%\Claude\claude_desktop_config.json
```

添加服务器配置：

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

（替换 /ABSOLUTE/PATH/TO （以及此目录的实际路径）

重启Claude桌面版

故障排除

如果您遇到问题：

检查Claude Desktop日志：

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

验证您的服务器构建是否成功且运行无误
确保配置路径是绝对路径且正确无误
完全重启Claude桌面版

工具

该服务器提供了以下支持双源的工具：

源管理

获取内容来源查看可用的文档源及其状态
刷新源手动刷新文档源并清除缓存

内容访问

列出类别列出所有可用的设计系统类别
列出组件列出特定类别中的所有组件
获取组件详细信息获取特定组件的详细信息，包括来源归属
- includeInternal访问内部文档（默认：false）
- sourceOnly按特定来源过滤（“公开”、“内部”、“全部”）
搜索设计系统通过关键词在所有组件中进行搜索，并应用源代码过滤
- includeInternal在搜索中包含内部文档
- sourceOnly按特定来源筛选结果

如需详细的API文档，请参阅 API指南。

示例查询

基本用法（公开文档）

“有哪些可用的设计系统类别？”
“显示‘布局’类别中的所有组件”
“获取有关‘卡片’组件的详细信息”
“在设计系统中搜索‘导航’”

双源使用（公开+内部）

“检查文档来源的状态”
“获取有关‘卡片’组件的详细信息，包括内部文档”
“仅在内部文档中搜索‘内部’组件”
“给我展示所有组件，包括内部组件”
“刷新文档源”

高级过滤

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

设计系统文档服务器

使用说明

设计系统MCP服务器

🔗 相关资源

⚡ 快速入门

特点/功能

安装

仅限公开文档

内部文档访问

高级配置

与 Amazon Q 的使用（Appian 特定）

您将需要的物品

更多关于Node.js的内容

步骤1：安装Amazon Q聊天应用

步骤2：下载此项目

选项A：下载ZIP文件（更简单）

选项B：使用Git进行克隆（如果你对Git熟悉的话）

步骤3：安装项目

步骤4：设置GitHub访问权限

仅公开文档（默认设置）

内部文档访问（可选）

详细步骤

第五步：配置Amazon Q

步骤6：设置您的工作项目

步骤7：进行测试

步骤8：设置内部文档（可选）

先决条件

设置步骤

使用内部文件

故障排除

接下来怎么办？

与Claude桌面版的使用

故障排除

工具

源管理

内容访问

示例查询

基本用法（公开文档）

双源使用（公开+内部）

高级过滤

使用说明

设计系统MCP服务器

🔗 相关资源

⚡ 快速入门

特点/功能

安装

仅限公开文档

内部文档访问

高级配置

与 Amazon Q 的使用（Appian 特定）

您将需要的物品

更多关于Node.js的内容

步骤1：安装Amazon Q聊天应用

步骤2：下载此项目

选项A：下载ZIP文件（更简单）

选项B：使用Git进行克隆（如果你对Git熟悉的话）

步骤3：安装项目

步骤4：设置GitHub访问权限

仅公开文档（默认设置）

内部文档访问（可选）

详细步骤

第五步：配置Amazon Q

步骤6：设置您的工作项目

步骤7：进行测试

步骤8：设置内部文档（可选）

先决条件

设置步骤

使用内部文件

故障排除

接下来怎么办？

与Claude桌面版的使用

故障排除

工具

源管理

内容访问

示例查询

基本用法（公开文档）

双源使用（公开+内部）

高级过滤

相关 MCP

文档管理服务

GitHub MCP服务器

文档管理服务器

GitHub代码上下文服务

模型上下文协议服务器

文档版本助手