FlowStudio MCP を使用した Power Automate のデバッグ

FlowStudio MCP サーバーを通じて、失敗した Power Automate クラウドフローを調査するためのステップバイステップの診断プロセスです。

実際のデバッグ例: 子フローの式エラー | フロー バグではなくデータ入力エラー | Null 値が子フローをクラッシュ

前提条件: 有効な JWT を使用して FlowStudio MCP サーバーに接続できることが必要です。 接続設定については、flowstudio-power-automate-mcp スキルを参照してください。 https://mcp.flowstudio.app でサブスクリプション登録してください。

---

信頼できる情報源

常に最初に list_skills / tool_search を呼び出して 利用可能なツール名とパラメータスキーマを確認してください。ツール名とパラメータはサーバーのバージョン間で変更される場合があります。 このスキルは、レスポンスシェイプ、動作上の注意、診断パターン（ツールスキーマには記載されていないもの）をカバーしています。このドキュメントが tool_search または実際の API レスポンスと矛盾している場合、API が優先されます。

---

Python ヘルパー

import json, urllib.request

MCP_URL   = "https://mcp.flowstudio.app/mcp"
MCP_TOKEN = "<YOUR_JWT_TOKEN>"

def mcp(tool, **kwargs):
    payload = json.dumps({"jsonrpc": "2.0", "id": 1, "method": "tools/call",
                          "params": {"name": tool, "arguments": kwargs}}).encode()
    req = urllib.request.Request(MCP_URL, data=payload,
        headers={"x-api-key": MCP_TOKEN, "Content-Type": "application/json",
                 "User-Agent": "FlowStudio-MCP/1.0"})
    try:
        resp = urllib.request.urlopen(req, timeout=120)
    except urllib.error.HTTPError as e:
        body = e.read().decode("utf-8", errors="replace")
        raise RuntimeError(f"MCP HTTP {e.code}: {body[:200]}") from e
    raw = json.loads(resp.read())
    if "error" in raw:
        raise RuntimeError(f"MCP error: {json.dumps(raw['error'])}")
    return json.loads(raw["result"]["content"][0]["text"])

ENV = "<environment-id>"   # e.g. Default-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

---

ステップ 1 — フローを検索

result = mcp("list_live_flows", environmentName=ENV)
# ラッパーオブジェクトを返す: {mode, flows, totalCount, error}
target = next(f for f in result["flows"] if "My Flow Name" in f["displayName"])
FLOW_ID = target["id"]   # プレーン UUID — flowName として直接使用
print(FLOW_ID)

---

ステップ 2 — 失敗した実行を検索

runs = mcp("get_live_flow_runs", environmentName=ENV, flowName=FLOW_ID, top=5)
# 直接配列を返す (最新順):
# [{"name": "08584296068667933411438594643CU15",
#   "status": "Failed",
#   "startTime": "2026-02-25T06:13:38.6910688Z",
#   "endTime": "2026-02-25T06:15:24.1995008Z",
#   "triggerName": "manual",
#   "error": {"code": "ActionFailed", "message": "An action failed..."}},
#  {"name": "...", "status": "Succeeded", "error": null, ...}]

for r in runs:
    print(r["name"], r["status"], r["startTime"])

RUN_ID = next(r["name"] for r in runs if r["status"] == "Failed")

---

ステップ 3 — トップレベルのエラーを取得

重要: get_live_flow_run_error は、どの アクションが失敗したかを示します。 get_live_flow_run_action_outputs は、なぜ 失敗したかを示します。両方を呼び出す必要があります。 エラーだけで停止してはいけません — ActionFailed、NotSpecified、InternalServerError などのエラーコードは一般的なラッパーです。実際の根本原因（フィールドが間違っている、Null 値、HTTP 500 レスポンス本文、スタックトレース）はアクションの入力と出力にのみ表示されます。

err = mcp("get_live_flow_run_error",
    environmentName=ENV, flowName=FLOW_ID, runName=RUN_ID)
