fix(power-automate): coerce JSON string args for large flow definitions (#298)

* fix(power-automate): coerce JSON string args for large flow definitions

The MCP transport may serialize large object arguments (definition,
connectionRefs, body) to JSON strings before they reach the Zod validator.
Previously, z.record(z.unknown()) rejected these with "Expected object,
received string". This adds a z.preprocess() wrapper (jsonRecord) that
parses JSON strings back to objects before validation.

Fixes: create_flow, update_flow, preview_update, validate_flow,
preflight_flow, run_flow, invoke_operation, run_desktop_flow,
pick_or_create_connection, and dynamic resolver tools.

Source: https://github.com/matow_microsoft/flow-agent (packages/core/src/mcp/server.ts)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* feat(power-automate): add Microsoft Learn MCP as companion knowledge source

Adds the Learn MCP server (https://learn.microsoft.com/api/mcp) to the
plugin's .mcp.json. Updates AGENTS.md with hybrid lookup guidance:
- Tier 1: local references/*.md (fast, offline, plugin-specific)
- Tier 2: Learn MCP (live, comprehensive, up-to-date)

No auth required, free, public endpoint. Tested and validated against
7 key scenarios (expressions, connectors, errors, child flows, ALM,
article fetch, code samples) — all return rich relevant results.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Matt Townsend <matow+microsoft@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 3 people

plugins/power-automate/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "power-automate",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Build, edit, run, and debug Power Automate cloud flows via the FlowAgent MCP server — connection lifecycle, surgical edits, copy across environments, run management, and validated expressions.",
   "author": {
     "name": "Microsoft",

plugins/power-automate/.mcp.json

@@ -6,6 +6,10 @@
         "-e",
         "const p=require('node:path'),fs=require('node:fs');const r=process.env.PLUGIN_ROOT||process.env.CLAUDE_PLUGIN_ROOT||process.cwd();const src=process.env.PLUGIN_ROOT?'PLUGIN_ROOT':process.env.CLAUDE_PLUGIN_ROOT?'CLAUDE_PLUGIN_ROOT':'cwd';const mjs=p.resolve(r,'server','mcp.mjs');if(!fs.existsSync(mjs)){console.error('FlowAgent MCP not found at '+mjs+' (resolved via '+src+'='+r+'). Run /setup to fix.');process.exit(1);}(async()=>{try{await import(require('node:url').pathToFileURL(mjs).href)}catch(e){console.error(e);process.exit(1)}})();"
       ]
+    },
+    "microsoft-learn": {
+      "type": "http",
+      "url": "https://learn.microsoft.com/api/mcp"
     }
   }
 }

plugins/power-automate/.plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "power-automate",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Build, edit, run, and debug Power Automate cloud flows via the FlowAgent MCP server — connection lifecycle, surgical edits, copy across environments, run management, and validated expressions.",
   "author": {
     "name": "Microsoft",

plugins/power-automate/AGENTS.md

@@ -29,7 +29,39 @@ this plugin's `.mcp.json` / the install steps in `README.md`.
   connection patterns, error troubleshooting)
 - `.claude-plugin/plugin.json` + `.plugin/plugin.json` — Claude / Copilot
   manifests
-- `.mcp.json` — MCP server wiring
+- `.mcp.json` — MCP server wiring (FlowAgent + Microsoft Learn)
 
 The flow-definition rules, auth model, error reference, and known issues live in
 the [FlowAgent repo CLAUDE.md](https://github.com/matow_microsoft/flow-agent/blob/main/CLAUDE.md) and apply whether you call via MCP or shell.
+
+## Documentation lookup (hybrid pattern)
+
+This plugin uses a **two-tier knowledge architecture**:
+
+### Tier 1: Local references (fast, offline, plugin-specific)
+The `references/*.md` files are curated, plugin-specific docs covering:
+- Flow definition rules (`$authentication`, `$connections`, `OpenApiConnection`)
+- Connection reference patterns (`Embedded` vs `Invoker`, logical names)
+- Error-to-fix mapping (the exact API errors FlowAgent users hit)
+- CLI command reference
+
+**Always check `references/*.md` first** — they contain hard-won knowledge that
+Learn docs don't cover or bury across many articles.
+
+### Tier 2: Microsoft Learn MCP (live, comprehensive, up-to-date)
+The `.mcp.json` wires `microsoft-learn` (`https://learn.microsoft.com/api/mcp`)
+which provides:
+- `microsoft_docs_search` — search Learn docs by topic
+- `microsoft_docs_fetch` — fetch a complete article by URL
+- `microsoft_code_sample_search` — find code examples
+
+**Use Learn MCP when:**
+- The user asks about a connector or action you don't recognize
+- An expression function isn't in the local expression reference
+- You need the latest API changes or preview features
+- The user asks "how do I..." for a scenario not in references/
+- You need to verify whether a pattern is officially supported
+- Error troubleshooting needs more context than the local table provides
+
+**Scoping tip:** Prefix queries with "Power Automate" or "cloud flow" for
+relevance. For connector docs, use the connector name directly.