dv-connect

スキル：接続

Dataverse に一度で接続し、何度実行しても安全です。各ステップでは、すでに完了しているかを確認し、完了していればスキップします。

環境優先ルール — すべてのメタデータとプラグイン登録は、API／スクリプトを使って環境内で作成してから、リポジトリに取り込みます。コンポーネントを作成するために、ソリューション XML を手作業で記述することは決してありません。

ステップは順番に実行し、先に進んでスキップしないでください。 例外： ワークスペースがすでにセットアップ済みの場合、ステップ 0 でフローを早期終了できます。

ホストの実行可否テスト（最初に実施 — ステップ 0 の前）。 ローカルの Windows／macOS ホストは、どのエージェントが操作していても、デフォルトで実行可能です — CLI を実行し、認証情報を保持し、ローカル MCP サーバーをホストできます。承認／サンドボックスの制約はなく、CLI がない場合はインストールします。制約があるのは、ランタイムを起動できない場合、認証情報を保持できない場合、またはホストが明示的に ChatGPT Work Mode／Codex cloud／CI／キーチェーンのない Linux の場合のみです（判定表：headless-hosts.md）。制約ありの場合 → Python と pip の依存関係、.env、scripts/auth.py のみをインストールし、python scripts/auth.py --check を実行して確認します。CLI／PAC／MCP はスキップします。実行可能の場合 → 以下の通常フローに進みます。

---

ステップ 0：既存のセットアップを検出する（最初に実行）

何かを変更する前に、このワークスペースがすでに Dataverse 環境に接続されているか確認します。セットアップ済みのワークスペースでセットアップを繰り返すと、.env が上書きされ、MCP が再登録され、時間が無駄になります。

Gemini がサポートするのは GA のみです。Preview が要求された場合は、その旨を説明し、セットアップのショートカットを実行する前に停止してください。

以下のチェックを順番に実行します。4 つすべてに合格した場合は、ステップ 7（最終確認）に進み、そこで終了します。

1. .env が存在し、必要な値がそろっている — ワークスペースのルートにファイルがあり、DATAVERSE_URL、TENANT_ID、MCP_CLIENT_ID に空でない値が設定されている
2. MCP が登録されている — ホストの MCP リストに DATAVERSE_URL を参照する dataverse-* エントリがあるか、Gemini にバンドルされた dataverse エントリがある
3. 両方の認証情報が .env と一致している — dataverse auth who で Environment Url が DATAVERSE_URL と一致するプロファイルが表示され、かつ同じ URL の PAC プロファイルに対する pac org who が成功する。（DV CLI の認証は Connect／Data／Query／Metadata／MCP／Python を対象とし、PAC の認証は dv-solution と dv-admin を対象とします。どちらも接続時に先に済ませることで、後から認証を求められないようにします。）
4. Python SDK をインポートでき、最新である — python -c "from PowerPlatform.Dataverse.client import DataverseClient; import pandas; from importlib.metadata import version; v=version('PowerPlatform-Dataverse-Client'); parts=tuple(int(p) for p in v.split('.')[:2]); assert parts>=(1,1), f'SDK {v} is outdated, need >=1.1.0'" が終了コード 0 で終了する

すべてに合格した場合： まず、.env の帰属情報が有効であることを確認します。読み込まれたマニフェストの version を DATAVERSE_PLUGIN_VERSION に設定し、DATAVERSE_PLUGIN_AGENT がない場合、または古い unknown／プレースホルダー値の場合は、検出したホスト（ステップ 3 に従う）を追加します。検出したセットアップ（URL、プロファイル、MCP サーバー）を確認し、ステップ 7 に進みます。それ以外の理由で .env を書き換えたり、MCP を再登録したり、pip install を再実行したりしないでください。

いずれかのチェックに失敗した場合： 通常のフロー（ステップ 1～7）に進みますが、各ステップ固有のスキップ条件に従ってください。一部のみ設定済みのワークスペースを最初からやり直す必要はありません。たとえば、.env と MCP だけが不足していて、ツールと認証が問題なければ、ステップ 2 またはステップ 3 から始めます。

