diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9f609cbd..ff4c6ab2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -20,7 +20,7 @@ jobs: fetch-depth: 0 # Need full history for branch comparison - name: Check DocC sync - run: make doccheck-branch + run: make doccheck-all lint: name: Lint & Type Check runs-on: ubuntu-latest diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cdf6fc1c..2f1073af 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -73,12 +73,12 @@ mypy src/ Ensure documentation changes are synced with DocC catalog: ```bash -make doccheck +make doccheck-all # or -python scripts/check_doc_sync.py +python scripts/check_doc_sync.py --all ``` -This checks that changes to `docs/*.md` files are also reflected in the DocC catalog (`Sources/XcodeMCPWrapper/Documentation.docc/`). +This checks that changes to `docs/*.md` files are also reflected in the DocC catalog (`Sources/XcodeMCPWrapper/Documentation.docc/`) across unstaged, staged, and branch scopes. ### 6. Build Verification @@ -118,7 +118,7 @@ echo "4. Running type checker..." mypy src/ echo "5. Checking doc sync..." -python scripts/check_doc_sync.py +python scripts/check_doc_sync.py --all echo "6. Building package..." python -m build && twine check dist/* diff --git a/Makefile b/Makefile index 4712b220..cd903029 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,6 @@ # Makefile for mcpbridge-wrapper -.PHONY: help install install-webui test test-webui lint format format-check typecheck doccheck doccheck-branch package-assets-check clean webui webui-health check +.PHONY: help install install-webui test test-webui lint format format-check typecheck doccheck doccheck-staged doccheck-branch doccheck-all package-assets-check clean webui webui-health check help: @echo "Available targets:" @@ -13,12 +13,14 @@ help: @echo " format-check - Run ruff formatter in check mode" @echo " typecheck - Run mypy type checker" @echo " doccheck - Check docs/ are synced with DocC catalog" + @echo " doccheck-staged - Check staged docs/ sync with DocC catalog" @echo " doccheck-branch - Check docs/ sync against git branch" + @echo " doccheck-all - Check docs/ sync for unstaged, staged, and branch changes" @echo " package-assets-check - Build artifacts and verify required packaged assets" @echo " webui - Start wrapper with Web UI dashboard (port 8080)" @echo " webui-health - Check Web UI health status" @echo " clean - Clean build artifacts" - @echo " check - Run all quality gates (test, lint, format, typecheck, doccheck, package-assets-check)" + @echo " check - Run all quality gates (test, lint, format, typecheck, doccheck-all, package-assets-check)" install: @if [ -z "$$VIRTUAL_ENV" ]; then \ @@ -57,14 +59,20 @@ typecheck: doccheck: python scripts/check_doc_sync.py +doccheck-staged: + python scripts/check_doc_sync.py --staged + doccheck-branch: python scripts/check_doc_sync.py --branch +doccheck-all: + python scripts/check_doc_sync.py --all + package-assets-check: python -m build --sdist --wheel python scripts/check_package_assets.py --dist-dir dist -check: test lint format-check typecheck doccheck package-assets-check +check: test lint format-check typecheck doccheck-all package-assets-check clean: rm -rf build/ dist/ *.egg-info/ diff --git a/README.md b/README.md index beb67979..6e0141d2 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ With Web UI dashboard (optional — adds real-time monitoring at http://localhos "command": "uvx", "args": [ "--from", - "mcpbridge-wrapper", + "mcpbridge-wrapper[webui]", "mcpbridge-wrapper", "--web-ui", "--web-ui-port", @@ -251,7 +251,7 @@ claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge **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 +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080 ``` **Using manual installation:** @@ -286,7 +286,7 @@ 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 +codex mcp add xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080 ``` **Using manual installation:** @@ -334,7 +334,7 @@ Edit `~/.zed/settings.json`: "command": "uvx", "args": [ "--from", - "mcpbridge-wrapper", + "mcpbridge-wrapper[webui]", "mcpbridge-wrapper", "--web-ui", "--web-ui-port", diff --git a/SPECS/ARCHIVE/FU-P9-T2-1_Fix_uvx_Web_UI_examples_to_include_webui_extras/FU-P9-T2-1_Fix_uvx_Web_UI_examples_to_include_webui_extras.md b/SPECS/ARCHIVE/FU-P9-T2-1_Fix_uvx_Web_UI_examples_to_include_webui_extras/FU-P9-T2-1_Fix_uvx_Web_UI_examples_to_include_webui_extras.md new file mode 100644 index 00000000..6ce6c114 --- /dev/null +++ b/SPECS/ARCHIVE/FU-P9-T2-1_Fix_uvx_Web_UI_examples_to_include_webui_extras/FU-P9-T2-1_Fix_uvx_Web_UI_examples_to_include_webui_extras.md @@ -0,0 +1,46 @@ +# FU-P9-T2-1 — Fix uvx Web UI examples to include `webui` extras + +**Priority:** P1 +**Dependencies:** P9-T2 +**Phase:** Phase 9 Follow-up Backlog + +## Objective +Remove documentation/config mismatches where users can copy a uvx command with `--web-ui` but without Web UI extras, causing runtime dependency failures. + +## Deliverables +1. Update all uvx + Web UI examples to use: + - `uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper` +2. Align client docs and config templates: + - `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` +3. Update troubleshooting guidance to include both supported paths: + - use `[webui]` extras for uvx + `--web-ui` + - remove `--web-ui` arguments when dashboard is not needed +4. Produce validation evidence in `SPECS/INPROGRESS/FU-P9-T2-1_Validation_Report.md`. + +## Acceptance Criteria +1. No documented command/config combines `--web-ui` with base-only `uvx --from mcpbridge-wrapper`. +2. All uvx Web UI examples consistently use `mcpbridge-wrapper[webui]`. +3. Copy/paste Cursor JSON Web UI config no longer implies a `ModuleNotFoundError: uvicorn` failure. +4. Troubleshooting docs include both fix options: add `[webui]` extras or remove `--web-ui`. + +## Execution Plan +1. Scan repository for `--web-ui` examples and uvx command variants. +2. Patch affected documentation and config templates only where Web UI is enabled. +3. Verify no remaining mismatched examples with targeted search checks. +4. Run quality gates: + - `pytest` + - `ruff check src/` + - `mypy src/` + - `pytest --cov` (>= 90%) +5. Write and commit validation report. + +--- +**Archived:** 2026-02-13 +**Verdict:** PASS diff --git a/SPECS/ARCHIVE/FU-P9-T2-1_Fix_uvx_Web_UI_examples_to_include_webui_extras/FU-P9-T2-1_Validation_Report.md b/SPECS/ARCHIVE/FU-P9-T2-1_Fix_uvx_Web_UI_examples_to_include_webui_extras/FU-P9-T2-1_Validation_Report.md new file mode 100644 index 00000000..93f7d20b --- /dev/null +++ b/SPECS/ARCHIVE/FU-P9-T2-1_Fix_uvx_Web_UI_examples_to_include_webui_extras/FU-P9-T2-1_Validation_Report.md @@ -0,0 +1,47 @@ +# FU-P9-T2-1 Validation Report + +**Task:** Fix uvx Web UI examples to include `webui` extras +**Date:** 2026-02-13 +**Verdict:** PASS + +## Changes Implemented + +1. Updated uvx + Web UI examples to use `mcpbridge-wrapper[webui]` in: + - `README.md` + - `docs/cursor-setup.md` + - `docs/claude-setup.md` + - `docs/codex-setup.md` +2. Updated config templates for uvx + Web UI usage: + - `config/cursor-mcp.json` + - `config/zed-agent.json` + - `config/claude-code.txt` + - `config/codex-cli.txt` +3. Updated troubleshooting guidance in `docs/troubleshooting.md` to include: + - uvx fix path with `mcpbridge-wrapper[webui]` + - manual install fix path (`./scripts/install.sh --webui`) + - fallback path to remove `--web-ui` args when dashboard is not needed + +## Acceptance Criteria Check + +| Criteria | Status | Evidence | +|---|---|---| +| No documented command/config combines `--web-ui` with base-only `uvx --from mcpbridge-wrapper` | PASS | Repository search returned no matches for base uvx + `--web-ui` patterns | +| All uvx Web UI examples use `mcpbridge-wrapper[webui]` | PASS | Updated docs/config files listed above now use `[webui]` in Web UI variants | +| Cursor JSON Web UI config no longer implies `ModuleNotFoundError: uvicorn` | PASS | `config/cursor-mcp.json` and `docs/cursor-setup.md` Web UI examples now install uvx Web UI extras | +| Troubleshooting includes both solutions | PASS | `docs/troubleshooting.md` now documents `[webui]` uvx path and removing `--web-ui` args | + +## Quality Gates + +Environment note: +- Initial `pytest` run failed during collection with `ModuleNotFoundError: mcpbridge_wrapper` because the package was not installed in the active interpreter. +- Installed dependencies with `python3 -m pip install -e '.[dev,webui]'`, then reran all gates. + +Results: +- `pytest` -> **324 passed, 5 skipped** +- `ruff check src/` -> **All checks passed** +- `mypy src/` -> **Success: no issues found** +- `pytest --cov` -> **Total coverage 96.62%** (>= 90% requirement) + +## Notes + +- Test runs emitted existing non-blocking warnings related to WebSocket deprecations and a transient Web UI port `8080` bind warning from a test thread. These warnings did not affect pass/fail status. diff --git a/SPECS/ARCHIVE/FU-P9-T2-1_Fix_uvx_Web_UI_examples_to_include_webui_extras/REVIEW_fu_p9_t2_1_uvx_webui_extras.md b/SPECS/ARCHIVE/FU-P9-T2-1_Fix_uvx_Web_UI_examples_to_include_webui_extras/REVIEW_fu_p9_t2_1_uvx_webui_extras.md new file mode 100644 index 00000000..4e5822fd --- /dev/null +++ b/SPECS/ARCHIVE/FU-P9-T2-1_Fix_uvx_Web_UI_examples_to_include_webui_extras/REVIEW_fu_p9_t2_1_uvx_webui_extras.md @@ -0,0 +1,30 @@ +## REVIEW REPORT — FU-P9-T2-1 uvx Web UI extras + +**Scope:** `origin/main..HEAD` +**Files:** 14 + +### Summary Verdict +- [x] Approve +- [ ] Approve with comments +- [ ] Request changes +- [ ] Block + +### Critical Issues +- None. + +### Secondary Issues +- None. + +### Architectural Notes +- Changes are documentation/config-template focused and correctly scoped to Web UI uvx examples. +- FLOW artifacts were produced and archived in expected locations. + +### Tests +- `pytest` passed (`324 passed, 5 skipped`) after installing editable deps. +- `ruff check src/` passed. +- `mypy src/` passed. +- `pytest --cov` passed with **96.62%** coverage (>= 90%). + +### Next Steps +- No actionable findings. +- FOLLOW-UP step is skipped. diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index ba88dec8..1db3fe50 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -78,6 +78,7 @@ | FU-P8-T1-1 | [FU-P8-T1-1_Reconcile_P8-T1_URL_Criteria_with_Current_GitHub_Pages_Path_and_Resolve_DocC_Reference_Warnings/](FU-P8-T1-1_Reconcile_P8-T1_URL_Criteria_with_Current_GitHub_Pages_Path_and_Resolve_DocC_Reference_Warnings/) | 2026-02-12 | PASS | | P9-T3 | [P9-T3_Release_version_0.3.0_Web_UI_Feature_Release/](P9-T3_Release_version_0.3.0_Web_UI_Feature_Release/) | 2026-02-13 | PASS | | FU-REBUILD-P10-T1-7 | [FU-REBUILD-P10-T1-7_WebUI_Static_Assets/](FU-REBUILD-P10-T1-7_WebUI_Static_Assets/) | 2026-02-13 | PASS | +| FU-P9-T2-1 | [FU-P9-T2-1_Fix_uvx_Web_UI_examples_to_include_webui_extras/](FU-P9-T2-1_Fix_uvx_Web_UI_examples_to_include_webui_extras/) | 2026-02-13 | PASS | ## Historical Artifacts @@ -121,6 +122,7 @@ | [REVIEW_FU-P8-T1-1_URL_DocC.md](FU-P8-T1-1_Reconcile_P8-T1_URL_Criteria_with_Current_GitHub_Pages_Path_and_Resolve_DocC_Reference_Warnings/REVIEW_FU-P8-T1-1_URL_DocC.md) | Review report for FU-P8-T1-1 | | [REVIEW_release-0.3.0.md](P9-T3_Release_version_0.3.0_Web_UI_Feature_Release/REVIEW_release-0.3.0.md) | Review report for P9-T3 | | [REVIEW_webui-static-assets.md](FU-REBUILD-P10-T1-7_WebUI_Static_Assets/REVIEW_webui-static-assets.md) | Review report for FU-REBUILD-P10-T1-7 | +| [REVIEW_fu_p9_t2_1_uvx_webui_extras.md](FU-P9-T2-1_Fix_uvx_Web_UI_examples_to_include_webui_extras/REVIEW_fu_p9_t2_1_uvx_webui_extras.md) | Review report for FU-P9-T2-1 | ## Archive Log @@ -196,3 +198,5 @@ | 2026-02-13 | P9-T3 | Archived REVIEW_release-0.3.0 report | | 2026-02-13 | FU-REBUILD-P10-T1-7 | Archived WebUI_Static_Assets (PASS) | | 2026-02-13 | FU-REBUILD-P10-T1-7 | Archived REVIEW_webui-static-assets report | +| 2026-02-13 | FU-P9-T2-1 | Archived Fix_uvx_Web_UI_examples_to_include_webui_extras (PASS) | +| 2026-02-13 | FU-P9-T2-1 | Archived REVIEW_fu_p9_t2_1_uvx_webui_extras report | diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index b7cb5979..02a6d83a 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -4,12 +4,12 @@ The previously selected task has been archived. ## Recently Archived +- 2026-02-13 — FU-P9-T2-1: Fix uvx Web UI examples to include `webui` extras (PASS) - 2026-02-13 — FU-REBUILD-P10-T1-7: Include Web UI static assets in published package artifacts (PASS) - 2026-02-13 — P9-T3: Release version 0.3.0 (Web UI Feature Release) (PASS) - 2026-02-12 — FU-P8-T1-1: Reconcile P8-T1 URL criteria with current GitHub Pages path and resolve DocC reference warnings (PASS) - 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) ## Suggested Next Tasks -- FU-P9-T2-1: Fix uvx Web UI examples to include `webui` extras (P1) +- None. All tasks in `SPECS/Workplan.md` are complete (88/88). diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index 1fced33c..1940f711 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -1157,9 +1157,9 @@ Main branch is currently unstable after an accidental merge of the Phase 10 Web --- Phase 9 Follow-up Backlog -- [ ] FU-P9-T2-1: Fix uvx Web UI examples to include `webui` extras (P1) +- [x] FU-P9-T2-1: Fix uvx Web UI examples to include `webui` extras (P1) -#### FU-P9-T2-1: Fix uvx Web UI examples to include `webui` extras +#### ✅ FU-P9-T2-1: Fix uvx Web UI examples to include `webui` extras - **Description:** Resolve documentation/config mismatch where examples use `uvx --from mcpbridge-wrapper ... --web-ui` without optional dependencies. Update all uvx Web UI examples to install extras via `--from mcpbridge-wrapper[webui]`, and align troubleshooting/runtime guidance with the correct uvx command. - **Priority:** P1 - **Dependencies:** P9-T2 diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md b/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md index d1ab08c1..a26ddb98 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md @@ -14,6 +14,14 @@ claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge That's it! uvx will automatically download and run the wrapper. +### Option 1B: Using uvx with Web UI (Optional) + +Use this variant to enable the dashboard on port `8080`: + +```bash +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080 +``` + ### Option 2: Using Manual Installation If you installed manually to `~/bin/xcodemcpwrapper`: diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md b/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md index 1a1eacc5..138216d2 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md @@ -14,6 +14,14 @@ codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper That's it! uvx will automatically download and run the wrapper. +### Option 1B: Using uvx with Web UI (Optional) + +Use this variant to enable the dashboard on port `8080`: + +```bash +codex mcp add xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080 +``` + ### Option 2: Using Manual Installation If you installed manually to `~/bin/xcodemcpwrapper`: diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/CursorSetup.md b/Sources/XcodeMCPWrapper/Documentation.docc/CursorSetup.md index 8fa6cd5c..33fc301c 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/CursorSetup.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/CursorSetup.md @@ -35,6 +35,26 @@ Or edit `~/.cursor/mcp.json` directly: } ``` +With Web UI: + +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "uvx", + "args": [ + "--from", + "mcpbridge-wrapper[webui]", + "mcpbridge-wrapper", + "--web-ui", + "--web-ui-port", + "8080" + ] + } + } +} +``` + ### Option 2: Using Manual Installation If you installed manually to `~/bin/xcodemcpwrapper`: diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md index c546050f..da350450 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md @@ -125,15 +125,23 @@ chmod +x ~/bin/xcodemcpwrapper **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. +**Cause:** The MCP config enables `--web-ui`, but the installed command is missing Web UI dependencies. -**Solution:** +**Solution (uvx):** +Use `[webui]` extras in the uvx package source when Web UI args are enabled: +```bash +uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --help +``` + +**Solution (manual install):** ```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. +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 diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md index 3503775b..87addfd7 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md @@ -55,7 +55,7 @@ With Web UI dashboard (optional — adds real-time monitoring at http://localhos "command": "uvx", "args": [ "--from", - "mcpbridge-wrapper", + "mcpbridge-wrapper[webui]", "mcpbridge-wrapper", "--web-ui", "--web-ui-port", @@ -170,6 +170,11 @@ For **uvx** setup (recommended), see **Cursor Quick Setup** above. 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[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080 +``` + **Using manual installation:** ```bash @@ -184,6 +189,11 @@ claude mcp add --transport stdio xcode -- /Users/YOUR_USERNAME/bin/xcodemcpwrapp 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[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080 +``` + **Using manual installation:** ```bash diff --git a/config/claude-code.txt b/config/claude-code.txt index 3cbd757b..831b5391 100644 --- a/config/claude-code.txt +++ b/config/claude-code.txt @@ -10,7 +10,7 @@ # ------------------------------------------- # 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 +# claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080 # # To install uv (which includes uvx): # curl -LsSf https://astral.sh/uv/install.sh | sh diff --git a/config/codex-cli.txt b/config/codex-cli.txt index 5e877681..6b93272e 100644 --- a/config/codex-cli.txt +++ b/config/codex-cli.txt @@ -10,7 +10,7 @@ # ------------------------------------------- # Enable the Web UI dashboard on port 8080: # -# codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --web-ui --web-ui-port 8080 +# codex mcp add xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080 # # To install uv (which includes uvx): # curl -LsSf https://astral.sh/uv/install.sh | sh diff --git a/config/cursor-mcp.json b/config/cursor-mcp.json index 6097195b..e9be83cc 100644 --- a/config/cursor-mcp.json +++ b/config/cursor-mcp.json @@ -10,7 +10,7 @@ "command": "uvx", "args": [ "--from", - "mcpbridge-wrapper", + "mcpbridge-wrapper[webui]", "mcpbridge-wrapper", "--web-ui", "--web-ui-port", diff --git a/config/zed-agent.json b/config/zed-agent.json index 1c348e08..195d9fe0 100644 --- a/config/zed-agent.json +++ b/config/zed-agent.json @@ -10,7 +10,7 @@ "command": "uvx", "args": [ "--from", - "mcpbridge-wrapper", + "mcpbridge-wrapper[webui]", "mcpbridge-wrapper", "--web-ui", "--web-ui-port", diff --git a/docs/claude-setup.md b/docs/claude-setup.md index 14e544bb..0a599a6a 100644 --- a/docs/claude-setup.md +++ b/docs/claude-setup.md @@ -18,7 +18,7 @@ That's it! uvx will automatically download and run the wrapper. Use this variant to enable the dashboard on port `8080`: ```bash -claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --web-ui --web-ui-port 8080 +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080 ``` ## Alternative: Using Manual Installation diff --git a/docs/codex-setup.md b/docs/codex-setup.md index becf07f1..ca42fee3 100644 --- a/docs/codex-setup.md +++ b/docs/codex-setup.md @@ -18,7 +18,7 @@ That's it! uvx will automatically download and run the wrapper. Use this variant to enable the dashboard on port `8080`: ```bash -codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --web-ui --web-ui-port 8080 +codex mcp add xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080 ``` ## Alternative: Using Manual Installation diff --git a/docs/cursor-setup.md b/docs/cursor-setup.md index 0a4d35a4..7406ddf8 100644 --- a/docs/cursor-setup.md +++ b/docs/cursor-setup.md @@ -43,7 +43,7 @@ Edit `~/.cursor/mcp.json` directly: "command": "uvx", "args": [ "--from", - "mcpbridge-wrapper", + "mcpbridge-wrapper[webui]", "mcpbridge-wrapper", "--web-ui", "--web-ui-port", diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 193f3936..a981fb20 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -154,15 +154,22 @@ source ~/.zshrc # or ~/.bashrc **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. +**Cause:** The MCP config enables `--web-ui`, but the installed command is missing Web UI dependencies. -**Solution:** +**Solution (uvx):** +Use `[webui]` extras in the uvx package source when Web UI args are enabled: +```bash +uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --help +``` + +**Solution (manual install):** ```bash cd /path/to/XcodeMCPWrapper ./scripts/install.sh --webui ``` -Then restart your MCP client. +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 @@ -185,6 +192,7 @@ If issues persist: 1. Check [GitHub Issues](https://github.com/SoundBlaster/XcodeMCPWrapper/issues) 2. Run tests: `pytest tests/` 3. Verify installation: - - uvx method: `uvx --from mcpbridge-wrapper mcpbridge-wrapper --help` + - uvx method (base): `uvx --from mcpbridge-wrapper mcpbridge-wrapper --help` + - uvx method (Web UI): `uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --help` - pip method: `pip show mcpbridge-wrapper` - manual method: `which xcodemcpwrapper` diff --git a/scripts/check_doc_sync.py b/scripts/check_doc_sync.py index 0482463a..0e753c14 100755 --- a/scripts/check_doc_sync.py +++ b/scripts/check_doc_sync.py @@ -9,6 +9,7 @@ python scripts/check_doc_sync.py # Check unstaged changes python scripts/check_doc_sync.py --staged # Check staged changes python scripts/check_doc_sync.py --branch # Check branch changes (CI) + python scripts/check_doc_sync.py --all # Check unstaged, staged, and branch changes Exit codes: 0 - All docs are synced or no docs changed @@ -19,7 +20,6 @@ import sys from typing import List, Optional, Set - # Mapping: docs/ file -> DocC file DOC_MAPPING = { "docs/installation.md": "Sources/XcodeMCPWrapper/Documentation.docc/Installation.md", @@ -28,7 +28,9 @@ "docs/codex-setup.md": "Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md", "docs/troubleshooting.md": "Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md", "docs/architecture.md": "Sources/XcodeMCPWrapper/Documentation.docc/Architecture.md", - "docs/environment-variables.md": "Sources/XcodeMCPWrapper/Documentation.docc/EnvironmentVariables.md", + "docs/environment-variables.md": ( + "Sources/XcodeMCPWrapper/Documentation.docc/EnvironmentVariables.md" + ), "README.md": "Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md", } @@ -37,6 +39,8 @@ "docs/webui-setup.md", } +ALL_MODES = ("unstaged", "staged", "branch") + def _run_git_name_only(args: List[str]) -> Optional[Set[str]]: """Run git diff and return changed files, or None if command fails.""" @@ -73,7 +77,9 @@ def get_changed_files(mode: str = "unstaged") -> Set[str]: return changed # Final fallback for detached or minimal clones: last commit delta. - changed = _run_git_name_only(["git", "diff-tree", "--no-commit-id", "--name-only", "-r", "HEAD"]) + changed = _run_git_name_only( + ["git", "diff-tree", "--no-commit-id", "--name-only", "-r", "HEAD"] + ) if changed is not None: print( "Warning: could not find main/master ref; " @@ -88,6 +94,36 @@ def get_changed_files(mode: str = "unstaged") -> Set[str]: return changed if changed is not None else set() +def run_check_for_mode(mode: str) -> bool: + """Run DocC sync check for a single change mode.""" + print(f"Checking {mode} changes for DocC sync...\n") + + changed_files = get_changed_files(mode) + if not changed_files: + print("No files changed") + return True + + return check_doc_sync(changed_files) + + +def run_all_modes() -> bool: + """Run DocC sync checks for unstaged, staged, and branch change scopes.""" + all_passed = True + + for mode in ALL_MODES: + print(f"=== Mode: {mode} ===") + mode_passed = run_check_for_mode(mode) + all_passed = all_passed and mode_passed + print() + + if all_passed: + print("✓ DocC sync checks passed across unstaged, staged, and branch scopes") + else: + print("⚠ DocC sync check failed in at least one change scope") + + return all_passed + + def check_doc_sync(changed_files: Set[str]) -> bool: """ Check if documentation changes are synced with DocC. @@ -134,21 +170,28 @@ def check_doc_sync(changed_files: Set[str]) -> bool: def main() -> int: + """Parse arguments and execute DocC sync checks.""" import argparse parser = argparse.ArgumentParser( description="Check if docs/ changes are synced with DocC catalog" ) - parser.add_argument( + group = parser.add_mutually_exclusive_group() + group.add_argument( "--staged", action="store_true", help="Check staged changes instead of unstaged", ) - parser.add_argument( + group.add_argument( "--branch", action="store_true", help="Check all changes in current branch (for CI)", ) + group.add_argument( + "--all", + action="store_true", + help="Check unstaged, staged, and branch changes", + ) parser.add_argument( "--skip-docc-check", action="store_true", @@ -161,18 +204,11 @@ def main() -> int: print("Skipping DocC sync check (--skip-docc-check)") return 0 - mode = "branch" if args.branch else ("staged" if args.staged else "unstaged") - print(f"Checking {mode} changes for DocC sync...\n") + if args.all: + return 0 if run_all_modes() else 1 - changed_files = get_changed_files(mode) - if not changed_files: - print("No files changed") - return 0 - - if check_doc_sync(changed_files): - return 0 - - return 1 + mode = "branch" if args.branch else ("staged" if args.staged else "unstaged") + return 0 if run_check_for_mode(mode) else 1 if __name__ == "__main__": diff --git a/tests/test_check_doc_sync.py b/tests/test_check_doc_sync.py index 2f9e5bfa..4cf473c7 100644 --- a/tests/test_check_doc_sync.py +++ b/tests/test_check_doc_sync.py @@ -60,3 +60,46 @@ def fake_ref_exists(ref: str) -> bool: assert changed_files == {"docs/installation.md"} assert ["git", "diff-tree", "--no-commit-id", "--name-only", "-r", "HEAD"] in called_args + + +def test_main_all_mode_checks_all_scopes_and_fails_on_unsynced(monkeypatch) -> None: + """--all should run unstaged/staged/branch and fail if any scope is unsynced.""" + module = load_script_module() + + observed_modes: list[str] = [] + + def fake_get_changed_files(mode: str): + observed_modes.append(mode) + return {f"{mode}.md"} + + def fake_check_doc_sync(changed_files: set[str]) -> bool: + return "staged.md" not in changed_files + + monkeypatch.setattr(module, "get_changed_files", fake_get_changed_files) + monkeypatch.setattr(module, "check_doc_sync", fake_check_doc_sync) + monkeypatch.setattr(module.sys, "argv", ["check_doc_sync.py", "--all"]) + + exit_code = module.main() + + assert exit_code == 1 + assert observed_modes == ["unstaged", "staged", "branch"] + + +def test_main_all_mode_passes_when_all_scopes_synced(monkeypatch) -> None: + """--all should pass when all scopes are synced.""" + module = load_script_module() + + observed_modes: list[str] = [] + + def fake_get_changed_files(mode: str): + observed_modes.append(mode) + return {f"{mode}.md"} + + monkeypatch.setattr(module, "get_changed_files", fake_get_changed_files) + monkeypatch.setattr(module, "check_doc_sync", lambda _: True) + monkeypatch.setattr(module.sys, "argv", ["check_doc_sync.py", "--all"]) + + exit_code = module.main() + + assert exit_code == 0 + assert observed_modes == ["unstaged", "staged", "branch"]