metabase-react-sdk-setup

@metabase/embedding-sdk-react に関するあらゆるタスク（初期設定、ダッシュボードの埋め込み、テーマ設定、プラグインなど）でこのスキルを使用してください。

コミュニケーションのスタイル：簡潔にしてください。一度に一つの手順だけ進めてください。ユーザーに入力を求めるときは、質問だけを出力してください。これからの手順や実装の詳細、次に何をする予定かは説明しないでください。ユーザーにロードマップは必要ありません。

重要 — 何よりも先に API キーを取得してください

ステップ 1 では、Metabase の URL と API キーをユーザーに尋ねます。両方がなければ先に進めません。 ユーザーが API キーを提供するまでは、Metabase のバージョンを検出したり、llms.txt を取得したり、パッケージをインストールしたり、コードを一切書いたりしてはいけません。 API キーなしで Metabase API エンドポイントを呼び出してはいけません。401 が返され、推測することになります。 Metabase API 呼び出しで 401 が返された場合は、すべての作業を中止し、ユーザーに API キーを求めてください。

ステップ 1 — Metabase の URL と API キーを取得する

何よりも先に、Metabase インスタンスの URL と管理者 API キーが必要です。

.env.metabase は、このスキル内の管理者タスク（Metabase への API 呼び出し）のみで使用します。 アプリの実行時設定ではありません。ユーザーのアプリケーションコードやビルド設定で .env.metabase をインポート、読み込み、参照してはいけません。アプリのインスタンス URL は、ユーザー独自の .env ファイル（例：VITE_METABASE_URL、NEXT_PUBLIC_METABASE_URL）に設定します。これはステップ 4 で行います。

プロジェクトのルートに .env.metabase が存在し、METABASE_INSTANCE_URL（空でない値）と METABASE_ADMIN_API_KEY（空でない値）の両方がすでに設定されているか確認します。設定されている場合は、ステップ 2 に進みます。

それ以外の場合は、ファイルを作成して gitignore に追加します。

grep -qxF '.env.metabase' .gitignore 2>/dev/null || echo '.env.metabase' >> .gitignore
printf 'METABASE_INSTANCE_URL=\nMETABASE_ADMIN_API_KEY=\n' > .env.metabase

その後、このメッセージだけを出力します。前置きや、次の手順についての説明、実装の詳細は含めないでください。

プロジェクトのルートに .env.metabase を作成しました。両方の値を入力してください。

1. METABASE_INSTANCE_URL に Metabase の URL を設定します（例：http://localhost:3000）。
2. {your URL}/admin/settings/authentication/api-keys を開き、新しい API キーを作成します。
3. METABASE_ADMIN_API_KEY にそのキーを設定します。
4. 完了したら知らせてください。

インスタンス URL を推測したり、仮定したりしてはいけません。localhost:3000 を事前入力してはいけません。キーをチャットに貼り付けるようユーザーに求めてはいけません。キーは .env.metabase にのみ設定してください。ユーザーが完了したと確認するまで待ってから、ステップ 2 に進みます。

ステップ 2 — バージョンを検出してダッシュボードを見つける

API キーを取得したら、バージョンを検出し、ダッシュボードを見つけます。

2a — バージョンを検出する

source .env.metabase && \
  curl -s "$METABASE_INSTANCE_URL/api/session/properties" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY" | grep -o '"tag":"[^"]*"'

タグからエディションとメジャーバージョンの両方を解析します。

タグの形式	エディション	例
v0.X.Y	OSS（Community）	v0.60.1 → メジャー 60、OSS
v1.X.Y	Enterprise（EE）	v1.60.1 → メジャー 60、EE

メジャーバージョンが 49 未満の場合は、Embedding SDK には Metabase 49 以降が必要であることをユーザーに伝え、そこで終了します。

タグが v1. で始まる場合、そのインスタンスは Enterprise Edition です。完全な JWT SSO 埋め込みを使用してください。 ゲスト埋め込みや OSS 専用の認証方法に切り替えてはいけません。

メジャーバージョン番号を記録してください。ステップ 3 で必要になります。

2b — Embedding SDK を有効にする

ユーザーが管理パネルで手動で切り替える必要がないよう、SDK を自動的に有効にします。

source .env.metabase && \
  curl -s -X PUT "$METABASE_INSTANCE_URL/api/setting/enable-embedding-sdk" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"value": true}'

エラー（例：403）が返された場合は、<INSTANCE_URL>/admin/settings/embedding で手動で有効にするようユーザーに伝え、そのまま次に進みます。

まだ llms.txt を取得してはいけません。 先にダッシュボード ID が必要です。

2c — ダッシュボードとテーブルの候補を見つける

以下の両方を実行します。

source .env.metabase && \
  curl -s "$METABASE_INSTANCE_URL/api/search?models=dashboard&archived=false" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY"

source .env.metabase && \
  curl -s "$METABASE_INSTANCE_URL/api/automagic-dashboards/database/1/candidates" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY"

結果を絞り込み、優先順位を付けます。

• 除外：「Usage analytics」コレクションのダッシュボードは除外します。これらはユーザーコンテンツではなく、Metabase の内部管理用ダッシュボードです。
• 優先度を下げる：「Sample Database」の項目の優先度を下げ、ユーザー独自のデータベースやダッシュボードを優先します。
• 各カテゴリから、ユーザーの依頼に最も関連性の高い上位 5 件を選びます。結果をすべて列挙しないでください。