---

ステップ 1：ツールがインストールされていることを確認する

各ツールを個別に確認し、不足しているツールをすべて一度に報告します。インストールコマンドについては、tools-setup.md を参照してください。

ツール	確認方法
Python 3	python --version
Git	git --version
Node.js	node --version
PAC CLI	pac（バージョンバナーが表示されます。pac --version は無効です）（PATH にない場合は tools-setup.md を参照してください）
Dataverse CLI	npm list -g @microsoft/dataverse
.NET SDK	dotnet --version
Azure CLI	az --version

.NET SDK は PAC CLI に必要ですが、Dataverse CLI には不要です（npm パッケージには独自のランタイムがバンドルされています）。Node.js は Dataverse CLI の npm パッケージ（@microsoft/dataverse）を実行します。このパッケージは MCP プロキシとして、またスクリプト化されたデータプレーン操作に使用されます。PAC CLI が利用できない場合、環境の検出には Azure CLI をフォールバックとして使用します（mcp-configuration.md のステップ 3b を参照してください）。GitHub CLI は接続には不要です。後で ALM／CI/CD のシナリオで使用します（dv-solution を参照）。

ツールが不足している場合は、インストールして（tools-setup.md を参照）、その後に確認してください。winget でツールをインストールしたものの PATH に含まれていない場合は、ターミナルを再起動するようユーザーに依頼してください。

Python が確認できたら、インストールする前に依存関係がすでに存在するか確認します。

python -c "from PowerPlatform.Dataverse.client import DataverseClient; import azure.identity, msal, msal_extensions, requests, pandas; print('OK')"

OK と表示された場合は、pip をスキップします。それ以外の場合：

pip install --upgrade azure-identity requests PowerPlatform-Dataverse-Client pandas msal msal-extensions

msal と msal-extensions を使用すると、scripts/auth.py は dataverse auth create のキャッシュを再利用できます。CLI、MCP、Python でのサインインは 1 回で済みます。

Node.js が確認できたら、Dataverse CLI が不足している場合にのみインストールします（接続のたびに再実行しないでください。管理対象デバイスでは、@latest の取得ごとに npm レジストリのセキュリティ確認が表示されることがあります。tools-setup.md を参照してください）。

npm install -g @microsoft/dataverse@latest

スキップ条件： すべてのツールがあり、Python SDK がインストール済みで、pandas をインポートできること（python -c "import pandas"）。

---

ステップ 2：環境を検出して選択する

ユーザーに URL を尋ねる前に、すでに利用可能なものを確認してください。

認証ツールの選択。 2 つのツール、2 つの AAD アプリ、2 つのキャッシュがあります。接続時に両方をあらかじめ用意します。

1. dataverse auth create（アプリ 0c412cc3-…）は DV CLI、MCP、Python を対象とします。
2. pac auth create（PAC 独自のアプリ）は dv-solution と dv-admin を対象とします。

まず既存の DV CLI プロファイルを確認し、必要に応じて環境の検出に PAC を使用します。

dataverse auth list
dataverse auth who
pac auth list   # PAC profiles are still useful for env discovery / pac org list

dataverse auth who にプロファイルが表示され、その環境がユーザーの対象環境と一致する場合：

• そのプロファイルを再利用します。プロファイルから DATAVERSE_URL と TENANT_ID を設定します。

DV CLI プロファイルが存在しない場合（または別の環境を指している場合）：

• 「既存の環境に接続しますか、それとも新しい環境を作成しますか？」と尋ねます。

選択する前に、テナント／リージョンの不一致を確認します。 対象 URL のリージョンが、認証済みアカウントの環境とは異なる場合は、古いプロファイルを再利用せず、正しいテナント用の新しいプロファイルを作成します。

dataverse auth create --environment <url>          # interactive (WAM broker on Windows → no browser tab)
dataverse auth create --environment <url> --deviceCode   # headless / remote / SSH

