Add P0 workplan bugs/tasks for MCP wrapper debug issues

README.md

@@ -467,6 +467,17 @@ Open http://localhost:8080 in your browser to view the dashboard.
 
 See [Web UI Setup Guide](docs/webui-setup.md) for detailed configuration.
 
+## Known Issues
+
+- **BUG-T5 → FU-P13-T7 (P0):** Empty-content tool results can still violate strict `structuredContent` expectations in strict MCP clients.
+- **BUG-T6 → FU-P13-T8 (P0):** Web UI port collisions can happen when multiple MCP sessions start with the same `--web-ui-port` (for example `8080`), producing `address already in use`.
+- **BUG-T7 → FU-P13-T9 (P0):** `resources/list` and `resources/templates/list` probing may return non-standard error shapes in some client paths.
+- **BUG-T3 (resolved):** If dashboard access is needed independently from MCP startup, run `--web-ui-only` for standalone diagnostics.
+
+### Disclaimer (Codex App)
+
+`mcpbridge-wrapper` normalizes Xcode MCP responses, but it does not control Codex App internals. Codex App transport/session behavior may change independently from Codex CLI and from this wrapper. If App and CLI differ, treat that as client-specific behavior first and verify with exact versions, config, and logs.
+
 ## Documentation
 
 - [Installation Guide](docs/installation.md)

SPECS/ARCHIVE/BUG-T3_webui_only_dashboard_mode/BUG-T3_Validation_Report.md

@@ -0,0 +1,41 @@
+# BUG-T3 Validation Report
+
+- **Task ID:** BUG-T3
+- **Task Name:** Web UI cannot stay available when MCP bridge initialization fails
+- **Date:** 2026-02-14
+- **Verdict:** PASS
+
+## Scope Validated
+
+- Added standalone `--web-ui-only` startup mode in `__main__.py`.
+- Verified standalone mode skips bridge startup and runs dashboard server.
+- Verified `--web-ui-only` honors custom port and implies Web UI enabled.
+- Added troubleshooting guidance for standalone dashboard diagnostics.
+
+## Acceptance Criteria Check
+
+1. `--web-ui-only` is accepted by argument parser.  
+   **Result:** PASS
+2. `--web-ui-only` implies Web UI enabled and honors `--web-ui-port`.  
+   **Result:** PASS
+3. Standalone mode does not start `create_bridge()` or stdin forwarding threads.  
+   **Result:** PASS
+4. Existing non-standalone behavior remains unchanged.  
+   **Result:** PASS
+5. Required quality gates pass (`pytest`, `ruff check src/`, `mypy src/`, `pytest --cov >= 90%`).  
+   **Result:** PASS
+
+## Quality Gate Results
+
+- `pytest`  
+  - Result: PASS (`348 passed, 5 skipped`)
+- `ruff check src/`  
+  - Result: PASS (`All checks passed!`)
+- `mypy src/`  
+  - Result: PASS (`Success: no issues found in 12 source files`)
+- `pytest --cov`  
+  - Result: PASS (`Total coverage: 96.31%`, required `>= 90%`)
+
+## Notes
+
+- Test runs emitted non-blocking dependency deprecation warnings from `websockets`/`uvicorn`; no functional regressions were detected.

SPECS/ARCHIVE/BUG-T3_webui_only_dashboard_mode/BUG-T3_webui_only_dashboard_mode.md

@@ -0,0 +1,69 @@
+# BUG-T3 PRD — webui only dashboard mode
+
+## 1. Context
+
+Users enabling `--web-ui` for MCP debugging can lose dashboard access when MCP bridge startup fails or when the MCP client session exits early. In those cases the process terminates and Safari shows "can't connect to server" for the dashboard URL.
+
+## 2. Goal
+
+Provide an explicit standalone mode that runs only the Web UI server so the dashboard remains reachable during MCP connection diagnostics.
+
+## 3. Scope
+
+In scope:
+- Add a CLI argument (`--web-ui-only`) in startup parsing
+- Ensure standalone mode starts FastAPI Web UI without launching bridge subprocess
+- Keep existing `--web-ui` behavior unchanged for normal MCP wrapper mode
+- Add unit tests for parsing and main startup behavior
+- Document standalone usage for troubleshooting
+
+Out of scope:
+- Changes to MCP protocol transformation behavior
+- Changes to Xcode bridge handshake handling
+- New dashboard features unrelated to startup mode
+
+## 4. Deliverables
+
+- Updated `src/mcpbridge_wrapper/__main__.py`:
+  - Parse `--web-ui-only`
+  - Run `run_server(...)` and return in standalone mode
+- Updated tests in `tests/unit/test_main_webui.py`
+- Updated troubleshooting docs with standalone mode guidance
+- Validation report at `SPECS/INPROGRESS/BUG-T3_Validation_Report.md`
+
+## 5. Acceptance Criteria
+
+1. `--web-ui-only` is accepted by argument parser.
+2. `--web-ui-only` implies Web UI enabled and honors `--web-ui-port`.
+3. In standalone mode, wrapper does not start `create_bridge()` or stdin forwarding threads.
+4. Existing non-standalone behavior remains unchanged.
+5. Quality gates pass:
+   - `pytest`
+   - `ruff check src/`
+   - `mypy src/`
+   - `pytest --cov` with coverage >= 90%
+
+## 6. Dependencies
+
+- Existing Web UI server entrypoint (`mcpbridge_wrapper.webui.server:run_server`)
+- Existing CLI parser logic in `src/mcpbridge_wrapper/__main__.py`
+
+## 7. Implementation Plan
+
+1. Extend web UI arg parser return shape to include standalone mode flag.
+2. Update main startup flow to short-circuit into `run_server(...)` for standalone mode.
+3. Add parser and main-path unit tests for standalone mode.
+4. Update troubleshooting docs with standalone command examples.
+5. Execute required quality gates and capture results.
+
+## 8. Risks and Mitigations
+
+- Risk: starting both thread mode and standalone mode could double-bind ports.
+- Mitigation: ensure standalone path returns before any bridge/websocket thread startup.
+
+- Risk: behavior regression in existing `--web-ui` MCP mode.
+- Mitigation: keep existing code path intact and covered by current tests.
+
+---
+**Archived:** 2026-02-14
+**Verdict:** PASS

