# pa-flow-mcp

Free, open MCP server to **edit Power Automate cloud flows live** from GitHub Copilot, Codex, or Claude Code — like Power Apps external tools, but for flows. Open a flow in the browser, paste its URL, and your AI assistant reads/writes the flow definition, manages connectors, and syncs changes back.

## Why
No official "external tools" exist for Power Automate. This MCP gives any AI assistant authenticated access to the same APIs the Designer uses. Free for everyone.

## Features
- **Plugin for Copilot & Claude Code**: ships skills (`/configure-pa-flow-mcp`, `/edit-flow`, `/add-connector-action`, `/manage-runs`, `/report-issue`) and a `flow-builder` subagent — same plugin shape as Microsoft's Power Platform skills.
- **Auth**: interactive browser login (loopback port), Azure CLI public client, token cached. No az CLI, no app registration.
- **1250+ connectors**: discover live (`list_connectors`) + curated catalog (SharePoint, Dataverse, SQL, Outlook, Excel, Teams).
- **No connection-reference errors**: `add_connector_action` wires `connectionReferences` + `parameters.$connections` automatically.
- **Local ↔ flow sync**: pull to `.pa-flow/<id>.json`, edit, validate, push.
- **Setup wizard**: URL + login + assistant (Copilot / Codex / Claude).
- **Clear errors** on no access / not found.

## Requirements (end user)
- **Node.js 18+** (`node -v`).
- A **Power Automate license** + access to the flow you want to edit.
- **GitHub Copilot CLI/Chat** or **Claude Code** (latest).
- A browser for one-time sign-in. No admin rights, no Azure CLI.

## Install

### A. As a plugin (recommended)
Clone and build once, then register the local marketplace in your AI tool.
```bash
git clone https://github.com/Mr-M-tastic/Power-Automate-MCP && cd pa-flow-mcp
npm install && npm run build
```
**Claude Code** — from the repo folder:
```shell
/plugin marketplace add .
/plugin install power-automate@pa-flow
```
The plugin auto-registers the `pa-flow` MCP server (`.mcp.json` uses `${CLAUDE_PLUGIN_ROOT}`) and loads the skills. Then run `/configure-pa-flow-mcp` or just say *"edit my flow"*.

**GitHub Copilot** — copy [.vscode/mcp.json](.vscode/mcp.json) into your project (already provided). Reload VS Code; the `pa-flow` tools and the skills under `skills/` are picked up automatically.

### B. Manual MCP config
If you don't use the plugin loader, point your assistant at the built server directly:
```json
{ "servers": { "pa-flow": { "command": "node", "args": ["dist/index.js"] } } }
```
Claude Code / Codex use the `mcpServers` key and an absolute path to `dist/index.js`. `AGENTS.md` / `CLAUDE.md` are auto-read for usage.

## Run it against your flow (step by step)
You don't run commands by hand — you chat with your assistant and it calls the tools.

1. **Open your flow** in Power Automate and copy the URL from the address bar:
   `https://make.powerautomate.com/environments/<env>/flows/<flowId>`
2. **Start a session** — tell the assistant: *"Configure session for `<paste URL>`"* → runs `configure_session`.
3. **Pull the flow** — *"Pull the flow"* → `sync_pull`. **First time a browser opens — sign in with your work account.** The token is cached, so login is one-time. A working copy is written to `.pa-flow/<flowId>.json`.
4. **Edit** — either ask in plain English (*"add a SharePoint Get items action"* → `add_connector_action`, which auto-wires the connection) or edit `.pa-flow/<flowId>.json` directly.
5. **Validate & push** — *"validate then push"* → `validate_flow` then `sync_push`.
6. **Refresh the browser tab** — your edits are now live in the Designer.

### What gets created on your machine
- Working copy: `.pa-flow/<flowId>.json` (safe to hand-edit)
- Cached login: `~/.pa-flow-mcp-token.json`

### Notes
- No Azure CLI, admin rights, or app registration needed.
- If a connector says *"create connection in maker portal"*, make it once in Power Automate, then retry the push.

## Optional env vars
`PA_CLIENT_ID`, `PA_PORT`, `PA_API_BASE`, `PA_API_VERSION` — override defaults if needed.

## Skills (slash commands)
| Command | Description |
|---------|-------------|
| `/configure-pa-flow-mcp` | Connect to a flow from its Designer URL, sign in, pull locally |
| `/edit-flow` | Pull → edit (action/condition/trigger) → validate → push |
| `/add-connector-action` | Add a SharePoint/Dataverse/SQL/Outlook/Excel/Teams (or any) connector step |
| `/manage-runs` | Turn flows on/off, list runs, resubmit, cancel |
| `/report-issue` | Open a prefilled GitHub issue with diagnostics |

Reference docs the agents read live in [references/](references/) (`FlowAuthoring.md`, `Connectors.md`); the `flow-builder` subagent in [agents/](agents/) applies one approved change at a time.

## Tools
`configure_session, setup_wizard, list_environments, list_flows, get_flow, update_flow, turn_on/off_flow, list_runs, resubmit_run, cancel_run, list_connectors, list_connections, ensure_connection, add_connector_action, sync_pull, validate_flow, sync_push`

## Related Microsoft tooling
This plugin follows the conventions of Microsoft's [power-platform-skills](https://github.com/microsoft/power-platform-skills) (canvas-apps, model-apps, power-pages). It focuses on **cloud flows**; for solution ALM, environments, and Dataverse use the [Power Platform CLI (PAC)](https://learn.microsoft.com/power-platform/developer/cli/introduction) and the [Power Platform Tools VS Code extension](https://learn.microsoft.com/power-platform/developer/howto/install-vs-code-extension).

## License
MIT