ユーザーに管理者の同意エラーが表示された場合、CLI はテナント管理者に共有するための、適切なスコープの同意 URL を出力します。URL を推測して作成しないでください。

既存の DV CLI プロファイルを切り替えるには：

dataverse auth select --name <profile-name>

新しい環境を作成するには（管理者権限が必要です）：

pac admin create --name "<name>" --type "<type>" --region "<region>"

権限エラーで失敗した場合は、Power Platform 管理センターで環境を作成してから接続するようユーザーに案内してください。

接続を確認するには：

dataverse auth who
dataverse org who --context "app=dataverse-skills/<ver>;skill=dv-connect;agent=<agent>"

出力を解析して DATAVERSE_URL、TENANT_ID、および ERP にリンクされた環境の場合は ERP_URL を抽出します（erp-detection.md を参照してください）。

どちらのコマンドにもテナント ID が表示されない場合は、次を使用します。

curl -sI https://<org>.crm.dynamics.com/api/data/v9.2/ \
  | grep -i "WWW-Authenticate" \
  | sed -n 's|.*login\.microsoftonline\.com/\([^/]*\).*|\1|p'

ステップ 2b：同じ環境の PAC CLI 認証をあらかじめ完了する

PAC は独自の AAD アプリを使用するため、dv-solution と dv-admin には別途サインインが必要です。ここで済ませてください。

pac auth list                                       # skip if a profile for $DATAVERSE_URL exists
pac auth create --name <orgid> --environment <DATAVERSE_URL>

ステップ 2 と同じアカウントを使用してください。PAC CLI がインストールされていない場合は、dv-solution／dv-admin では後で必要になることを注記してスキップしてください。

ステップ 3：.env を作成する

認証方法を提示します。

Dataverse への認証方法を選択してください。

1. 対話型ログイン（推奨） — ブラウザーでサインインします。アプリの登録は不要です。トークンはセッションをまたいでキャッシュされます。
2. CI/CD サービスプリンシパル — CLIENT_SECRET または CLIENT_CERTIFICATE_PATH を使用します。

.env に直接書き込みます。ユーザーに作成を指示しないでください。

検出した tool_type を 1 つ使用して、MCP_CLIENT_ID と正規の帰属情報の両方を導出します。読み込んだマニフェストから PLUGIN_VERSION を設定します。Antigravity では、ネイティブの plugin.json にバージョンがないため、.claude-plugin/plugin.json を使用します。

tool_type = "<copilot | claude | cursor | codex | gemini | antigravity | unknown>"
plugin_version = "<plugin manifest version, e.g. 1.5.0>"
mcp_client_id = "aebc6443-996d-45c2-90f0-388ff96faa56" if tool_type == "copilot" else "0c412cc3-0dd6-449b-987f-05b053db9457"
agent_host = {
    "copilot": "copilot", "claude": "claude-code", "cursor": "cursor",
    "codex": "codex", "gemini": "gemini-cli",
    "antigravity": "antigravity-cli",
}.get(tool_type, "unknown")

with open(".env", "w") as f:
    f.write(f"DATAVERSE_URL={dataverse_url}\n")
    f.write(f"TENANT_ID={tenant_id}\n")
    f.write(f"MCP_CLIENT_ID={mcp_client_id}\n")
    f.write(f"DATAVERSE_PLUGIN_VERSION={plugin_version}\n")
    f.write(f"DATAVERSE_PLUGIN_AGENT={agent_host}\n")
    f.write(f"SOLUTION_NAME={solution_name}\n")
    f.write(f"PUBLISHER_PREFIX=\n")  # filled in when solution is created
    f.write(f"PAC_AUTH_PROFILE=nonprod\n")
    if client_id:
        f.write(f"CLIENT_ID={client_id}\n")
    if client_secret:
        f.write(f"CLIENT_SECRET={client_secret}\n")

.env が .gitignore に含まれていることを確認します。