SPECS/ARCHIVE/BUG-T3_webui_only_dashboard_mode/REVIEW_BUG-T3_webui_only_mode.md

@@ -0,0 +1,29 @@
+## REVIEW REPORT — BUG-T3 webui-only mode
+
+**Scope:** origin/main..HEAD
+**Files:** 8
+
+### Summary Verdict
+- [x] Approve
+- [ ] Approve with comments
+- [ ] Request changes
+- [ ] Block
+
+### Critical Issues
+- None.
+
+### Secondary Issues
+- None.
+
+### Architectural Notes
+- Standalone dashboard mode is correctly isolated from bridge startup, which removes the lifecycle coupling that caused dashboard availability loss during MCP handshake failures.
+
+### Tests
+- Quality gates executed and passed:
+  - `pytest` passed (`348 passed, 5 skipped`)
+  - `ruff check src/` passed
+  - `mypy src/` passed
+  - `pytest --cov` passed with `96.31%` coverage (>= 90%)
+
+### Next Steps
+- FOLLOW-UP skipped: no actionable findings requiring new backlog tasks.

SPECS/ARCHIVE/INDEX.md

@@ -84,6 +84,7 @@
 | FU-P9-T4-1 | [FU-P9-T4-1_Align_publish_helper_output_with_protected_main_branch_workflow/](FU-P9-T4-1_Align_publish_helper_output_with_protected_main_branch_workflow/) | 2026-02-13 | PASS |
 | FU-P9-T2-2 | [FU-P9-T2-2_Add_troubleshooting_guidance_for_stale_uvx_cache_process_versions/](FU-P9-T2-2_Add_troubleshooting_guidance_for_stale_uvx_cache_process_versions/) | 2026-02-13 | PASS |
 | BUG-T2 | [BUG-T2_codex_mcp_add_with_Web_UI_extras_fails_in_zsh/](BUG-T2_codex_mcp_add_with_Web_UI_extras_fails_in_zsh/) | 2026-02-14 | PASS |
+| BUG-T3 | [BUG-T3_webui_only_dashboard_mode/](BUG-T3_webui_only_dashboard_mode/) | 2026-02-14 | PASS |
 
 ## Historical Artifacts
 
@@ -133,6 +134,7 @@
 | [REVIEW_fu_p9_t4_1_publish_helper_protected_main.md](FU-P9-T4-1_Align_publish_helper_output_with_protected_main_branch_workflow/REVIEW_fu_p9_t4_1_publish_helper_protected_main.md) | Review report for FU-P9-T4-1 |
 | [REVIEW_fu_p9_t2_2_stale_uvx_troubleshooting.md](FU-P9-T2-2_Add_troubleshooting_guidance_for_stale_uvx_cache_process_versions/REVIEW_fu_p9_t2_2_stale_uvx_troubleshooting.md) | Review report for FU-P9-T2-2 |
 | [REVIEW_BUG-T2_zsh_webui_extras.md](BUG-T2_codex_mcp_add_with_Web_UI_extras_fails_in_zsh/REVIEW_BUG-T2_zsh_webui_extras.md) | Review report for BUG-T2 |
+| [REVIEW_BUG-T3_webui_only_mode.md](BUG-T3_webui_only_dashboard_mode/REVIEW_BUG-T3_webui_only_mode.md) | Review report for BUG-T3 |
 
 ## Archive Log
 
@@ -220,3 +222,5 @@
 | 2026-02-13 | FU-P9-T4-1 | Archived REVIEW_fu_p9_t4_1_publish_helper_protected_main report |
 | 2026-02-14 | BUG-T2 | Archived codex_mcp_add_with_Web_UI_extras_fails_in_zsh (PASS) |
 | 2026-02-14 | BUG-T2 | Archived REVIEW_BUG-T2_zsh_webui_extras report |
+| 2026-02-14 | BUG-T3 | Archived webui_only_dashboard_mode (PASS) |
+| 2026-02-14 | BUG-T3 | Archived REVIEW_BUG-T3_webui_only_mode report |

SPECS/INPROGRESS/next.md

@@ -4,6 +4,7 @@ The previously selected task has been archived.
 
 ## Recently Archived
 
+- 2026-02-14 — BUG-T3: Web UI cannot stay available when MCP bridge initialization fails (PASS)
 - 2026-02-14 — BUG-T2: codex mcp add with Web UI extras fails in zsh (PASS)
 - 2026-02-13 — FU-P9-T2-2: Add troubleshooting guidance for stale uvx cache/process versions (PASS)
 - 2026-02-13 — FU-P9-T4-1: Align publish_helper output with protected main branch workflow (PASS)