Power Automate via FlowStudio MCP — Foundation

このスキルは基盤層です。AI エージェントが FlowStudio MCP サーバーと確実に通信でき、利用可能なツールを発見でき、レスポンスをクリーンに処理する方法を提供します。実際のワークフロー構成は、すべてこのスキルの上に構築される 4 つの特化したスキルに含まれています。

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

必須: FlowStudio MCP サブスクリプション (または互換性のある Power Automate MCP サーバー)。以下が必要です:

• MCP エンドポイント: https://mcp.flowstudio.app/mcp (すべてのサブスクライバーで共通)
• API キー / JWT トークン (x-api-key ヘッダー — Bearer ではない)
• 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、実行エラーツールを呼び出します — 異なるのは方向 (前進 vs 後進) と意図 (作成 vs 診断) です。 flowstudio-power-automate-monitoring と flowstudio-power-automate-governance は両方とも Store ツールを呼び出します — 異なるのは対象者 (運用 vs コンプライアンス) と結果 (健全性読み取り vs メタデータ書き込み) です。「どのツールがどのスキルに属するか」を暗記しようとしないでください; ユーザーが何をしているかでスキルを選択してください。

---

信頼できる情報源

優先度	ソース	対象
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) を確認して 1 つ選択
tool_search with query: "skill:<name>"	1 つのバンドルの完全スキーマセットをロード (例: skill:debug-flow)
tool_search with query: "select:tool1,tool2"	特定のツールを名前で指定してロード (バンドル全体でチェーンするとき)
tool_search with query: "<keywords>"	ユーザーリクエストが曖昧なときにフリーテキスト検索 (例: "cancel run")

サーバーの tool_search バンドルは意図的にこのスキル ファミリーより狭くなっています — 意図ごとに最も必要な可能性が高いツールのスターターパックです。ワークフロー スキル (例: flowstudio-power-automate-debug) はバンドルをプルしてから、ワークフローが進むにつれて追加ツールについて tool_search を再度呼び出す場合があります。

# コールドスタート — 意図でバンドルを選択
skills = mcp("list_skills", {})
# [{"name": "debug-flow", "description": "Investigate why a flow is failing...",
#   "tools": ["get_live_flow_runs", "get_live_flow_run_error", ...]}, ...]

# バンドルのスキーマをロード
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

このスキル ファミリーのすべての例は、Python with urllib.request を使用しています (stdlib — 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 パーサーなし

TL;DR — 以下の 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, ...} → 間違っているか欠落しているツール引数。tool_search を select:<toolname> で呼び出してスキーマを確認してください。

---

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 を stdlib の 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\":), したがってプレーン grep は "OperationId": にマッチしません。最初に解析してからフィルター処理してください。
5. ツール出力をユーザーに要約する。 フロー リストの name + state + trigger と実行エラーの actionName + status + code をエコーしてください — 要求されない限り、raw JSON ではなく。

# 良い — コネクタ swagger の 1 つの操作にドリル ダウン
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"))

# 悪い — 全体の 500 KB swagger をコンテキストに保つ
print(json.dumps(conn, indent=2))   # これをしないでください

---

認証と接続の注記

フィールド	値
認証ヘッダー	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 — コネクタ リファレンス ガイド