import os

GITIGNORE_ENTRIES = [
    ".env", ".vscode/settings.json", ".claude/mcp_settings.json",
    ".token_cache.bin", ".dataverse/", "*.snk", "__pycache__/", "*.pyc",
    "solutions/*.zip", "plugins/**/bin/", "plugins/**/obj/",
]
gitignore = open(".gitignore").read() if os.path.exists(".gitignore") else ""
missing = [e for e in GITIGNORE_ENTRIES if e not in gitignore]
if missing:
    with open(".gitignore", "a") as f:
        f.write("\n" + "\n".join(missing) + "\n")

スキップ条件： .env に必要な値がすべて設定済みの場合。

---

ステップ 4：プロジェクト構造をセットアップする（新規プロジェクトのみ）

新規プロジェクト（scripts/ ディレクトリがない）の場合：

mkdir -p solutions plugins scripts

scripts/auth.py と scripts/enable-mcp-client.py が存在することを確認します。詳しくは references/helper-scripts.md を参照してください。

templates/CLAUDE.md がリポジトリのルートに存在しない場合は、コピーします。プレースホルダー（{{DATAVERSE_URL}}、{{SOLUTION_NAME}}、{{PUBLISHER_PREFIX}}）を .env の値に置き換えます。

---

ステップ 5：接続を確認する

dataverse auth who
pac org who
python scripts/auth.py --check

--check はトークンの確認だけではなく、実際のデータプレーン呼び出しを行います。組織に実際に到達可能であることを証明する唯一の方法です。組織のドメインがブロックされていても、トークンは発行されることがあります。すべてが同じユーザー／環境を解決する必要があります。これにより、DV CLI キャッシュ、PAC プロファイル（ステップ 2b）、および共有キャッシュの Python による再利用が正しく連携していることが証明されます。

いずれかが失敗した場合：

• dataverse auth who が失敗する → ステップ 2 を再実行します。
• pac org who が失敗する → ステップ 2b を再実行します。
• python scripts/auth.py --check がデバイスコードの URL を表示する → ブラウザー／WAM キャッシュに、Python で再利用できるトークンがありません。自動修正： dataverse auth create --environment <url> --deviceCode を再実行してから、もう一度試します。それでもプロンプトが表示される場合は、pip show msal msal-extensions を確認してください。ヘッドレスホスト（ChatGPT／Codex クラウド／CI）では、dataverse auth create で認証情報を永続化できません。繰り返し実行しないでください（headless-hosts.md を参照）。
• python scripts/auth.py --check が接続エラー／タイムアウトエラーとともに NOT REACHABLE を表示する → 認証の問題ではなく、ネットワークの送信トラフィックによって組織のドメインがブロックされています。成功や件数を報告しないでください。対処方法については headless-hosts.md を参照してください。
• その他の Python エラー → SDK のインストールと .env を確認します。

メタデータの作業に入る前に、アカウントに prvCreateEntity カスタマイズ権限があることも確認します。詳しくは tools-setup.md を参照してください。

---

手順 6：MCP サーバーを設定する

現在のホストが選択した環境を参照している場合にのみ、この手順をスキップしてください。

• Gemini：gemini mcp list で、バンドルされたサーバー dataverse が選択した URL に解決される
• Antigravity：agy mcp list に選択した環境が含まれている
• その他のホスト：MCP のリストまたは設定に、選択した URL の Dataverse サーバーが含まれている

MCP が設定されていない場合は、mcp-configuration.md に従ってください。

1. コンテキストから、ユーザーが使用しているツール（Copilot、Claude、Cursor、Codex、Gemini、Antigravity）を検出する
2. ツールの選択に基づいて MCP_CLIENT_ID を設定する
3. .env から環境 URL を取得する
4. GA エンドポイント（/api/mcp）をデフォルトとして使用する
5. ホストごとに MCP サーバーを登録する（以下のホスト別ブロックを参照）
6. Dataverse の管理者の同意と許可リストを処理する — ポータルより dataverse mcp allow <MCP_CLIENT_ID> を優先する（テナント／環境ごとに一度だけ）
7. ERP_URL が存在する場合は、ERP を別途許可リストに追加して検証する

