设计系统服务器

Name: 设计系统服务器
Author: appian-design

作者：appian-design5 星标更新：2025-09-28

安装使用来源：spider==github.com

项目介绍

设计系统 MCP 服务器

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

🔗 相关资源

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

⚡ 快速开始

对于希望快速启动的技术用户：

克隆并设置：

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

配置GitHub访问：

cp .env.example .env
# 使用您的GitHub令牌和仓库详情编辑.env文件

构建并配置MCP：

npm run build
# 添加到~/.aws/amazonq/mcp.json或Claude Desktop配置中

测试连接：
```
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_DOCS=true

# 内部仓库的GitHub令牌（必须有访问私有仓库的权限）
INTERNAL_DOCS_TOKEN=your_github_token_for_private_repo

# 可选：内部仓库拥有者（默认为GITHUB_OWNER）
INTERNAL_GITHUB_OWNER=your_internal_repo_owner

# 可选：内部仓库名称（默认为design-system-docs-internal）
INTERNAL_GITHUB_REPO=your_internal_repo_name

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

高级配置

有关详细配置选项，请参阅配置指南。

与Amazon Q（Appian特定）的使用

本节将帮助您设置Design System MCP Server以与Amazon Q聊天工具配合使用。该工具允许您通过对话式AI直接查询设计系统组件、模式和布局，支持公共和内部文档源。

您需要什么

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

第一步：安装Amazon Q聊天

[!重要] 在安装过程中，使用“与Pro许可证一起使用”的选项登录。您需要从我们内部文档中找到启动URL。

访问Amazon Q聊天安装页面：Amazon Q开发者（命令行）
- 我们想要使用命令行版本（CLI），因为它更可靠且可以访问MCP工具。
点击“开始”并按照适用于您操作系统的安装说明进行操作
安装完成后，可以通过在终端命令行中键入q chat来访问Amazon Q
- 开始Q后，我们建议切换模型到Claude 4，通过键入/model并选择该选项。

第二步：下载此项目

您有两个选项来获取项目文件：

选项A：下载ZIP（更容易）

转到项目的GitHub页面
点击绿色的“Code”按钮
选择“Download ZIP”
将ZIP文件提取到桌面或其他首选位置
- 它将下载并提取为aurora-mcp-main。您可以删除-main或保持不变，但其余说明假设它不存在。

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

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

第三步：安装项目

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

第四步：设置GitHub访问

MCP服务器需要API访问GitHub以获取设计系统文档。您可以仅为公共文档设置访问，也可以为公共和内部文档设置访问。

仅限公共文档（默认设置）

总体来说，您需要做的是：

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

访问内部文档（可选）

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

访问内部文档仓库
私有仓库的单独GitHub令牌
额外的环境配置

详细步骤

创建GitHub个人访问令牌：
- 前往GitHub设置 > 开发者设置 > 个人访问令牌 > 细粒度令牌
- 点击“生成新令牌”
- 给它一个描述性的名称，如“Appian Aurora Docs Access”
- 设置到期时间为您喜欢的时间
- 在仓库访问下，确认设置为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）
编辑配置文件：
- 在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"
            ]
        }
    }
}
```
保存文件并重启Amazon Q
确认MCP配置
- 在新的终端窗口中，键入此命令：qchat mcp list
- 您应该看到刚刚编辑的文件（在全局下）列出的design-system项

第六步：设置您的工作项目

现在MCP服务器已经配置好，您需要创建一个单独的工作空间用于设计系统工作。这是您生成和组织文件的地方，然后再将其复制到界面设计器中。

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

第七步：试一试

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

第八步：内部文档设置（可选）

如果您需要访问内部文档，请遵循以下额外步骤：

先决条件

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

设置步骤

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

更新您的.env文件：

# 将这些行添加到现有的.env文件中
ENABLE_INTERNAL_DOCS=true
INTERNAL_DOCS_TOKEN=your_internal_token_here

重新构建并测试：
```
npm run build
```
使用Amazon Q测试：
- “检查文档来源的状态”
- 您应该看到列出的公共和内部来源

使用内部文档

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

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

示例查询：

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

故障排除

如果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文件以获取更多详细的故障排除信息
查看Migration Guide以升级单源设置
查看Configuration Guide以获取高级配置选项
配置文件路径必须是完整的绝对路径才能正常工作

下一步是什么？

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

与Claude Desktop的使用

确保您已安装并更新了Claude Desktop

编辑Claude Desktop配置文件：

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 Desktop

故障排除

如果您遇到问题：

检查Claude Desktop日志：

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

验证您的服务器构建并运行无误
确保配置路径是绝对且正确的
完全重启Claude Desktop

工具

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

来源管理

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

内容访问

list-categories：列出所有可用的设计系统类别
list-components：列出特定类别中的所有组件
get-component-details：获取特定组件的详细信息，附带来源归属
- includeInternal：访问内部文档（默认：false）
- sourceOnly：按特定来源过滤（“public”，“internal”，“all”）
search-design-system：按关键词搜索所有组件，并进行来源过滤
- includeInternal：在搜索中包含内部文档
- sourceOnly：按特定来源过滤结果

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

示例查询

基础用法（公共文档）

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

双源用法（公共+内部）

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

高级过滤

// 公共用户 - 默认行为
"获取卡片组件的详细信息"

// 内部用户 - 访问内部文档
"获取卡片组件的详细信息，包含内部文档"

// 仅在内部文档中搜索
"在内部文档中搜索‘小部件’

设计系统服务器

项目介绍

设计系统 MCP 服务器

🔗 相关资源

⚡ 快速开始

功能

安装

仅限公共文档

访问内部文档

高级配置

与Amazon Q（Appian特定）的使用

您需要什么

更多关于Node.js

第一步：安装Amazon Q聊天

第二步：下载此项目

选项A：下载ZIP（更容易）

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

第三步：安装项目

第四步：设置GitHub访问

仅限公共文档（默认设置）

访问内部文档（可选）

详细步骤

第五步：配置Amazon Q

第六步：设置您的工作项目

第七步：试一试

第八步：内部文档设置（可选）

先决条件

设置步骤

使用内部文档

故障排除

下一步是什么？

与Claude Desktop的使用

故障排除

工具

来源管理

内容访问

示例查询

基础用法（公共文档）

双源用法（公共+内部）

高级过滤