Merge pull request #13 from SoundBlaster/feature/FU-REBUILD-P10-T1-4-web-ui-args-examples

P10-T1-4 Add web UI args examples

Author: SoundBlaster

README.md

@@ -148,6 +148,25 @@ Edit `~/.cursor/mcp.json`:
 }
 ```
 
+**Using uvx with Web UI (Optional):**
+```json
+{
+  "mcpServers": {
+    "xcode-tools": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "mcpbridge-wrapper",
+        "mcpbridge-wrapper",
+        "--web-ui",
+        "--web-ui-port",
+        "8080"
+      ]
+    }
+  }
+}
+```
+
 **Using manual installation:**
 
 ```json
@@ -161,6 +180,18 @@ Edit `~/.cursor/mcp.json`:
 }
 ```
 
+**Using manual installation with Web UI (Optional):**
+```json
+{
+  "mcpServers": {
+    "xcode-tools": {
+      "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
+      "args": ["--web-ui", "--web-ui-port", "8080"]
+    }
+  }
+}
+```
+
 #### Claude Code
 
 **Using uvx (Recommended):**
@@ -169,12 +200,22 @@ Edit `~/.cursor/mcp.json`:
 claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper
 ```
 
+**Using uvx with Web UI (Optional):**
+```bash
+claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --web-ui --web-ui-port 8080
+```
+
 **Using manual installation:**
 
 ```bash
 claude mcp add --transport stdio xcode -- ~/bin/xcodemcpwrapper
 ```
 
+**Using manual installation with Web UI (Optional):**
+```bash
+claude mcp add --transport stdio xcode -- ~/bin/xcodemcpwrapper --web-ui --web-ui-port 8080
+```
+
 #### Codex CLI
 
 **Using uvx (Recommended):**
@@ -183,12 +224,22 @@ claude mcp add --transport stdio xcode -- ~/bin/xcodemcpwrapper
 codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper
 ```
 
+**Using uvx with Web UI (Optional):**
+```bash
+codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --web-ui --web-ui-port 8080
+```
+
 **Using manual installation:**
 
 ```bash
 codex mcp add xcode -- ~/bin/xcodemcpwrapper
 ```
 
+**Using manual installation with Web UI (Optional):**
+```bash
+codex mcp add xcode -- ~/bin/xcodemcpwrapper --web-ui --web-ui-port 8080
+```
+
 #### Zed Agent
 
 **Using uvx (Recommended):**
@@ -205,6 +256,24 @@ Edit `~/.zed/settings.json`:
 }
 ```
 
+**Using uvx with Web UI (Optional):**
+```json
+{
+  "xcode-tools": {
+    "command": "uvx",
+    "args": [
+      "--from",
+      "mcpbridge-wrapper",
+      "mcpbridge-wrapper",
+      "--web-ui",
+      "--web-ui-port",
+      "8080"
+    ],
+    "env": {}
+  }
+}
+```
+
 **Using manual installation:**
 
 ```json
@@ -217,6 +286,17 @@ Edit `~/.zed/settings.json`:
 }
 ```
 
+**Using manual installation with Web UI (Optional):**
+```json
+{
+  "xcode-tools": {
+    "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
+    "args": ["--web-ui", "--web-ui-port", "8080"],
+    "env": {}
+  }
+}
+```
+
 #### Kimi CLI
 
 **Using uvx (Recommended):**

SPECS/ARCHIVE/FU-REBUILD-P10-T1-4_Add_Web_UI_Argument_Examples_for_Client_Configs/FOLLOWUP_FU-REBUILD-P10-T1-4_Web_UI_Docs_Coverage.md

@@ -0,0 +1,11 @@
+# FOLLOW-UP — FU-REBUILD-P10-T1-4 Web UI Docs Coverage
+
+## Source Review
+- `SPECS/INPROGRESS/REVIEW_FU-REBUILD-P10-T1-4_Web_UI_Docs_Coverage.md`
+
+## Result
+- No actionable issues were identified in review.
+- No new backlog tasks added to `SPECS/Workplan.md`.
+
+## Decision
+- FOLLOW-UP step is complete with no additional tasks.

SPECS/ARCHIVE/FU-REBUILD-P10-T1-4_Add_Web_UI_Argument_Examples_for_Client_Configs/FU-REBUILD-P10-T1-4_Add_Web_UI_Argument_Examples_for_Client_Configs.md

