[maui-labs docs] Document multi-agent targeting refusal in DevFlow CLI and MCP tools (PR #353)

[MauiBot]

Source PR

PR: dotnet/maui-labs#353
Title: fix(devflow): refuse ambiguous multi-agent targeting (CLI + MCP) — Fixes #343
Author: @jfversluis
Merged: 2026-07-08

---

Summary of Changes

Prior to this change, when multiple MAUI DevFlow agents were connected (i.e., multiple apps running simultaneously) and no agent port was specified, the CLI and MCP tools silently picked an arbitrary agent. This could cause commands to target the wrong app without any warning.

New behavior: When multiple agents are connected and no target is explicitly specified, all maui devflow subcommands and all MCP tools now refuse the operation with an actionable error listing the connected agents and their ports.

Error message format (CLI):

Multiple MAUI DevFlow agents are connected and no target was specified. Re-run with --agent-port (port) to choose which app to target.
  --agent-port 7000  FirstApp (iOS net10.0-ios)
  --agent-port 7001  SecondApp (MacCatalyst net10.0-maccatalyst)
```

**Error message format (MCP)**:
```
Multiple MAUI DevFlow agents are connected and no target was specified. Re-run with agentPort (port) to choose which app to target.
  agentPort 7000  FirstApp (iOS net10.0-ios)
  agentPort 7001  SecondApp (MacCatalyst net10.0-maccatalyst)

Additional fix: DevFlow commands that fail now return exit code 1 (previously they could return 0 even on failure), making them reliable for scripting.

Bypass: This refusal is skipped when:

• --agent-port (CLI) or agentPort (MCP) is explicitly provided
• A .mauidevflow config file specifies a port
• --agent-host targets a remote host (the broker only describes agents on the local machine)

---

Documentation Pages Affected

• docs/developer-tools/devflow/get-started.md (or equivalent agent connection page) — update agent connection/discovery section to document the multi-agent requirement
• docs/developer-tools/devflow/mcp.md (or equivalent MCP tools page) — update the agentPort parameter description to clarify it is required when multiple apps are running
• docs/developer-tools/cli/devflow.md (or equivalent CLI reference) — update --agent-port / -ap option description and add a "Multiple apps" section

---

Suggested Changes

1. CLI reference (docs/developer-tools/cli/devflow.md or similar)

In the Global options or Connection options table, update the description of --agent-port:

Before (approximately):
| --agent-port, -ap | Agent HTTP port (auto-discovered via broker, .mauidevflow, or default 9223) |

After:
| --agent-port, -ap | Agent HTTP port. Auto-discovered when only one app is running; required when multiple apps are connected. |

Add a new "Multiple apps running" section after the options table:

### Multiple apps running simultaneously

When more than one app with the DevFlow agent is running at the same time, DevFlow cannot
determine which app to target. In this case, commands fail with a message listing all
connected agents:

```
Multiple MAUI DevFlow agents are connected and no target was specified. Re-run with --agent-port (port) to choose which app to target.
  --agent-port 7000  MyApp.iOS (iOS net10.0-ios)
  --agent-port 7001  MyApp.Mac (MacCatalyst net10.0-maccatalyst)

Resolve this by passing --agent-port with the port of the app you want to target:

maui devflow screenshot --agent-port 7000

Alternatively, create a .mauidevflow file in your project root with the target port:

{ "agentPort": 7000 }
```

2. MCP tools reference (docs/developer-tools/devflow/mcp.md or similar)

Update the agentPort parameter description in the tool parameter tables and/or the overview section:

Add a note (e.g., in a callout/note block) near the agentPort parameter description:

> [!IMPORTANT]
> The `agentPort` parameter is **required** when multiple apps are running simultaneously.
> When only one app is running the parameter is optional and the agent is discovered
> automatically. If you omit `agentPort` and multiple agents are connected, the tool
> returns an error listing the available agents and their ports.

Update the agentPort column in the parameter table for all tools from:

Agent HTTP port (optional if only one agent connected)

to:

Agent HTTP port. Optional when only one app is running; required when multiple apps are connected simultaneously.

3. Exit code note (CLI reference or scripting guide)

If there is a scripting / automation page, add a note:

> [!NOTE]
> DevFlow commands exit with code `1` on failure. You can use this in shell scripts
> to detect errors:
>
> ```shell
> maui devflow screenshot --output screen.png || echo "Screenshot failed"
> ```

Generated by PR Documentation Check for issue #353 · ◷