设计系统MCP服务器
这是一个模型上下文协议（MCP）服务器，它通过GitHub仓库提供对Appian设计系统文档的访问。该服务器支持公共和内部文档来源，允许像Claude这样的大型语言模型（LLM）在适当的访问控制下查询和探索设计系统的组件、布局和模式。
🔗 相关资源
- Aurora 设计系统文档： Appian设计/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
更多关于Node.js的内容
通过打开终端应用程序并运行以下命令来检查其安装情况，同时查看版本号： node -v.
如果你收到“命令未找到”的信息，请前往 要获取它，你可以使用选择工具通过命令行运行安装程序，或者下载二进制文件并从你的机器上运行它。
选择当前的Node长期支持（LTS）版本。
命令行工具会提示您选择一个Node.js版本管理器和Node.js包管理器。除非您有特定的偏好，否则建议使用 nvm 和 npm。
步骤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个人访问令牌：
- 首选 - 点击“生成新令牌” - 给它起一个描述性的名字，比如“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
- 创建内部文档令牌：
- 首选 - 创建一个具有访问内部仓库权限的新令牌 - 设置与您的公开令牌相同的权限（内容：读取，元数据：读取）
- 更新你的 .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
- 安装后重启您的终端/命令提示符
如果内部文档不起作用：
- 验证
ENABLE_INTERNAL_DOCS=true设置在你的 .env 文件中 - 检查一下
INTERNAL_DOCS_TOKEN具有正确的权限 - 通过在浏览器中访问仓库来手动测试令牌
- 使用“检查文档源的状态”来验证两个源是否都已启用
如果你看到“需要身份验证”的错误：
- 您的内部文档令牌可能已过期
- 验证令牌是否具有对正确存储库的访问权限
- 尝试使用相同的权限重新生成令牌
需要帮助吗？
接下来怎么办？
一旦设置好，您就可以使用Amazon Q，通过用自然语言提问组件、模式和布局相关的问题来探索您的设计系统。人工智能将帮助您找到所需内容，无需手动浏览文档。
与Claude桌面版的使用
- 确保您已安装Claude Desktop并且版本是最新的
- 编辑Claude桌面配置文件：
MacOS：（可译为“苹果操作系统”或保持原样，根据上下文决定是否需要具体翻译）
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows：
%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?"