Design System MCP Server

设计系统 MCP 服务

这是一个模型上下文协议（MCP）服务，可通过 GitHub 仓库访问 Appian 的设计系统文档。它支持公共和内部文档来源，让 Claude 等大模型能够在适当的访问控制下查询和探索设计系统组件、布局和模式。

🔗 相关资源

• Aurora 设计系统文档：appian-design/aurora - 设计系统文档的源仓库
• 在线文档站点：https://appian-design.github.io/aurora/ - 在线浏览设计系统

⚡ 快速开始

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

1. 克隆并设置：

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

2. 配置 GitHub 访问权限：

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

3. 构建并配置 MCP：

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

4. 测试连接：

   npm test
   

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

功能

• 多来源支持：访问公共和内部文档仓库
• 来源标注：清楚标明内容来源（公共/内部）
• 按优先级合并：公共和内部文档同时存在时，以内部文档为准
• 访问控制：可配置内部文档的访问权限
• 浏览设计系统分类（组件、布局、模式、品牌等）
• 列出某个分类中的组件，并附带来源信息
• 获取组件详细信息，包括指导说明和代码示例
• 按关键词搜索所有组件，并筛选来源
• 来源管理：查看来源状态并手动刷新内容

安装

仅公共文档

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

1. 克隆此仓库（或将其复刻到你自己的 GitHub 账户）
2. 复制环境文件并进行配置：

   cp .env.example .env
   

3. 编辑 .env 并更新以下值：
   • GITHUB_TOKEN：你的 GitHub 个人访问令牌（可在 https://github.com/settings/tokens 生成）
   • GITHUB_OWNER：你的 GitHub 用户名（仓库所有者）
   • GITHUB_REPO：你的仓库名称（例如，“aurora”）
4. 安装依赖项：

   npm install
   

5. 构建服务：

   npm run build
   

访问内部文档

同时访问公共和内部文档：

1. 按照上方的公共文档设置步骤操作
2. 在 .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
   

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

高级配置

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

与 Amazon Q 搭配使用（Appian 专用）

本节将介绍如何设置设计系统 MCP 服务，以便与 Amazon Q 聊天功能搭配使用。通过此工具，你可以直接借助对话式 AI 查询设计系统组件、模式和布局，并同时支持公共和内部文档来源。

所需条件

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

了解更多 Node.js 信息

打开终端应用并运行以下命令，查看版本以确认是否已安装：node -v。

如果收到“command not found”消息，请前往 Node.js 下载页面获取。你可以使用选择工具从命令行运行安装程序，也可以下载二进制文件并在机器上运行。

选择当前的 LTS（长期支持）版本的 Node。

命令行工具会提示你选择 Node 版本管理器和 Node 包管理器。如果你没有其他偏好，请使用 nvm 和 npm。

步骤 1：安装 Amazon Q Chat

重要

安装期间，请使用 Use with Pro license 选项登录。您需要从我们的内部文档中查找启动 URL。

1. 访问 Amazon Q 聊天安装页面：Amazon Q Developer（命令行）
   • 我们要使用命令行版本（CLI），因为它更可靠，并且可以访问 MCP 工具。
2. 点击“Get Started”，并按照适用于您操作系统的安装说明操作
3. 安装完成后，可在终端命令行中输入 q chat 来访问 Amazon Q
   • 启动 Q 后，我们建议输入 /model 并选择 Claude 4，以切换模型。

步骤 2：下载此项目

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

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

1. 前往项目的 GitHub 页面
2. 点击绿色的“Code”按钮
3. 选择“Download ZIP”
4. 将 ZIP 文件解压到桌面或您喜欢的位置
   • 下载并解压后的文件夹名称为 aurora-mcp-main。您可以删除 -main，也可以保留；不过，后续说明均假定文件夹名称中没有它。

选项 B：使用 Git 克隆（如果您熟悉 Git）

1. 打开终端（Mac）或命令提示符（Windows）
2. 导航到项目存放位置，例如：~/repo/
3. 运行：git clone [repository-url]

步骤 3：安装项目

1. 打开终端（Mac）或命令提示符（Windows）
2. 导航到项目文件夹，例如：

   cd Desktop/aurora
   

3. 安装所需的依赖项：

   npm install
   

4. 构建项目：

   npm run build
   

步骤 4：设置 GitHub 访问权限