# 返す:
# {
#   "runName": "08584296068667933411438594643CU15",
#   "failedActions": [
#     {"actionName": "Apply_to_each_prepare_workers", "status": "Failed",
#      "error": {"code": "ActionFailed", "message": "An action failed..."},
#      "startTime": "...", "endTime": "..."},
#     {"actionName": "HTTP_find_AD_User_by_Name", "status": "Failed",
#      "code": "NotSpecified", "startTime": "...", "endTime": "..."}
#   ],
#   "allActions": [
#     {"actionName": "Apply_to_each", "status": "Skipped"},
#     {"actionName": "Compose_WeekEnd", "status": "Succeeded"},
#     ...
#   ]
# }

# failedActions は外側から内側へ順序付けられています。ルート原因は最後のエントリです:
root = err["failedActions"][-1]
print(f"Root action: {root['actionName']} → code: {root.get('code')}")

# allActions はすべてのアクションのステータスを表示します — スキップされたものを見つけるのに役立ちます
# common-errors.md を参照してエラーコードをデコードしてください。

---

ステップ 4 — 失敗しているアクションの入力と出力を検査

これが最も重要なステップです。 get_live_flow_run_error はジェネリックなエラーコードのみを提供します。実際のエラーの詳細 — HTTP ステータスコード、レスポンス本文、スタックトレース、Null 値 — はアクションのランタイム入力と出力に含まれています。失敗しているアクションを特定した直後に、常にそれを検査してください。

# ルート失敗アクションの完全な入力と出力を取得
root_action = err["failedActions"][-1]["actionName"]
detail = mcp("get_live_flow_run_action_outputs",
    environmentName=ENV,
    flowName=FLOW_ID,
    runName=RUN_ID,
    actionName=root_action)

if len(detail) > 1:
    print(f"{root_action} returned {len(detail)} repetitions; inspect iteration indexes")
out = detail[0] if detail else {}
print(f"Action: {out.get('actionName')}")
print(f"Status: {out.get('status')}")

# HTTP アクションの場合、実際のエラーは outputs.body にあります
if isinstance(out.get("outputs"), dict):
    status_code = out["outputs"].get("statusCode")
    body = out["outputs"].get("body", {})
    print(f"HTTP {status_code}")
    print(json.dumps(body, indent=2)[:500])

    # エラー本文はネストされた JSON 文字列であることが多い — それらを解析してください
    if isinstance(body, dict) and "error" in body:
        err_detail = body["error"]
        if isinstance(err_detail, str):
            err_detail = json.loads(err_detail)
        print(f"Error: {err_detail.get('message', err_detail)}")

# 式エラーの場合、エラーはエラーフィールドにあります
if out.get("error"):
    print(f"Error: {out['error']}")

# また入力も確認してください — これらは使用された式/URL/本文を示します
if out.get("inputs"):
    print(f"Inputs: {json.dumps(out['inputs'], indent=2)[:500]}")

アクション出力が明らかにするもの（エラーコードでは明らかにされない）

get_live_flow_run_error のエラーコード	get_live_flow_run_action_outputs が明らかにするもの
ActionFailed	実際に失敗したネストされたアクションとその HTTP レスポンス
NotSpecified	HTTP ステータスコード + 実際のエラーを含むレスポンス本文
InternalServerError	サーバーのエラーメッセージ、スタックトレース、または API エラー JSON
InvalidTemplate	失敗した正確な式と Null/間違った型の値
BadRequest	送信されたリクエスト本文とサーバーが拒否した理由

Foreach イテレーション

actionName が foreach 内のアクションを参照する場合、出力ツールはそのアクションのすべての繰り返しを返すことができます。各アイテムには、ループ名とゼロベースの itemIndex を含む repetitionIndexes が含まれる場合があります。疑わしいアイテムを見つけたら、iterationIndex を使用して 1 回の繰り返しを検査してください:

