flowstudio-power-automate-build

FlowStudio MCP で Power Automate フローを構築・デプロイする

FlowStudio MCP サーバーを通じて、Power Automate クラウドフローをプログラムで 構築してデプロイする手順ガイドです。

前提条件：有効な JWT で FlowStudio MCP サーバーに接続できる必要があります。 接続の設定については、flowstudio-power-automate-mcp スキルを参照してください。 https://mcp.flowstudio.app で登録してください。

ワークフロー：

1. 現在のビルドツールを読み込みます。
2. 既存のフローを確認します。
3. 接続参照を解決します。
4. 定義を構築します。
5. デプロイします。
6. 検証します。
7. テストします。

---

信頼できる情報源

利用可能なツール名とパラメータースキーマを確認するため、必ず最初に 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

---

0. 現在のビルドツールを読み込む

新しいフローを作成する場合は、サーバーの create-flow バンドルを読み込みます。既存のフローを編集する場合は、build-flow を読み込みます。これにより、JSON を構築する前に、エージェントを MCP サーバーの現在のスキーマに合わせられます。

schemas = mcp("tool_search", query="skill:create-flow")
# Includes list_live_environments, list_live_connections,
# describe_live_connector, get_live_dynamic_options, update_live_flow.

バンドルに含まれていないツールが必要な場合は、明示的に読み込みます。

mcp("tool_search", query="select:get_live_dynamic_properties")

---

1. 安全確認：フローはすでに存在しますか？

重複を避けるため、構築する前に必ず確認してください。

results = mcp("list_live_flows",
    environmentName=ENV,
    mode="owner",
    search="My New Flow",
    top=20)

# list_live_flows returns { "flows": [...], "mode": "...", ... }
matches = [f for f in results["flows"]
           if "My New Flow".lower() in f["displayName"].lower()]

if len(matches) > 0:
    # Flow exists — modify rather than create
    FLOW_ID = matches[0]["id"]   # plain UUID from list_live_flows
    print(f"Existing flow: {FLOW_ID}")
    defn = mcp("get_live_flow", environmentName=ENV, flowName=FLOW_ID)
else:
    print("Flow not found — building from scratch")
    FLOW_ID = None

非常に大規模な環境では、list_live_flows が続きの URL を返す場合があります。同じ mode とともに、その URL を continuationUrl として渡すと、次のバッチを取得できます。すべての環境フローが必要で、MCP の ID に管理者権限がある場合に限り、mode="admin" を使用してください。

---

2. 接続参照を取得する

すべてのコネクタアクションには、フローの connectionReferences マップ内のキーを参照する connectionName が必要です。このキーは、環境内の認証済み接続に紐づいています。

必須：必ず最初に list_live_connections を呼び出してください。接続名や GUID をユーザーに尋ねてはいけません。API が必要な正確な値を返します。必要な接続が不足していることを API が確認した場合に限り、ユーザーに問い合わせてください。

2a — アクティブな接続を確認する

conns = mcp("list_live_connections", environmentName=ENV)
active = [c for c in conns["connections"]
          if c["statuses"][0]["status"] == "Connected"]
conn_map = {c["connectorName"]: c["id"] for c in active}

対象のコネクタが分かっている場合は、search を渡すと出力を絞り込め、コピーしてすぐに使用できる connectionReferenceTemplate と hostTemplate の値を取得できます。

sp_conns = mcp("list_live_connections",
    environmentName=ENV,
    search="shared_sharepointonline")

2b — フローに必要なコネクタを特定する

一般的なコネクタ API 名：SharePoint shared_sharepointonline、Outlook shared_office365、Teams shared_teams、Approvals shared_approvals、 OneDrive shared_onedriveforbusiness、Excel shared_excelonlinebusiness、 Dataverse shared_commondataserviceforapps、Forms shared_microsoftforms。

Recurrence + Compose + HTTP のみなど、コネクタを必要としないフローでは、 connectionReferences を省略できます。

2c — 接続が不足している場合は、ユーザーを案内する

connectors_needed = ["shared_sharepointonline", "shared_office365"]  # adjust per flow
missing = [c for c in connectors_needed if c not in conn_map]
if missing:
    # STOP: connections require browser OAuth consent.
    # Ask the user to create the missing connector connections in the
    # selected environment, then re-run list_live_connections.
    raise Exception(f"Missing active connections: {missing}")

2d — connectionReferences ブロックを構築する