MCP のプラグイン帰属： このプラグインは stdio プロキシ トランスポート（npx @microsoft/dataverse mcp <url>）を使用します。登録時は、DATAVERSE_OPERATION_CONTEXT を環境ブロックに含めてください。これにより、CLI が /api/mcp へのリクエスト時にこの値を User-Agent に追加します。.env から値を作成してください。

DATAVERSE_OPERATION_CONTEXT=app=dataverse-skills/{DATAVERSE_PLUGIN_VERSION};skill=mcp-direct;agent={DATAVERSE_PLUGIN_AGENT}

Claude Code（claude mcp add -t stdio）では、-e DATAVERSE_OPERATION_CONTEXT=... を使って渡します。JSON／TOML を使うホストでは、サーバーの環境ブロックに追加してください。

重要： MCP の設定を反映するには、エディター／CLI の再起動が必要です。

Copilot の場合： JSON 設定を書き込み、その後次のように伝えます。

✅ Dataverse MCP サーバーを設定しました。変更を反映するには、エディターを再起動してください。

Claude の場合： claude mcp add コマンドを実行し、次回起動時に表示される認証ポップアップについてユーザーに警告します。

✅ Dataverse MCP サーバーを登録しました。MCP ツールを有効にするには、Claude Code を再起動してください。 コンテキストを失わずにセッションを再開するには、claude --continue を使用してください。

再起動時に、Dataverse 環境にサインインするためのブラウザーウィンドウが開くことがあります（MCP プロキシがユーザーに代わって認証します）。詳細は mcp-configuration.md を参照してください。

Cursor の場合： JSON 設定を書き込み、その後次のように伝えます。

✅ Dataverse MCP サーバー dataverse-{orgid} を ~/.cursor/mcp.json に設定しました。Settings → Tools & MCPs に新しい MCP サーバーを表示するには、Cursor ウィンドウを再読み込みしてください（Ctrl+Shift+P → "Developer: Reload Window"）。

初回使用時に npx @microsoft/dataverse プロキシがブラウザーのデバイスコードでサインインし、その後は共有キャッシュを使ってサイレントに認証を再利用します。詳細は mcp-configuration.md を参照してください。

Codex の場合： TOML 設定を ~/.codex/config.toml に書き込みます。Codex は起動時にのみ MCP ツールを読み込むため、ユーザーが再起動するまではツールを呼び出せると伝えないでください。次のように伝えます。

✅ Dataverse MCP サーバー dataverse-{orgid} を ~/.codex/config.toml に設定しました。MCP ツールを読み込むには、Codex（CLI）を再起動するか、Codex IDE を再読み込みしてください。

---

ステップ 7：最終確認

エディター／CLI の再起動後、セットアップ完了と判断する前に、以下の両方が成功する必要があります。

確認 1：ホストの MCP リストに、Dataverse サーバーが接続済みとして表示される

• Claude：claude mcp list
• Gemini：gemini extensions list、続けて gemini mcp list
• Antigravity：agy mcp list。再起動後に /mcp これにより MCP サーバーが起動することは確認できますが、データ操作が機能することまでは確認できません。

確認 2：エージェントが describe／search を使ってテーブルを正常に一覧表示し、データを返す

「Dataverse 環境内のテーブルを一覧表示してください。」

これにより、認証、テナントの同意、環境の許可リスト、エンドポイントへの到達性がすべて正しく設定されていることを、エンドツーエンドで確認できます。エージェントが PAC CLI または Web API にフォールバックする場合は、トラブルシューティングについて mcp-configuration.md を参照してください。

両方の確認に成功した場合に限り、セットアップが検証済みとなります。

失敗時の解釈：

