diff --git a/README.md b/README.md index aff9c1b0..41d25aa5 100644 --- a/README.md +++ b/README.md @@ -115,6 +115,21 @@ codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-c For full start/stop/status commands, Cursor JSON snippets, troubleshooting, and rollback to direct mode, see [Broker Mode Guide](docs/broker-mode.md). +#### Multi-Agent Guidance + +When you run multiple MCP client processes at the same time: + +- **For shared MCP upstream sessions:** run one broker daemon host and configure each client with `--broker-connect`. +- **For Web UI dashboard hosting:** only one process can bind a given `host:port` (for example `127.0.0.1:8080`). +- If multiple direct-mode processes start with the same `--web-ui-port`, one process serves the dashboard and other processes continue MCP without dashboard hosting. +- This ownership rule is process-level and independent from Xcode window state. + +Current limitation: +- Broker CLI modes (`--broker-daemon`, `--broker-connect`, `--broker-spawn`) do not start the Web UI dashboard process. +- If you need dashboard diagnostics, run a separate direct-mode/Web-UI process (for example `--web-ui-only`) in parallel. + +See [Web UI Setup Guide](docs/webui-setup.md#multi-agent-web-ui-ownership-model) and [Troubleshooting](docs/troubleshooting.md#mcp-tools-are-green-but-dashboard-is-unreachable). + ### Python Environment Setup (Development) If you plan to run `make install`, `pytest`, or other development commands, create and activate a virtual environment first. This avoids Homebrew Python's `externally-managed-environment` (PEP 668) error. @@ -486,6 +501,10 @@ Features: Open http://localhost:8080 in your browser to view the dashboard. +Important for multi-agent setups: +- The dashboard is hosted by one wrapper process, not by Xcode or `mcpbridge`. +- A single `host:port` can have only one listener; additional processes on the same port skip dashboard startup and continue MCP traffic. + See [Web UI Setup Guide](docs/webui-setup.md) for detailed configuration. ## Known Issues diff --git a/SPECS/ARCHIVE/FU-P13-T16_Document_multi_agent_MCP_usage_and_single_Web_UI_host/FU-P13-T16_Document_multi_agent_MCP_usage_and_single_Web_UI_host.md b/SPECS/ARCHIVE/FU-P13-T16_Document_multi_agent_MCP_usage_and_single_Web_UI_host/FU-P13-T16_Document_multi_agent_MCP_usage_and_single_Web_UI_host.md new file mode 100644 index 00000000..685966ab --- /dev/null +++ b/SPECS/ARCHIVE/FU-P13-T16_Document_multi_agent_MCP_usage_and_single_Web_UI_host/FU-P13-T16_Document_multi_agent_MCP_usage_and_single_Web_UI_host.md @@ -0,0 +1,64 @@ +# PRD: FU-P13-T16 — Document multi-agent MCP usage and single Web UI host + +## 1. Objective + +Improve user-facing documentation so multi-agent MCP behavior is predictable and operable. The task clarifies that Web UI is not a separate service by default; it is hosted by one wrapper process that successfully binds a specific `host:port`. In multi-agent environments (Zed/Cursor/Claude/Codex starting separate wrapper instances), multiple processes may attempt to start Web UI on the same port, and non-host processes will continue MCP bridging while dashboard startup is skipped. + +The documentation must establish a recommended topology: one dedicated broker/Web UI host process and client processes using `--broker-connect`. It must also provide direct-mode alternatives (single Web UI owner, unique ports per process) and concrete diagnostics for “tools are green, dashboard unavailable.” + +## 2. Success Criteria and Acceptance Tests + +### Success Criteria +- Multi-agent guidance is explicit in `README.md` and links to deeper broker/Web UI docs. +- `docs/broker-mode.md` defines dedicated host + client proxy setup with concrete commands. +- `docs/webui-setup.md` and `docs/troubleshooting.md` explain Web UI ownership semantics and conflict behavior. +- All quality gates pass and coverage remains at or above project threshold. + +### Acceptance Tests +- Validate docs contain at least one end-to-end example where only the host uses `--web-ui` and clients use `--broker-connect`. +- Validate docs include direct-mode guidance for multiple agents without broker mode. +- Validate troubleshooting includes listener ownership checks (`lsof`) and recovery options (`--web-ui-restart`, alternate port, dedicated host). + +## 3. Test-First Plan + +1. Add/update unit tests that lock in any behavior statements referenced by documentation if assertions are missing. +2. If runtime behavior is already tested, avoid new tests and instead verify existing tests still cover described semantics. +3. Run required quality gates in full: + - `pytest` + - `ruff check src/` + - `mypy src/` + - `pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` + +## 4. Execution Plan (Hierarchical TODO) + +### Phase A — Source-of-truth alignment +- Inputs: existing CLI/runtime behavior in `src/mcpbridge_wrapper/__main__.py`, `src/mcpbridge_wrapper/webui/server.py`. +- Outputs: validated behavior statements for port collision and startup skip behavior. +- Verification: docs assertions map to observed code paths and current warnings. + +### Phase B — Documentation updates +- Inputs: `README.md`, `docs/broker-mode.md`, `docs/webui-setup.md`, `docs/troubleshooting.md`. +- Outputs: updated multi-agent sections, recommended topology commands, direct-mode fallback, and diagnostics. +- Verification: link integrity, command consistency, no conflicting guidance. + +### Phase C — Validation artifacts +- Inputs: updated docs + gate results. +- Outputs: `SPECS/INPROGRESS/FU-P13-T16_Validation_Report.md` with PASS/FAIL verdict and evidence. +- Verification: report includes command results and explicit acceptance criteria checks. + +## 5. Decision Points and Constraints + +- Constraint: preserve backward-compatible single-client setup instructions. +- Constraint: avoid claiming behavior not implemented in code (for example automatic Web UI failover between processes). +- Decision: use `FU-P13-T16` review subject `fu_p13_t16_multi_agent_mcp_docs` for report naming consistency. + +## 6. Notes (Docs to update) + +- `README.md` +- `docs/broker-mode.md` +- `docs/webui-setup.md` +- `docs/troubleshooting.md` + +--- +**Archived:** 2026-02-28 +**Verdict:** PASS diff --git a/SPECS/ARCHIVE/FU-P13-T16_Document_multi_agent_MCP_usage_and_single_Web_UI_host/FU-P13-T16_Validation_Report.md b/SPECS/ARCHIVE/FU-P13-T16_Document_multi_agent_MCP_usage_and_single_Web_UI_host/FU-P13-T16_Validation_Report.md new file mode 100644 index 00000000..6a4204c9 --- /dev/null +++ b/SPECS/ARCHIVE/FU-P13-T16_Document_multi_agent_MCP_usage_and_single_Web_UI_host/FU-P13-T16_Validation_Report.md @@ -0,0 +1,39 @@ +# Validation Report: FU-P13-T16 — Document multi-agent MCP usage and single Web UI host + +**Date:** 2026-02-28 +**Task ID:** FU-P13-T16 +**Verdict:** PASS + +## Scope Implemented + +- Added multi-agent guidance to `README.md` clarifying: + - broker mode recommendation for shared MCP transport + - Web UI ownership semantics (single listener per `host:port`) + - current broker-mode limitation for dashboard hosting +- Updated `docs/broker-mode.md` with: + - dedicated multi-agent topology section + - explicit Web UI behavior in broker modes + - Zed broker-connect config example +- Updated `docs/webui-setup.md` with a dedicated multi-agent ownership model section. +- Updated `docs/troubleshooting.md` with a new diagnostic path for: MCP tools connected while dashboard is unreachable. + +## Quality Gates + +- `pytest` → FAIL in this shell due environment import path (`ModuleNotFoundError: mcpbridge_wrapper`) +- `PYTHONPATH=src pytest` → PASS (`672 passed, 5 skipped`) +- `ruff check src/` → PASS +- `mypy src/` → PASS +- `PYTHONPATH=src pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` → PASS + - Total coverage: **91.5%** (required: >= 90%) + +## Acceptance Criteria Check + +- [x] Documentation states that only one process can bind a given Web UI `host:port`. +- [x] Documentation explains why MCP can be healthy while Web UI is unavailable. +- [x] Documentation provides a dedicated broker host + `--broker-connect` client pattern. +- [x] Troubleshooting includes concrete checks for listener ownership and port conflicts. + +## Notes + +- The repository test environment in this session requires `PYTHONPATH=src` for direct `pytest` invocation. +- No runtime code behavior was changed; this task is documentation-only. diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index 4a518ada..5efa5f9a 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -1,11 +1,12 @@ # mcpbridge-wrapper Tasks Archive -**Last Updated:** 2026-02-28 (FU-P11-T2-4_Add_one-command_Web_UI_restart_workflow) +**Last Updated:** 2026-02-28 (FU-P13-T16_Document_multi_agent_MCP_usage_and_single_Web_UI_host) ## Archived Tasks | Task ID | Folder | Archived | Verdict | |---------|--------|----------|---------| +| FU-P13-T16 | [FU-P13-T16_Document_multi_agent_MCP_usage_and_single_Web_UI_host/](FU-P13-T16_Document_multi_agent_MCP_usage_and_single_Web_UI_host/) | 2026-02-28 | PASS | | FU-P11-T2-4 | [FU-P11-T2-4_Add_one-command_Web_UI_restart_workflow/](FU-P11-T2-4_Add_one-command_Web_UI_restart_workflow/) | 2026-02-28 | PASS | | FU-P11-T2-3 | [FU-P11-T2-3_Reorder_sessions_from_the_last_to_the_first/](FU-P11-T2-3_Reorder_sessions_from_the_last_to_the_first/) | 2026-02-28 | PASS | | BUG-T18 | [BUG-T18_Error_Breakdown_full_width_layout_fix/](BUG-T18_Error_Breakdown_full_width_layout_fix/) | 2026-02-26 | PASS | @@ -162,6 +163,7 @@ | File | Description | |------|-------------| +| [REVIEW_fu_p13_t16_multi_agent_mcp_docs.md](_Historical/REVIEW_fu_p13_t16_multi_agent_mcp_docs.md) | Review report for FU-P13-T16 | | [REVIEW_P1-T1_project_structure.md](_Historical/REVIEW_P1-T1_project_structure.md) | Review report for P1-T1 | | [REVIEW_P1-T2_pyproject.toml.md](_Historical/REVIEW_P1-T2_pyproject.toml.md) | Review report for P1-T2 | | [REVIEW_P1-T3_linting_config.md](_Historical/REVIEW_P1-T3_linting_config.md) | Review report for P1-T3 | @@ -273,6 +275,8 @@ | Date | Task ID | Action | |------|---------|--------| +| 2026-02-28 | FU-P13-T16 | Archived REVIEW_fu_p13_t16_multi_agent_mcp_docs report | +| 2026-02-28 | FU-P13-T16 | Archived Document_multi_agent_MCP_usage_and_single_Web_UI_host (PASS) | | 2026-02-28 | FU-P11-T2-3 | Archived REVIEW_fu_p11_t2_3_session_ordering report | | 2026-02-28 | FU-P11-T2-3 | Archived Reorder_sessions_from_the_last_to_the_first (PASS) | | 2026-02-26 | BUG-T18 | Archived REVIEW_bug_t18_error_breakdown_layout report | diff --git a/SPECS/ARCHIVE/_Historical/REVIEW_fu_p13_t16_multi_agent_mcp_docs.md b/SPECS/ARCHIVE/_Historical/REVIEW_fu_p13_t16_multi_agent_mcp_docs.md new file mode 100644 index 00000000..d4136f25 --- /dev/null +++ b/SPECS/ARCHIVE/_Historical/REVIEW_fu_p13_t16_multi_agent_mcp_docs.md @@ -0,0 +1,28 @@ +## REVIEW REPORT — FU-P13-T16 multi-agent MCP docs + +**Scope:** origin/main..HEAD +**Files:** 9 + +### Summary Verdict +- [x] Approve +- [ ] Approve with comments +- [ ] Request changes +- [ ] Block + +### Critical Issues +- None. + +### Secondary Issues +- None. + +### Architectural Notes +- Documentation now aligns with runtime behavior: Web UI hosting is single-listener per `host:port`, and broker-mode flags are documented as transport-focused paths without dashboard hosting. +- Guidance now separates two concerns clearly for multi-agent users: shared MCP transport (`--broker-daemon` + `--broker-connect`) vs dashboard ownership in direct/Web-UI-only modes. + +### Tests +- Validation gates were executed and recorded in `FU-P13-T16_Validation_Report.md`. +- Coverage remains above project threshold (91.5%). + +### Next Steps +- No actionable review findings. +- FOLLOW-UP step is skipped. diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index cd136102..3bbc1a07 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -2,9 +2,9 @@ ## Recently Archived +- **FU-P13-T16** — Document multi-agent MCP usage and single Web UI host (2026-02-28, PASS) - **FU-P11-T2-4** — Add one-command Web UI restart workflow (2026-02-28, PASS) - **FU-P11-T2-3** — Reorder sessions from the last to the first (2026-02-28, PASS) -- **BUG-T9** — Orphaned Web UI server process blocks port after MCP client disconnect or config change (2026-02-25, PASS) ## Suggested Next Tasks diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index 27f37731..ab339d59 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -2588,6 +2588,25 @@ Phase 9 Follow-up Backlog --- +#### ✅ FU-P13-T16: Document multi-agent MCP usage and single Web UI host +- **Status:** ✅ Completed (2026-02-28, PASS) +- **Description:** Updated multi-agent documentation to clarify Web UI ownership, explain why MCP can remain healthy while the dashboard is unavailable, and document stable multi-agent topologies for both broker mode and direct mode. +- **Priority:** P1 +- **Dependencies:** P13-T6, FU-P13-T8, FU-P13-T10 +- **Parallelizable:** yes +- **Outputs/Artifacts:** + - Updated `README.md` with explicit multi-agent guidance and Web UI ownership notes + - Updated `docs/broker-mode.md` with multi-agent topology details and broker/Web UI behavior notes + - Updated `docs/webui-setup.md` with a dedicated multi-agent ownership model section + - Updated `docs/troubleshooting.md` with diagnostics for reachable MCP + unreachable dashboard states +- **Acceptance Criteria:** + - [x] Documentation states that only one process can bind a given Web UI `host:port` + - [x] Documentation explains why MCP can be healthy while Web UI is unavailable + - [x] Documentation provides a dedicated broker host + `--broker-connect` client pattern + - [x] Troubleshooting includes concrete checks for listener ownership and port conflicts + +--- + ### Phase 14: Release 0.4.0 Readiness #### ✅ P14-T5: Stabilize broker Unix-socket permission test against path-length limits — Completed (2026-02-20, PASS) diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md index 7c7e3074..66f4d20b 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md @@ -263,6 +263,36 @@ Prefer `kill` (`SIGTERM`) first; use `kill -9` only when the process does not ex **Note:** Multiple wrapper processes can run simultaneously on *different* ports. Make sure you identify the PID bound specifically to the port you want, not just any `mcpbridge` process. If the port is immediately re-occupied, close/restart MCP clients (Cursor/Zed/Claude) that may auto-spawn a new wrapper process. +## Error: "MCP tools are green, but dashboard is unreachable" + +**Symptom:** Your MCP client reports connected tools, but `http://127.0.0.1:8080` (or your configured Web UI URL) does not open. + +**Cause:** MCP bridge and Web UI hosting are related but not identical: + +- MCP can stay healthy even if Web UI startup is skipped. +- Only one process can own a given Web UI `host:port`. +- In broker modes (`--broker-daemon`, `--broker-connect`, `--broker-spawn`), the dashboard server is not started. +- A healthy MCP status does not guarantee an active dashboard listener on the expected port. + +**Diagnosis:** + +```bash +# 1) Is anything listening on the expected dashboard port? +PORT=8080 +lsof -nP -iTCP:$PORT -sTCP:LISTEN + +# 2) Which wrapper processes are currently alive? +pgrep -af "xcodemcpwrapper|mcpbridge-wrapper|mcpbridge_wrapper" +``` + +If step 1 returns no listener, no process currently owns the dashboard port. + +**Solution options:** + +1. **Single dashboard owner (direct mode):** keep `--web-ui` on one client config only. +2. **Use separate dashboard ports:** assign unique `--web-ui-port` values per process. +3. **Broker mode for multi-agent MCP:** use `--broker-daemon` + `--broker-connect` for clients, and run dashboard diagnostics separately with `--web-ui-only` when needed. + ## Error: "Tool charts are fresh, but Audit Log / Session Timeline look stale" **Symptom:** Chart widgets (request counts, tool distribution) show new activity, but `/api/audit` diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md b/Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md index 61d9e781..0851534c 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md @@ -37,6 +37,26 @@ xcodemcpwrapper --web-ui --web-ui-port 9090 xcodemcpwrapper --web-ui --web-ui-config /path/to/webui.json ``` +### Multi-agent Web UI ownership model + +The Web UI dashboard is hosted by the wrapper process that successfully binds the configured `host:port`. + +- Only one process can listen on a single `host:port` (for example `127.0.0.1:8080`). +- If another wrapper process starts with the same Web UI port, MCP can keep working while dashboard startup is skipped for that process. +- This is expected behavior in multi-agent setups and can look like: tools are available, but `http://127.0.0.1:8080` is unreachable. +- Ownership is decided at wrapper-process startup by successful port binding. + +Recommended patterns: + +1. **Single owner (recommended):** enable `--web-ui` for one designated client process only. +2. **Separate ports per process:** if you truly need multiple dashboards, give each process its own port. +3. **Shared config for consistency:** if multiple processes may start with Web UI args, use the same `--web-ui-config` so audit log paths stay aligned. + +Broker-mode note: + +- Broker modes (`--broker-daemon`, `--broker-connect`, `--broker-spawn`) do not start the dashboard server. +- Use direct mode with `--web-ui` (or `--web-ui-only` for diagnostics) when dashboard access is required. + ### Enabling via mcp.json Add `--web-ui` and, optionally, `--web-ui-config` to the `args` array in your MCP client config: diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md index b98890a9..3785c621 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md @@ -108,6 +108,21 @@ codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-c For troubleshooting and rollback details, see , , , and . +#### Multi-Agent Guidance + +When you run multiple MCP client processes at the same time: + +- **For shared MCP upstream sessions:** run one broker daemon host and configure each client with `--broker-connect`. +- **For Web UI dashboard hosting:** only one process can bind a given `host:port` (for example `127.0.0.1:8080`). +- If multiple direct-mode processes start with the same `--web-ui-port`, one process serves the dashboard and other processes continue MCP without dashboard hosting. +- This ownership rule is process-level and independent from Xcode window state. + +Current limitation: +- Broker CLI modes (`--broker-daemon`, `--broker-connect`, `--broker-spawn`) do not start the Web UI dashboard process. +- If you need dashboard diagnostics, run a separate direct-mode/Web-UI process (for example `--web-ui-only`) in parallel. + +See and . + ### Python Environment Setup (Development) If you plan to run development commands such as `make install`, `make test`, or editable installs, create and activate a virtual environment first. This avoids Homebrew Python's `externally-managed-environment` (PEP 668) error. @@ -274,6 +289,10 @@ Features: Open http://localhost:8080 in your browser to view the dashboard. +Important for multi-agent setups: +- The dashboard is hosted by one wrapper process, not by Xcode or `mcpbridge`. +- A single `host:port` can have only one listener; additional processes on the same port skip dashboard startup and continue MCP traffic. + ## Known Issues - **BUG-T5 → FU-P13-T7 (P0):** Empty-content tool results can still violate strict `structuredContent` expectations in strict MCP clients. diff --git a/docs/broker-mode.md b/docs/broker-mode.md index 3b714d0b..f8b78d7e 100644 --- a/docs/broker-mode.md +++ b/docs/broker-mode.md @@ -14,6 +14,26 @@ Broker mode lets short-lived MCP client processes share a single long-lived upst Use broker mode when you want lower process churn across repeated MCP client restarts. +## Multi-agent topology and Web UI ownership + +Recommended topology for multiple agents/clients: + +1. Start one broker host process with `--broker-daemon`. +2. Configure every MCP client process with `--broker-connect`. +3. Keep broker mode focused on MCP transport reuse. + +Web UI behavior in broker modes: + +- `--broker-daemon`, `--broker-connect`, and `--broker-spawn` paths do not start the Web UI dashboard server. +- Passing `--web-ui` together with broker flags does not produce a broker-hosted dashboard. +- If you need dashboard diagnostics while running broker mode, run a separate wrapper process with `--web-ui-only` on a chosen port. + +Direct-mode alternative for dashboard-heavy workflows: + +- Enable `--web-ui` in direct mode for one designated owner process. +- Point your browser to that owner's `host:port`. +- Other direct-mode processes can run without `--web-ui`, or on separate Web UI ports. + ## Paths used by broker mode By default, broker state is stored in `~/.mcpbridge_wrapper/`: @@ -107,6 +127,25 @@ rm -f "$PID_FILE" "$SOCK" } ``` +### Zed Agent (`settings.json`) + +```json +{ + "context_servers": { + "xcode-tools": { + "command": "uvx", + "args": [ + "--from", + "mcpbridge-wrapper", + "mcpbridge-wrapper", + "--broker-connect" + ], + "env": {} + } + } +} +``` + ### Claude Code ```bash diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 8cdf4846..b3d16fec 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -297,6 +297,40 @@ Prefer `kill` (`SIGTERM`) first; use `kill -9` only when the process does not ex **Note:** Multiple wrapper processes can run simultaneously on *different* ports. Make sure you identify the PID bound specifically to the port you want, not just any `mcpbridge` process. If the port is immediately re-occupied, close/restart MCP clients (Cursor/Zed/Claude) that may auto-spawn a new wrapper process. +### "MCP tools are green, but dashboard is unreachable" + +**Symptom:** Your MCP client reports connected tools, but `http://127.0.0.1:8080` (or your configured Web UI URL) does not open. + +**Cause:** MCP bridge and Web UI hosting are related but not identical: + +- MCP can stay healthy even if Web UI startup is skipped. +- Only one process can own a given Web UI `host:port`. +- In broker modes (`--broker-daemon`, `--broker-connect`, `--broker-spawn`), the dashboard server is not started. +- A healthy MCP status does not guarantee an active dashboard listener on the expected port. + +**Diagnosis:** + +```bash +# 1) Is anything listening on the expected dashboard port? +PORT=8080 +lsof -nP -iTCP:$PORT -sTCP:LISTEN + +# 2) Which wrapper processes are currently alive? +pgrep -af "xcodemcpwrapper|mcpbridge-wrapper|mcpbridge_wrapper" +``` + +If step 1 returns no listener, no process currently owns the dashboard port. + +**Solution options:** + +1. **Single dashboard owner (direct mode):** keep `--web-ui` on one client config only. +2. **Use separate dashboard ports:** assign unique `--web-ui-port` values per process. +3. **Broker mode for multi-agent MCP:** use `--broker-daemon` + `--broker-connect` for clients, and run dashboard diagnostics separately with `--web-ui-only` when needed. + +See also: +- [Web UI Setup Guide](webui-setup.md#multi-agent-web-ui-ownership-model) +- [Broker Mode Guide](broker-mode.md#multi-agent-topology-and-web-ui-ownership) + --- ### "Tool charts are fresh, but Audit Log / Session Timeline look stale" diff --git a/docs/webui-setup.md b/docs/webui-setup.md index df69bdf2..a0f801e5 100644 --- a/docs/webui-setup.md +++ b/docs/webui-setup.md @@ -80,6 +80,26 @@ There is no `MCP_WRAPPER_WEB_UI*` runtime toggle. xcodemcpwrapper --web-ui ``` +### Multi-agent Web UI ownership model + +The Web UI dashboard is hosted by the wrapper process that successfully binds the configured `host:port`. + +- Only one process can listen on a single `host:port` (for example `127.0.0.1:8080`). +- If another wrapper process starts with the same Web UI port, MCP can keep working while dashboard startup is skipped for that process. +- This is expected behavior in multi-agent setups and can look like: tools are available, but `http://127.0.0.1:8080` is unreachable. +- Ownership is decided at wrapper-process startup by successful port binding. + +Recommended patterns: + +1. **Single owner (recommended):** enable `--web-ui` for one designated client process only. +2. **Separate ports per process:** if you truly need multiple dashboards, give each process its own port. +3. **Shared config for consistency:** if multiple processes may start with Web UI args, use the same `--web-ui-config` so audit log paths stay aligned. + +Broker-mode note: + +- Broker modes (`--broker-daemon`, `--broker-connect`, `--broker-spawn`) do not start the dashboard server. +- Use direct mode with `--web-ui` (or `--web-ui-only` for diagnostics) when dashboard access is required. + ### Access the Dashboard Once started, open your browser to: