flowstudio-power-automate-mcp

通过 FlowStudio MCP 使用 Power Automate — 基础

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

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

要求： 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 解析器

TL;DR — 使用下面的核心 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 替换为 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>"}]

需要两次解析才能获得可用对象：

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\":），因此直接 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 — 连接器参考指南