optics-mcp

Optics MCP サーバー

Optics Design System のための Model Context Protocol（MCP）サーバーです。https://docs.optics.rolemodel.design のデザイントークン、コンポーネント、ドキュメントを LLM が理解し、活用できるようにします。

⚠️ 重要：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

インストール

VS Code 🎨

クイックセットアップ：

1. コマンドパレット → MCP: Open User Configuration
2. 次の設定を追加します。

{
  "servers": {
    "optics": {
      "command": "npx",
      "args": [
        "@rolemodel/optics-mcp@latest"
      ]
    }
  }
}

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": [
        "@rolemodel/optics-mcp@latest"
      ]
    }
  }
}

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

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

Optics MCP を使う最も簡単な方法です。インストールは必要ありません！

Claude Desktop

MCP 設定に追加します。

{
  "mcpServers": {
    "optics": {
      "command": "npx",
      "args": [
        "@rolemodel/optics-mcp@latest"
      ]
    }
  }
}

Claude Code CLI

次のコマンドを 1 つ実行するだけで追加できます。

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

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

# List all MCP servers
claude mcp list

# Remove the Optics server
claude mcp remove optics

# View server details
claude mcp get optics

# Test the connection
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 start

利用可能なツール（合計 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トークン）：エレベーションシステム（極小から極大まで）

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

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

• Accordion：折りたたみ可能なコンテンツパネル
• Alert：通知メッセージ（警告、危険、情報、お知らせ）
• Avatar：ユーザープロフィール画像
• Badge：ステータスインジケーターとラベル
• Breadcrumbs：ナビゲーション階層
• Button：バリエーションのあるインタラクティブなボタン
• ButtonGroup：ボタンをまとめるコンテナー
• Card：エレベーション付きのコンテンツコンテナー
• ConfirmDialog：アクション確認用モーダル
• Divider：コンテンツの区切り線
• Form：入力フィールド、テキストエリア、セレクト
• Icon：Material Symbolsアイコン
• Modal：オーバーレイダイアログ
• Navbar：上部ナビゲーション
• Pagination：ページナビゲーション
• SidePanel：スライド式サイドパネル
• Sidebar：サイドナビゲーション
• Spinner：読み込みインジケーター
• Switch：トグルスイッチ
• Tab：タブインターフェース
• Table：データテーブル
• Tag：分類ラベル
• TextPair：ラベルと値のペア
• Tooltip：コンテキスト情報

各コンポーネントには、使用するOpticsデザイントークンが指定されているため、依存関係を把握し、一貫性を保ちやすくなります。

開発

ビルド

npm run build

ウォッチモード

npm run watch

プロジェクト構成

optics-mcp/
├── src/
│   ├── index.ts          # MCP server implementation
│   └── optics-data.ts    # Design tokens and component data
├── dist/                 # Compiled 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