Design System MCP Server

Design System MCP Server

これは、GitHub リポジトリを通じて Appian のデザインシステムのドキュメントにアクセスできる Model Context Protocol（MCP）サーバーです。公開ドキュメントと社内ドキュメントの両方をサポートしており、適切なアクセス制御のもとで、Claude などの LLM がデザインシステムのコンポーネント、レイアウト、パターンを検索して調べることができます。

🔗 関連リソース

• 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 固有）

このセクションでは、Amazon Q チャットで Design System MCP Server を使用するためのセットアップ方法を説明します。このツールを使用すると、公開および社内のドキュメントソースに対応しながら、会話型 AI を通じてデザインシステムのコンポーネント、パターン、レイアウトを直接検索できます。

必要なもの

• AWS アカウントへのアクセス
• VS Code（推奨）
• マシンにインストールされた Node.js

Node.js の詳細

インストールされているか確認するには、ターミナルアプリを開き、次のコマンドを実行してバージョンを確認します：node -v。

「command not found」というメッセージが表示された場合は、Node.js のダウンロードページから入手してください。選択ツールを使ってコマンドラインからインストールを実行するか、バイナリをダウンロードしてマシン上で実行できます。

Node.js の現行 LTS（長期サポート）バージョンを選択してください。

コマンドラインツールで、Node.js のバージョンマネージャーとパッケージマネージャーを選択します。特に希望がなければ、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：このプロジェクトをダウンロードする

プロジェクトファイルを取得するには、次の 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 アクセスを必要とします。公開ドキュメントのみへのアクセス、または公開ドキュメントと社内ドキュメントの両方へのアクセスを設定できます。

公開ドキュメントのみ（デフォルト設定）

概要として、次の作業が必要です。

• すべての公開リポジトリへの API アクセスを許可する Personal Access Token（PAT）を作成します（簡単です）
  • 代わりに、自分用のリポジトリのフォークを作成し、そのリポジトリ用の PAT を作成することもできます（開発向けです）
• PAT を、ローカルコピーの aurora-mcp リポジトリがあるフォルダー内の .env ファイルにコピーします

社内ドキュメントへのアクセス（任意）

社内ドキュメントへのアクセスが必要な場合は、次も必要です。

• 社内ドキュメントリポジトリへのアクセス権
• プライベートリポジトリ用の別の GitHub トークン
• 追加の環境設定

詳細な手順

1. GitHub Personal Access Token を作成する：

   • 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. 設定ファイルを編集します：

   • 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"
               ]
           }
       }
   }
   

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 カテゴリーのすべてのコンポーネントを表示してください」
   • 「デザインシステム内でカードを検索してください」
   • 「ドキュメントソースのステータスを確認してください」（内部ドキュメントが有効かどうかを確認します）。
   • 「内部ドキュメントを含めて、カードコンポーネントの詳細を取得してください」（内部アクセス権がある場合）。

ステップ 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 に正しい権限があることを確認します
• ブラウザーでリポジトリにアクセスして、トークンを手動でテストします
• 「ドキュメントソースのステータスを確認」を使用して、両方のソースが有効になっていることを確認します

「Authentication required」エラーが表示される場合：

• 内部ドキュメント用トークンの有効期限が切れている可能性があります
• トークンが正しいリポジトリにアクセスできることを確認します
• 同じ権限でトークンを再生成してみます

サポートが必要な場合

• 詳細なトラブルシューティングについては、メインの 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』を検索して」

2つのソースの使用（公開＋内部）

• 「ドキュメントソースのステータスを確認する」
• 「内部ドキュメントも含めて、『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?"