MCP 服务需要访问 GitHub API，以获取设计系统文档。您可以仅设置对公开文档的访问权限，也可以同时设置对公开和内部文档的访问权限。

仅访问公开文档（默认设置）

总体而言，您需要完成以下操作：

• 创建个人访问令牌（PAT），以允许访问所有公开仓库的 API（更简单）
  • 或者，您也可以复刻一份自己的仓库副本，并为该副本创建 PAT（更适合开发）
• 将 PAT 复制到本地 aurora-mcp 仓库副本文件夹中的 .env 文件

访问内部文档（可选）

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

• 有权访问内部文档仓库
• 为私有仓库单独创建一个 GitHub 令牌
• 进行额外的环境配置

详细步骤

1. 创建 GitHub 个人访问令牌：

   • 前往 GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens
   • 点击“Generate new token”
   • 为令牌设置一个描述性名称，例如“Appian Aurora Docs Access”
   • 根据需要设置过期时间
   • 在 Repository Access 下，确认已设置为 Public repositories
   • 点击“Generate token”
   • **重要：**请立即复制令牌——之后将无法再次查看！（您可以先将其粘贴到临时位置，待设置完成后再处理。）

2. 创建 .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

   • 保存并关闭文件

3. 重新构建项目：

   npm run build
   

步骤 5：配置 Amazon Q

现在，你需要告知 Amazon Q 在哪里可以找到此设计系统服务。

1. 设置配置文件：

   • 在终端中运行此命令，在正确的位置创建空文件并使用 TextEdit 打开：

     mkdir -p ~/.aws/amazonq && touch ~/.aws/amazonq/mcp.json && open -e ~/.aws/amazonq/mcp.json
     

2. 获取项目的完整路径：

   • 在终端／命令提示符中，进入 aurora-mcp 项目文件夹后运行：

     pwd
     

   • 复制显示的完整路径，暂时粘贴到方便的位置（路径类似 /Users/first.last/Desktop/aurora-mcp）

3. 编辑配置文件：

   • 在 VS Code 或任何文本编辑器中打开 mcp.json 文件（如果它尚未在 TextEdit 中打开）
   • 添加此配置（将 YOUR_FULL_PATH_HERE 替换为你复制的路径，并保留路径后的 /build/index.js）：

   {
       "mcpServers": {
           "design-system": {
               "command": "node",
               "args": [
                   "YOUR_FULL_PATH_HERE/build/index.js"
               ]
           }
       }
   }
   

4. 保存文件并重启 Amazon Q

5. 确认 MCP 配置

   • 在新的终端窗口中，输入此命令：qchat mcp list
   • 你应该能看到对刚才编辑的文件的引用（位于 global: 下），其中列出了 design-system 项

步骤 6：设置工作项目

现在 MCP 服务已配置完成，你可以为设计系统工作创建一个独立的工作区。你可以在这里生成和整理文件，然后再将它们复制到 Interface Designer 中。

1. 创建新的项目文件夹：

   • 在桌面上创建一个新文件夹，例如 design-system-work 或 my-design-project
   • 此文件夹应与之前下载的 MCP 服务文件夹分开

2. 在 VS Code 中打开工作文件夹：

   • 启动 VS Code
   • 前往“文件” → “打开文件夹”
   • 选择新的工作项目文件夹
   • 这样就能为你的设计系统文件提供一个干净的工作区

3. 了解工作流：

   • 你将使用 Amazon Q 聊天来查询设计系统并生成组件代码
   • Amazon Q 会提供 SAIL 代码片段
   • 你可以将这些代码片段保存为 VS Code 项目中的文件以供参考
   • 准备就绪后，你可以将最终代码复制并粘贴到 Interface Designer 中

4. 整理工作区：

   • 可以考虑创建如下文件夹：
     • components/ - 用于存放单个组件文件
     • layouts/ - 用于存放布局模式
     • examples/ - 用于存放代码示例和变体
     • notes/ - 用于记录设计决策和文档

步骤 7：试用

1. 打开 Amazon Q 聊天（在终端中输入 q chat）
2. 尝试提出以下问题：
   • “有哪些设计系统类别可用？”
   • “显示 components 类别中的所有组件”
   • “在设计系统中搜索卡片”
   • “检查文档来源的状态”（查看是否启用了内部文档）
   • “获取 cards 组件的详细信息，包括内部文档”（如果你有内部访问权限）

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