• 確認 1 が失敗する場合（サーバーが ✓ Connected ではない）：MCP サーバー自体を起動できていません。ステップ 6 を再実行し、npx／Node.js がインストールされていること、および MCP の登録が成功したことを確認してください。
• 確認 1 は成功するものの、確認 2 が失敗する場合（サーバーは起動するが describe／search がエラーになる）：サーバーは MCP で通信できますが、Dataverse に到達できないか、Dataverse を読み取れません。以下の --validate を実行して原因を調べてください。

診断 — --validate（失敗の調査にのみ使用）：

npx @microsoft/dataverse mcp {DATAVERSE_URL} --validate

新しい認証ハンドシェイクを行って 2 つの Dataverse MCP エンドポイントをテストし、詳細なエラー（認証、許可リスト、同意、エンドポイントへの到達性）を報告します。

• GA／本番エンドポイント — {DATAVERSE_URL}/api/mcp。プラグインが実行時に実際に使用するエンドポイントです。
• プレビューエンドポイント — {DATAVERSE_URL}/api/mcp_preview。環境ごとにオプトインが必要で、プラグインでは使用されません。

初回セットアップ時に成功判定の条件として --validate を使用しないでください。 新しく設定したワークスペースでは、トークンキャッシュがまだ温まっていないため、MCP はその後の実際の呼び出しで正常に動作しても、--validate が MsalClientException または 403 で失敗することがあります。確認 1 または確認 2 で失敗が確定した場合の診断に限り、--validate を使用してください。

--validate の出力の読み方：

• まず GA／本番エンドポイント（/api/mcp）の結果を確認してください。 これが成功すれば、プレビューエンドポイントの結果にかかわらず、通常のプラグイン利用で MCP は動作します。
• プレビューエンドポイント（/api/mcp_preview）の 403 Forbidden は、多くの環境で想定される結果です。 プレビューは環境ごとにオプトインが必要です。環境で有効になっていない場合、プレビューのチェックは常に失敗します。これはセットアップに問題があることを示すものではありません。
• この場合、全体の終了コードと ⚠ Partial success の警告は無視してください。 /api/mcp と /api/mcp_preview の両方が成功しない限り、検証ツールは終了コード 1（失敗）を返します。ほとんどの環境ではプレビューエンドポイントが有効になっていないため、GA エンドポイント経由で MCP が完全に機能していても、--validate は終了コード 1 で終了します。集計ステータスではなく、エンドポイントごとの結果を確認してください。
• GA エンドポイント（/api/mcp）が失敗する場合： これは実際に調査が必要な兆候です。認証、テナントの同意、環境の許可リスト、またはエンドポイントへの到達性を確認してください。

MCP サーバーの機能

MCP でできることとできないこと（データの CRUD と最大 25 件のバッチ処理、選択肢／参照を含むテーブル／列の作成、search／describe、ファイルのアップロード／ダウンロード）と、SDK／Web API との違いについては、overview スキルの Tool Capabilities マトリックスを参照してください。

MCP が動作することを確認したら、ユーザーに次のように伝えてください。

✅ {DATAVERSE_URL} の Dataverse に接続しました。ツールはインストール済みで、認証済みです。MCP は稼働中です。

次のことができます。

• テーブル、列、リレーションシップを作成する（dv-metadata）
• データを書き込み、インポートする（dv-data）
• データをクエリおよび分析する（dv-query）
• ソリューションをエクスポートおよび昇格する（dv-solution）

最初のソリューションを作成するには、dv-solution スキルを参照してください。 サンプルデータ（取引先企業、連絡先、商談）を読み込むには、「Dataverse 環境にデモデータを読み込んでください」と尋ねてください。

---

対応エージェント

このプラグインのスキルは、プラグインとしてインストールすると GitHub Copilot CLI、Claude Code CLI、Gemini CLI、Antigravity CLI によってネイティブに読み込まれます。手動でコンテキストを読み込む必要はありません。

PAC CLI コマンド、Python スクリプト、XML テンプレートは、どのホストでも同じように動作します。