From 5acc964bd5ccd7921dc848382b1c097cba34fc2b Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Thu, 12 Feb 2026 22:54:25 +0300 Subject: [PATCH 01/10] Add follow-up task for Web UI install mismatch --- SPECS/Workplan.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index f54d188b..23341b44 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -866,6 +866,7 @@ Create a Python-based protocol compatibility wrapper that intercepts MCP respons Phase 8 Follow-up Backlog - [ ] FU-P8-T1-1: Reconcile P8-T1 URL criteria with current GitHub Pages path and resolve DocC reference warnings (P2) +- [ ] FU-P6-T10-1: Align manual install script with Web UI configuration expectations (P1) #### FU-P8-T1-1: Reconcile P8-T1 URL criteria with current GitHub Pages path and resolve DocC reference warnings - **Description:** Review follow-up to align Phase 8 tracking artifacts with the live documentation URL `soundblaster.github.io/XcodeMCPWrapper/` and remove remaining DocC ambiguity warnings in the Phase 8 documentation index. @@ -879,7 +880,25 @@ Phase 8 Follow-up Backlog - **Acceptance Criteria:** - Workplan Phase 8 no longer references the legacy `/mcpbridge-wrapper` GitHub Pages URL as the active deployment URL - Phase 8 review/validation artifacts clearly document that the active URL is `soundblaster.github.io/XcodeMCPWrapper/` - - `swift package generate-documentation --target XcodeMCPWrapper` completes without `Architecture` ambiguity warnings +- `swift package generate-documentation --target XcodeMCPWrapper` completes without `Architecture` ambiguity warnings + +#### FU-P6-T10-1: Align manual install script with Web UI configuration expectations +- **Description:** Fix the mismatch where `scripts/install.sh` installs only the base package (`pip install -e .`) while docs/config examples allow `--web-ui` usage from `~/bin/xcodemcpwrapper`. This causes runtime failure when users enable Web UI without optional dependencies. Add an explicit installer mode for Web UI extras and update documentation to make the dependency requirement unambiguous. +- **Priority:** P1 +- **Dependencies:** P6-T3, P10-T1 +- **Parallelizable:** yes +- **Outputs/Artifacts:** + - Updated `scripts/install.sh` with Web UI-aware install option (e.g., `--webui`) that installs `-e ".[webui]"` + - Updated `README.md` and `docs/installation.md` with clear mapping: + - base install => no `--web-ui` args + - webui install => `--web-ui` args supported + - Updated `docs/troubleshooting.md` to include this specific symptom/cause/fix path +- **Acceptance Criteria:** + - Running `./scripts/install.sh` (default) keeps current base behavior and works with no Web UI args + - Running `./scripts/install.sh --webui` installs required Web UI dependencies (`fastapi`, `uvicorn`, etc.) + - `~/bin/xcodemcpwrapper --web-ui --web-ui-port 8080 --help` no longer fails after Web UI install mode + - Zed/Cursor configs that include `--web-ui` work when installer is run with Web UI mode + - Documentation examples do not imply Web UI works on base-only install --- From bceb9383bc62e4f2e24ba9f259a48bbb2dad7a6c Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Thu, 12 Feb 2026 22:56:24 +0300 Subject: [PATCH 02/10] Branch for FU-P6-T10-1: align manual install with web ui expectations From 6890b680fd2905748636c1420bb58b90a61957ec Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Thu, 12 Feb 2026 22:56:24 +0300 Subject: [PATCH 03/10] Select task FU-P6-T10-1: Align manual install script with Web UI configuration expectations --- SPECS/INPROGRESS/next.md | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index 5d9e26ca..a68b9faf 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,14 +1,23 @@ -# No Active Task +# Active Task -The previously selected task has been archived. +- **Task ID:** FU-P6-T10-1 +- **Title:** Align manual install script with Web UI configuration expectations +- **Priority:** P1 +- **Phase:** Follow-up Backlog +- **Dependencies:** P6-T3, P10-T1 +- **Status:** In Progress +- **Started:** 2026-02-12 + +## Objective +Add an explicit Web UI install mode to `scripts/install.sh` and align docs so Web UI args are only shown for environments with `.[webui]` dependencies installed. + +## Next Actions +1. Add `--webui` option to install script (`pip install -e ".[webui]"`). +2. Update installation and troubleshooting docs with base vs Web UI mapping. +3. Validate behavior with/without Web UI extras and capture report. ## Recently Archived - 2026-02-12 — P7-T12: Move Cursor IDE uvx settings before installation instructions in README (PASS) - 2026-02-12 — FU-REBUILD-P10-T1-6: Fix uninstall.sh package detection/removal asymmetry and venv cleanup (PASS) - 2026-02-11 — FU-REBUILD-P10-T1-5: Validate and fix documentation paths for local-running MCP server with Web UI (PASS) - -## Suggested Next Tasks - -- FU-P8-T1-1: Reconcile P8-T1 URL criteria with current GitHub Pages path and resolve DocC reference warnings (P2) -- Run SELECT after adding new tasks to the workplan. From ed0ba965fea9a2fc6320b490e9a6e2d85915c46f Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Thu, 12 Feb 2026 22:56:24 +0300 Subject: [PATCH 04/10] Plan task FU-P6-T10-1: Align manual install script with Web UI configuration expectations --- ..._with_Web_UI_configuration_expectations.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 SPECS/INPROGRESS/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations.md diff --git a/SPECS/INPROGRESS/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations.md b/SPECS/INPROGRESS/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations.md new file mode 100644 index 00000000..b0c5aa18 --- /dev/null +++ b/SPECS/INPROGRESS/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations.md @@ -0,0 +1,28 @@ +# FU-P6-T10-1 — Align manual install script with Web UI configuration expectations + +**Priority:** P1 +**Dependencies:** P6-T3, P10-T1 +**Phase:** Follow-up Backlog + +## Objective +Eliminate the installation mismatch where `scripts/install.sh` installs only base dependencies while users can copy configs that enable `--web-ui`, causing runtime ImportError for missing Web UI packages. + +## Deliverables +1. `scripts/install.sh` supports explicit Web UI install mode via `--webui`. +2. `README.md` and `docs/installation.md` clearly map: + - base install => no `--web-ui` args + - webui install => `--web-ui` args supported +3. `docs/troubleshooting.md` includes symptom/cause/fix for this mismatch. +4. Validation report records command-level verification. + +## Acceptance Criteria +1. `./scripts/install.sh` keeps base install behavior by default. +2. `./scripts/install.sh --webui` installs `-e ".[webui]"` dependencies. +3. `xcodemcpwrapper --web-ui --web-ui-port 8080 --help` does not fail after Web UI install mode. +4. Documentation no longer implies Web UI works on base-only install. + +## Execution Plan +1. Extend installer argument parsing and install command selection. +2. Update docs in focused sections only (no broad restructuring). +3. Run quality gates plus targeted runtime checks. +4. Produce `SPECS/INPROGRESS/FU-P6-T10-1_Validation_Report.md`. From c8e7c07fbe6863eb77bd3b61f85c0a9c2569bd7b Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Thu, 12 Feb 2026 22:58:15 +0300 Subject: [PATCH 05/10] Implement FU-P6-T10-1: add webui install mode and clarify docs --- README.md | 10 ++++ .../FU-P6-T10-1_Validation_Report.md | 48 +++++++++++++++++++ docs/installation.md | 8 ++++ docs/troubleshooting.md | 15 ++++++ scripts/install.sh | 44 ++++++++++++++++- 5 files changed, 123 insertions(+), 2 deletions(-) create mode 100644 SPECS/INPROGRESS/FU-P6-T10-1_Validation_Report.md diff --git a/README.md b/README.md index 6126bc54..beb67979 100644 --- a/README.md +++ b/README.md @@ -142,6 +142,12 @@ cd XcodeMCPWrapper The install script creates a virtual environment, installs the package, and places a wrapper at `~/bin/xcodemcpwrapper`. +If you plan to use `--web-ui` MCP args, install Web UI extras explicitly: + +```bash +./scripts/install.sh --webui +``` + Add the following to your `~/.bashrc` or `~/.zshrc`: ```bash export PATH="$HOME/bin:$PATH" @@ -200,6 +206,7 @@ For **uvx** setup (recommended), see [Cursor Quick Setup](#cursor-quick-setup) a ``` **Using manual installation with Web UI (Optional):** +> Requires installing with `./scripts/install.sh --webui` (or equivalent `.[webui]` dependencies). ```json { "mcpServers": { @@ -254,6 +261,7 @@ claude mcp add --transport stdio xcode -- ~/bin/xcodemcpwrapper ``` **Using manual installation with Web UI (Optional):** +Requires installing with `./scripts/install.sh --webui` (or equivalent `.[webui]` dependencies). ```bash claude mcp add --transport stdio xcode -- ~/bin/xcodemcpwrapper --web-ui --web-ui-port 8080 ``` @@ -288,6 +296,7 @@ codex mcp add xcode -- ~/bin/xcodemcpwrapper ``` **Using manual installation with Web UI (Optional):** +Requires installing with `./scripts/install.sh --webui` (or equivalent `.[webui]` dependencies). ```bash codex mcp add xcode -- ~/bin/xcodemcpwrapper --web-ui --web-ui-port 8080 ``` @@ -349,6 +358,7 @@ Edit `~/.zed/settings.json`: ``` **Using manual installation with Web UI (Optional):** +Requires installing with `./scripts/install.sh --webui` (or equivalent `.[webui]` dependencies). ```json { "xcode-tools": { diff --git a/SPECS/INPROGRESS/FU-P6-T10-1_Validation_Report.md b/SPECS/INPROGRESS/FU-P6-T10-1_Validation_Report.md new file mode 100644 index 00000000..1033e11f --- /dev/null +++ b/SPECS/INPROGRESS/FU-P6-T10-1_Validation_Report.md @@ -0,0 +1,48 @@ +# FU-P6-T10-1 Validation Report + +**Task:** Align manual install script with Web UI configuration expectations +**Date:** 2026-02-12 +**Verdict:** PASS + +## Changes Implemented + +1. Added Web UI install mode to `scripts/install.sh`: + - `--webui` flag support + - `--help` output and unknown-arg validation + - Base install remains default (`pip install -e .`) + - Web UI mode installs extras (`pip install -e ".[webui]"`) + - Post-install guidance now states whether Web UI extras are present + +2. Updated docs to prevent base/Web UI ambiguity: + - `README.md`: manual install section now documents `./scripts/install.sh --webui` + - `README.md`: manual Web UI config snippets now explicitly require Web UI extras + - `docs/installation.md`: Option D now documents base vs `--webui` mode + - `docs/troubleshooting.md`: added dedicated symptom/cause/fix for missing Web UI deps (`uvicorn` import error) + +## Acceptance Criteria Check + +| Criteria | Status | Evidence | +|---|---|---| +| Default `./scripts/install.sh` keeps base behavior | PASS | Installer runs successfully and prints base-only note | +| `./scripts/install.sh --webui` installs Web UI extras | PASS | Installer runs in Web UI mode and prints Web UI deps installed message | +| `xcodemcpwrapper --web-ui --web-ui-port 8080 --help` works in Web UI install mode | PASS | Command exits successfully after `--webui` install | +| Docs no longer imply Web UI works on base-only install | PASS | README/installation/troubleshooting updated with explicit dependency mapping | + +## Quality Gates + +Environment note: +- Initial `pytest` run with global interpreter failed (`ModuleNotFoundError: mcpbridge_wrapper`). +- Quality gates were rerun in project venv after installing dev/webui extras. + +Results in `.venv`: +- `python -m pytest` → **324 passed, 5 skipped** +- `python -m ruff check src/` → **All checks passed** +- `python -m mypy src/` → **Success: no issues found** +- `python -m pytest --cov` → **Coverage 96.62%** (>= 90% requirement) + +## Files Modified + +- `scripts/install.sh` +- `README.md` +- `docs/installation.md` +- `docs/troubleshooting.md` diff --git a/docs/installation.md b/docs/installation.md index dfaacb85..3e7ec13d 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -97,12 +97,20 @@ cd XcodeMCPWrapper ./scripts/install.sh ``` +If you need Web UI support for `--web-ui` args, install with: + +```bash +./scripts/install.sh --webui +``` + This will: - Create a virtual environment (`.venv`) if not already active - Install the package into the venv - Create `~/bin/xcodemcpwrapper` wrapper with the correct Python interpreter - Make `xcodemcpwrapper` available in your PATH +Default `./scripts/install.sh` is base-only (no Web UI extras). + Add the following to your `~/.bashrc` or `~/.zshrc`: ```bash export PATH="$HOME/bin:$PATH" diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index f254131a..193f3936 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -150,6 +150,21 @@ Then reload: source ~/.zshrc # or ~/.bashrc ``` +### "Web UI dependencies not installed" / `ModuleNotFoundError: uvicorn` + +**Symptom:** Wrapper exits when client config includes `--web-ui` args. + +**Cause:** Manual install used base mode (`./scripts/install.sh`), but Web UI args require optional `.[webui]` dependencies. + +**Solution:** +```bash +cd /path/to/XcodeMCPWrapper +./scripts/install.sh --webui +``` + +Then restart your MCP client. +If you do not need Web UI, remove `--web-ui` and `--web-ui-port` from MCP config args. + ## Debug Mode For verbose output, check the stderr stream: diff --git a/scripts/install.sh b/scripts/install.sh index 86a2522e..0760cef4 100755 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -8,6 +8,31 @@ set -e +INSTALL_WEBUI=false + +for arg in "$@"; do + case "$arg" in + --webui) + INSTALL_WEBUI=true + ;; + -h|--help) + cat << 'EOF' +Usage: ./scripts/install.sh [--webui] + +Options: + --webui Install optional Web UI dependencies (fastapi/uvicorn/etc) + -h, --help Show this help message +EOF + exit 0 + ;; + *) + echo -e "${RED}Error: Unknown option '$arg'${NC}" + echo "Run ./scripts/install.sh --help for usage." + exit 1 + ;; + esac +done + # Colors for output RED='\033[0;31m' GREEN='\033[0;32m' @@ -62,9 +87,17 @@ fi PYTHON_BIN="$(which python3)" # Install using pip (inside venv) -echo "Installing xcodemcpwrapper..." +if [ "$INSTALL_WEBUI" = true ]; then + echo "Installing xcodemcpwrapper with Web UI dependencies..." +else + echo "Installing xcodemcpwrapper..." +fi cd "$PROJECT_ROOT" -python3 -m pip install -e . --quiet +if [ "$INSTALL_WEBUI" = true ]; then + python3 -m pip install -e ".[webui]" --quiet +else + python3 -m pip install -e . --quiet +fi # Create wrapper script in ~/bin that uses the venv Python cat > "$INSTALL_DIR/xcodemcpwrapper" << WRAPPER @@ -91,6 +124,13 @@ fi echo "" echo "Installation complete!" +if [ "$INSTALL_WEBUI" = true ]; then + echo -e "${GREEN}✓ Web UI dependencies installed (use --web-ui args in MCP client config)${NC}" +else + echo -e "${YELLOW}Note: Installed without Web UI extras.${NC}" + echo " If you want to use --web-ui args, reinstall with:" + echo " ./scripts/install.sh --webui" +fi echo "" echo "Next steps:" echo " 1. Ensure Xcode 26.3+ is installed" From 1d399509ad0d2dde01d971e483f9fabfc256138f Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Thu, 12 Feb 2026 22:59:09 +0300 Subject: [PATCH 06/10] Archive task FU-P6-T10-1: Align manual install script with Web UI configuration expectations (PASS) --- ..._with_Web_UI_configuration_expectations.md | 4 ++++ .../FU-P6-T10-1_Validation_Report.md | 0 SPECS/ARCHIVE/INDEX.md | 2 ++ SPECS/INPROGRESS/next.md | 24 +++++++------------ SPECS/Workplan.md | 4 ++-- 5 files changed, 16 insertions(+), 18 deletions(-) rename SPECS/{INPROGRESS => ARCHIVE/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations}/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations.md (96%) rename SPECS/{INPROGRESS => ARCHIVE/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations}/FU-P6-T10-1_Validation_Report.md (100%) diff --git a/SPECS/INPROGRESS/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations.md b/SPECS/ARCHIVE/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations.md similarity index 96% rename from SPECS/INPROGRESS/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations.md rename to SPECS/ARCHIVE/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations.md index b0c5aa18..13c76979 100644 --- a/SPECS/INPROGRESS/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations.md +++ b/SPECS/ARCHIVE/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations.md @@ -26,3 +26,7 @@ Eliminate the installation mismatch where `scripts/install.sh` installs only bas 2. Update docs in focused sections only (no broad restructuring). 3. Run quality gates plus targeted runtime checks. 4. Produce `SPECS/INPROGRESS/FU-P6-T10-1_Validation_Report.md`. + +--- +**Archived:** 2026-02-12 +**Verdict:** PASS diff --git a/SPECS/INPROGRESS/FU-P6-T10-1_Validation_Report.md b/SPECS/ARCHIVE/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations/FU-P6-T10-1_Validation_Report.md similarity index 100% rename from SPECS/INPROGRESS/FU-P6-T10-1_Validation_Report.md rename to SPECS/ARCHIVE/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations/FU-P6-T10-1_Validation_Report.md diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index 66e39761..5f3c8a78 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -74,6 +74,7 @@ | FU-REBUILD-P10-T1-5 | [FU-REBUILD-P10-T1-5_Validate_Documentation_Paths/](FU-REBUILD-P10-T1-5_Validate_Documentation_Paths/) | 2026-02-11 | PASS | | FU-REBUILD-P10-T1-6 | [FU-REBUILD-P10-T1-6_Fix_Uninstall_Asymmetry/](FU-REBUILD-P10-T1-6_Fix_Uninstall_Asymmetry/) | 2026-02-12 | PASS | | P7-T12 | [P7-T12_Move_Cursor_UVX_Before_Installation/](P7-T12_Move_Cursor_UVX_Before_Installation/) | 2026-02-12 | PASS | +| FU-P6-T10-1 | [FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations/](FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations/) | 2026-02-12 | PASS | ## Historical Artifacts @@ -178,3 +179,4 @@ | 2026-02-12 | FU-REBUILD-P10-T1-6 | Archived REVIEW_FU-REBUILD-P10-T1-6_Uninstall_Asymmetry report | | 2026-02-12 | P7-T12 | Archived Move_Cursor_UVX_Before_Installation (PASS) | | 2026-02-12 | P7-T12 | Archived REVIEW_P7-T12_Cursor_Quick_Setup report | +| 2026-02-12 | FU-P6-T10-1 | Archived Align_manual_install_script_with_Web_UI_configuration_expectations (PASS) | diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index a68b9faf..09a0b77c 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,23 +1,15 @@ -# Active Task +# No Active Task -- **Task ID:** FU-P6-T10-1 -- **Title:** Align manual install script with Web UI configuration expectations -- **Priority:** P1 -- **Phase:** Follow-up Backlog -- **Dependencies:** P6-T3, P10-T1 -- **Status:** In Progress -- **Started:** 2026-02-12 - -## Objective -Add an explicit Web UI install mode to `scripts/install.sh` and align docs so Web UI args are only shown for environments with `.[webui]` dependencies installed. - -## Next Actions -1. Add `--webui` option to install script (`pip install -e ".[webui]"`). -2. Update installation and troubleshooting docs with base vs Web UI mapping. -3. Validate behavior with/without Web UI extras and capture report. +The previously selected task has been archived. ## Recently Archived +- 2026-02-12 — FU-P6-T10-1: Align manual install script with Web UI configuration expectations (PASS) - 2026-02-12 — P7-T12: Move Cursor IDE uvx settings before installation instructions in README (PASS) - 2026-02-12 — FU-REBUILD-P10-T1-6: Fix uninstall.sh package detection/removal asymmetry and venv cleanup (PASS) - 2026-02-11 — FU-REBUILD-P10-T1-5: Validate and fix documentation paths for local-running MCP server with Web UI (PASS) + +## Suggested Next Tasks + +- FU-P8-T1-1: Reconcile P8-T1 URL criteria with current GitHub Pages path and resolve DocC reference warnings (P2) +- Run SELECT after choosing the next task. diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index 23341b44..9bf04e7a 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -866,7 +866,7 @@ Create a Python-based protocol compatibility wrapper that intercepts MCP respons Phase 8 Follow-up Backlog - [ ] FU-P8-T1-1: Reconcile P8-T1 URL criteria with current GitHub Pages path and resolve DocC reference warnings (P2) -- [ ] FU-P6-T10-1: Align manual install script with Web UI configuration expectations (P1) +- [x] FU-P6-T10-1: Align manual install script with Web UI configuration expectations (P1) #### FU-P8-T1-1: Reconcile P8-T1 URL criteria with current GitHub Pages path and resolve DocC reference warnings - **Description:** Review follow-up to align Phase 8 tracking artifacts with the live documentation URL `soundblaster.github.io/XcodeMCPWrapper/` and remove remaining DocC ambiguity warnings in the Phase 8 documentation index. @@ -882,7 +882,7 @@ Phase 8 Follow-up Backlog - Phase 8 review/validation artifacts clearly document that the active URL is `soundblaster.github.io/XcodeMCPWrapper/` - `swift package generate-documentation --target XcodeMCPWrapper` completes without `Architecture` ambiguity warnings -#### FU-P6-T10-1: Align manual install script with Web UI configuration expectations +#### ✅ FU-P6-T10-1: Align manual install script with Web UI configuration expectations - **Description:** Fix the mismatch where `scripts/install.sh` installs only the base package (`pip install -e .`) while docs/config examples allow `--web-ui` usage from `~/bin/xcodemcpwrapper`. This causes runtime failure when users enable Web UI without optional dependencies. Add an explicit installer mode for Web UI extras and update documentation to make the dependency requirement unambiguous. - **Priority:** P1 - **Dependencies:** P6-T3, P10-T1 From 86dd9aaba14a4f0101a5711e9db96f3e2938180c Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Thu, 12 Feb 2026 22:59:23 +0300 Subject: [PATCH 07/10] Review FU-P6-T10-1: install Web UI alignment --- ...VIEW_FU-P6-T10-1_Install_WebUI_Mismatch.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 SPECS/INPROGRESS/REVIEW_FU-P6-T10-1_Install_WebUI_Mismatch.md diff --git a/SPECS/INPROGRESS/REVIEW_FU-P6-T10-1_Install_WebUI_Mismatch.md b/SPECS/INPROGRESS/REVIEW_FU-P6-T10-1_Install_WebUI_Mismatch.md new file mode 100644 index 00000000..dadb8b5f --- /dev/null +++ b/SPECS/INPROGRESS/REVIEW_FU-P6-T10-1_Install_WebUI_Mismatch.md @@ -0,0 +1,28 @@ +## REVIEW REPORT — FU-P6-T10-1 Install/Web UI Alignment + +**Scope:** origin/main..HEAD +**Files:** 8 + +### Summary Verdict +- [x] Approve +- [ ] Approve with comments +- [ ] Request changes +- [ ] Block + +### Critical Issues +- None. + +### Secondary Issues +- [Low] `scripts/install.sh` now has argument parsing in shell; future flags should preserve backward-compatible default mode and avoid changing current no-arg behavior. + +### Architectural Notes +- Root cause (base install + Web UI args) is now addressed in both installer behavior and docs, reducing client-specific confusion (Zed/Cursor/Claude/Codex). + +### Tests +- `./.venv/bin/python -m pytest` passed +- `./.venv/bin/python -m ruff check src/` passed +- `./.venv/bin/python -m mypy src/` passed +- `./.venv/bin/python -m pytest --cov` passed (96.62%) + +### Next Steps +- No actionable follow-up tasks required from this review. From edd262caa4cbbb22228a539f7c436a11c69353f0 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Thu, 12 Feb 2026 22:59:32 +0300 Subject: [PATCH 08/10] Follow-up FU-P6-T10-1: no additional actions required --- .../FOLLOWUP_FU-P6-T10-1_Install_WebUI_Mismatch.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 SPECS/INPROGRESS/FOLLOWUP_FU-P6-T10-1_Install_WebUI_Mismatch.md diff --git a/SPECS/INPROGRESS/FOLLOWUP_FU-P6-T10-1_Install_WebUI_Mismatch.md b/SPECS/INPROGRESS/FOLLOWUP_FU-P6-T10-1_Install_WebUI_Mismatch.md new file mode 100644 index 00000000..1086c346 --- /dev/null +++ b/SPECS/INPROGRESS/FOLLOWUP_FU-P6-T10-1_Install_WebUI_Mismatch.md @@ -0,0 +1,13 @@ +# FOLLOW-UP — FU-P6-T10-1 Install/Web UI Alignment + +**Parent Task:** FU-P6-T10-1 +**Review File:** REVIEW_FU-P6-T10-1_Install_WebUI_Mismatch.md +**Date:** 2026-02-12 + +## Actionable Findings + +No actionable follow-up tasks were identified. + +## Decision + +FOLLOW-UP step completed with no new workplan tasks added. From 7d76465c58b3862e7caebb13ffef1f7c8baa9454 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Thu, 12 Feb 2026 22:59:55 +0300 Subject: [PATCH 09/10] Archive REVIEW_FU-P6-T10-1_Install_WebUI_Mismatch report --- .../FOLLOWUP_FU-P6-T10-1_Install_WebUI_Mismatch.md | 0 .../REVIEW_FU-P6-T10-1_Install_WebUI_Mismatch.md | 0 SPECS/ARCHIVE/INDEX.md | 4 ++++ 3 files changed, 4 insertions(+) rename SPECS/{INPROGRESS => ARCHIVE/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations}/FOLLOWUP_FU-P6-T10-1_Install_WebUI_Mismatch.md (100%) rename SPECS/{INPROGRESS => ARCHIVE/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations}/REVIEW_FU-P6-T10-1_Install_WebUI_Mismatch.md (100%) diff --git a/SPECS/INPROGRESS/FOLLOWUP_FU-P6-T10-1_Install_WebUI_Mismatch.md b/SPECS/ARCHIVE/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations/FOLLOWUP_FU-P6-T10-1_Install_WebUI_Mismatch.md similarity index 100% rename from SPECS/INPROGRESS/FOLLOWUP_FU-P6-T10-1_Install_WebUI_Mismatch.md rename to SPECS/ARCHIVE/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations/FOLLOWUP_FU-P6-T10-1_Install_WebUI_Mismatch.md diff --git a/SPECS/INPROGRESS/REVIEW_FU-P6-T10-1_Install_WebUI_Mismatch.md b/SPECS/ARCHIVE/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations/REVIEW_FU-P6-T10-1_Install_WebUI_Mismatch.md similarity index 100% rename from SPECS/INPROGRESS/REVIEW_FU-P6-T10-1_Install_WebUI_Mismatch.md rename to SPECS/ARCHIVE/FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations/REVIEW_FU-P6-T10-1_Install_WebUI_Mismatch.md diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index 5f3c8a78..5b54d3c8 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -113,6 +113,8 @@ | [REVIEW_FU-REBUILD-P10-T1-5_Documentation_Paths.md](FU-REBUILD-P10-T1-5_Validate_Documentation_Paths/REVIEW_FU-REBUILD-P10-T1-5_Documentation_Paths.md) | Review report for FU-REBUILD-P10-T1-5 | | [REVIEW_FU-REBUILD-P10-T1-6_Uninstall_Asymmetry.md](FU-REBUILD-P10-T1-6_Fix_Uninstall_Asymmetry/REVIEW_FU-REBUILD-P10-T1-6_Uninstall_Asymmetry.md) | Review report for FU-REBUILD-P10-T1-6 | | [REVIEW_P7-T12_Cursor_Quick_Setup.md](P7-T12_Move_Cursor_UVX_Before_Installation/REVIEW_P7-T12_Cursor_Quick_Setup.md) | Review report for P7-T12 | +| [REVIEW_FU-P6-T10-1_Install_WebUI_Mismatch.md](FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations/REVIEW_FU-P6-T10-1_Install_WebUI_Mismatch.md) | Review report for FU-P6-T10-1 | +| [FOLLOWUP_FU-P6-T10-1_Install_WebUI_Mismatch.md](FU-P6-T10-1_Align_manual_install_script_with_Web_UI_configuration_expectations/FOLLOWUP_FU-P6-T10-1_Install_WebUI_Mismatch.md) | Follow-up report for FU-P6-T10-1 | ## Archive Log @@ -180,3 +182,5 @@ | 2026-02-12 | P7-T12 | Archived Move_Cursor_UVX_Before_Installation (PASS) | | 2026-02-12 | P7-T12 | Archived REVIEW_P7-T12_Cursor_Quick_Setup report | | 2026-02-12 | FU-P6-T10-1 | Archived Align_manual_install_script_with_Web_UI_configuration_expectations (PASS) | +| 2026-02-12 | FU-P6-T10-1 | Archived REVIEW_FU-P6-T10-1_Install_WebUI_Mismatch report | +| 2026-02-12 | FU-P6-T10-1 | Archived FOLLOWUP_FU-P6-T10-1_Install_WebUI_Mismatch report | From 7e648302ba17f5ac24a7714e6b800c0206433ddb Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Thu, 12 Feb 2026 23:31:22 +0300 Subject: [PATCH 10/10] Sync DocC pages for Web UI install guidance --- .../Documentation.docc/Installation.md | 8 ++++++++ .../Documentation.docc/Troubleshooting.md | 14 ++++++++++++++ .../Documentation.docc/XcodeMCPWrapper.md | 18 ++++++++++++++++++ 3 files changed, 40 insertions(+) diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Installation.md b/Sources/XcodeMCPWrapper/Documentation.docc/Installation.md index e98a2a74..51fe3dd4 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/Installation.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/Installation.md @@ -62,12 +62,20 @@ This installs the package and creates the `mcpbridge-wrapper` or `xcodemcpwrappe ./scripts/install.sh ``` +If you need Web UI support for `--web-ui` args, install with: + +```bash +./scripts/install.sh --webui +``` + This script will: 1. Create a virtual environment (`.venv`) if not already active 2. Install the package into the venv 3. Create `~/bin/xcodemcpwrapper` wrapper with the correct Python interpreter 4. Make it executable +Default `./scripts/install.sh` is base-only (no Web UI extras). + ### Method 4: Local Development (venv) For development or running directly from the cloned repository: diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md index a14295fd..c546050f 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md @@ -121,6 +121,20 @@ source bin/activate chmod +x ~/bin/xcodemcpwrapper ``` +## Error: "Web UI dependencies not installed" / `ModuleNotFoundError: uvicorn` + +**Symptom:** Wrapper exits when MCP client config includes `--web-ui` args. + +**Cause:** Manual install used base mode (`./scripts/install.sh`), but Web UI args require optional `.[webui]` dependencies. + +**Solution:** +```bash +cd /path/to/XcodeMCPWrapper +./scripts/install.sh --webui +``` + +Then restart your MCP client. If you do not need Web UI, remove `--web-ui` and `--web-ui-port` from MCP config args. + ## Tool Returns Empty Results **Symptom:** Tools execute but return no data. diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md index 4a9fbfa4..3503775b 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md @@ -109,6 +109,11 @@ cd XcodeMCPWrapper ./scripts/install.sh ``` +If you plan to use `--web-ui` MCP args with manual install: +```bash +./scripts/install.sh --webui +``` + For local development from a clone: ```bash git clone https://github.com/SoundBlaster/XcodeMCPWrapper.git @@ -144,6 +149,19 @@ For **uvx** setup (recommended), see **Cursor Quick Setup** above. } ``` +**Using manual installation with Web UI (Optional):** +> Requires installing with `./scripts/install.sh --webui` (or equivalent `.[webui]` dependencies). +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper", + "args": ["--web-ui", "--web-ui-port", "8080"] + } + } +} +``` + #### Claude Code **Using uvx (Recommended):**