如果你需要访问内部文档，请按照以下附加步骤操作：

前提条件

• 有权访问内部文档仓库
• 有权为私有仓库创建 GitHub Personal Access Token

设置步骤

1. 获取内部仓库的访问权限：

   • 联系团队负责人，获取内部文档仓库的访问权限
   • 该仓库通常名为 aurora-internal

2. 创建内部文档令牌：

   • 前往 GitHub 设置 > Personal access tokens > Fine-grained tokens
   • 创建一个可访问内部仓库的新令牌
   • 设置与公共令牌相同的权限（Contents：Read，Metadata：Read）

3. 更新你的 .env 文件：

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

4. 重新构建并测试：

   npm run build
   

   使用 Amazon Q 进行测试：

   • “检查文档来源的状态”
   • 你应该能看到 PUBLIC 和 INTERNAL 两个来源

使用内部文档

设置完成后，你可以通过以下方式访问内部文档：

• 在查询中添加“包括内部文档”
• 使用具体的内部组件名称
• 仅在内部文档中搜索

查询示例：

• “获取 admin-panel 组件的详细信息，包括内部文档”
• “仅在内部文档中搜索‘internal’组件”

故障排除

如果 Amazon Q 找不到服务：

• 仔细检查配置文件中的路径是否正确且为绝对路径（Mac 上以 / 开头，Windows 上以 C:\ 开头）
• 确保已成功运行 npm run build
• 完全重启 Amazon Q

如果 npm 命令无法运行：

• 从 nodejs.org 安装 Node.js
• 安装后重启终端/命令提示符

如果内部文档无法使用：

• 确认 .env 文件中已设置 ENABLE_INTERNAL_DOCS=true
• 检查 INTERNAL_DOCS_TOKEN 是否具有正确的权限
• 在浏览器中访问代码库，手动测试令牌
• 使用“检查文档源的状态”来确认两个来源均已启用

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

• 你的内部文档令牌可能已过期
• 确认该令牌有权访问正确的代码库
• 尝试使用相同权限重新生成令牌

需要帮助？

• 查看主 README.md 文件，了解更详细的故障排除信息
• 请参阅迁移指南，了解如何从单一来源配置升级
• 请参阅配置指南，了解高级配置选项
• 配置文件路径必须是完整的绝对路径才能正常工作

接下来呢？

设置完成后，你可以通过自然语言提问组件、模式和布局相关问题，使用 Amazon Q 探索你的设计系统。AI 会帮助你找到所需内容，无需手动浏览文档。

与 Claude Desktop 配合使用

1. 确保已安装并更新 Claude Desktop

2. 编辑 Claude Desktop 配置文件：

   MacOS：

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

   Windows：

   %AppData%\Claude\claude_desktop_config.json
   

3. 添加服务配置：

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

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

4. 重启 Claude Desktop

故障排除

如果遇到问题：

1. 检查 Claude Desktop 日志：

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

2. 确认服务可以正常构建和运行，没有错误
3. 确保配置路径是正确的绝对路径
4. 完全重启 Claude Desktop

工具

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

来源管理

1. get-content-sources：查看可用文档来源及其状态
2. refresh-sources：手动刷新文档来源并清除缓存

内容访问

3. list-categories：列出所有可用的设计系统类别
4. list-components：列出指定类别中的所有组件
5. get-component-details：获取特定组件的详细信息，并注明来源
   • includeInternal：访问内部文档（默认值：false）
   • sourceOnly：按特定来源筛选（"public"、"internal"、"all"）
6. search-design-system：按关键词搜索所有组件，并筛选来源
   • includeInternal：在搜索中包含内部文档
   • sourceOnly：按特定来源筛选结果

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

查询示例

基本用法（公开文档）

• “有哪些可用的设计系统类别？”
• “显示‘layouts’类别中的所有组件”
• “获取‘cards’组件的详细信息”
• “在设计系统中搜索‘navigation’”

双源使用（公开 + 内部）

• “检查文档来源的状态”
• “获取 ‘cards’ 组件的详细信息，包括内部文档”
• “仅在内部文档中搜索 ‘internal’ 组件”
• “显示所有组件，包括内部组件”
• “刷新文档来源”

高级筛选

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