power-automate-mcp

FlowStudio MCP による Power Automate — 基礎

このスキルは基盤レイヤーです。AI エージェントが FlowStudio MCP サーバーと確実に通信し、利用可能なツールを確認して、レスポンスを適切に処理する方法を提供します。実際のワークフローの説明は、このスキルを基盤として構築された4つの専門スキルにあります。

実際のデバッグ例：子フローの式エラー | フローのバグではなくデータ入力の問題 | Null 値による子フローのクラッシュ

必要なもの： FlowStudio MCP サブスクリプション（または互換性のある Power Automate MCP サーバー）。次のものが必要です。

• MCP エンドポイント：https://mcp.flowstudio.app/mcp（すべてのサブスクライバーで共通）
• API キー／JWT トークン（x-api-key ヘッダー — Bearer ではありません）
• ChatGPT または claude.ai ではキーは不要です。コネクターとして https://mcp.flowstudio.app/mcp/oauth を追加し、Microsoft でサインインしてください — ChatGPT の手順を参照
• Power Platform の環境名（例：Default-<tenant-guid>）

---

スキルを使い分けるには

スキルは、呼び出すツールではなくユースケースの目的に応じて整理されています。複数のスキルが同じ基盤ツールを再利用しています。ユーザーが何を実現しようとしているかに基づいて選んでください。

ユーザーの目的	使用するスキル
フローの作成または変更（新規作成、既存フローの変更、バグ修正、デプロイ）	power-automate-build
フローが失敗した理由の診断（失敗した実行の根本原因分析）	power-automate-debug
テナント全体のフローの健全性、失敗率、アセットのインベントリを確認	power-automate-monitoring (Pro+)
フローへのタグ付け、監査、分類、スコア付け、またはオフボーディング	power-automate-governance (Pro+)
接続、認証設定、ヘルパーの作成、レスポンスの解析のみ	このスキル（基礎）

ツールは同じでも、視点は異なります。 power-automate-build と power-automate-debug は、どちらも update_live_flow、get_live_flow、実行エラー関連のツールを呼び出します。異なるのは方向性（順方向と逆方向）と目的（構成と診断）です。power-automate-monitoring と power-automate-governance はどちらも Store ツールを呼び出しますが、対象（運用とコンプライアンス）と結果（健全性の確認とメタデータの書き込み）が異なります。「どのツールがどのスキルに属するか」を暗記しようとせず、ユーザーが何をしようとしているかに基づいてスキルを選んでください。

---

信頼できる情報源

優先順位	情報源	対象
1	実際の API レスポンス	常にサーバーが実際に返す内容を信頼します
2	tool_search / list_skills	信頼できるツールスキーマ、パラメーター名、型、必須フラグ
3	SKILL ドキュメントとリファレンスファイル	ワークフローの説明、レスポンスの形式、分かりにくい動作

ドキュメントと実際の API レスポンスが食い違う場合は、API を優先してください。このスキル（または他のスキル）のツールスキーマは、サーバーの更新に追いついていないことがあります。最近使っていないツールを呼び出す前に、tool_search を呼び出して現在の形式を確認してください。

---

エージェントによるツールの検出方法

FlowStudio MCP サーバー（v1.1.5 以降）は、エージェントが現在のタスクに関連するツールだけを読み込める、課金対象外のメタツールを 2 つ公開しています。すべての 30 個以上のスキーマを一度に読み込む tools/list を使ったり、ツール名を推測したりする代わりに、これらを使ってください。

メタツール	呼び出すタイミング
list_skills	コールドスタート時 — 利用できるバンドル（build-flow、create-flow、debug-flow、monitor-flow、discover、governance）を確認して、1 つ選びます
query: "skill:<name>" を指定した tool_search	1 つのバンドルの全スキーマを読み込みます（例：skill:debug-flow）
query: "select:tool1,tool2" を指定した tool_search	名前を指定して特定のツールを読み込みます（例：バンドルをまたいでツールを連携する場合）
query: "<keywords>" を指定した tool_search	ユーザーの依頼が曖昧な場合のフリーテキスト検索（例："cancel run"）

サーバーの tool_search バンドルは、意図的にこのスキルファミリーよりも絞り込まれています。各インテントで最も必要とされる可能性が高いツールのスターターパックです。ワークフロースキル（例：power-automate-debug）は、まずバンドルを読み込んだ後、ワークフローの進行に応じて、追加のツールを取得するために再度 tool_search を呼び出す場合があります。

