flowstudio-power-automate-mcp

透過 FlowStudio MCP 操作 Power Automate — 基礎技能

此技能是基礎架構層。它讓 AI 代理能夠可靠地與 FlowStudio MCP 伺服器通訊、探索可用的工具，並乾淨地處理回應。實際的工作流程敘述則位於四個專門的技能中，這些技能都建構在此技能之上。

實際除錯範例：子流程中的運算式錯誤 |
資料輸入問題，非流程錯誤 |
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	技能文件與參考檔案	工作流程敘述、回應格式、不明顯的行為

如果文件與實際 API 回應不一致，以 API 為準。此技能（或任何其他技能）中的工具結構定義可能落後於伺服器 — 請呼叫 tool_search 來確認當前結構，然後再呼叫您最近未使用的工具。

---

代理如何探索工具

FlowStudio MCP 伺服器（v1.1.5+）提供了兩個不計費的中繼工具，讓代理僅載入與當前任務相關的工具。請優先使用這些工具，而非 tools/list（會一次載入全部 30+ 個結構定義）或猜測工具名稱。

中繼工具	何時呼叫
list_skills	冷啟動 — 查看可用的套件（build-flow、create-flow、debug-flow、monitor-flow、discover、governance）並選擇一個
tool_search 搭配 query: "skill:<name>"	載入單一套件的完整結構定義集（例如 skill:debug-flow）
tool_search 搭配 query: "select:tool1,tool2"	依名稱載入特定工具（例如在跨套件串接時）
tool_search 搭配 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 搭配 urllib.request（標準函式庫 — 無需 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	可行但脆弱	Shell 跳脫巢狀 JSON 容易出錯；無原生 JSON 解析器

總結 — 請使用下方的核心 MCP 輔助函式（Python 或 Node.js）。 兩者都在一個可重複使用的函式中處理 JSON-RPC 框架、驗證和回應解析。

---

核心 MCP 輔助函式（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> 來確認結構定義。

---

核心 MCP 輔助函式（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。

---

驗證連線

一個三行的快速測試，確認權杖、端點和輔助函式都能正常運作：

skills = mcp("list_skills", {})
print(f"已連線 — {len(skills)} 個技能套件可用：",
      [s["name"] for s in skills])

預期輸出：

已連線 — 6 個技能套件可用：['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>"}]

需要兩次解析才能取得可用的物件：

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. 提取，不要回顯。 只取出您需要的特定欄位（一個 operationId、一個動作的輸出），然後在進行推理前丟棄其餘部分。
2. 務必將 actionName 傳遞給 get_live_flow_run_action_outputs。 省略它會擷取所有頂層動作。對於 foreach 內的動作，傳遞 actionName 而不傳遞 iterationIndex 可能會回傳該動作的每次重複結果。
3. 在同一個工作階段中重複使用溢位檔案。 重新擷取同一個連接器的 Swagger 需要 30 秒以上，並會產生另一個溢位檔案 — 請快取路徑。
4. 不要直接對溢位檔案使用 grep 搜尋 JSON 鍵。 字串在檔案內是 JSON 跳脫的（\"OperationId\":），因此直接 grep "OperationId": 會找不到。請先解析，再進行過濾。
5. 向使用者摘要工具輸出。 對於流程清單，回顯 name + state + trigger；對於執行錯誤，回顯 actionName + status + code — 除非被要求，否則不要回傳原始 JSON。

# 良好 — 深入連接器 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"))

# 不良 — 將整個 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 — 連接器參考指南