flowstudio-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>）

---

使用するスキル

スキルは、呼び出すツールではなく、ユースケースの意図に基づいて分類されています。複数のスキルで同じ基盤ツールを再利用します。ユーザーが達成しようとしていることに合わせて選んでください。

ユーザーの目的	読み込むスキル
フローを作成または変更する（新規作成、既存フローの修正、バグ修正、デプロイ）	flowstudio-power-automate-build
フローの失敗原因を診断する（失敗した実行の根本原因分析）	flowstudio-power-automate-debug
テナント全体のフローの健全性、失敗率、アセット一覧を確認する	flowstudio-power-automate-monitoring (Pro+)
フローにタグを付ける、監査する、分類する、スコアを付ける、またはオフボードする	flowstudio-power-automate-governance (Pro+)
接続、認証の設定、ヘルパーの作成、応答の解析のみを行う	このスキル（基盤）

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

---

信頼できる情報源

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

ドキュメントの内容が実際の API 応答と異なる場合は、API を優先してください。このスキル（または他のスキル）に記載されているツールスキーマは、サーバーの変更に追いついていない場合があります。最近使用していないツールを呼び出す前に、tool_search を実行して現在の形式を確認してください。

---

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

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

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

サーバーの tool_search バンドルは、このスキルファミリーよりも意図的に絞り込まれています。目的ごとに、必要になる可能性が最も高いツールをまとめたスターターパックです。ワークフロースキル（例：flowstudio-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 も同様に適しています。Node 18 以降では fetch が組み込まれており、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 のフレーミング、認証、レスポンスの解析を、再利用可能な単一の関数で処理します。

---

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 — コネクタのリファレンスガイド