flowstudio-power-automate-mcp

通过 FlowStudio MCP 使用 Power Automate — 基础

此技能是底层管道层。它为 AI Agent 提供了一种可靠方式，用于与 FlowStudio MCP 服务通信、发现可用工具并干净地处理响应。实际的工作流叙述位于四个专门技能中，它们都构建在此技能之上。

真实调试示例：子流中的表达式错误 | 数据录入问题，而非流缺陷 | 空值导致子流崩溃

需要： 一个 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 以及运行错误工具 — 它们的区别在于方向（正向 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 确认 当前结构。

---

Agent 如何发现工具

FlowStudio MCP 服务（v1.1.5+）暴露了两个不计费的元工具，让 Agent 只加载与当前任务相关的工具。请优先使用这些工具，而不是 tools/list（它会一次性加载全部 30+ 个 schema）或猜测工具名称。

元工具	何时调用
list_skills	冷启动时——查看可用的工具包（build-flow、create-flow、debug-flow、monitor-flow、discover、governance）并选择一个
tool_search 配合 query: "skill:<name>"	加载某个工具包的完整 schema 集合（例如 skill:debug-flow）
tool_search 配合 query: "select:tool1,tool2"	按名称加载特定工具（例如跨工具包链式调用时）
tool_search 配合 query: "<keywords>"	当用户请求不明确时进行自由文本搜索（例如 "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

本技能系列中的所有示例都使用 Python 配合 urllib.request（标准库——无需 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	可行但脆弱	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 → token 缺失、过期或格式错误。从 mcp.flowstudio.app 获取新的 JWT。
• HTTP 400 → JSON-RPC 负载格式错误。检查 Content-Type: application/json 和请求体结构。
• MCP error: {"code": -32602, ...} → 工具参数错误或缺失。调用 tool_search 并传入 select:<toolname> 以确认 schema。

---

核心 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。

---

验证连接

一个 3 行冒烟测试，用于确认 token、端点和助手都能正常工作：

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 工具响应大到足以撑爆 Agent 的上下文窗口：

工具	典型大小	原因
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	数百条流记录

当 harness 溢出到文件时

Agent harness（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. 始终向 get_live_flow_run_action_outputs 传入 actionName。 省略它会抓取所有顶层操作。对于 foreach 内的操作，传入 actionName 而不传 iterationIndex 可能会返回该操作的每一次重复。
3. 在会话内复用溢出文件。 重新抓取同一个连接器 swagger 要花 30 多秒，还会再产生一次溢出——请缓存该路径。
4. 不要直接在溢出文件中 grep JSON 键。 文件内的字符串是 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
Token 格式	纯 JWT——不要剥离、修改或添加前缀
超时	对 get_live_flow_run_action_outputs（大输出）使用 ≥ 120 s
环境名称	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——连接器参考指南