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

---

何时使用哪个技能

技能按使用场景意图组织，而不是按调用的工具组织。 多个技能会复用相同的底层工具 — 根据用户想要完成的事情选择技能。

用户想要……	加载此技能
创建或更改流程（构建新流程、修改现有流程、修复错误、部署）	power-automate-build
诊断流程失败的原因（分析失败运行的根本原因）	power-automate-debug
查看整个租户范围内的流程运行状况、失败率和资产清单	power-automate-monitoring (Pro+)
标记、审计、分类、评分或停用流程	power-automate-governance (Pro+)
仅需连接、设置身份验证、编写辅助程序、解析响应	此技能（基础）

工具相同，侧重点不同。power-automate-build 和 power-automate-debug 都会调用 update_live_flow、get_live_flow 和运行错误工具 — 两者在方向（向前与向后）和意图（编排与诊断）上有所不同。power-automate-monitoring 和 power-automate-governance 都会调用 Store 工具 — 两者在受众（运维与合规）和结果（读取运行状况与写入元数据）上有所不同。不要试图记住“哪些工具属于哪个技能”；应根据用户正在做的事情选择技能。

---

信息来源的优先级

优先级	来源	涵盖内容
1	实际 API 响应	始终以服务器实际返回的内容为准
2	tool_search / list_skills	权威的工具架构、参数名称、类型和必填标记
3	SKILL 文档和参考文件	工作流说明、响应结构、非显而易见的行为

如果文档与实际 API 响应不一致，以 API 为准。此技能（或其他任何技能）中的工具架构可能落后于服务器 — 调用 tool_search，确认当前结构后，再调用你近期未使用过的工具。

---

Agent 如何发现工具

FlowStudio MCP 服务（v1.1.5+）提供两个不计费的元工具，让 Agent 仅加载与当前任务相关的工具。优先使用这些工具，而不是使用 tools/list（一次性加载全部 30 多个架构）或猜测工具名称。

元工具	调用时机
list_skills	冷启动时——查看可用的工具包（build-flow、create-flow、debug-flow、monitor-flow、discover、governance）并选择一个
使用 query: "skill:<name>" 调用 tool_search	加载某个工具包的完整架构集（例如 skill:debug-flow）
使用 query: "select:tool1,tool2" 调用 tool_search	按名称加载特定工具（例如需要跨工具包串联调用时）
使用 query: "<keywords>" 调用 tool_search	用户请求含糊时进行自由文本搜索（例如 "cancel run"）

服务端的 tool_search 工具包有意设置得比此技能系列更精简——它们是针对每种意图挑选最可能需要的工具所组成的入门包。工作流技能（例如 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 进行 Shell 转义容易出错；没有原生 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 工具响应大到足以撑爆 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——连接器参考指南