all_reps = mcp("get_live_flow_run_action_outputs",
    environmentName=ENV,
    flowName=FLOW_ID,
    runName=RUN_ID,
    actionName=root_action)

for rep in all_reps[:10]:
    print(rep.get("repetitionIndexes"), rep.get("status"), rep.get("error"))

one_rep = mcp("get_live_flow_run_action_outputs",
    environmentName=ENV,
    flowName=FLOW_ID,
    runName=RUN_ID,
    actionName=root_action,
    iterationIndex=3)

エビデンス Compose ブックエンド

不確実なコネクタ作業の場合、リスクのあるアクションの前に Compose_*_Request を、その後に Compose_*_Result を追加してください。結果アクションは Succeeded と Failed の両方で許可されます。これにより、別のデプロイを必要とせずに、将来のデバッグが整理されたペイロードスナップショットを取得できます。これらのブックエンドにはシークレットまたは長いバイナリペイロードを含めないでください。

例: HTTP アクションが 500 を返す

エラーコード: "InternalServerError" ← これは何も教えてくれません

アクション出力が明らかにするもの:
  HTTP 500
  body: {"error": "Cannot read properties of undefined (reading 'toLowerCase')
    at getClientParamsFromConnectionString (storage.js:20)"}
  ← これは Azure Function がクラッシュしたことを教えてくれます。接続文字列が未定義です

例: Null での式エラー

エラーコード: "BadRequest" ← 一般的

アクション出力が明らかにするもの:
  inputs: "body('HTTP_GetTokenFromStore')?['token']?['access_token']"
  outputs: ""   ← 空の文字列。パスは Null に解決されました
  ← これは応答シェイプが変更されたことを教えてくれます — トークンは body.token.access_token ではなく body.access_token にあります

---

ステップ 5 — フロー定義を読む

defn = mcp("get_live_flow", environmentName=ENV, flowName=FLOW_ID)
actions = defn["properties"]["definition"]["actions"]
print(list(actions.keys()))

定義内で失敗しているアクションを見つけてください。その inputs 式を検査して、どのようなデータが必要とされているかを理解してください。

---

ステップ 6 — 失敗から遡って進む

失敗しているアクションの入力が上流のアクションを参照する場合、それらも検査してください。悪いデータのソースが見つかるまでチェーンを遡ってください:

# 失敗に至る複数のアクションを検査
for action_name in [root_action, "Compose_WeekEnd", "HTTP_Get_Data"]:
    result = mcp("get_live_flow_run_action_outputs",
        environmentName=ENV,
        flowName=FLOW_ID,
        runName=RUN_ID,
        actionName=action_name)
    out = result[0] if result else {}
    print(f"\n--- {action_name} ({out.get('status')}) ---")
    print(f"Inputs:  {json.dumps(out.get('inputs', ''), indent=2)[:300]}")
    print(f"Outputs: {json.dumps(out.get('outputs', ''), indent=2)[:300]}")

⚠️ 配列処理アクションの出力ペイロードは非常に大きくなる可能性があります。 印刷する前に常にスライス (例: [:500]) してください。

ヒント: どのアクションが悪いデータを生成したか不確かな場合は、actionName を省略してトップレベルアクションをリストアップしてください。foreach 内のアクションを選択したら、すべての繰り返しをコンテキストに引き込むのを避けるために iterationIndex を渡してください。

---

ステップ 7 — 根本原因を特定する

式エラー (例: Null 上の split)

エラーが InvalidTemplate または関数名を言及している場合:

1. 定義内のアクションを見つけてください
2. これがどの上流のアクション/式から読み込んでいるかを確認してください
3. その上流のアクションの出力を検査して null/不足しているフィールドがないか確認してください

# 例: アクションが split(item()?['Name'], ' ') を使用
# → ソースデータの Null 名前
result = mcp("get_live_flow_run_action_outputs", ..., actionName="Compose_Names")
if not result:
    print("No outputs returned for Compose_Names")
    names = []
else:
    names = result[0].get("outputs", {}).get("body") or []
nulls = [x for x in names if x.get("Name") is None]
print(f"{len(nulls)} records with null Name")

間違ったフィールドパス

式 triggerBody()?['fieldName'] が Null を返す → fieldName が間違っています。 トリガー出力を検査して 実際のフィールド名を確認してください:

result = mcp("get_live_flow_run_action_outputs", ..., actionName="<trigger-action-name>")
print(json.dumps(result[0].get("outputs"), indent=2)[:500])

HTTP アクションがエラーを返す

エラーコードが InternalServerError または NotSpecified と言う — 常にアクション出力を検査して 実際の HTTP ステータスとレスポンス本文を取得してください:

result = mcp("get_live_flow_run_action_outputs", ..., actionName="HTTP_Get_Data")
out = result[0]
print(f"HTTP {out['outputs']['statusCode']}")
print(json.dumps(out['outputs']['body'], indent=2)[:500])

接続/認証エラー

ConnectionAuthorizationFailed を探してください — 接続所有者はフローを実行するサービスアカウントと一致する必要があります。API 経由では修正できません。PA デザイナーで修正してください。

Outlook ユーザー選択エラー (DynamicListValuesUndefinedOrInvalid)

GetEmailsV3 などの Outlook アクションは、ドロップダウンが builtInOperation:AadGraph.GetUsers でサポートされているパラメータ (mailboxAddress、to、cc、from) を使用します — これは PA listEnum レイヤーで壊れており、常に DynamicListValuesUndefinedOrInvalid を返します。これは、エージェントが Outlook アクションを update_live_flow で再構築または修正しようとし、動的オプションを通じてユーザーを解決しようとする場合に表示されます。AadGraph を再試行して修正しないでください — 代わりに shared_office365users.SearchUserV2 に切り替えてください（同じ AAD ユーザー シェイプを返します）。describe_live_connector を使用して、影響を受けるパラメータが構造化された fallback を公開しているかどうかを確認してから、壊れた AadGraph オペレーションの代わりに shared_office365users.SearchUserV2 に対して get_live_dynamic_options を呼び出してください。 動的フィールド スキーマ（ドロップダウン オプションではなく）の場合は、describe_live_connector から返されたメタデータを使用して get_live_dynamic_properties を使用してください。

---

ステップ 8 — 修正を適用する

式/データの問題の場合:

defn = mcp("get_live_flow", environmentName=ENV, flowName=FLOW_ID)
acts = defn["properties"]["definition"]["actions"]

# 例: 潜在的に Null な Name での分割を修正
acts["Compose_Names"]["inputs"] = \
    "@coalesce(item()?['Name'], 'Unknown')"

conn_refs = defn["properties"]["connectionReferences"]
result = mcp("update_live_flow",
    environmentName=ENV,
    flowName=FLOW_ID,
    definition=defn["properties"]["definition"],
    connectionReferences=conn_refs)

print(result.get("error"))  # None = success

⚠️ update_live_flow は常に error キーを返します。 null 値（Python None）は成功を意味します。

---

ステップ 9 — 修正を確認する

resubmit_live_flow_run を使用してANYフローをテストしてください — HTTP トリガーだけではありません。 resubmit_live_flow_run は元のトリガー ペイロードを使用して前の実行を再度実行します。これはすべてのトリガー タイプで機能します: 定期実行、SharePoint「アイテムが作成されたとき」、コネクタ webhook、ボタン トリガー、HTTP トリガー。ユーザーにフローを手動でトリガーするよう依頼したり、次のスケジュール実行を待つ必要がありません。

resubmit が利用できない唯一のケースは、まだ実行されたことのない新しいフロー です — 再度実行する前の実行がありません。

# 失敗した実行を再度実行 — すべてのトリガー タイプで機能
resubmit = mcp("resubmit_live_flow_run",
    environmentName=ENV, flowName=FLOW_ID, runName=RUN_ID)
print(resubmit)   # {"resubmitted": true, "triggerName": "..."}

# 約 30 秒待ってから確認
import time; time.sleep(30)
new_runs = mcp("get_live_flow_runs", environmentName=ENV, flowName=FLOW_ID, top=3)
print(new_runs[0]["status"])   # Succeeded = 完了

resubmit とトリガーをいつ使用するか

シナリオ	使用	理由
任意のフロー上での修正テスト	resubmit_live_flow_run	失敗を引き起こした正確なトリガー ペイロードを再度実行 — 検証の最良の方法
定期実行/スケジュール フロー	resubmit_live_flow_run	別の方法でオンデマンドでトリガーできません
SharePoint/コネクタ トリガー	resubmit_live_flow_run	実際の SP アイテムを作成せずにトリガーできません
カスタム テスト ペイロードを使用した HTTP トリガー	trigger_live_flow	元の実行とは異なるデータを送信する必要がある場合
まだ実行されたことのない新しいフロー	trigger_live_flow (HTTP のみ)	再度実行する前の実行が存在しません

カスタム ペイロードを使用した HTTP トリガー フローのテスト

Request (HTTP) トリガーを持つフローの場合、元の実行とは異なる ペイロードを送信する必要がある場合は、trigger_live_flow を使用してください:

# 最初にトリガーが期待するものを検査 — フロー定義から直接読み込みます
defn = mcp("get_live_flow", environmentName=ENV, flowName=FLOW_ID)
triggers = defn["properties"]["definition"]["triggers"]
manual = next(iter(triggers.values()))   # 通常は HTTP フロー上の唯一のトリガー
request_schema = manual.get("inputs", {}).get("schema")
print("Expected body schema:", request_schema)

# Response スキーマはアクション ブロック内の Response アクション上にあります
for name, act in defn["properties"]["definition"]["actions"].items():
    if act.get("type") == "Response":
        print(f"Response {name}:", act.get("inputs", {}).get("schema"))

# テスト ペイロードでトリガー
result = mcp("trigger_live_flow",
    environmentName=ENV,
    flowName=FLOW_ID,
    body={"name": "Test User", "value": 42})
print(f"Status: {result['responseStatus']}, Body: {result.get('responseBody')}")

trigger_live_flow は AAD 認証済みトリガーを自動的に処理します。 Request (HTTP) トリガー タイプを持つフローに対してのみ機能します。

---

クイックリファレンス診断決定ツリー

症状	最初のツール	次に必ず呼び出してください	何を探すべきか
フローが失敗として表示される	get_live_flow_run_error	失敗しているアクション上の get_live_flow_run_action_outputs	outputs 内の HTTP ステータス + レスポンス本文
エラーコードが一般的 (ActionFailed、NotSpecified)	—	get_live_flow_run_action_outputs	outputs.body は実際のエラーメッセージ、スタックトレース、または API エラーを含みます
HTTP アクションが 500 を返す	—	get_live_flow_run_action_outputs	outputs.statusCode + サーバーエラー詳細を含む outputs.body
式クラッシュ	—	前のアクション上の get_live_flow_run_action_outputs	出力本文内の Null/間違った型フィールド
フローが開始しない	get_live_flow	—	properties.state = "Started" であることを確認
アクションが間違ったデータを返す	get_live_flow_run_action_outputs	—	実際の出力本文と期待される
修正を適用しましたが、まだ失敗します	再度実行後の get_live_flow_runs	—	新しい実行 status フィールド

ルール: エラーコードだけで診断しないでください。 get_live_flow_run_error は失敗しているアクションを特定します。get_live_flow_run_action_outputs は実際の原因を明らかにします。常に両方を呼び出してください。

---

リファレンス ファイル

• common-errors.md — エラーコード、可能性のある原因、修正
• debug-workflow.md — 複雑な失敗の完全な決定ツリー

関連スキル

• flowstudio-power-automate-mcp — 基本スキル: 接続設定、MCP ヘルパー、ツール検出
• flowstudio-power-automate-build — 新しいフローの構築とデプロイ