connection_references = {}
host_templates = {}
for connector in connectors_needed:
    c = next(c for c in active if c["connectorName"] == connector)
    connection_references[connector] = c.get("connectionReferenceTemplate") or {
        "connectionName": c["id"],   # the connection id from list_live_connections
        "source": "Invoker",
        "id": f"/providers/Microsoft.PowerApps/apis/{connector}"
    }
    host_templates[connector] = c.get("hostTemplate") or {
        "connectionName": connector
    }

ステップ 3 のアクション JSON では、inputs.host.connectionName に GUID ではなく、shared_teams などのマップキーを指定する必要があります。GUID を指定するのは、connectionReferences[connector].connectionName の値の中だけです。既存のフローで同じコネクタが使われている場合は、get_live_flow からその properties.connectionReferences をコピーしてもかまいません。

---

3. フロー定義を構築する

定義オブジェクトを構築します。完全なスキーマについては flow-schema.md を参照してください。また、コピーして使用できるテンプレートについては、次のアクションパターンのリファレンスを参照してください。

• action-patterns-core.md — 変数、制御フロー、式
• action-patterns-data.md — 配列変換、HTTP、解析
• action-patterns-connectors.md — SharePoint、Outlook、Teams、Approvals

definition = {
    "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#",
    "contentVersion": "1.0.0.0",
    "triggers": { ... },   # see trigger-types.md / build-patterns.md
    "actions": { ... }     # see ACTION-PATTERNS-*.md / build-patterns.md
}

Recurrence+SharePoint+Teams、HTTP トリガーなどを含む、すぐに使える完全なフロー定義については、build-patterns.md を参照してください。

JSONを推測する前に、コネクターの操作を確認する

コネクターに基づくトリガー／アクションでは、手書きのスキーマよりも、稼働中のコネクター記述ツールを優先してください。作成者が指定したヒント、標準的な例、バリアントキー、入力／出力、動的メタデータへのポインターを返すことができます。

# Search across connectors when you know the user's intent but not the API.
matches = mcp("describe_live_connector",
    environmentName=ENV,
    search="send email",
    top=5)

# Describe a specific operation before copying an exampleDefinition.
op = mcp("describe_live_connector",
    environmentName=ENV,
    connectorName="shared_office365",
    operationId="SendEmailV2")
print(op.get("hint"))

操作に複数の作成済みバリアントがある場合は、フローに必要なバリアントをリクエストしてください。

teams_chat = mcp("describe_live_connector",
    environmentName=ENV,
    connectorName="shared_teams",
    operationId="PostMessageToConversation",
    variant="flowbot_chat")

操作の説明に、パラメーターに動的オプションまたは動的プロパティがあると記載されている場合は、指定された次のツールを呼び出してください。

sp_op = mcp("describe_live_connector",
    environmentName=ENV,
    connectorName="shared_sharepointonline",
    operationId="GetItems")

sites = mcp("get_live_dynamic_options",
    environmentName=ENV,
    connectorName="shared_sharepointonline",
    connectionName=conn_map["shared_sharepointonline"],
    operationId="GetItems",
    parameterName="dataset",
    dynamicMetadata=sp_op["dynamicParameters"]["dataset"])

fields = mcp("get_live_dynamic_properties",
    environmentName=ENV,
    connectorName="shared_sharepointonline",
    connectionName=conn_map["shared_sharepointonline"],
    operationId="GetItems",
    parameterName="item",
    parameters={"dataset": "<site-url>", "table": "<list-id>"},
    dynamicMetadata=sp_op["dynamicProperties"]["item"])

SharePoint のサイト／リストや Teams のチーム／チャネルなど、ドロップダウンの ID には動的オプションを使用してください。SharePoint のリストアイテムの列など、スキーマ／フィールドの構造には動的プロパティを使用してください。

---

4. デプロイ（作成または更新）

update_live_flow は、1 つのツールで作成と更新の両方に対応します。

新しいフローを作成する（既存のフローがない場合）

flowName を省略してください。サーバーが新しい GUID を生成し、PUT で作成します。

definition["description"] = "Weekly SharePoint → Teams notification flow, built by agent"

result = mcp("update_live_flow",
    environmentName=ENV,
    # flowName omitted → creates a new flow
    definition=definition,
    connectionReferences=connection_references,
    displayName="Overdue Invoice Notifications"
)

if result.get("error") is not None:
    print("Create failed:", result["error"])
else:
    # Capture the new flow ID for subsequent steps
    FLOW_ID = result["created"]
    print(f"✅ Flow created: {FLOW_ID}")

既存のフローを更新する

PATCH を実行するには flowName を指定してください。

definition["description"] = (
    "Updated by agent on " + __import__('datetime').datetime.utcnow().isoformat()
)

result = mcp("update_live_flow",
    environmentName=ENV,
    flowName=FLOW_ID,
    definition=definition,
    connectionReferences=connection_references,
    displayName="My Updated Flow"
)

