Optics MCP

🚀 Optics MCP Server

Optics Design SystemのためのModel Context Protocol (MCP) サーバーです。これにより、LLMはhttps://docs.optics.rolemodel.design のデザイントークン、コンポーネント、およびドキュメントを理解し、操作することができます。

⚠️ 重要: Opticsの理解

AIエージェントの場合は、まずSYSTEM_OVERVIEW.mdを読んでください！

Opticsは、一般的なデザインシステムとは異なる、洗練されたHSLベースのカラーシステムを使用しています。システムの概要では以下が説明されています。

• --color-primaryトークンがない理由（代わりに--op-color-primary-baseを使用する）
• 3層構造のトークンアーキテクチャ（HSLベース → スケール → Onトークン）
• 正しいトークンを見つけて使用する方法
• 一般的な間違いとその回避方法

重要なポイント: Opticsには500以上のカラートークンがあり、単純な名前と値のペアではなく、予測可能なスケールシステムとして整理されています。

🚀 クイックスタート

このMCPサーバーは、Opticsデザインシステムを操作するための14のツールとリソースを提供します。

• 83のデザイントークン：実際のHSLベースの色、calcベースのスペーシング、タイポグラフィ、ボーダー、およびシャドウ
• 24のコンポーネント：SCSSから抽出された正確なトークン依存関係を持つすべてのOpticsコンポーネント
• 7つのコアツール：トークン、コンポーネント、およびドキュメントをクエリする
• 7つの高度なツール：テーマ生成、検証、アクセシビリティチェック、コードスキャフォールディング、およびスタイルガイド生成
• 5つのMCPプロンプト：一般的なデザインシステムタスクのための事前設定されたワークフロー
• ドキュメント：デザインシステムのガイドラインとベストプラクティス

✨ 主な機能

アーキテクチャ