# Cold start — pick a bundle by intent
skills = mcp("list_skills", {})
# [{"name": "debug-flow", "description": "Investigate why a flow is failing...",
#   "tools": ["get_live_flow_runs", "get_live_flow_run_error", ...]}, ...]

# Load schemas for the bundle
debug_tools = mcp("tool_search", {"query": "skill:debug-flow"})

現在よく使われるバンドル：

バンドル	使用するタイミング
create-flow	新しいフローを作成するとき。環境／接続の検出、コネクタの説明、動的オプション、update_live_flow が含まれます
build-flow	既存のフロー定義を読み取る、または変更するとき
debug-flow	失敗した実行とアクションレベルの入力／出力を調査するとき
monitor-flow	実行の開始／停止、トリガー、キャンセル、再送信を行うとき
discover	環境、フロー、接続を列挙するとき
governance	Pro+ のキャッシュストアのタグ付け、作成者の監査、メタデータの更新を行うとき

---

推奨言語：Python または Node.js

このスキルファミリーのすべての例では、urllib.request を使った Python（標準ライブラリ — pip install は不要）を使用しています。Node.js も同様に適しています。fetch は Node 18 以降に組み込まれており、JSON の処理はネイティブで、async/await は MCP ツール呼び出しのリクエスト／レスポンスパターンに自然に対応するため、JavaScript／TypeScript のスタックをすでに使用しているチームに適しています。

言語	評価	備考
Python	推奨	JSON を簡潔に処理でき、エスケープの問題がなく、すべてのスキル例で使用されています
Node.js (≥ 18)	推奨	ネイティブの fetch と JSON.stringify／JSON.parse を使用でき、追加パッケージは不要です
PowerShell	フロー操作では避けてください	ConvertTo-Json -Depth はネストされた定義を気付かれないまま切り詰めます。また、引用符とエスケープにより複雑なペイロードが壊れます。接続を手早くスモークテストする用途には使えますが、フローの構築や更新には適しません。
cURL ／ Bash	使用できますが不安定です	ネストされた JSON のシェルエスケープはエラーが起きやすく、ネイティブの JSON パーサーもありません

要約 — 以下の Core MCP Helper（Python または Node.js）を使用してください。 どちらも、JSON-RPC のフレーミング、認証、レスポンスの解析を、再利用可能な 1 つの関数で処理します。

---

Core MCP Helper（Python）

以降のすべての操作で、このヘルパーを使用してください。

import json, urllib.request

TOKEN = "<YOUR_JWT_TOKEN>"
MCP   = "https://mcp.flowstudio.app/mcp"