if result.get("error") is not None:
    print("Update failed:", result["error"])
else:
    print("Update succeeded:", result)

⚠️ update_live_flow は常に error キーを返します。 null（Python の None）は成功を意味します。キーが存在することを失敗とみなさないでください。

⚠️ フローの説明は definition["description"] にあります。現在のサーバーは、使用状況の追跡のために #flowstudio-mcp を追加します。有効なスキーマに tool_search で表示されない限り、トップレベルの description 引数を渡さないでください。

よくあるデプロイエラー

エラーメッセージ（次の文字列を含む）	原因	対処方法
missing from connectionReferences	アクションの host.connectionName が、connectionReferences マップに存在しないキーを参照しています	host.connectionName には、生の GUID ではなく connectionReferences のキー（例：shared_teams）を指定してください
ConnectionAuthorizationFailed / 403	接続 GUID が別のユーザーに属しているか、認証されていません	ステップ 2a を再実行し、現在の x-api-key ユーザーが所有する接続を使用してください
InvalidTemplate / InvalidDefinition	定義 JSON に構文エラーがあります	runAfter チェーン、式の構文、アクションの種類の表記を確認してください
ConnectionNotConfigured	コネクターアクションが存在しますが、接続 GUID が無効または期限切れです	list_live_connections で新しい GUID を再確認してください

---

5. デプロイを検証する

check = mcp("get_live_flow", environmentName=ENV, flowName=FLOW_ID)

# Confirm state
print("State:", check["properties"]["state"])  # Should be "Started"
# If state is "Stopped", use set_live_flow_state — NOT update_live_flow
# mcp("set_live_flow_state", environmentName=ENV, flowName=FLOW_ID, state="Started")

# Confirm the action we added is there
acts = check["properties"]["definition"]["actions"]
print("Actions:", list(acts.keys()))

---

6. フローをテストする

必須：テスト実行をトリガーする前に、必ずユーザーに確認してください。 フローの実行には実際の副作用があります。メールの送信、Teams メッセージの投稿、SharePoint への書き込み、承認の開始、外部 API の呼び出しなどが発生する可能性があります。フローが実行する内容を説明し、trigger_live_flow または resubmit_live_flow_run を呼び出す前に、明示的な承認を待ってください。

更新済みのフロー（以前の実行履歴がある場合）— トリガーの種類を問わない

まず resubmit_live_flow_run を使用してください。 Recurrence、SharePoint、コネクターの Webhook、Button、HTTP など、あらゆるトリガータイプで動作します。 元のトリガーペイロードを再実行します。ユーザーに手動でフローをトリガーするよう求めたり、次のスケジュール実行を待ったりしないでください。

runs = mcp("get_live_flow_runs", environmentName=ENV, flowName=FLOW_ID, top=1)
if runs:
    # Works for Recurrence, SharePoint, connector triggers — not just HTTP
    result = mcp("resubmit_live_flow_run",
        environmentName=ENV, flowName=FLOW_ID, runName=runs[0]["name"])
    print(result)   # {"resubmitted": true, "triggerName": "..."}

HTTP、Button、PowerApps フロー — カスタムテストペイロード

元の実行とは異なるペイロードを送信する必要がある場合に限り、trigger_live_flow を使用してください。修正を検証する場合は、失敗の原因となった正確なデータを使用する resubmit_live_flow_run の方が適しています。

defn = mcp("get_live_flow", environmentName=ENV, flowName=FLOW_ID)
triggers = defn["properties"]["definition"]["triggers"]
manual = next(iter(triggers.values()))
print("Expected body:", manual.get("inputs", {}).get("schema"))

result = mcp("trigger_live_flow",
    environmentName=ENV, flowName=FLOW_ID,
    body={"name": "Test", "value": 1})
print(f"Status: {result['responseStatus']}, via: {result['invocation']}")
print(result.get("warning"))   # set when a required input was missing: the run still ran, with null

新規の非 HTTP フロー

新規のRecurrenceフローに回避策は必要ありません。デプロイ後、body を指定せずに trigger_live_flow で直ちに実行します。ポータルの「フローを実行」ボタンと同じです。本文は拒否されます。スケジュールトリガーは入力を受け取りません。

新規のコネクタートリガー型フロー（SharePoint、Webhook）には実行履歴がなく、実際のソースイベントが発生しない限り起動できません。一時的な HTTP トリガーを使ってデプロイし、アクションをテストしてから、本番用トリガーに差し替えてください。