graph TB
    subgraph "MCP Client (AI/LLM)"
        CLIENT[AI Agent/LLM]
    end

    subgraph "Optics MCP Server"
        SERVER[MCP Server<br/>stdio transport]
        
        subgraph "Resources (13)"
            SYSTEM[optics://system-overview]
            DOC_INTRO[optics://documentation/introduction]
            DOC_START[optics://documentation/getting-started]
            DOC_TOKENS[optics://documentation/design-tokens]
            DOC_COLOR[optics://documentation/color-system]
            DOC_SPACING[optics://documentation/spacing]
            DOC_TYPO[optics://documentation/typography]
            DOC_COMP[optics://documentation/components]
            DOC_A11Y[optics://documentation/accessibility]
            TOK_ALL[optics://tokens/all]
            TOK_COLOR[optics://tokens/color]
            TOK_SPACING[optics://tokens/spacing]
            TOK_TYPO[optics://tokens/typography]
            COMP_ALL[optics://components/all]
        end
        
        subgraph "Core Tools (7)"
            T1[get_token]
            T2[search_tokens]
            T3[get_token_usage_stats]
            T4[get_component_info]
            T5[list_components]
            T6[get_component_tokens]
            T7[search_documentation]
        end
        
        subgraph "Advanced Tools (7)"
            T8[generate_theme]
            T9[validate_token_usage]
            T10[replace_hard_coded_values]
            T11[check_contrast]
            T12[suggest_token_migration]
            T13[generate_component_scaffold]
            T14[generate_sticker_sheet]
        end
        
        subgraph "Prompts (5)"
            P1[start-here]
            P2[get-token-reference]
            P3[component-guide]
            P4[theme-customization]
            P5[migration-guide]
        end
        
        subgraph "Data Layer"
            TOKENS[83 Design Tokens<br/>HSL colors, spacing,<br/>typography, borders, shadows]
            COMPONENTS[24 Components<br/>with token dependencies]
            DOCS[Documentation<br/>Guidelines & best practices]
        end
    end
    
    CLIENT -->|JSON-RPC| SERVER
    SERVER --> SYSTEM
    SERVER --> DOC_INTRO
    SERVER --> DOC_START
    SERVER --> DOC_TOKENS
    SERVER --> DOC_COLOR
    SERVER --> DOC_SPACING
    SERVER --> DOC_TYPO
    SERVER --> DOC_COMP
    SERVER --> DOC_A11Y
    SERVER --> TOK_ALL
    SERVER --> TOK_COLOR
    SERVER --> TOK_SPACING
    SERVER --> TOK_TYPO
    SERVER --> COMP_ALL
    SERVER --> T1
    SERVER --> T2
    SERVER --> T3
    SERVER --> T4
    SERVER --> T5
    SERVER --> T6
    SERVER --> T7
    SERVER --> T8
    SERVER --> T9
    SERVER --> T10
    SERVER --> T11
    SERVER --> T12
    SERVER --> T13
    SERVER --> T14
    SERVER --> P1
    SERVER --> P2
    SERVER --> P3
    SERVER --> P4
    SERVER --> P5
    T1 --> TOKENS
    T2 --> TOKENS
    T3 --> TOKENS
    T4 --> COMPONENTS
    T5 --> COMPONENTS
    T6 --> COMPONENTS
    T7 --> DOCS
    T8 --> TOKENS
    T9 --> TOKENS
    T10 --> TOKENS
    T11 --> TOKENS
    T12 --> TOKENS
    T13 --> COMPONENTS
    T14 --> TOKENS
    T14 --> COMPONENTS
    P1 --> SYSTEM
    P2 --> TOKENS
    P3 --> COMPONENTS
    P4 --> T8
    P5 --> T12

利用可能なツール（合計14個）

すべてのツールの詳細なドキュメントについては、TOOLS.mdを参照してください。

コアツール

• get_token：特定のデザイントークンに関する詳細情報を取得します。
• search_tokens：カテゴリまたは名前パターンでデザイントークンを検索します。
• get_token_usage_stats：システム全体のデザイントークンの使用統計を取得します。
• get_component_info：コンポーネントの詳細情報（デザイントークンの依存関係を含む）を取得します。
• list_components：デザインシステムで利用可能なすべてのコンポーネントをリストします。
• get_component_tokens：特定のコンポーネントで使用されるすべてのデザイントークンを取得します。
• search_documentation：Opticsのドキュメントを検索します。

高度なツール

• generate_theme：CSS変数とFigma Variables JSONを使用してカスタムブランドテーマを作成します。
  • HSLベースのテーマオーバーライドを出力します。
  • Figma Variables形式を生成します。
  • テーマのプレビューを作成します。
• validate_token_usage：コード内のハードコードされた値を見つけ、デザイントークンを使用するべき箇所を特定します。
  • 色、スペーシング、フォント、ボーダー、シャドウを検出します。
  • トークンの置き換えを提案します。
  • トークンの使用を検証します。
• replace_hard_coded_values：ハードコードされた値を自動的にデザイントークンに置き換えます。
  • 手動モード：提案のみ
  • 自動修正モード：置き換えを適用
  • コード構造を維持します。
• check_contrast：トークン間のWCAG色コントラスト比をチェックします。
  • AAおよびAAAレベルをサポートします。
  • トークン名または16進数の色で動作します。
  • アクセシビリティの推奨事項を提供します。
• suggest_token_migration：レガシーコードの移行に適したトークンを提案します。
  • 古い値を新しいトークンにマッピングします。
  • セマンティックトークンを優先します。
  • 根拠を提供します。
• generate_component_scaffold：Opticsトークンを使用してコンポーネントコードを生成します。
  • React、Vue、Svelte、HTMLをサポートします。
  • デザイントークンで事前設定されています。
  • TypeScriptの型が含まれています。
• generate_sticker_sheet：すべてのデザイントークンとコンポーネントを示すビジュアルスタイルガイドを生成します。
  • スワッチ付きの完全なカラーパレット
  • タイポグラフィのスケール例
  • スペーシングのビジュアライゼーション
  • コンポーネントの例
  • マルチフレームワークサポート（React、Vue、Svelte、HTML）
  • 本番環境で使用可能なコード出力

利用可能なリソース

サーバーは、optics:// URIスキームを介して以下のリソースを公開しています。

• ドキュメント
  • optics://documentation/introduction - Opticsの概要
  • optics://documentation/getting-started - 入門ガイド
  • optics://documentation/design-tokens - デザイントークンのドキュメント
  • optics://documentation/color-system - カラーシステムガイド
  • optics://documentation/spacing - スペーシングシステムガイド
  • optics://documentation/typography - タイポグラフィガイド
  • optics://documentation/components - コンポーネントライブラリの概要
  • optics://documentation/accessibility - アクセシビリティガイドライン
• トークン
  • optics://tokens/all - すべてのデザイントークン
  • optics://tokens/color - 色トークンのみ
  • optics://tokens/spacing - スペーシングトークンのみ
  • optics://tokens/typography - タイポグラフィトークンのみ
• コンポーネント
  • optics://components/all - すべてのコンポーネント

デザインシステムの概要

デザイントークンのカテゴリ

1. 色 (25のトークン)：プライマリ、ニュートラル、およびアラート色を持つHSLベースのカラーシステム
2. スペーシング (11のトークン)：10進スケール（2pxから80px）のcalcベースのrem単位
3. タイポグラフィ (32のトークン)：サイズ、太さ、および行の高さを持つNoto Sans/Serifフォント
4. ボーダー (10のトークン)：ボーダー半径（小から丸）と幅
5. シャドウ (5のトークン)：エレベーションシステム（x-smallからx-large）

コンポーネント（合計24個）

すべてのコンポーネントは、実際のOptics SCSSから抽出され、正確なトークン依存関係を持っています。

• アコーディオン：折りたたみ可能なコンテンツパネル
• アラート：通知メッセージ（警告、危険、情報、通知）
• アバター：ユーザープロフィール画像
• バッジ：ステータスインジケーターとラベル
• パンくずリスト：ナビゲーション階層
• ボタン：バリエーションを持つインタラクティブなボタン
• ボタングループ：グループ化されたボタンコンテナ
• カード：エレベーションを持つコンテンツコンテナ
• 確認ダイアログ：アクションの確認モーダル
• 区切り線：コンテンツの区切り
• フォーム：入力フィールド、テキストエリア、セレクトボックス
• アイコン：Material Symbolsアイコン
• モーダル：オーバーレイダイアログ
• ナビゲーションバー：上部ナビゲーション
• ページネーション：ページナビゲーション
• サイドパネル：スライド式のサイドパネル
• サイドバー：サイドナビゲーション
• スピナー：ローディングインジケーター
• スイッチ：トグルスイッチ
• タブ：タブ付きインターフェイス
• テーブル：データテーブル
• タグ：分類ラベル
• テキストペア：ラベルと値のペア
• ツールチップ：コンテキスト情報

各コンポーネントは、使用するOpticsデザイントークンを指定しており、依存関係を理解しやすく、一貫性を維持しやすくなっています。

トークン使用状況の追跡

サーバーは、各コンポーネントがどのデザイントークンを使用しているかを追跡し、以下のことを可能にします。

• 依存関係分析：コンポーネントが依存しているトークンを理解します。
• 影響分析：トークンの変更がどのコンポーネントに影響するかを確認します。
• 使用統計：トークンの使用パターンに関する洞察を得ます。

📦 インストール

VS Code 🎨

クイックセットアップ：

1. コマンドパレット → MCP: Open User Configuration
2. 以下の構成を追加します。

{
  "servers": {
    "optics": {
      "command": "npx",
      "args": ["-y", "optics-mcp"]
    }
  }
}

3. エージェントモードでGitHub Copilotを開きます。
4. ツールアイコンをクリックして、利用可能なOpticsツールを表示します。

または、ワークスペースに.vscode/mcp.jsonを作成し、同じ構成を追加します。

公式MCPレジストリ：registry.modelcontextprotocol.ioに掲載されています ✅

Cursor 🎯

ワンクリックインストール（クリックしてCursorを開く）：

cursor://anysphere.cursor-deeplink/mcp/install?name=optics&config=eyJvcHRpY3MiOnsiY29tbWFuZCI6Im5weCIsImFyZ3MiOlsiLXkiLCJvcHRpY3MtbWNwIl19fQ==

または手動設定：

1. Cursorの設定 → MCPを開きます。
2. 以下の構成を追加します。

{
  "servers": {
    "optics": {
      "command": "npx",
      "args": ["-y", "optics-mcp"]
    }
  }
}

3. Cursor AIとチャットして、Opticsツールにアクセスします。

クイックスタート（インストール不要） ⚡

Optics MCPを使用する最も簡単な方法 - インストール不要！

Claude Desktop

MCP構成に以下を追加します。

{
  "mcpServers": {
    "optics": {
      "command": "npx",
      "args": ["-y", "optics-mcp"]
    }
  }
}

Claude Code CLI

1つのコマンドで追加します。

claude mcp add optics -- npx -y optics-mcp

その他の便利なコマンド：

# すべてのMCPサーバーをリストする
claude mcp list

# Opticsサーバーを削除する
claude mcp remove optics

# サーバーの詳細を表示する
claude mcp get optics

# 接続をテストする
claude mcp test optics

以上です！ MCPクライアントが必要なときにサーバーは自動的に実行されます。

ローカルインストール（開発用）

サーバーを変更したり、貢献したりする場合は、以下の手順を実行します。

git clone https://github.com/RoleModel/optics-mcp.git
cd optics-mcp
npm install
npm run build

次に、ローカルパスで構成します。

{
  "mcpServers": {
    "optics": {
      "command": "node",
      "args": ["/absolute/path/to/optics-mcp/dist/index.js"]
    }
  }
}

🔧 技術詳細

ビルド

npm run build

ウォッチモード

npm run watch

プロジェクト構造

optics-mcp/
├── src/
│   ├── index.ts          # MCPサーバーの実装
│   └── optics-data.ts    # デザイントークンとコンポーネントデータ
├── dist/                 # コンパイルされたJavaScript
├── package.json
├── tsconfig.json
└── README.md

🤝 貢献の方法

新しいデザイントークンまたはコンポーネントを追加するには、以下の手順を実行します。

1. src/optics-data.tsを編集します。
2. designTokens配列にトークンを追加します。
3. components配列にコンポーネントを追加し、そのトークン依存関係を指定します。
4. プロジェクトを再構築します：npm run build

📄 ライセンス

MIT

🔗 リンク

• Optics Design System Documentation
• Model Context Protocol
• MCP TypeScript SDK