From f7de6335c770fb2fef593c04a016f70e54987e06 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sat, 28 Feb 2026 22:58:51 +0300 Subject: [PATCH 1/7] Branch for FU-P13-T18: unified config docs From 1daa7c6bf9646cc2faf2e5049617eec40132da01 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sat, 28 Feb 2026 22:59:26 +0300 Subject: [PATCH 2/7] Select task FU-P13-T18: Document unified single-config setup for broker + Web UI multi-agent workflows --- SPECS/INPROGRESS/next.md | 19 +++++++++++-------- SPECS/Workplan.md | 2 +- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index 07d3abc1..41fb9a23 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,12 +1,15 @@ -# No Active Task +# Next Task: FU-P13-T18 — Document unified single-config setup for broker + Web UI multi-agent workflows -## Recently Archived +**Priority:** P1 +**Phase:** Phase 13: Persistent Broker & Shared Xcode Session +**Effort:** 4-6 hours +**Dependencies:** FU-P13-T17 +**Status:** Selected -- **FU-P13-T17** — Enable broker-hosted Web UI with shared multi-client telemetry (2026-02-28, PASS) -- **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) +## Description -## Suggested Next Tasks +Update setup and troubleshooting documentation so users can configure one shared broker host and dashboard endpoint while reusing a single MCP client configuration across Cursor, Claude Code, Codex, and Zed. -- **FU-P13-T18** — Document unified single-config setup for broker + Web UI multi-agent workflows -- **FU-P13-T19** — Add integration coverage for broker-hosted Web UI observability +## Next Step + +Run the PLAN command to generate the implementation-ready PRD. diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index 011d1939..62b7eded 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -2626,7 +2626,7 @@ Phase 9 Follow-up Backlog --- -#### ⬜️ FU-P13-T18: Document unified single-config setup for broker + Web UI multi-agent workflows +#### ⬜️ FU-P13-T18: Document unified single-config setup for broker + Web UI multi-agent workflows **INPROGRESS** - **Description:** Update setup and troubleshooting docs so users can apply one MCP config across agents while reusing a shared broker host and one dashboard endpoint. - **Priority:** P1 - **Dependencies:** FU-P13-T17 From 2ed6d0a4fb33f89c2571cc900aee4ecbdb59bcd9 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sat, 28 Feb 2026 23:00:14 +0300 Subject: [PATCH 3/7] Plan task FU-P13-T18: Document unified single-config setup for broker + Web UI multi-agent workflows --- ...r_broker_+_Web_UI_multi-agent_workflows.md | 74 +++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 SPECS/INPROGRESS/FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows.md diff --git a/SPECS/INPROGRESS/FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows.md b/SPECS/INPROGRESS/FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows.md new file mode 100644 index 00000000..0f4906d7 --- /dev/null +++ b/SPECS/INPROGRESS/FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows.md @@ -0,0 +1,74 @@ +# PRD: FU-P13-T18 — Document unified single-config setup for broker + Web UI multi-agent workflows + +## 1. Objective + +Document one repeatable setup where multiple AI clients share the same broker and dashboard endpoint without per-client config drift. The goal is to let users keep a single MCP server definition in each client (Cursor, Zed, Claude Code, Codex) that points to a broker-aware command path, while only one broker host process owns `--web-ui` listener startup. + +This task builds directly on FU-P13-T17 behavior. Documentation must describe: +- Which process starts and owns the dashboard listener. +- How `--broker-spawn` and `--broker-connect` clients should be configured when using one shared broker host. +- What users should expect when broker MCP transport stays healthy but dashboard endpoint is unavailable. +- How DocC mirrors stay aligned with Markdown docs. + +## 2. Success Criteria and Acceptance Tests + +### Success Criteria +- `README.md` contains a clear “single-config, shared broker host” quick path and links to detailed docs. +- `docs/broker-mode.md` includes unified config examples for Cursor, Zed, Claude Code, and Codex with explicit host/client roles. +- `docs/webui-setup.md` defines dashboard ownership rules and fallback behavior when the chosen listener is unavailable. +- `docs/troubleshooting.md` adds broker-hosted Web UI diagnostics that distinguish broker health from dashboard reachability. +- Mapped DocC documentation is updated to match user-facing guidance. + +### Acceptance Tests +- Verify docs include one end-to-end flow where one process runs broker + Web UI and all other agents use broker connection mode without `--web-ui`. +- Verify docs include explicit expectations for shared dashboard endpoint reuse and port conflict outcomes. +- Verify troubleshooting steps include concrete commands (`lsof`, broker host start/restart checks, endpoint verification). + +## 3. Test-First Plan + +1. Review current behavior coverage to ensure docs claims are already validated by tests from FU-P13-T17 and prior broker-mode work. +2. Add/adjust tests only if a new behavior statement lacks evidence in existing test suite. +3. Run required quality gates after documentation updates: + - `pytest` + - `ruff check src/` + - `mypy src/` + - `pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` + +## 4. Execution Plan (Hierarchical TODO) + +### Phase A — Behavior and config alignment +- Inputs: runtime behavior from `src/mcpbridge_wrapper/__main__.py`, broker and Web UI docs. +- Outputs: authoritative wording for broker host ownership and multi-agent shared endpoint semantics. +- Verification: no docs claim behavior that code does not implement. + +### Phase B — Documentation and examples +- Inputs: `README.md`, `docs/broker-mode.md`, `docs/webui-setup.md`, `docs/troubleshooting.md`. +- Outputs: unified single-config examples, ownership matrix, fallback and diagnostics guidance. +- Verification: examples are internally consistent and use current CLI flags. + +### Phase C — DocC synchronization +- Inputs: mapped files under `Sources/XcodeMCPWrapper/Documentation.docc/`. +- Outputs: mirrored guidance aligned with Markdown docs. +- Verification: key sections and commands match without contradictions. + +### Phase D — Validation report +- Inputs: edited docs and gate outputs. +- Outputs: `SPECS/INPROGRESS/FU-P13-T18_Validation_Report.md` with verdict and acceptance criteria checks. +- Verification: report records all required gates and result status. + +## 5. Decision Points and Constraints + +- Preserve compatibility with existing single-agent quick start instructions. +- Do not imply automatic dashboard failover or multi-owner listener support. +- Keep commands copy/paste-ready and avoid introducing unsupported CLI flags. +- Review subject for REPORT step: `fu_p13_t18_unified_config_docs`. + +## 6. Notes (Files likely touched) + +- `README.md` +- `docs/broker-mode.md` +- `docs/webui-setup.md` +- `docs/troubleshooting.md` +- `Sources/XcodeMCPWrapper/Documentation.docc/tutorials/broker-mode.md` +- `Sources/XcodeMCPWrapper/Documentation.docc/tutorials/webui-setup.md` +- `Sources/XcodeMCPWrapper/Documentation.docc/tutorials/troubleshooting.md` From 6903bb299c91b1aedf7d37098336aac9ad2f4b5d Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sat, 28 Feb 2026 23:05:53 +0300 Subject: [PATCH 4/7] Implement FU-P13-T18: unify broker-hosted Web UI docs and diagnostics --- README.md | 14 ++-- ...r_broker_+_Web_UI_multi-agent_workflows.md | 6 +- .../FU-P13-T18_Validation_Report.md | 41 +++++++++++ .../Documentation.docc/Troubleshooting.md | 12 +++- .../Documentation.docc/WebUIDashboard.md | 10 +-- .../Documentation.docc/XcodeMCPWrapper.md | 14 ++-- docs/broker-mode.md | 72 ++++++++++++------- docs/troubleshooting.md | 12 +++- docs/webui-setup.md | 12 ++-- 9 files changed, 135 insertions(+), 58 deletions(-) create mode 100644 SPECS/INPROGRESS/FU-P13-T18_Validation_Report.md diff --git a/README.md b/README.md index 41d25aa5..5be9a5cb 100644 --- a/README.md +++ b/README.md @@ -101,6 +101,7 @@ upstream bridge session. - Use `--broker-connect` to attach to an already-running broker. - Use `--broker-spawn` to auto-start the broker if needed. +- Add `--web-ui` (plus optional `--web-ui-config`) when you want the spawned or daemon host to own one shared dashboard endpoint. Quick migration examples: @@ -119,14 +120,11 @@ rollback to direct mode, see [Broker Mode Guide](docs/broker-mode.md). 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. +- **Unified single-config pattern:** configure each client with `--broker-spawn --web-ui --web-ui-config `. +- **Runtime expectation:** the first client that must spawn the broker starts the broker host and dashboard; later clients reuse the same broker and dashboard endpoint. +- **Ownership rule:** only one process can bind a given Web UI `host:port` (for example `127.0.0.1:8080`). +- **Connect-only behavior:** `--broker-connect` clients never start the dashboard by themselves. +- **Fallback behavior:** if dashboard bind fails (port already in use), broker MCP transport continues and only dashboard startup is skipped. 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). diff --git a/SPECS/INPROGRESS/FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows.md b/SPECS/INPROGRESS/FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows.md index 0f4906d7..57ff93ef 100644 --- a/SPECS/INPROGRESS/FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows.md +++ b/SPECS/INPROGRESS/FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows.md @@ -69,6 +69,6 @@ This task builds directly on FU-P13-T17 behavior. Documentation must describe: - `docs/broker-mode.md` - `docs/webui-setup.md` - `docs/troubleshooting.md` -- `Sources/XcodeMCPWrapper/Documentation.docc/tutorials/broker-mode.md` -- `Sources/XcodeMCPWrapper/Documentation.docc/tutorials/webui-setup.md` -- `Sources/XcodeMCPWrapper/Documentation.docc/tutorials/troubleshooting.md` +- `Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md` +- `Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md` +- `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md` diff --git a/SPECS/INPROGRESS/FU-P13-T18_Validation_Report.md b/SPECS/INPROGRESS/FU-P13-T18_Validation_Report.md new file mode 100644 index 00000000..ca35933a --- /dev/null +++ b/SPECS/INPROGRESS/FU-P13-T18_Validation_Report.md @@ -0,0 +1,41 @@ +# Validation Report: FU-P13-T18 — Document unified single-config setup for broker + Web UI multi-agent workflows + +**Date:** 2026-02-28 +**Task ID:** FU-P13-T18 +**Verdict:** PASS + +## Scope Implemented + +- Updated `README.md` multi-agent guidance to document unified broker + dashboard single-config behavior with `--broker-spawn --web-ui`. +- Updated `docs/broker-mode.md` with: + - Unified single-config examples for Cursor, Zed, Claude Code, and Codex CLI. + - Runtime expectations for broker-hosted dashboard ownership and fallback behavior. + - Updated operational and migration guidance for broker-hosted Web UI flows. +- Updated `docs/webui-setup.md` multi-agent ownership guidance to reflect broker-hosted dashboard behavior. +- Updated `docs/troubleshooting.md` with broker-hosted dashboard diagnostics and decision paths for unified config vs dedicated host. +- Synced mapped DocC pages: + - `Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md` + - `Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md` + - `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md` + +## Quality Gates + +- `pytest` → FAIL in this environment (`ModuleNotFoundError: mcpbridge_wrapper` during collection; project uses `PYTHONPATH=src` for local gates) +- `PYTHONPATH=src pytest` → PASS (`692 passed, 5 skipped`) +- `ruff check src/` → PASS (`All checks passed!`) +- `mypy src/` → PASS (`Success: no issues found in 18 source files`) +- `PYTHONPATH=src pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` → PASS + - Total coverage: **91.72%** (required: >= 90%) + +## Acceptance Criteria Check + +- [x] Docs include one-config examples for Zed/Cursor/Claude/Codex with broker + dashboard expectations. +- [x] Docs clearly define dashboard ownership and fallback behavior. +- [x] Troubleshooting includes broker-hosted Web UI diagnostics. + +## Notes + +- Broker dashboard startup semantics documented here align with implemented runtime behavior from FU-P13-T17: + - Broker host (`--broker-daemon --web-ui`) can own dashboard startup. + - Auto-spawn path (`--broker-spawn --web-ui`) propagates Web UI args to spawned host. + - Connect-only clients (`--broker-connect`) do not host dashboards. diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md index 66f4d20b..2170c13a 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md @@ -271,7 +271,9 @@ Prefer `kill` (`SIGTERM`) first; use `kill -9` only when the process does not ex - 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. +- Dashboard starts in a direct-mode owner (`--web-ui`) or a broker host (`--broker-daemon --web-ui`). +- `--broker-connect` never starts a dashboard by itself; `--broker-spawn --web-ui` only starts one when it must spawn a host. +- If dashboard bind fails (port already in use), wrapper logs a warning and continues MCP without dashboard hosting. - A healthy MCP status does not guarantee an active dashboard listener on the expected port. **Diagnosis:** @@ -283,6 +285,10 @@ lsof -nP -iTCP:$PORT -sTCP:LISTEN # 2) Which wrapper processes are currently alive? pgrep -af "xcodemcpwrapper|mcpbridge-wrapper|mcpbridge_wrapper" + +# 3) If you expect broker-hosted dashboard, inspect broker host logs +LOG="$HOME/.mcpbridge_wrapper/broker.log" +test -f "$LOG" && rg -n "Web UI dashboard started|Skipping Web UI startup" "$LOG" | tail -n 10 ``` If step 1 returns no listener, no process currently owns the dashboard port. @@ -291,7 +297,9 @@ If step 1 returns no listener, no process currently owns the dashboard port. 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. +3. **Unified broker single-config:** use `--broker-spawn --web-ui --web-ui-config ` in all clients so one spawned host owns the dashboard. +4. **Dedicated host pattern:** run one `--broker-daemon --web-ui` process, keep clients on `--broker-connect`, and monitor `~/.mcpbridge_wrapper/broker.log`. +5. **Standalone diagnostics:** run `--web-ui-only` when you need dashboard-only debugging independent from MCP startup. ## Error: "Tool charts are fresh, but Audit Log / Session Timeline look stale" diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md b/Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md index 0851534c..f612769f 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md @@ -49,13 +49,15 @@ The Web UI dashboard is hosted by the wrapper process that successfully binds th 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. +2. **Unified broker config (multi-agent):** use `--broker-spawn --web-ui --web-ui-config ` across Cursor/Zed/Claude/Codex so the first auto-spawn host owns one shared dashboard endpoint. +3. **Separate ports per process:** if you truly need multiple dashboards, give each process its own port. 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. +- `--broker-daemon --web-ui` starts the dashboard in the broker host process. +- `--broker-spawn --web-ui` can start the dashboard when it has to spawn the broker host. +- `--broker-connect` never starts the dashboard by itself. +- If dashboard bind fails, broker MCP transport still runs and dashboard startup is skipped. ### Enabling via mcp.json diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md index 3785c621..818a4c9c 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md @@ -94,6 +94,7 @@ Broker mode lets short-lived MCP sessions share one persistent upstream bridge. - `--broker-connect`: attach to an already-running broker. - `--broker-spawn`: best-effort auto-start, then connect. +- Add `--web-ui` (plus optional `--web-ui-config`) when you want the spawned or daemon host to own one shared dashboard endpoint. Quick migration examples: @@ -112,14 +113,11 @@ For troubleshooting and rollback details, see , 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. +- **Unified single-config pattern:** configure each client with `--broker-spawn --web-ui --web-ui-config `. +- **Runtime expectation:** the first client that must spawn the broker starts the broker host and dashboard; later clients reuse the same broker and dashboard endpoint. +- **Ownership rule:** only one process can bind a given Web UI `host:port` (for example `127.0.0.1:8080`). +- **Connect-only behavior:** `--broker-connect` clients never start the dashboard by themselves. +- **Fallback behavior:** if dashboard bind fails (port already in use), broker MCP transport continues and only dashboard startup is skipped. See and . diff --git a/docs/broker-mode.md b/docs/broker-mode.md index f8b78d7e..72be043f 100644 --- a/docs/broker-mode.md +++ b/docs/broker-mode.md @@ -18,21 +18,18 @@ Use broker mode when you want lower process churn across repeated MCP client res 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. +1. **Unified single-config (recommended):** use the same client args everywhere: + `--broker-spawn --web-ui --web-ui-config `. +2. **Dedicated host alternative:** run one explicit broker host with + `--broker-daemon --web-ui` and configure clients with `--broker-connect`. 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. +- `--broker-daemon --web-ui` starts broker + dashboard in one host process. +- `--broker-spawn --web-ui` forwards Web UI flags to the spawned daemon when auto-start is needed. +- `--broker-connect` never starts a dashboard by itself. +- Only one process can own a given Web UI `host:port`. +- If dashboard bind fails (for example port already in use), broker transport continues and only dashboard startup is skipped. ## Paths used by broker mode @@ -50,7 +47,7 @@ Start a dedicated background broker host first for predictable operation: ```bash mkdir -p "$HOME/.mcpbridge_wrapper" -nohup mcpbridge-wrapper --broker-daemon \ +nohup mcpbridge-wrapper --broker-daemon --web-ui --web-ui-config "$HOME/.mcpbridge_wrapper/webui.json" \ > "$HOME/.mcpbridge_wrapper/broker.log" 2>&1 & echo "Broker started (PID $!)" ``` @@ -58,16 +55,18 @@ echo "Broker started (PID $!)" Or using `uvx`: ```bash -nohup uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-daemon \ +nohup uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper \ + --broker-daemon --web-ui --web-ui-config "$HOME/.mcpbridge_wrapper/webui.json" \ > "$HOME/.mcpbridge_wrapper/broker.log" 2>&1 & ``` Then configure MCP clients with `--broker-connect` (see client examples below). -`--broker-spawn` is available as a best-effort alternative that auto-starts the daemon when needed: +`--broker-spawn` is available as a best-effort alternative that auto-starts the daemon when needed (including dashboard args): ```bash -uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-spawn +uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper \ + --broker-spawn --web-ui --web-ui-config "$HOME/.mcpbridge_wrapper/webui.json" ``` ### Status @@ -109,6 +108,10 @@ rm -f "$PID_FILE" "$SOCK" ## Client configuration examples +### Unified single-config examples (recommended) + +Use the same args in every client. The first client that needs auto-spawn starts the broker host and dashboard; later clients attach to the same host/session. + ### Cursor (`~/.cursor/mcp.json`) ```json @@ -118,9 +121,12 @@ rm -f "$PID_FILE" "$SOCK" "command": "uvx", "args": [ "--from", + "mcpbridge-wrapper[webui]", "mcpbridge-wrapper", - "mcpbridge-wrapper", - "--broker-connect" + "--broker-spawn", + "--web-ui", + "--web-ui-config", + "/Users/YOUR_USERNAME/.mcpbridge_wrapper/webui.json" ] } } @@ -136,9 +142,12 @@ rm -f "$PID_FILE" "$SOCK" "command": "uvx", "args": [ "--from", + "mcpbridge-wrapper[webui]", "mcpbridge-wrapper", - "mcpbridge-wrapper", - "--broker-connect" + "--broker-spawn", + "--web-ui", + "--web-ui-config", + "/Users/YOUR_USERNAME/.mcpbridge_wrapper/webui.json" ], "env": {} } @@ -149,25 +158,34 @@ rm -f "$PID_FILE" "$SOCK" ### Claude Code ```bash -claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect +claude mcp add --transport stdio xcode -- \ + uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper \ + --broker-spawn --web-ui --web-ui-config "$HOME/.mcpbridge_wrapper/webui.json" ``` ### Codex CLI ```bash -codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect +codex mcp add xcode -- \ + uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper \ + --broker-spawn --web-ui --web-ui-config "$HOME/.mcpbridge_wrapper/webui.json" ``` +### Dedicated host + connect-only alternative + +If you prefer explicit host lifecycle management, start one `--broker-daemon --web-ui` process manually and configure clients with `--broker-connect` only. + ## Migration from direct mode to broker mode 1. Back up your current MCP client configuration. -2. Start a broker host (recommended) and set MCP clients to `--broker-connect`. -3. Optional alternative: use `--broker-spawn` for best-effort auto-start. -4. Restart your MCP client. -5. Run a first MCP request and verify broker files exist: +2. Choose one rollout pattern: + - Unified config: set clients to `--broker-spawn --web-ui --web-ui-config `. + - Dedicated host: start `--broker-daemon --web-ui` once and set clients to `--broker-connect`. +3. Restart each MCP client. +4. Run a first MCP request and verify broker files exist: - `~/.mcpbridge_wrapper/broker.pid` - `~/.mcpbridge_wrapper/broker.sock` -6. Keep the same wrapper binary and package version across all clients that share the broker. +5. Keep the same wrapper binary and package version across all clients that share the broker. ## Rollback to direct mode diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index b3d16fec..ac1c05b8 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -305,7 +305,9 @@ Prefer `kill` (`SIGTERM`) first; use `kill -9` only when the process does not ex - 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. +- Dashboard starts in a direct-mode owner (`--web-ui`) or a broker host (`--broker-daemon --web-ui`). +- `--broker-connect` never starts a dashboard by itself; `--broker-spawn --web-ui` only starts one when it must spawn a host. +- If dashboard bind fails (port already in use), wrapper logs a warning and continues MCP without dashboard hosting. - A healthy MCP status does not guarantee an active dashboard listener on the expected port. **Diagnosis:** @@ -317,6 +319,10 @@ lsof -nP -iTCP:$PORT -sTCP:LISTEN # 2) Which wrapper processes are currently alive? pgrep -af "xcodemcpwrapper|mcpbridge-wrapper|mcpbridge_wrapper" + +# 3) If you expect broker-hosted dashboard, inspect broker host logs +LOG="$HOME/.mcpbridge_wrapper/broker.log" +test -f "$LOG" && rg -n "Web UI dashboard started|Skipping Web UI startup" "$LOG" | tail -n 10 ``` If step 1 returns no listener, no process currently owns the dashboard port. @@ -325,7 +331,9 @@ If step 1 returns no listener, no process currently owns the dashboard port. 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. +3. **Unified broker single-config:** use `--broker-spawn --web-ui --web-ui-config ` in all clients so one spawned host owns the dashboard. +4. **Dedicated host pattern:** run one `--broker-daemon --web-ui` process, keep clients on `--broker-connect`, and monitor `~/.mcpbridge_wrapper/broker.log`. +5. **Standalone diagnostics:** run `--web-ui-only` when you need dashboard-only debugging independent from MCP startup. See also: - [Web UI Setup Guide](webui-setup.md#multi-agent-web-ui-ownership-model) diff --git a/docs/webui-setup.md b/docs/webui-setup.md index a0f801e5..4931f823 100644 --- a/docs/webui-setup.md +++ b/docs/webui-setup.md @@ -92,13 +92,17 @@ The Web UI dashboard is hosted by the wrapper process that successfully binds th 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. +2. **Unified broker config (multi-agent):** use `--broker-spawn --web-ui --web-ui-config ` across Cursor/Zed/Claude/Codex so the first auto-spawn host owns one shared dashboard endpoint. +3. **Separate ports per process:** if you truly need multiple dashboards, give each process its own port. 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. +- `--broker-daemon --web-ui` starts the dashboard in the broker host process. +- `--broker-spawn --web-ui` can start the dashboard when it has to spawn the broker host. +- `--broker-connect` never starts the dashboard by itself. +- If dashboard bind fails, broker MCP transport still runs and dashboard startup is skipped. + +For full single-config examples by client (Cursor, Zed, Claude Code, Codex CLI), see [Broker Mode Guide](broker-mode.md#client-configuration-examples). ### Access the Dashboard From f82a02d91a8d2e14e673931b80b86b594c0a8d4b Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sat, 28 Feb 2026 23:07:14 +0300 Subject: [PATCH 5/7] Archive task FU-P13-T18: Document unified single-config setup for broker + Web UI multi-agent workflows (PASS) --- ...or_broker_+_Web_UI_multi-agent_workflows.md | 4 ++++ .../FU-P13-T18_Validation_Report.md | 0 SPECS/ARCHIVE/INDEX.md | 4 +++- SPECS/INPROGRESS/next.md | 18 +++++++----------- SPECS/Workplan.md | 9 +++++---- 5 files changed, 19 insertions(+), 16 deletions(-) rename SPECS/{INPROGRESS => ARCHIVE/FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows}/FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows.md (98%) rename SPECS/{INPROGRESS => ARCHIVE/FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows}/FU-P13-T18_Validation_Report.md (100%) diff --git a/SPECS/INPROGRESS/FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows.md b/SPECS/ARCHIVE/FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows/FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows.md similarity index 98% rename from SPECS/INPROGRESS/FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows.md rename to SPECS/ARCHIVE/FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows/FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows.md index 57ff93ef..dc49f515 100644 --- a/SPECS/INPROGRESS/FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows.md +++ b/SPECS/ARCHIVE/FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows/FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows.md @@ -72,3 +72,7 @@ This task builds directly on FU-P13-T17 behavior. Documentation must describe: - `Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md` - `Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md` - `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md` + +--- +**Archived:** 2026-02-28 +**Verdict:** PASS diff --git a/SPECS/INPROGRESS/FU-P13-T18_Validation_Report.md b/SPECS/ARCHIVE/FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows/FU-P13-T18_Validation_Report.md similarity index 100% rename from SPECS/INPROGRESS/FU-P13-T18_Validation_Report.md rename to SPECS/ARCHIVE/FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows/FU-P13-T18_Validation_Report.md diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index cb32786a..1c3ad7d1 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-P13-T17_Enable_broker-hosted_Web_UI_with_shared_multi-client_telemetry) +**Last Updated:** 2026-02-28 (FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows) ## Archived Tasks | Task ID | Folder | Archived | Verdict | |---------|--------|----------|---------| +| FU-P13-T18 | [FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows/](FU-P13-T18_Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows/) | 2026-02-28 | PASS | | FU-P13-T17 | [FU-P13-T17_Enable_broker-hosted_Web_UI_with_shared_multi-client_telemetry/](FU-P13-T17_Enable_broker-hosted_Web_UI_with_shared_multi-client_telemetry/) | 2026-02-28 | PASS | | 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 | @@ -277,6 +278,7 @@ | Date | Task ID | Action | |------|---------|--------| +| 2026-02-28 | FU-P13-T18 | Archived Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows (PASS) | | 2026-02-28 | FU-P13-T17 | Archived REVIEW_fu_p13_t17_broker_hosted_webui report | | 2026-02-28 | FU-P13-T17 | Archived Enable_broker-hosted_Web_UI_with_shared_multi-client_telemetry (PASS) | | 2026-02-28 | FU-P13-T16 | Archived REVIEW_fu_p13_t16_multi_agent_mcp_docs report | diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index 41fb9a23..50f25ecc 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,15 +1,11 @@ -# Next Task: FU-P13-T18 — Document unified single-config setup for broker + Web UI multi-agent workflows +# No Active Task -**Priority:** P1 -**Phase:** Phase 13: Persistent Broker & Shared Xcode Session -**Effort:** 4-6 hours -**Dependencies:** FU-P13-T17 -**Status:** Selected +## Recently Archived -## Description +- **FU-P13-T18** — Document unified single-config setup for broker + Web UI multi-agent workflows (2026-02-28, PASS) +- **FU-P13-T17** — Enable broker-hosted Web UI with shared multi-client telemetry (2026-02-28, PASS) +- **FU-P13-T16** — Document multi-agent MCP usage and single Web UI host (2026-02-28, PASS) -Update setup and troubleshooting documentation so users can configure one shared broker host and dashboard endpoint while reusing a single MCP client configuration across Cursor, Claude Code, Codex, and Zed. +## Suggested Next Tasks -## Next Step - -Run the PLAN command to generate the implementation-ready PRD. +- **FU-P13-T19** — Add integration coverage for broker-hosted Web UI observability diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index 62b7eded..6ed515fb 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -2626,7 +2626,8 @@ Phase 9 Follow-up Backlog --- -#### ⬜️ FU-P13-T18: Document unified single-config setup for broker + Web UI multi-agent workflows **INPROGRESS** +#### ✅ FU-P13-T18: Document unified single-config setup for broker + Web UI multi-agent workflows — Completed (2026-02-28, PASS) +- **Status:** ✅ Completed (2026-02-28, PASS) - **Description:** Update setup and troubleshooting docs so users can apply one MCP config across agents while reusing a shared broker host and one dashboard endpoint. - **Priority:** P1 - **Dependencies:** FU-P13-T17 @@ -2635,9 +2636,9 @@ Phase 9 Follow-up Backlog - Updated `README.md`, `docs/broker-mode.md`, `docs/webui-setup.md`, and `docs/troubleshooting.md` - Updated mapped DocC files in `Sources/XcodeMCPWrapper/Documentation.docc/` - **Acceptance Criteria:** - - [ ] Docs include one-config examples for Zed/Cursor/Claude/Codex with broker + dashboard expectations - - [ ] Docs clearly define dashboard ownership and fallback behavior - - [ ] Troubleshooting includes broker-hosted Web UI diagnostics + - [x] Docs include one-config examples for Zed/Cursor/Claude/Codex with broker + dashboard expectations + - [x] Docs clearly define dashboard ownership and fallback behavior + - [x] Troubleshooting includes broker-hosted Web UI diagnostics --- From 4719646e687fba3b4e521c62c012a07df87ea707 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sat, 28 Feb 2026 23:07:41 +0300 Subject: [PATCH 6/7] Review FU-P13-T18: unified config docs --- .../REVIEW_fu_p13_t18_unified_config_docs.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 SPECS/INPROGRESS/REVIEW_fu_p13_t18_unified_config_docs.md diff --git a/SPECS/INPROGRESS/REVIEW_fu_p13_t18_unified_config_docs.md b/SPECS/INPROGRESS/REVIEW_fu_p13_t18_unified_config_docs.md new file mode 100644 index 00000000..34cf1dec --- /dev/null +++ b/SPECS/INPROGRESS/REVIEW_fu_p13_t18_unified_config_docs.md @@ -0,0 +1,32 @@ +## REVIEW REPORT — FU-P13-T18 Unified Config Docs + +**Scope:** origin/main..HEAD +**Files:** 12 + +### Summary Verdict +- [x] Approve +- [ ] Approve with comments +- [ ] Request changes +- [ ] Block + +### Critical Issues +- None. + +### Secondary Issues +- None actionable. + +### Architectural Notes +- Documentation now aligns with broker-hosted dashboard behavior delivered in FU-P13-T17 (`--broker-daemon --web-ui` and `--broker-spawn --web-ui` host-path semantics). +- Multi-agent guidance is internally consistent across README, broker/web UI/troubleshooting docs, and mapped DocC pages. +- Archive bookkeeping (`Workplan`, `next.md`, task artifacts, archive index/log) follows FLOW conventions and remains coherent. + +### Tests +- `pytest` (without `PYTHONPATH`) fails in this repo environment due import resolution; gate path uses `PYTHONPATH=src`. +- `PYTHONPATH=src pytest` passed (`692 passed, 5 skipped`). +- `ruff check src/` passed. +- `mypy src/` passed. +- `PYTHONPATH=src pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` passed with 91.72% coverage (>=90%). + +### Next Steps +- No follow-up tasks required from this review. +- FOLLOW-UP step can be skipped per FLOW because there are no actionable findings. From 50d96ccd79b3dea3677a4987d3ec8728550d22a9 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sat, 28 Feb 2026 23:08:02 +0300 Subject: [PATCH 7/7] Archive REVIEW_fu_p13_t18_unified_config_docs report --- SPECS/ARCHIVE/INDEX.md | 2 ++ .../_Historical}/REVIEW_fu_p13_t18_unified_config_docs.md | 0 2 files changed, 2 insertions(+) rename SPECS/{INPROGRESS => ARCHIVE/_Historical}/REVIEW_fu_p13_t18_unified_config_docs.md (100%) diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index 1c3ad7d1..5cf6c411 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -165,6 +165,7 @@ | File | Description | |------|-------------| +| [REVIEW_fu_p13_t18_unified_config_docs.md](_Historical/REVIEW_fu_p13_t18_unified_config_docs.md) | Review report for FU-P13-T18 | | [REVIEW_fu_p13_t17_broker_hosted_webui.md](_Historical/REVIEW_fu_p13_t17_broker_hosted_webui.md) | Review report for FU-P13-T17 | | [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 | @@ -278,6 +279,7 @@ | Date | Task ID | Action | |------|---------|--------| +| 2026-02-28 | FU-P13-T18 | Archived REVIEW_fu_p13_t18_unified_config_docs report | | 2026-02-28 | FU-P13-T18 | Archived Document_unified_single-config_setup_for_broker_+_Web_UI_multi-agent_workflows (PASS) | | 2026-02-28 | FU-P13-T17 | Archived REVIEW_fu_p13_t17_broker_hosted_webui report | | 2026-02-28 | FU-P13-T17 | Archived Enable_broker-hosted_Web_UI_with_shared_multi-client_telemetry (PASS) | diff --git a/SPECS/INPROGRESS/REVIEW_fu_p13_t18_unified_config_docs.md b/SPECS/ARCHIVE/_Historical/REVIEW_fu_p13_t18_unified_config_docs.md similarity index 100% rename from SPECS/INPROGRESS/REVIEW_fu_p13_t18_unified_config_docs.md rename to SPECS/ARCHIVE/_Historical/REVIEW_fu_p13_t18_unified_config_docs.md