production_trigger = definition["triggers"]
definition["triggers"] = {
    "manual": {"type": "Request", "kind": "Http", "inputs": {"schema": {}}}
}
result = mcp("update_live_flow", environmentName=ENV,
    flowName=FLOW_ID,       # omit if creating new
    definition=definition, connectionReferences=connection_references,
    displayName="Overdue Invoice Notifications")
FLOW_ID = FLOW_ID or result["flowName"]

mcp("trigger_live_flow", environmentName=ENV, flowName=FLOW_ID,
    body={"sample": "payload"})
runs = mcp("get_live_flow_runs", environmentName=ENV, flowName=FLOW_ID, top=1)
if runs[0]["status"] == "Failed":
    err = mcp("get_live_flow_run_error",
        environmentName=ENV, flowName=FLOW_ID, runName=runs[0]["name"])
    raise Exception(err["failedActions"][-1])

definition["triggers"] = production_trigger
mcp("update_live_flow", environmentName=ENV, flowName=FLOW_ID,
    definition=definition, connectionReferences=connection_references)

トリガーはエントリーポイントにすぎません。HTTP 経由のテストでも、同じアクションが実行されます。アクションが triggerBody() または triggerOutputs() を使用する場合は、本番トリガーのペイロードと同じ構造の代表的な body を渡してください。

---

注意点

間違い	影響	防止策
デプロイ時に connectionReferences がない	400「Supply connectionReferences」	必ず最初に list_live_connections を呼び出してください
Foreach に "operationOptions" がない	並列実行により、書き込みで競合状態が発生します	必ず "Sequential" を追加してください
union(old_data, new_data)	古い値が新しい値を上書きします（先勝ち）	union(new_data, old_data) を使用してください
null の可能性がある文字列に split() を使用	InvalidTemplate エラーでクラッシュします	coalesce(field, '') でラップしてください
result["error"] の存在を確認	常に存在します。実際のエラーは != null です	result.get("error") is not None を使用してください
フローはデプロイされたが、状態が「Stopped」	フローはスケジュールどおりに実行されません	state: "Started" を指定して set_live_flow_state を呼び出してください。状態の変更に update_live_flow は 使用しないでください
Teams「Chat with Flow bot」の受信者をオブジェクトで指定	400 GraphUserDetailNotFound	末尾にセミコロンを付けたプレーン文字列を使用してください（以下を参照）
Copilot／Skills フローがソリューションに含まれていない	Copilot Studio がエージェントツールとして検出できない場合があります	デプロイ後、対象の solutionId を指定して add_live_flow_to_solution を呼び出してください
MCP のテストにボタン／Skills トリガーを使用	必須入力が欠けていても（null でも）実行されます	trigger_live_flow の body に入力を渡してください。warning が出た場合はキャンセルし、完全な body で再試行してください
コネクタアクションに metadata.operationMetadataId がない	デザイナー／実行専用 UI の動作が不安定になる場合があります	既存の ID は保持し、新しいコネクタアクションには安定した GUID を追加してください
Excel の scriptId がプレースホルダー	保存時に動的検証が失敗します	デプロイ前に実際の Office Script ID を解決してください
SharePoint の PatchItem で必須フィールドが省略されている	フィールドを変更しない場合でも保存に失敗することがあります	item/Title など、変更しない必須フィールドも返してください
Copilot Studio コネクタがドラフトのエージェントを呼び出す	コネクタの呼び出しに失敗したり、古い動作が発生したりする場合があります	フローをテスト／再送信する前に、エージェントを公開してください

Teams PostMessageToConversation — 受信者の形式

body/recipient パラメーターの形式は、location の値によって異なります。

場所	body/recipient の形式	例
Chat with Flow bot	末尾にセミコロンを付けたプレーンなメールアドレス文字列	"[email protected];"
Channel	groupId と channelId を持つオブジェクト	{"groupId": "...", "channelId": "..."}

よくある間違い：「Chat with Flow bot」に {"to": "[email protected]"} を渡すと、 400 GraphUserDetailNotFound エラーが返されます。API が想定しているのはプレーン文字列です。

---

参考ファイル

• flow-schema.md — フロー定義の完全な JSON スキーマ
• trigger-types.md — トリガータイプのテンプレート
• action-patterns-core.md — 変数、制御フロー、式
• action-patterns-data.md — 配列変換、HTTP、解析
• action-patterns-connectors.md — SharePoint、Outlook、Teams、承認
• build-patterns.md — フロー定義の完全なテンプレート（Recurrence+SP+Teams、HTTP トリガー）

関連スキル

• flowstudio-power-automate-mcp — コア接続のセットアップとツールのリファレンス
• flowstudio-power-automate-debug — デプロイ後に失敗するフローをデバッグ