def mcp(tool, args, cid=1):
    payload = {"jsonrpc": "2.0", "method": "tools/call", "id": cid,
               "params": {"name": tool, "arguments": args}}
    req = urllib.request.Request(MCP, data=json.dumps(payload).encode(),
        headers={"x-api-key": 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'])}")
    text = raw["result"]["content"][0]["text"]
    return json.loads(text)

よくある認証エラー：

• HTTP 401／403 → トークンがない、期限切れ、または形式が正しくありません。mcp.flowstudio.app から新しい JWT を取得してください。
• HTTP 400 → JSON-RPC ペイロードの形式が正しくありません。Content-Type: application/json と本文の構造を確認してください。
• MCP error: {"code": -32602, ...} → ツールの引数が間違っているか、不足しています。select:<toolname> を指定して tool_search を呼び出し、スキーマを確認してください。

---

Core MCP Helper（Node.js）

Node.js 18 以降に対応した同等のヘルパーです（fetch は組み込み — パッケージは不要です）。

const TOKEN = "<YOUR_JWT_TOKEN>";
const MCP   = "https://mcp.flowstudio.app/mcp";

async function mcp(tool, args, cid = 1) {
  const payload = {
    jsonrpc: "2.0",
    method: "tools/call",
    id: cid,
    params: { name: tool, arguments: args },
  };
  const res = await fetch(MCP, {
    method: "POST",
    headers: {
      "x-api-key": TOKEN,
      "Content-Type": "application/json",
      "User-Agent": "FlowStudio-MCP/1.0",
    },
    body: JSON.stringify(payload),
  });
  if (!res.ok) {
    const body = await res.text();
    throw new Error(`MCP HTTP ${res.status}: ${body.slice(0, 200)}`);
  }
  const raw = await res.json();
  if (raw.error) throw new Error(`MCP error: ${JSON.stringify(raw.error)}`);
  return JSON.parse(raw.result.content[0].text);
}

Node.js 18 以降が必要です。古い Node の場合は、fetch を標準ライブラリの https.request に置き換えるか、node-fetch をインストールしてください。

---

接続を確認する

トークン、エンドポイント、ヘルパーがすべて動作することを確認する、3 行のスモークテストです。

skills = mcp("list_skills", {})
print(f"Connected — {len(skills)} skill bundles available:",
      [s["name"] for s in skills])

想定される出力：

Connected — 6 skill bundles available: ['build-flow', 'create-flow', 'debug-flow', 'monitor-flow', 'discover', 'governance']

失敗する場合は、上記の よくある認証エラー の説明を参照してください。成功した場合は、ユーザーの意図に合ったワークフロースキルに引き継いでください。

---

サイズ超過レスポンスの処理

一部の MCP ツールのレスポンスは非常に大きく、エージェントのコンテキストウィンドウに収まらないことがあります。

ツール	一般的なサイズ	原因
describe_live_connector	100-600 KB	コネクタの完全な Swagger 仕様
get_live_dynamic_properties	50-500 KB	SharePoint リストの列など、動的なコネクタフィールドのスキーマ
get_live_flow_run_action_outputs (actionName なし)	50 KB – 数 MB	トップレベルのアクション出力。foreach 内のアクションを指定すると、すべての繰り返しが返されることがあります
get_live_flow (大きなフロー)	50-500 KB	深くネストされた分岐
list_live_flows (大規模なテナント)	50-200 KB	数百件のフローレコード

ハーネスがファイルに退避する場合

エージェントハーネス（Claude Code、VS Code Copilot など）は、サイズ超過したレスポンスを一時ファイル（例：tool-results/mcp-flowstudio-describe_live_connector-NNNN.txt）に保存し、インライン JSON の代わりにそのパスを返します。ファイルは二重にラップされています。外側に MCP エンベロープ、内側に JSON エスケープされたペイロードがあります。

[{"type":"text","text":"<JSON-escaped payload>"}]

使用可能なオブジェクトを取得するには、2 回パースします。

import json
with open(path) as f:
    raw = json.loads(f.read())
payload = json.loads(raw[0]["text"])

$payload = ((Get-Content $path -Raw | ConvertFrom-Json)[0].text) | ConvertFrom-Json

基本的なルール

1. エコーせず、抽出します。 必要な特定のフィールド（1 つの operationId、1 つのアクションの出力など）を取り出し、残りは破棄してから内容を検討します。
2. get_live_flow_run_action_outputs には必ず actionName を渡します。 省略すると、すべてのトップレベルアクションが取得されます。foreach 内のアクションでは、iterationIndex を指定せずに actionName を渡すと、そのアクションのすべての繰り返しが返されることがあります。
3. セッション中は退避ファイルを再利用します。 同じコネクタの Swagger を再取得すると 30 秒以上かかり、別の退避ファイルも生成されます。パスをキャッシュしてください。
4. 退避ファイル内の JSON キーを直接 grep しないでください。 文字列はファイル内で JSON エスケープされているため（\"OperationId\":）、"OperationId": のように単純に grep しても一致しません。まずパースしてから絞り込んでください。
5. ツールの出力は要約してユーザーに伝えます。 フローの一覧では name + state + trigger、実行エラーでは actionName + status + code を返し、求められない限り生の JSON は返しません。

# Good — drill into one operation in a connector swagger
conn = mcp("describe_live_connector", {"environmentName": ENV, "connectorName": "shared_sharepointonline"})
op = conn["properties"]["swagger"]["paths"]["/datasets/{dataset}/tables/{table}/items"]["get"]
print(op["operationId"], "—", op.get("summary"))

# Bad — keeping the whole 500 KB swagger in context
print(json.dumps(conn, indent=2))   # don't do this

---

認証と接続に関する注意事項

フィールド	値
認証ヘッダー	x-api-key: <JWT> — Authorization: Bearer ではありません
トークン形式	プレーンな JWT — 削除、変更、プレフィックスの追加はしないでください
タイムアウト	get_live_flow_run_action_outputs には 120 秒以上を使用します（大きな出力の場合）
環境名	Default-<tenant-guid>（list_live_environments または list_live_flows のレスポンスで確認します）

---

参照ファイル

• MCP-BOOTSTRAP.md — エンドポイント、認証、リクエスト／レスポンス形式（まずこちらをお読みください）
• tool-reference.md — レスポンス形式と動作に関する注意事項（パラメーターは tool_search にあります）
• action-types.md — Power Automate のアクションタイプのパターン
• connection-references.md — コネクタのリファレンスガイド