Skip to main content

MCP Server

Experimental

この機能は実験的です。今後のバージョンで API が変更される可能性があります。

Compose Preview Lab は MCP (Model Context Protocol) サーバを内蔵しており、AI アシスタント (Claude, Cursor など) から Preview の情報を取得・操作することができます。

現在 jvm プラットフォームでのみ利用できます。

概要​

MCP Server を使用すると、以下のことが可能です：

  • PreviewLabGallery の操作: Preview の選択、検索クエリの変更、比較パネルへの追加
  • PreviewLab の操作: フィールド値の取得・更新、イベントの取得・クリア、スクリーンショットの撮影

セットアップ​

1. PreviewLabGallery での有効化​

PreviewLabGalleryWindows を使用している場合、MCP Server はデフォルトで有効です。

fun main() {
    application {
        PreviewLabGalleryWindows(
            previewList = app.PreviewList,
            // MCP Server はデフォルトで有効 (port: 7007)
        )
    }
}

2. MCP Client の設定​

Claude Code の場合

以下のコマンドを実行：

claude mcp add compose-preview-lab --transport sse http://localhost:7007
Claude Desktop の場合

claude_desktop_config.json に以下を追加：

{
  "mcpServers": {
    "compose-preview-lab": {
      "url": "http://localhost:7007"
    }
  }
}
Cursor の場合

.cursor/mcp.json に以下を追加：

{
  "mcpServers": {
    "compose-preview-lab": {
      "url": "http://localhost:7007"
    }
  }
}

3. アプリケーションを起動する​

PreviewLabGallery を使用したアプリケーションを起動すると、MCP Server も自動的に起動します。

MCP Server の設定​

mcpServerConfig パラメータで MCP Server の動作をカスタマイズできます。

PreviewLabGalleryWindows(
    previewList = app.PreviewList,
    mcpServerConfig = PreviewLabMcpServerConfig(
        enabled = true,       // MCP Server を有効化 (デフォルト: true)
        host = "127.0.0.1",   // バインドするホスト (デフォルト: "0.0.0.0")
        port = 7007,          // ポート番号 (デフォルト: 7007)
    ),
)
セキュリティに関する注意

デフォルト設定では 0.0.0.0 にバインドするため、ローカルネットワーク上のすべてのクライアントから MCP Server にアクセス可能です。MCP Server は認証なしで Preview の操作やスクリーンショット取得が可能なため、ローカル開発環境以外での使用時は host = "127.0.0.1" を設定してローカルホストのみに制限することを推奨します。

MCP Server を無効化する​

PreviewLabGalleryWindows(
    previewList = app.PreviewList,
    mcpServerConfig = PreviewLabMcpServerConfig.Disable,
)

利用可能な Resources​

PreviewLabGallery Resources​

Resource説明
preview-lab:///previewsGallery 内の全 Preview 一覧
preview-lab:///featuredFilesFeatured Files の一覧
preview-lab:///gallery-stateGallery の現在の状態 (検索クエリ、選択中の Preview)

PreviewLab Resources​

Resource説明
preview-lab:///preview-lab/list利用可能な PreviewLab インスタンスの ID 一覧
preview-lab:///preview-lab/{previewId}/fields指定した Preview のフィールド一覧
preview-lab:///preview-lab/{previewId}/events指定した Preview のイベント一覧

利用可能な Tools​

PreviewLabGallery Tools​

Tool説明
Update PreviewLabGallery.query検索クエリを更新
Select preview PreviewLabGallery.selectPreview を選択して表示
Unselect preview PreviewLabGallery.unselect選択を解除
Add to compare panel PreviewLabGallery.addToComparePanel比較パネルに Preview を追加
Remove from compare panel PreviewLabGallery.removeFromComparePanel比較パネルから Preview を削除

PreviewLab Tools​

Tool説明
Update PreviewLab fieldフィールドの値を JSON シリアライズ値で更新
Update PreviewLab field with test valueフィールドの値を testValues() の要素で更新
Take PreviewLab screenshotスクリーンショットを PNG 画像として取得
Clear PreviewLab events記録されたイベントを全てクリア

使用例​

AI Agent へ入力する prompt 例​

Preview の確認​

PreviewLabGallery で利用可能な Preview を確認して

フィールドの操作​

MyButtonPreview の color フィールドを testValues の 2番目の値に変更して

スクリーンショットの取得​

現在表示中の Preview のスクリーンショットを撮って

複数 Preview の比較​

MyButton の Primary と Secondary バリアントを比較パネルに追加して

制限事項​

  • MCP Server は JVM プラットフォーム (Desktop) でのみ利用可能です
  • MCP Server は SSE (Server-Sent Events) プロトコルを使用します
  • スクリーンショット機能は Compose の captureToImage() を使用するため、一部の Composable では動作しない場合があります

トラブルシューティング​

MCP Server に接続できない​

  • PreviewLabGallery が起動していることを確認
  • ポート 7007 が他のアプリケーションで使用されていないか確認
  • ファイアウォールの設定を確認

Tools/Resources が見つからない​

  • MCP Client で Resources/Tools の一覧を再読み込みしてください。PreviewLab の Resources/Tools は Preview が表示されたタイミングで登録されます。