@@ -0,0 +1,56 @@
+# PRD — FU-REBUILD-P10-T1-4 Add Web UI Argument Examples for Client Configs
+
+## Objective Summary
+The goal of this follow-up task is to close the documentation gap for enabling the optional Web UI dashboard when configuring MCP clients. Existing docs and config examples show the base wrapper command but do not consistently include argument examples for `--web-ui` and `--web-ui-port`. This creates avoidable setup friction for users who want audit logs, live metrics, and request inspection from day one.
+
+This task updates client-facing configuration examples for Zed, Cursor, Claude Code, and Codex CLI so each client has an explicit “with Web UI” variant. Examples must be copy/paste-ready, consistent with actual wrapper CLI options, and aligned with current configuration formats used in this repository (`json` snippets for Zed/Cursor and command-line examples for Claude/Codex).
+
+The deliverable is documentation/config updates only; runtime behavior is already implemented and out of scope for code changes.
+
+## Success Criteria and Acceptance Tests
+- Each target client has a concrete Web UI-enabled example that includes both `--web-ui` and `--web-ui-port`.
+- No existing non-Web-UI examples are removed; Web UI usage is additive and clearly labeled optional.
+- Examples are syntactically valid for each client’s expected format.
+- README and docs remain internally consistent (same flags, same option spelling, no contradictory guidance).
+
+Acceptance tests:
+1. Search-based verification confirms all four clients expose Web UI example usage.
+2. Manual snippet review confirms command argument placement is correct per client format.
+3. `pytest`, `ruff check src/`, `mypy src/`, and `pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` all pass.
+
+## Test-First Plan
+1. Add/adjust docs assertions through deterministic checks:
+   - `rg` checks for each client and each flag (`--web-ui`, `--web-ui-port`).
+2. Make minimal doc/config edits needed to satisfy checks.
+3. Re-run search checks and standard quality gates.
+
+## Hierarchical TODO Plan
+### Phase A — Baseline and Scope Validation
+- **Inputs:** `README.md`, `docs/*setup.md`, `config/*` examples.
+- **Outputs:** Gap list showing where Web UI argument examples are missing.
+- **Verification:** `rg` output demonstrates pre-change absence or incompleteness.
+
+### Phase B — Implement Documentation and Config Updates
+- **Inputs:** Gap list from Phase A.
+- **Outputs:** Updated snippets for Zed, Cursor, Claude Code, and Codex CLI showing Web UI variants.
+- **Verification:** Render/read each snippet for correctness and consistency of flag usage.
+
+### Phase C — Validate and Record Evidence
+- **Inputs:** Updated files.
+- **Outputs:** Passing quality gates and a validation report at `SPECS/INPROGRESS/FU-REBUILD-P10-T1-4_Validation_Report.md`.
+- **Verification:** Command outputs captured in report with PASS/PARTIAL/FAIL verdict.
+
+## Decision Points and Constraints
+- Keep defaults unchanged: Web UI remains optional and opt-in.
+- Use a single illustrative port (8080) unless an existing file already uses another standard.
+- Avoid introducing client-specific behavior claims not backed by existing project behavior.
+
+## Notes
+After implementation, ensure these references remain aligned:
+- `README.md` client sections
+- `docs/cursor-setup.md`, `docs/claude-setup.md`, `docs/codex-setup.md`
+- `config/cursor-mcp.json`, `config/claude-code.txt`, `config/codex-cli.txt`, `config/zed-agent.json`
+
+---
+**Archived:** 2026-02-11
+**Verdict:** PASS

SPECS/ARCHIVE/FU-REBUILD-P10-T1-4_Add_Web_UI_Argument_Examples_for_Client_Configs/FU-REBUILD-P10-T1-4_Validation_Report.md

