adf-mcp-server

Azure Data Factory の監視と根本原因分析のための読み取り専用 MCP (Model Context Protocol) サーバーです。VS Code / Claude Code から使用することを想定しています。

ステータス: ステップ 1 (スケルトン + ヘルスチェック)。 まだ Azure 接続はありません。これはステップ 2 (認証) とステップ 3 (ADF ツール) で追加されます。

要件

• Python 3.11+

• 検査対象の Data Factory リソースに対して Reader ロールを持つ Azure AD アプリ登録 (サービス プリンシパル) (Reader で十分です。このサーバーはエンドツーエンドで読み取り専用のため、Contributor は不要です)

Related MCP server: mcp-azure-landing-zone

ローカル設定

cd adf-mcp-server
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env

サービス プリンシパルの作成 (1 回限り、az-cli を使用)

az ad sp create-for-rbac \
  --name "adf-mcp-server-reader" \
  --role "Reader" \
  --scopes "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.DataFactory/factories/<FACTORY_NAME>"

これにより appId、password、tenant が出力されます。これらを .env の AZURE_CLIENT_ID、AZURE_CLIENT_SECRET、AZURE_TENANT_ID にそれぞれマッピングします。ロールの割り当ては、サブスクリプション全体ではなく、特定のファクトリ (または最大でもリソース グループ) にスコープします。最小特権の原則に従い、この SPN が ADF 以外のものに触れる必要は一切ありません。

サーバーの実行

python -m adf_mcp.server
# or, after `pip install -e .`:
adf-mcp-server

サーバーは stdio で通信します。ターミナルで直接実行するとハングしているように見えますが、これは想定どおりです。MCP クライアント (VS Code 拡張機能、Claude Code、mcp dev など) が stdin/stdout 経由で接続するのを待機しています。

VS Code での設定

MCP 対応拡張機能のサーバー設定を次のように指定します:

{
  "command": "python",
  "args": ["-m", "adf_mcp.server"],
  "cwd": "/absolute/path/to/adf-mcp-server"
}

接続後:

1. health_check を呼び出します。Azure に一切触れずに {"status": "ok", ...} が返るはずです。

2. check_auth を呼び出します。これは Azure AD に対して実際に 1 回呼び出しを行い、ARM トークンを取得します。成功すると次のようになります:

   {"authenticated": true, "auth_mode": "service_principal", "token_expires_on": 1735000000}

   失敗した場合は、スタック トレースではなく構造化された説明が返されます (例: 環境変数の欠落、シークレットの無効など)。下記の「トラブルシューティング」を参照してください。

3. list_factories を呼び出します。これは Azure Data Factory に対して実際に呼び出しを行います。各ファクトリの resource_group が返されます。これは以下のすべてのツールで入力として必要です:

   {"factories": [{"name": "shell-prod-adf", "resource_group": "rg-shell-prod", "location": "eastus"}]}

利用可能なツール (ステップ 3)

すべてのツールは 読み取り専用 です。Azure Data Factory 内の何かを作成、変更、トリガー、削除することはできません。

エージェント向けの RCA フローの例: list_factories → list_pipeline_runs(status="Failed") → get_failed_activity_details(run_id=...) でエラーの内訳を直接取得します。

利用可能なツール (ステップ 4 の追加)

失敗したパイプラインの完全な RCA フロー: list_pipeline_runs(status="Failed") → get_failed_activity_details(run_id=...) でエラーを取得し、さらに get_trigger_status(trigger_name=...) で「そもそも起動しなかった」可能性を除外します。

テストの実行

pip install -e ".[dev]" pytest-asyncio
pytest -v

プロジェクト構成

src/adf_mcp/ を参照してください。server.py (MCP トランスポート)、config.py (設定)、logging_config.py (構造化ログ)。ドメイン ロジックと Azure 接続は、ステップ 3 以降で src/adf_mcp/domain/ の下に追加されます。

トラブルシューティング

• クライアントに「サーバーがすぐに切断された」と表示される: まず python -m adf_mcp.server が単独で正常に実行されることを確認してください。起動時の例外は、クライアントが接続する前にプロセスを強制終了させます。

• クライアントが応答を解析できない / 出力が文字化けする: MCP プロトコル以外の何かが stdout に書き込まれています (例: 余分な print())。このプロジェクトのすべてのログは、まさにこの理由で stderr に出力されます。

• check_auth が「Missing required Service Principal setting(s)」を返す: .env 内の AZURE_TENANT_ID / AZURE_CLIENT_ID / AZURE_CLIENT_SECRET のいずれかが空です。これら 3 つには ADF_MCP_ プレフィックスが付かないことに注意してください。

• check_auth が「Azure authentication failed」を返す: 通常は、クライアント シークレットの期限切れ/ローテーション、アプリ登録の無効化、テナント ID のタイプミスが原因です。az ad sp show --id <AZURE_CLIENT_ID> で再確認してください。

• ClientAuthenticationError: AADSTS7000215: クライアント シークレットが無効です。アプリ登録で再生成し、.env を更新してください。

• ツールが {"error": "AZURE_SUBSCRIPTION_ID is not set..."} を返す: .env に AZURE_SUBSCRIPTION_ID を追加してください。これはすべての ADF ツールで必要です (check_auth はテナント/クライアント/シークレットのみが必要なため不要)。

• ツールが {"error": "Azure API error (403): ..."} を返す: サービス プリンシパルにそのファクトリ/リソース グループへの Reader アクセス権がありません。セットアップ時の az ad sp create-for-rbac --role Reader --scopes ... の割り当てを再確認してください。

• ツールが {"error": "Azure API error (404): ..."} を返す: resource_group/factory_name/pipeline_name のスペルを確認してください。これらは大文字と小文字を区別し、list_factories/list_pipelines が返したものと完全に一致する必要があります。

• get_failed_activity_details が空のリストを返すが、パイプラインが失敗したことがわかっている場合: 失敗がパイプライン レベル (例: 無効なパラメーター) で発生している可能性があります。個々のアクティビティではなく、親実行の message を get_pipeline_run で確認してください。

• パイプラインが「単に実行されなかった」が、失敗した実行がまったくない場合: そのトリガーの get_trigger_status を確認してください。runtime_state: "Stopped" は、トリガーが無効化されて起動しなかったことを意味します。実行が作成されていないため、失敗した実行としては表示されません。