From 26b796f30d303741dcfe36ca3389634286a7d30a Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sat, 14 Feb 2026 14:06:41 +0300 Subject: [PATCH 1/8] Branch for BUG-T2: codex webui zsh glob --- SPECS/Workplan.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index b325d7ae..9e9c3020 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -994,6 +994,40 @@ Use alternative MCP clients that work correctly: --- +### BUG-T2: `codex mcp add` with Web UI extras fails in `zsh` +- **Type:** Bug / Documentation / CLI UX +- **Status:** 🔴 Open +- **Priority:** P1 +- **Discovered:** 2026-02-14 +- **Component:** Installation & Configuration Docs +- **Affected Client:** Codex CLI (shell command setup) +- **Affected Shell:** `zsh` (default macOS shell) + +#### Description +The documented/pasted Web UI setup command for Codex using uvx extras fails in `zsh` because square brackets are treated as a glob pattern when unquoted. + +#### Symptoms +```zsh +egor@MacBook-Pro-Egor bin % codex mcp add xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080 +zsh: no matches found: mcpbridge-wrapper[webui] +``` + +#### Root Cause Analysis +`zsh` performs filename globbing on unquoted bracket expressions like `[webui]`. The token `mcpbridge-wrapper[webui]` is parsed as a glob instead of a literal package specifier. + +#### Workaround +Use any of the following forms so the extras spec is passed literally: +- `uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080` +- `uvx --from mcpbridge-wrapper\\[webui\\] mcpbridge-wrapper --web-ui --web-ui-port 8080` + +#### Resolution Path +- [ ] Update README and setup docs to quote extras in all shell commands (`'mcpbridge-wrapper[webui]'`) +- [ ] Update configuration templates/examples that include extras to avoid raw unquoted bracket syntax +- [ ] Add a troubleshooting entry for `zsh: no matches found` with shell-safe examples +- [ ] Add a short note explaining why quotes are required in `zsh` + +--- + ### Phase 10: Web UI Control & Audit Dashboard **Intent:** Create a web-based dashboard for real-time monitoring, control, and audit logging of the XcodeMCPWrapper. Provides visibility into MCP tool usage, performance metrics, and operational control. From 934561b17e4fe130aba2d0acf75f71e0350b5d9f Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sat, 14 Feb 2026 14:06:56 +0300 Subject: [PATCH 2/8] Select task BUG-T2: codex mcp add with Web UI extras fails in zsh --- SPECS/INPROGRESS/next.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index 7283278d..63a52950 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,6 +1,16 @@ -# No Active Task +# Active Task -The previously selected task has been archived. +- **Task ID:** BUG-T2 +- **Task Name:** codex mcp add with Web UI extras fails in zsh +- **Status:** In Progress +- **Priority:** P1 +- **Selected On:** 2026-02-14 +- **Review Subject:** BUG-T2_zsh_webui_extras + +## Task Summary + +Fix shell-unsafe Web UI extras command examples so `zsh` users do not hit: +`zsh: no matches found: mcpbridge-wrapper[webui]`. ## Recently Archived @@ -9,7 +19,3 @@ The previously selected task has been archived. - 2026-02-13 — P9-T4: Create the publishing helper (PASS) - 2026-02-13 — BUG-T0: Uptime widget on Web UI always shows 1h 0m 0s (PASS) - 2026-02-13 — FU-P9-T2-1: Fix uvx Web UI examples to include `webui` extras (PASS) - -## Suggested Next Tasks - -- BUG-T1: Kimi CLI MCP Connection Failure (if applicable) From e1acf2ec33c3a4eadb0d1ec87d14499e780bdcfe Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sat, 14 Feb 2026 14:07:19 +0300 Subject: [PATCH 3/8] Plan task BUG-T2: codex mcp add with Web UI extras fails in zsh --- .../BUG-T2_codex_mcp_add_webui_zsh_glob.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 SPECS/INPROGRESS/BUG-T2_codex_mcp_add_webui_zsh_glob.md diff --git a/SPECS/INPROGRESS/BUG-T2_codex_mcp_add_webui_zsh_glob.md b/SPECS/INPROGRESS/BUG-T2_codex_mcp_add_webui_zsh_glob.md new file mode 100644 index 00000000..c169f13c --- /dev/null +++ b/SPECS/INPROGRESS/BUG-T2_codex_mcp_add_webui_zsh_glob.md @@ -0,0 +1,63 @@ +# BUG-T2 PRD — codex mcp add with Web UI extras fails in zsh + +## 1. Context + +When users run Codex MCP setup with uvx extras using an unquoted package specifier, zsh treats `[...]` as a glob pattern and fails before executing `uvx`. + +Failing command observed: + +```zsh +codex mcp add xcode -- uvx --from mcpbridge-wrapper[webui] mcpbridge-wrapper --web-ui --web-ui-port 8080 +# zsh: no matches found: mcpbridge-wrapper[webui] +``` + +## 2. Goal + +Make all user-facing shell command examples for uvx Web UI extras shell-safe in zsh and add explicit troubleshooting guidance. + +## 3. Scope + +In scope: +- Documentation and setup snippets where users copy/paste shell commands +- Troubleshooting updates for `zsh: no matches found` +- Task tracking updates for BUG-T2 completion + +Out of scope: +- Runtime code changes in wrapper core +- MCP protocol behavior changes + +## 4. Deliverables + +- Updated docs and command snippets to use quoted extras form: + - `uvx --from 'mcpbridge-wrapper[webui]' ...` +- Troubleshooting section with symptom/cause/fix for zsh globbing +- Validation report at `SPECS/INPROGRESS/BUG-T2_Validation_Report.md` + +## 5. Acceptance Criteria + +1. No unquoted shell command examples remain for `uvx --from mcpbridge-wrapper[webui]` in active docs/config text examples. +2. Codex setup examples with Web UI extras show a zsh-safe command form. +3. Troubleshooting docs include the exact symptom `zsh: no matches found: mcpbridge-wrapper[webui]` and a fix. +4. Quality gates pass: + - `pytest` + - `ruff check src/` + - `mypy src/` + - `pytest --cov` with project coverage >= 90% + +## 6. Dependencies + +- Existing bug record in `SPECS/Workplan.md` (`BUG-T2`) +- Existing docs pages: README, codex setup, troubleshooting, AGENTS + +## 7. Implementation Plan + +1. Find all user-facing shell examples using unquoted extras. +2. Update command snippets to quoted extras. +3. Add troubleshooting guidance for zsh glob expansion. +4. Run quality gates and capture results. +5. Archive task artifacts according to FLOW. + +## 8. Risks and Mitigations + +- Risk: Over-editing machine-readable config examples where shell quoting is irrelevant. +- Mitigation: Restrict quoting changes to shell command strings and explanatory text meant for terminal copy/paste. From 4b7178865a1c1d29e9810c7e879d33cbb0115e5b Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sat, 14 Feb 2026 14:08:31 +0300 Subject: [PATCH 4/8] Implement BUG-T2: quote uvx webui extras and add zsh troubleshooting --- README.md | 4 +- SPECS/INPROGRESS/BUG-T2_Validation_Report.md | 40 +++++++++++++++++++ .../Documentation.docc/ClaudeCodeSetup.md | 2 +- .../Documentation.docc/CodexCLISetup.md | 2 +- .../Documentation.docc/Troubleshooting.md | 19 ++++++++- .../Documentation.docc/XcodeMCPWrapper.md | 4 +- config/claude-code.txt | 2 +- config/codex-cli.txt | 2 +- docs/claude-setup.md | 2 +- docs/codex-setup.md | 2 +- docs/troubleshooting.md | 21 +++++++++- 11 files changed, 87 insertions(+), 13 deletions(-) create mode 100644 SPECS/INPROGRESS/BUG-T2_Validation_Report.md diff --git a/README.md b/README.md index b3ab04ad..fb97854b 100644 --- a/README.md +++ b/README.md @@ -266,7 +266,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[webui] 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:** @@ -301,7 +301,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[webui] 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:** diff --git a/SPECS/INPROGRESS/BUG-T2_Validation_Report.md b/SPECS/INPROGRESS/BUG-T2_Validation_Report.md new file mode 100644 index 00000000..4894b5bf --- /dev/null +++ b/SPECS/INPROGRESS/BUG-T2_Validation_Report.md @@ -0,0 +1,40 @@ +# BUG-T2 Validation Report + +- **Task ID:** BUG-T2 +- **Task Name:** codex mcp add with Web UI extras fails in zsh +- **Date:** 2026-02-14 +- **Verdict:** PASS + +## Scope Validated + +- Updated shell command examples using uvx Web UI extras to a zsh-safe quoted form: + - `uvx --from 'mcpbridge-wrapper[webui]' ...` +- Added explicit troubleshooting guidance for: + - `zsh: no matches found: mcpbridge-wrapper[webui]` +- Applied updates across user-facing docs and command template text files. + +## Acceptance Criteria Check + +1. No unquoted shell command examples remain for `uvx --from mcpbridge-wrapper[webui]` in active docs/config text examples. + **Result:** PASS +2. Codex setup examples with Web UI extras show a zsh-safe command form. + **Result:** PASS +3. Troubleshooting includes exact zsh symptom and fix. + **Result:** PASS +4. Required quality gates pass. + **Result:** PASS + +## Quality Gate Results + +- `pytest` + - Result: PASS (`345 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.62%`, required `>= 90%`) + +## Notes + +- Test runs emitted non-blocking warnings about local port collisions (`127.0.0.1:8080` / `9090`) from background Web UI thread startup in tests; suite still passed and coverage threshold was met. diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md b/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md index a26ddb98..49d25c58 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md @@ -19,7 +19,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[webui] 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 ``` ### Option 2: Using Manual Installation diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md b/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md index 138216d2..3e3cba4a 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md @@ -19,7 +19,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[webui] 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 ``` ### Option 2: Using Manual Installation diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md index 5bb2efcc..d3dbb39c 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md @@ -130,7 +130,7 @@ chmod +x ~/bin/xcodemcpwrapper **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 +uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --help ``` **Solution (manual install):** @@ -143,6 +143,23 @@ Then restart your MCP client. If you do not need Web UI, remove `--web-ui` and `--web-ui-port` from MCP config args. +## Error: `zsh: no matches found: mcpbridge-wrapper[webui]` + +**Symptom:** Setup commands fail immediately in `zsh` before `uvx` runs. + +**Cause:** `zsh` treats unquoted brackets as glob patterns. + +**Solution:** +Quote (or escape) the extras package specifier: +```bash +codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080 +``` + +Alternative escaped form: +```bash +codex mcp add xcode -- uvx --from mcpbridge-wrapper\\[webui\\] mcpbridge-wrapper --web-ui --web-ui-port 8080 +``` + ## Error: "Uptime still shows 1h 0m 0s" or behavior is unchanged after upgrade **Symptom:** You upgraded to a newer release, but dashboard behavior still matches an older version (for example uptime stays `1h 0m 0s`). diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md index 58430e4b..577cab28 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md @@ -187,7 +187,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[webui] 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:** @@ -206,7 +206,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[webui] 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:** diff --git a/config/claude-code.txt b/config/claude-code.txt index 831b5391..b793cce2 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[webui] 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 6b93272e..cff5cfa4 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[webui] 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/docs/claude-setup.md b/docs/claude-setup.md index 0a599a6a..4aa43c51 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[webui] 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 ca42fee3..3e6a6c4d 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[webui] 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/troubleshooting.md b/docs/troubleshooting.md index 6278c1c9..06ee5931 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -159,7 +159,7 @@ source ~/.zshrc # or ~/.bashrc **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 +uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --help ``` **Solution (manual install):** @@ -172,6 +172,23 @@ Then restart your MCP client. If you do not need Web UI, remove `--web-ui` and `--web-ui-port` from MCP config args. +### `zsh: no matches found: mcpbridge-wrapper[webui]` + +**Symptom:** Setup commands fail immediately in `zsh` before `uvx` runs. + +**Cause:** `zsh` treats unquoted brackets as glob patterns. + +**Solution:** +Quote (or escape) the extras package specifier: +```bash +codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080 +``` + +Alternative escaped form: +```bash +codex mcp add xcode -- uvx --from mcpbridge-wrapper\\[webui\\] mcpbridge-wrapper --web-ui --web-ui-port 8080 +``` + ### "Uptime still shows 1h 0m 0s" or behavior is unchanged after upgrade **Symptom:** You upgraded to a newer release, but dashboard behavior still matches an older version (for example uptime stays `1h 0m 0s`). @@ -236,6 +253,6 @@ If issues persist: 2. Run tests: `pytest tests/` 3. Verify installation: - uvx method (base): `uvx --from mcpbridge-wrapper mcpbridge-wrapper --help` - - uvx method (Web UI): `uvx --from mcpbridge-wrapper[webui] 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` From beff4610c279ac0d0c426c444aa2709dd6fedafc Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sat, 14 Feb 2026 14:09:37 +0300 Subject: [PATCH 5/8] Archive task BUG-T2: codex mcp add with Web UI extras fails in zsh (PASS) --- .../BUG-T2_Validation_Report.md | 0 .../BUG-T2_codex_mcp_add_webui_zsh_glob.md | 4 ++++ SPECS/ARCHIVE/INDEX.md | 4 +++- SPECS/INPROGRESS/next.md | 19 +++++++------------ SPECS/Workplan.md | 13 +++++++------ 5 files changed, 21 insertions(+), 19 deletions(-) rename SPECS/{INPROGRESS => ARCHIVE/BUG-T2_codex_mcp_add_with_Web_UI_extras_fails_in_zsh}/BUG-T2_Validation_Report.md (100%) rename SPECS/{INPROGRESS => ARCHIVE/BUG-T2_codex_mcp_add_with_Web_UI_extras_fails_in_zsh}/BUG-T2_codex_mcp_add_webui_zsh_glob.md (97%) diff --git a/SPECS/INPROGRESS/BUG-T2_Validation_Report.md b/SPECS/ARCHIVE/BUG-T2_codex_mcp_add_with_Web_UI_extras_fails_in_zsh/BUG-T2_Validation_Report.md similarity index 100% rename from SPECS/INPROGRESS/BUG-T2_Validation_Report.md rename to SPECS/ARCHIVE/BUG-T2_codex_mcp_add_with_Web_UI_extras_fails_in_zsh/BUG-T2_Validation_Report.md diff --git a/SPECS/INPROGRESS/BUG-T2_codex_mcp_add_webui_zsh_glob.md b/SPECS/ARCHIVE/BUG-T2_codex_mcp_add_with_Web_UI_extras_fails_in_zsh/BUG-T2_codex_mcp_add_webui_zsh_glob.md similarity index 97% rename from SPECS/INPROGRESS/BUG-T2_codex_mcp_add_webui_zsh_glob.md rename to SPECS/ARCHIVE/BUG-T2_codex_mcp_add_with_Web_UI_extras_fails_in_zsh/BUG-T2_codex_mcp_add_webui_zsh_glob.md index c169f13c..67f9a7f1 100644 --- a/SPECS/INPROGRESS/BUG-T2_codex_mcp_add_webui_zsh_glob.md +++ b/SPECS/ARCHIVE/BUG-T2_codex_mcp_add_with_Web_UI_extras_fails_in_zsh/BUG-T2_codex_mcp_add_webui_zsh_glob.md @@ -61,3 +61,7 @@ Out of scope: - Risk: Over-editing machine-readable config examples where shell quoting is irrelevant. - Mitigation: Restrict quoting changes to shell command strings and explanatory text meant for terminal copy/paste. + +--- +**Archived:** 2026-02-14 +**Verdict:** PASS diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index 88d20a2f..ae748c4d 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -1,6 +1,6 @@ # mcpbridge-wrapper Tasks Archive -**Last Updated:** 2026-02-13 +**Last Updated:** 2026-02-14 ## Archived Tasks @@ -83,6 +83,7 @@ | P9-T4 | [P9-T4_Create_the_publishing_helper/](P9-T4_Create_the_publishing_helper/) | 2026-02-13 | PASS | | 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 | ## Historical Artifacts @@ -216,3 +217,4 @@ | 2026-02-13 | FU-P9-T2-2 | Archived Add_troubleshooting_guidance_for_stale_uvx_cache_process_versions (PASS) | | 2026-02-13 | FU-P9-T2-2 | Archived REVIEW_fu_p9_t2_2_stale_uvx_troubleshooting report | | 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) | diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index 63a52950..245009db 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,21 +1,16 @@ -# Active Task +# No Active Task -- **Task ID:** BUG-T2 -- **Task Name:** codex mcp add with Web UI extras fails in zsh -- **Status:** In Progress -- **Priority:** P1 -- **Selected On:** 2026-02-14 -- **Review Subject:** BUG-T2_zsh_webui_extras - -## Task Summary - -Fix shell-unsafe Web UI extras command examples so `zsh` users do not hit: -`zsh: no matches found: mcpbridge-wrapper[webui]`. +The previously selected task has been archived. ## Recently Archived +- 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) - 2026-02-13 — P9-T4: Create the publishing helper (PASS) - 2026-02-13 — BUG-T0: Uptime widget on Web UI always shows 1h 0m 0s (PASS) - 2026-02-13 — FU-P9-T2-1: Fix uvx Web UI examples to include `webui` extras (PASS) + +## Suggested Next Tasks + +- BUG-T1: Kimi CLI MCP Connection Failure (if applicable) diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index 9e9c3020..28facaee 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -994,11 +994,12 @@ Use alternative MCP clients that work correctly: --- -### BUG-T2: `codex mcp add` with Web UI extras fails in `zsh` +### BUG-T2: `codex mcp add` with Web UI extras fails in `zsh` ✅ - **Type:** Bug / Documentation / CLI UX -- **Status:** 🔴 Open +- **Status:** ✅ Complete - **Priority:** P1 - **Discovered:** 2026-02-14 +- **Completed:** 2026-02-14 - **Component:** Installation & Configuration Docs - **Affected Client:** Codex CLI (shell command setup) - **Affected Shell:** `zsh` (default macOS shell) @@ -1021,10 +1022,10 @@ Use any of the following forms so the extras spec is passed literally: - `uvx --from mcpbridge-wrapper\\[webui\\] mcpbridge-wrapper --web-ui --web-ui-port 8080` #### Resolution Path -- [ ] Update README and setup docs to quote extras in all shell commands (`'mcpbridge-wrapper[webui]'`) -- [ ] Update configuration templates/examples that include extras to avoid raw unquoted bracket syntax -- [ ] Add a troubleshooting entry for `zsh: no matches found` with shell-safe examples -- [ ] Add a short note explaining why quotes are required in `zsh` +- [x] Update README and setup docs to quote extras in all shell commands (`'mcpbridge-wrapper[webui]'`) +- [x] Update configuration templates/examples that include extras to avoid raw unquoted bracket syntax +- [x] Add a troubleshooting entry for `zsh: no matches found` with shell-safe examples +- [x] Add a short note explaining why quotes are required in `zsh` --- From 177ee44f772aa73eae5b8aa04ca655503f95e4d6 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sat, 14 Feb 2026 14:10:11 +0300 Subject: [PATCH 6/8] Review BUG-T2: zsh webui extras --- .../REVIEW_BUG-T2_zsh_webui_extras.md | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 SPECS/INPROGRESS/REVIEW_BUG-T2_zsh_webui_extras.md diff --git a/SPECS/INPROGRESS/REVIEW_BUG-T2_zsh_webui_extras.md b/SPECS/INPROGRESS/REVIEW_BUG-T2_zsh_webui_extras.md new file mode 100644 index 00000000..1f1221e6 --- /dev/null +++ b/SPECS/INPROGRESS/REVIEW_BUG-T2_zsh_webui_extras.md @@ -0,0 +1,29 @@ +## REVIEW REPORT — BUG-T2 zsh Web UI extras + +**Scope:** origin/main..HEAD +**Files:** 15 + +### Summary Verdict +- [ ] Approve +- [x] Approve with comments +- [ ] Request changes +- [ ] Block + +### Critical Issues +- None. + +### Secondary Issues +- [Low] Test runs produced non-blocking warnings from local port conflicts (`127.0.0.1:8080`/`9090`) in background Web UI test threads; this does not affect pass/fail status but can add noise in CI/local logs. + +### Architectural Notes +- The fix correctly targets shell command examples only and avoids changing JSON-based MCP config argument arrays, where shell glob expansion is not applicable. + +### Tests +- Quality gates executed and passed: + - `pytest` passed (`345 passed, 5 skipped`) + - `ruff check src/` passed + - `mypy src/` passed + - `pytest --cov` passed with `96.62%` coverage (>= 90%) + +### Next Steps +- FOLLOW-UP skipped: no actionable defects requiring additional backlog tasks. From cbe91abc4f09e5d57765abff2095bcfba54d112e Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sat, 14 Feb 2026 14:10:47 +0300 Subject: [PATCH 7/8] Archive REVIEW_BUG-T2_zsh_webui_extras report --- .../REVIEW_BUG-T2_zsh_webui_extras.md | 0 SPECS/ARCHIVE/INDEX.md | 2 ++ 2 files changed, 2 insertions(+) rename SPECS/{INPROGRESS => ARCHIVE/BUG-T2_codex_mcp_add_with_Web_UI_extras_fails_in_zsh}/REVIEW_BUG-T2_zsh_webui_extras.md (100%) diff --git a/SPECS/INPROGRESS/REVIEW_BUG-T2_zsh_webui_extras.md b/SPECS/ARCHIVE/BUG-T2_codex_mcp_add_with_Web_UI_extras_fails_in_zsh/REVIEW_BUG-T2_zsh_webui_extras.md similarity index 100% rename from SPECS/INPROGRESS/REVIEW_BUG-T2_zsh_webui_extras.md rename to SPECS/ARCHIVE/BUG-T2_codex_mcp_add_with_Web_UI_extras_fails_in_zsh/REVIEW_BUG-T2_zsh_webui_extras.md diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index ae748c4d..08483563 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -132,6 +132,7 @@ | [REVIEW_p9_t4_publishing_helper.md](P9-T4_Create_the_publishing_helper/REVIEW_p9_t4_publishing_helper.md) | Review report for P9-T4 | | [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 | ## Archive Log @@ -218,3 +219,4 @@ | 2026-02-13 | FU-P9-T2-2 | Archived REVIEW_fu_p9_t2_2_stale_uvx_troubleshooting report | | 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 | From 1d32d272a21b608c69d64359e77db3afe892c885 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sat, 14 Feb 2026 14:16:14 +0300 Subject: [PATCH 8/8] Add gh-create-pr skill for template-compliant PR creation --- .agents/skills/gh-create-pr/SKILL.md | 57 +++++++++++++++++++ .../skills/gh-create-pr/agents/openai.yaml | 4 ++ 2 files changed, 61 insertions(+) create mode 100644 .agents/skills/gh-create-pr/SKILL.md create mode 100644 .agents/skills/gh-create-pr/agents/openai.yaml diff --git a/.agents/skills/gh-create-pr/SKILL.md b/.agents/skills/gh-create-pr/SKILL.md new file mode 100644 index 00000000..cea12f46 --- /dev/null +++ b/.agents/skills/gh-create-pr/SKILL.md @@ -0,0 +1,57 @@ +--- +name: gh-create-pr +description: Create or update GitHub pull requests with the GitHub CLI (`gh`) using the repository PR template. Use when asked to open a PR, fix PR description formatting, align description with `.github/PULL_REQUEST_TEMPLATE.md`, or prepare a merge-ready PR with validation results. +--- + +# GH Create PR + +## Workflow + +1. Confirm branch and working tree are ready. +- Run `git status -sb`. +- Ensure commits are complete and branch is pushed. + +2. Collect PR context. +- Read `.github/PULL_REQUEST_TEMPLATE.md` when present. +- Gather summary of changes and executed checks from commits and task artifacts. +- Prefer factual check results and avoid claiming manual tests that were not run. + +3. Create or update PR with `gh`. +- Create: +```bash +gh pr create --base main --head --title "" --body-file <body.md> +``` +- Update existing PR description: +```bash +gh pr edit <number-or-url> --body-file <body.md> +``` + +4. Use template-accurate checkboxes. +- Mark only items that were actually completed. +- Leave unchecked items for unperformed steps. +- Keep wording from the template unchanged; only fill values/check states. + +5. Verify PR state. +- Open or print PR URL from `gh` output. +- Optionally run: +```bash +gh pr view <number-or-url> --json number,title,url,headRefName,baseRefName +``` + +## Body Authoring Rules + +- Keep description short and concrete. +- Include changed areas, bug/task ID when available, and validation commands. +- Mention warnings or non-blocking caveats if present. +- Do not include markdown sections not in the template when template compliance is requested. + +## Fast Patterns + +Template-first PR update: +1. Read template. +2. Create `body.md` following the exact headings/order. +3. Apply with `gh pr edit <pr> --body-file body.md`. + +New PR from current branch: +1. Build `body.md` from template. +2. Run `gh pr create --base main --head $(git branch --show-current) ...`. diff --git a/.agents/skills/gh-create-pr/agents/openai.yaml b/.agents/skills/gh-create-pr/agents/openai.yaml new file mode 100644 index 00000000..8c748264 --- /dev/null +++ b/.agents/skills/gh-create-pr/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "GitHub PR Creator" + short_description: "Create/update template-compliant GitHub PRs" + default_prompt: "Use $gh-create-pr to create or update a GitHub pull request with the repository template and accurate check results."