@@ -0,0 +1,67 @@
+# Validation Report — FU-REBUILD-P10-T1-4
+
+**Task:** Add Web UI Argument Examples for Client Configs
+**Date:** 2026-02-11
+**Verdict:** PASS
+
+## Scope
+Validated documentation and configuration updates adding optional Web UI examples for:
+- Zed Agent
+- Cursor
+- Claude Code
+- Codex CLI
+
+## Change Verification
+
+### 1. Web UI argument coverage in target files
+Command:
+```bash
+rg -n -e "--web-ui" -e "--web-ui-port" README.md docs/cursor-setup.md docs/claude-setup.md docs/codex-setup.md config/cursor-mcp.json config/zed-agent.json config/claude-code.txt config/codex-cli.txt
+```
+
+Result: PASS
+- Matches found across all targeted docs/config files for both `--web-ui` and `--web-ui-port`.
+
+## Required Quality Gates
+
+### 2. Test suite
+Command:
+```bash
+pytest
+```
+Result: PASS
+- `202 passed, 5 skipped`
+
+### 3. Linting
+Command:
+```bash
+ruff check src/
+```
+Result: PASS
+- `All checks passed!`
+
+### 4. Type checking
+Command:
+```bash
+mypy src/
+```
+Result: PASS
+- `Success: no issues found in 5 source files`
+
+### 5. Coverage
+Command:
+```bash
+pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing
+```
+Result: PASS
+- `TOTAL 95.0%`
+- Requirement `>=90%` satisfied.
+
+## Acceptance Criteria Mapping
+- Web UI examples include both flags for all required clients: PASS
+- Existing base examples preserved as optional/additive variants: PASS
+- Examples syntactically match each client format (JSON vs CLI): PASS
+- Cross-doc consistency of flags and port example (`8080`): PASS
+
+## Notes
+- No source code behavior changes were required; this task is documentation/configuration only.

SPECS/ARCHIVE/FU-REBUILD-P10-T1-4_Add_Web_UI_Argument_Examples_for_Client_Configs/REVIEW_FU-REBUILD-P10-T1-4_Web_UI_Docs_Coverage.md

@@ -0,0 +1,30 @@
+## REVIEW REPORT — FU-REBUILD-P10-T1-4 Web UI Docs Coverage
+
+**Scope:** origin/main..HEAD
+**Files:** 13
+
+### Summary Verdict
+- [x] Approve
+- [ ] Approve with comments
+- [ ] Request changes
+- [ ] Block
+
+### Critical Issues
+- None.
+
+### Secondary Issues
+- None.
+
+### Architectural Notes
+- Documentation and template changes are consistent with current CLI behavior and keep Web UI as an optional additive path. Existing non-Web-UI examples remain intact.
+
+### Tests
+- `pytest`: PASS (`202 passed, 5 skipped`)
+- `ruff check src/`: PASS
+- `mypy src/`: PASS
+- `pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing`: PASS (95.04%, >=90%)
+- Residual risk: this is a docs/config task, so no runtime regressions are expected; command examples rely on CLI flag stability.
+
+### Next Steps
+- No actionable follow-up tasks required.
+- Proceed to archive this review artifact under `_Historical` per FLOW `ARCHIVE-REVIEW` step.

SPECS/ARCHIVE/INDEX.md

@@ -69,6 +69,7 @@
 | FU-REBUILD-P10-T1-1 | [FU-REBUILD-P10-T1-1_Align_WebSocket_Auth_Flow/](FU-REBUILD-P10-T1-1_Align_WebSocket_Auth_Flow/) | 2026-02-10 | PASS |
 | FU-REBUILD-P10-T1-2 | [FU-REBUILD-P10-T1-2_Validate_WebUI_Port_Input/](FU-REBUILD-P10-T1-2_Validate_WebUI_Port_Input/) | 2026-02-10 | PASS |
 | FU-REBUILD-P10-T1-3 | [FU-REBUILD-P10-T1-3_Reconcile_WebUI_Env_Docs/](FU-REBUILD-P10-T1-3_Reconcile_WebUI_Env_Docs/) | 2026-02-10 | PASS |
+| FU-REBUILD-P10-T1-4 | [FU-REBUILD-P10-T1-4_Add_Web_UI_Argument_Examples_for_Client_Configs/](FU-REBUILD-P10-T1-4_Add_Web_UI_Argument_Examples_for_Client_Configs/) | 2026-02-11 | PASS |
 
 ## Historical Artifacts
 
@@ -99,6 +100,8 @@
 | [P5-T1_Create_Unit_Test_Framework_PRD.md](_Historical/P5-T1_Create_Unit_Test_Framework_PRD.md) | Historical PRD source file for P5-T1 |
 | [P5-T1_validation_report.md](_Historical/P5-T1_validation_report.md) | Historical validation report source file for P5-T1 |
 | [Web_UI_Debugging_Summary.md](_Historical/Web_UI_Debugging_Summary.md) | Web UI debugging summary moved from INPROGRESS |