次のような形式にします。

既存のダッシュボード：

1. 売上概要（ID 3）
2. 顧客分析（ID 7） ...

または、データから新しいダッシュボードを作成できます： A. 注文テーブル B. 商品テーブル ...

どれを埋め込みますか？（例：「1 と 3」または「A」）

ユーザーが選択するまで待ちます。テーブルを選んだ場合は、X-ray ダッシュボードを生成して保存します。

source .env.metabase && \
  DASHBOARD=$(curl -s "$METABASE_INSTANCE_URL/api/automagic-dashboards/table/<TABLE_ID>" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY")

source .env.metabase && \
  curl -s "$METABASE_INSTANCE_URL/api/dashboard/save" \
    -H "X-API-Key: $METABASE_ADMIN_API_KEY" \
    -H "Content-Type: application/json" \
    -d "$DASHBOARD"

保存の応答には、実際の id フィールドを含む永続化されたダッシュボードが含まれています。以降はこれらの ID を使用します。

ステップ 3 — ドキュメントを取得し、認証を設定して SDK をインストールする

このステップに進む前に、実際のダッシュボード ID を取得しておく必要があります。取得していない場合は、ステップ 2 に戻ります。

次に、ステップ 2a で取得したメジャーバージョンを使って、バージョン別のドキュメントインデックスを取得します。

curl -s https://www.metabase.com/docs/v0.<MAJOR>/llms.txt

空の場合は、https://www.metabase.com/docs/latest/llms.txt にフォールバックします。ここには、このバージョンで正しいプロパティ名、認証設定の形式、SDK のインストールコマンド、破壊的変更が記載されています。llms-embedding-full.txt は大きすぎるため、取得しないでください。

3a — JWT SSO 認証を設定する（設定済みの場合はスキップ）

llms.txt の認証設定手順に従います。特に、次の点に注意してください。

• Metabase から JWT 署名シークレットを取得します：Settings → Admin → Embedding → Embedding secret key
• サーバー側の環境にのみ METABASE_JWT_SECRET として保存するようユーザーに伝えます（ブラウザーからアクセスできる環境変数には絶対に設定しないでください）。
• 使用しているバックエンドフレームワーク（Next.js API route、Express、Fastify など）をユーザーに尋ね、llms.txt のパターンに従って最小限の JWT 署名エンドポイントを作成します。

3b — SDK をインストールする（正しいバージョンが既にインストールされている場合はスキップ）

ユーザーの package.json に @metabase/embedding-sdk-react が既に含まれているか確認します。

• 未インストールの場合：llms.txt のインストールコマンドを使用します（適切な dist-tag はインスタンスのメジャーバージョンに一致します）。
• インストール済みの場合：メジャーバージョンが一致していることを確認します。不一致の場合は警告し、更新を提案します。

ステップ 4 — 埋め込みコードを生成する

すべての API の形式について、llms.txt を信頼できる参照情報として使用します。ファイルはユーザーのプロジェクトに直接書き込みます。既存のファイルをその場で編集し、隣に新しいファイルを作成しないでください。

コード規約（ドキュメントの内容より優先）

• JWT SSO のみ：API キーは管理者レベルのアクセス権を付与するため、エンドユーザー向けの埋め込みには安全ではありません。サーバー側の JWT 署名エンドポイントを使用します。MetabaseProvider にはその URL を渡します。apiKey、METABASE_API_KEY、api-key、x-api-key は、プレースホルダーとしても絶対に生成しないでください。ユーザーが明示的に要求し、セキュリティリスクを理解している場合に限り、この規則から逸脱できます。
• インスタンス URL は環境変数から取得：Vite の場合は VITE_METABASE_URL、Next.js の場合は NEXT_PUBLIC_METABASE_URL などを使用します。ハードコードしないでください。
• ダッシュボード ID はインラインリテラルとして指定：ダッシュボード ID は常に JSX に直接ハードコードします。例：<InteractiveDashboard dashboardId={7} />。ダッシュボード ID はシークレットではありません。import.meta.env.VITE_METABASE_DASHBOARD_*、環境変数、設定オブジェクト、parseDashboardId ヘルパーなど、ダッシュボード ID を間接的に指定する方法は絶対に使用しないでください。目的は、ユーザーがすぐに理解して調整できる、すっきりした最小限のコードにすることです。
• シークレットはサーバー側のみに保存：JWT シークレットをブラウザーからアクセスできる環境変数やフロントエンドコードに含めてはいけません。

テーマ設定

埋め込みコードを生成した後、ユーザーのアプリに既存のスタイルがあるか確認します。CSS 変数、Tailwind の設定、またはテーマファイルを確認してください。MetabaseProvider の theme プロパティを設定し、アプリの外観に合わせます。最低限、次の項目を調整してください。

• colors.brand — アプリのメインカラー／アクセントカラー
• colors.background — ページの背景色に合わせ、暗いページに白いボックスが表示される（またはその逆の）状態にならないようにします
• fontFamily — アプリのフォントに合わせます

テーマの完全な形式については、llms.txt を参照してください。設定は最小限にし、Metabase のデフォルト値と異なる値だけを指定します。