Update FlowStudio Power Automate skills (#1664)

* feat(flowstudio): align Power Automate skills with MCP server v1.1.6 Foundation skill (flowstudio-power-automate-mcp) rewritten to use the server's new tool_search and list_skills meta-tools (v1.1.5+) for discovery instead of cataloging every tool by hand. Cut from 519 to 295 lines. New "Which Skill to Use When" intent-keyed decision tree points at the four specialized skills. Build/debug/governance/monitoring updated for use-case framing. Tools that genuinely cross tiers (e.g. debug skill borrowing get_store_flow_summary) are correct when the workflow needs them — the split between skills is by use-case intent, not by tool partition. Build skill: new Step 3a Resolving Dynamic Connector Values covers get_live_dynamic_options outer-parameter auto-bridge (v1.1.6+) and the AadGraph user-picker fallback via shared_office365users.SearchUserV2 (replaces broken builtInOperation:AadGraph.GetUsers). Debug skill: Outlook user-picker failure note pointing at the fallback. Monitoring skill description disambiguates from the server's monitor-flow tool bundle (runtime control of a single flow) — this skill is tenant-wide health analytics over the cached store. All 5 skills validate via npm run skill:validate; line endings LF only; codespell clean; auto-regenerated docs/README.skills.md included. * fix(flowstudio): remove deprecated tool references The v1.1.5 MCP server release marked 5 tools [DEPRECATED] but the previous alignment commit missed them. Replacements per server source: - get_live_flow_http_schema → read trigger.inputs.schema from get_live_flow - get_live_flow_trigger_url → read trigger.metadata.callbackUrl from get_live_flow - get_store_flow_trigger_url → get_store_flow.triggerUrl field - get_store_flow_errors → get_store_flow_runs(status=["Failed"]) - set_store_flow_state → set_live_flow_state Touches build, debug, governance, monitoring SKILL.md and the foundation skill's tool-reference.md. Remaining mentions of the deprecated names are intentional — they live in deprecation notices naming the obsolete wrapper alongside its replacement. * Update FlowStudio Power Automate skills * Cover latest FlowStudio MCP actions * Trim FlowStudio Power Automate skills * Number FlowStudio build workflow steps
2026-05-15 19:21:45 +00:00 · 2026-05-11 11:28:29 +10:00
parent cf6bbba6fc
commit e67c66c441
17 changed files with 730 additions and 775 deletions
@@ -9,13 +9,6 @@ description: >-
  fix a broken Power Automate flow, diagnose a timeout, trace a DynamicOperationRequestFailure,
  check connector auth errors, read error details from a run, or troubleshoot
  expression failures. Requires a FlowStudio MCP subscription — see https://mcp.flowstudio.app
-metadata:
-  openclaw:
-    requires:
-      env:
-        - FLOWSTUDIO_MCP_TOKEN
-    primaryEnv: FLOWSTUDIO_MCP_TOKEN
-    homepage: https://mcp.flowstudio.app
 ---

 # Power Automate Debugging with FlowStudio MCP
@@ -28,18 +21,19 @@ cloud flows through the FlowStudio MCP server.
 > [Null value crashes child flow](https://github.com/ninihen1/power-automate-mcp-skills/blob/main/examples/null-child-flow.md)

 **Prerequisite**: A FlowStudio MCP server must be reachable with a valid JWT.
-See the `power-automate-mcp` skill for connection setup.  
+See the `flowstudio-power-automate-mcp` skill for connection setup.
 Subscribe at https://mcp.flowstudio.app

 ---

 ## Source of Truth

-> **Always call `tools/list` first** to confirm available tool names and their
-> parameter schemas. Tool names and parameters may change between server versions.
+> **Always call `list_skills` / `tool_search` first** to confirm available tool
+> names and parameter schemas. Tool names and parameters may change between
+> server versions.
 > This skill covers response shapes, behavioral notes, and diagnostic patterns —
-> things `tools/list` cannot tell you. If this document disagrees with `tools/list`
-> or a real API response, the API wins.
+> things tool schemas cannot tell you. If this document disagrees with
+> `tool_search` or a real API response, the API wins.

 ---

@@ -161,6 +155,8 @@ detail = mcp("get_live_flow_run_action_outputs",
    runName=RUN_ID,
    actionName=root_action)

+if len(detail) > 1:
+    print(f"{root_action} returned {len(detail)} repetitions; inspect iteration indexes")
 out = detail[0] if detail else {}
 print(f"Action: {out.get('actionName')}")
 print(f"Status: {out.get('status')}")
@@ -198,6 +194,39 @@ if out.get("inputs"):
 | `InvalidTemplate` | The exact expression that failed and the null/wrong-type value |
 | `BadRequest` | The request body that was sent and why the server rejected it |

+### Foreach iterations
+
+When `actionName` refers to an action inside a foreach, the output tool can
+return every repetition of that action. Each item may include
+`repetitionIndexes` with the loop name and zero-based `itemIndex`. Use
+`iterationIndex` to inspect one iteration after you find the suspicious item:
+
+```python
+all_reps = mcp("get_live_flow_run_action_outputs",
+    environmentName=ENV,
+    flowName=FLOW_ID,
+    runName=RUN_ID,
+    actionName=root_action)
+
+for rep in all_reps[:10]:
+    print(rep.get("repetitionIndexes"), rep.get("status"), rep.get("error"))
+
+one_rep = mcp("get_live_flow_run_action_outputs",
+    environmentName=ENV,
+    flowName=FLOW_ID,
+    runName=RUN_ID,
+    actionName=root_action,
+    iterationIndex=3)
+```
+
+### Evidence Compose Bookends
+
+For uncertain connector work, add a `Compose_*_Request` before the risky action
+and a `Compose_*_Result` after it, with the result action allowed on both
+`Succeeded` and `Failed`. This gives future debugging a clean payload snapshot
+without requiring another deploy. Do not include secrets or long binary payloads
+in these bookends.
+
 ### Example: HTTP action returning 500

 ```
@@ -259,10 +288,9 @@ for action_name in [root_action, "Compose_WeekEnd", "HTTP_Get_Data"]:
 > ⚠️ Output payloads from array-processing actions can be very large.
 > Always slice (e.g. `[:500]`) before printing.

-> **Tip**: Omit `actionName` to get ALL actions in a single call.
-> This returns every action's inputs/outputs — useful when you're not sure
-> which upstream action produced the bad data. But use 120s+ timeout as
-> the response can be very large.
+> **Tip**: Omit `actionName` to list top-level actions when you're not sure
+> which action produced the bad data. Once you pick an action inside a foreach,
+> pass `iterationIndex` to avoid pulling every repetition into context.

 ---

@@ -317,9 +345,12 @@ is broken at the PA listEnum layer and always returns
 modifies an Outlook action via `update_live_flow` and tries to resolve a user
 through dynamic options. **Don't fix it by retrying AadGraph** — switch to
 `shared_office365users.SearchUserV2` instead (returns the same AAD user shape).
-See the `power-automate-build` skill, **Step 3a — Resolving Dynamic Connector
-Values**, for the working pattern. `describe_live_connector` (v1.1.6+) returns
-this fallback as a structured `fallback` field on the affected parameter.
+Use `describe_live_connector` to confirm whether the affected parameter exposes
+a structured `fallback`, then call `get_live_dynamic_options` against
+`shared_office365users.SearchUserV2` instead of the broken AadGraph operation.
+For dynamic field schemas rather than dropdown options, use
+`get_live_dynamic_properties` with the metadata returned by
+`describe_live_connector`.

 ---

@@ -389,11 +420,17 @@ For flows with a `Request` (HTTP) trigger, use `trigger_live_flow` when you
 need to send a **different** payload than the original run:

 ```python
-# First inspect what the trigger expects
-schema = mcp("get_live_flow_http_schema",
-    environmentName=ENV, flowName=FLOW_ID)
-print("Expected body schema:", schema.get("requestSchema"))
-print("Response schemas:", schema.get("responseSchemas"))
+# First inspect what the trigger expects — read directly from the flow definition
+defn = mcp("get_live_flow", environmentName=ENV, flowName=FLOW_ID)
+triggers = defn["properties"]["definition"]["triggers"]
+manual = next(iter(triggers.values()))   # usually the only trigger on HTTP flows
+request_schema = manual.get("inputs", {}).get("schema")
+print("Expected body schema:", request_schema)
+
+# Response schemas live on Response action(s) in the actions block
+for name, act in defn["properties"]["definition"]["actions"].items():
+    if act.get("type") == "Response":
+        print(f"Response {name}:", act.get("inputs", {}).get("schema"))

 # Trigger with a test payload
 result = mcp("trigger_live_flow",
@@ -433,5 +470,5 @@ print(f"Status: {result['responseStatus']}, Body: {result.get('responseBody')}")

 ## Related Skills

- `power-automate-mcp` — Foundation skill: connection setup, MCP helper, tool discovery
- `power-automate-build` — Build and deploy new flows
+- `flowstudio-power-automate-mcp` — Foundation skill: connection setup, MCP helper, tool discovery
+- `flowstudio-power-automate-build` — Build and deploy new flows
@@ -149,6 +149,24 @@ iterations in parallel, causing write conflicts or undefined ordering.

 ---

+### Foreach Parent Failed After Handled Inner Failure
+
+**Symptom**: Inner actions have failure handlers, but the parent `Foreach` still
+shows `Failed`, and downstream actions such as `Response` are skipped.
+
+**Root cause**: A handled child failure can still mark the loop container as
+failed. Downstream `runAfter` that only accepts `Succeeded` will not run.
+
+**Diagnosis**: Inspect the parent foreach with `get_live_flow_run_error`, then
+inspect child action outputs for the iteration that failed.
+
+**Fix**: If partial success is acceptable, allow the downstream join/response to
+run after `Succeeded` and `Failed`, and include an explicit error summary in the
+payload. If the loop must be all-or-nothing, wrap risky inner work in a Scope and
+handle success/failure at the Scope boundary.
+
+---
+
 ## Update / Deploy Errors

 ### `update_live_flow` Returns No-Op
@@ -186,3 +204,20 @@ values override new_data for matching records.
 Before: @sort(union(outputs('Old_Array'), body('New_Array')), 'Date')
 After:  @sort(union(body('New_Array'), outputs('Old_Array')), 'Date')
 ```
+
+---
+
+### Null Cascade in Filter Array / Query
+
+**Symptom**: A lookup/filter step returns the wrong record or a later expression
+fails on null even though the filter action itself succeeded.
+
+**Root cause**: The lookup key is null or empty. A condition such as
+`equals(item()?['Email'], outputs('Lookup_Email'))` can accidentally match rows
+where both sides are null, or can pass an empty array downstream.
+
+**Diagnosis**: Inspect the action that creates the lookup key and the filter
+output length. Confirm the key is non-empty before trusting the filter result.
+
+**Fix**: Add a non-empty guard before the filter, normalize comparison values
+with `trim()`/`toLower()`, and branch explicitly when no match is found.
@@ -27,6 +27,9 @@ Flow is failing
 │   ├── error.code = "ActionFailed" + message mentions HTTP
 │   │   └── ► See: HTTP Action Workflow below
 │   │
+│   ├── parent action is Foreach / Apply to each
+│   │   └── ► Inspect child actions; handled child failures can still fail the parent
+│   │
 │   └── Unknown / generic error
 │       └── ► Walk actions backwards (Step B below)
 │
@@ -113,6 +116,9 @@ Flow succeeds but output data is wrong
 │   ├── Check foreach condition — filter may be too strict
 │   └── Check if parallel foreach caused race condition (add Sequential)
 │
+├── Filter/Query result unexpectedly matches nulls or returns empty
+│   └── Guard lookup keys before the filter; do not compare null-to-null
+│
 └── Date/time values wrong timezone
    └── Use convertTimeZone() — utcNow() is always UTC
 ```