+| [REVIEW_FU-REBUILD-P10-T1-4_Web_UI_Docs_Coverage.md](FU-REBUILD-P10-T1-4_Add_Web_UI_Argument_Examples_for_Client_Configs/REVIEW_FU-REBUILD-P10-T1-4_Web_UI_Docs_Coverage.md) | Review report for FU-REBUILD-P10-T1-4 |
+| [FOLLOWUP_FU-REBUILD-P10-T1-4_Web_UI_Docs_Coverage.md](FU-REBUILD-P10-T1-4_Add_Web_UI_Argument_Examples_for_Client_Configs/FOLLOWUP_FU-REBUILD-P10-T1-4_Web_UI_Docs_Coverage.md) | Follow-up report for FU-REBUILD-P10-T1-4 |
 
 ## Archive Log
 
@@ -154,3 +157,5 @@
 | 2026-02-11 | P5-T1 | Archived historical artifacts (PRD and validation source files) |
 | 2026-02-11 | P4-T9 | Archived Handle_Large_JSON_Responses (PASS) |
 | 2026-02-11 | HISTORICAL | Archived Web_UI_Debugging_Summary.md to _Historical |
+| 2026-02-11 | FU-REBUILD-P10-T1-4 | Archived Add_Web_UI_Argument_Examples_for_Client_Configs (PASS) |
+| 2026-02-11 | FU-REBUILD-P10-T1-4 | Archived REVIEW_FU-REBUILD-P10-T1-4_Web_UI_Docs_Coverage report |

SPECS/INPROGRESS/next.md

@@ -1,15 +1,11 @@
-# Next Task: FU-REBUILD-P10-T1-4 — Add Web UI Argument Examples for Client Configs
+# No Active Task
 
-**Priority:** P2
-**Phase:** Rebuild Follow-up Backlog (Phase 10)
-**Effort:** 1-2 hours
-**Dependencies:** FU-REBUILD-P10-T1-1, FU-REBUILD-P10-T1-2, FU-REBUILD-P10-T1-3
-**Status:** Selected
+The previously selected task has been archived.
 
-## Description
+## Recently Archived
 
-Add Web UI argument examples for client configs (Zed, Cursor, Claude Code, Codex CLI), including `--web-ui` and `--web-ui-port` usage.
+- 2026-02-11 — FU-REBUILD-P10-T1-4: Add Web UI Argument Examples for Client Configs (PASS)
 
-## Next Step
+## Suggested Next Tasks
 
-Run the PLAN command to generate the implementation-ready PRD.
+- Run SELECT to identify the next available task from `SPECS/Workplan.md`.

SPECS/Workplan.md

@@ -1163,6 +1163,7 @@ Completion criteria:
 Post-Completion Validation:
 - [x] P8-T3 validated: Installation with new path `xcodemcpwrapper` tested successfully
 - [x] Client compatibility verified: Zed Agent ✅, Cursor ✅, Claude Code ✅, Codex CLI ✅
+- [x] FU-REBUILD-P10-T1-4 completed: Web UI argument examples documented for Zed, Cursor, Claude Code, and Codex CLI (2026-02-11)
 - [ ] Known issue documented: Kimi CLI v1.9.0 has MCP connection issues (BUG-T1)
 
 Phase 10: Web UI Dashboard

config/claude-code.txt

@@ -6,6 +6,12 @@
 #
 #   claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper
 #
+# OPTION 1B: Using uvx with Web UI (Optional)
+# -------------------------------------------
+# Enable the Web UI dashboard on port 8080:
+#
+#   claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --web-ui --web-ui-port 8080
+#
 # To install uv (which includes uvx):
 #   curl -LsSf https://astral.sh/uv/install.sh | sh
 #   or: brew install uv
@@ -17,6 +23,12 @@
 #
 #   claude mcp add --transport stdio xcode -- /Users/USERNAME/bin/xcodemcpwrapper
 #
+# OPTION 2B: Manual Installation with Web UI (Optional)
+# -----------------------------------------------------
+# Enable the Web UI dashboard on port 8080:
+#
+#   claude mcp add --transport stdio xcode -- /Users/USERNAME/bin/xcodemcpwrapper --web-ui --web-ui-port 8080
+#
 #
 # Verification:
 #   claude mcp list