diff --git a/.claude/skills b/.claude/skills new file mode 120000 index 00000000..bc9bee63 --- /dev/null +++ b/.claude/skills @@ -0,0 +1 @@ +/Users/egor/Development/GitHub/XcodeMCPWrapper/.agents/skills \ No newline at end of file diff --git a/SPECS/ARCHIVE/FU-BUG-T6-1_Document_stale_process_cleanup/FU-BUG-T6-1_Document_stale_process_cleanup.md b/SPECS/ARCHIVE/FU-BUG-T6-1_Document_stale_process_cleanup/FU-BUG-T6-1_Document_stale_process_cleanup.md new file mode 100644 index 00000000..7a3bbe37 --- /dev/null +++ b/SPECS/ARCHIVE/FU-BUG-T6-1_Document_stale_process_cleanup/FU-BUG-T6-1_Document_stale_process_cleanup.md @@ -0,0 +1,73 @@ +# FU-BUG-T6-1: Document stale-process cleanup for Web UI port collisions + +**Task ID:** FU-BUG-T6-1 +**Type:** Follow-Up / Documentation +**Priority:** P2 +**Status:** In Progress +**Branch:** feature/FU-BUG-T6-1-stale-process-troubleshooting +**Created:** 2026-02-15 +**Depends on:** BUG-T6 (completed) + +--- + +## 1. Context + +BUG-T6 introduced port-availability checks so that when the Web UI port is already occupied, the wrapper: +- In bridge+webui mode: prints `Warning: Web UI port {port} is already in use. Skipping Web UI startup — MCP bridge will run without the dashboard.` and continues without the dashboard. +- In `--web-ui-only` mode: prints `Error: Web UI port {port} is already in use. Stop the existing process and retry.` and exits with code 1. + +These messages are clear, but users who see them have no guidance on *how* to identify and stop the stale process. This follow-up adds that guidance to `docs/troubleshooting.md`. + +--- + +## 2. Deliverables + +| # | Artifact | Location | +|---|----------|----------| +| 1 | New troubleshooting section "Web UI port is already in use" | `docs/troubleshooting.md` | + +--- + +## 3. Acceptance Criteria + +- [ ] AC1: Troubleshooting entry title or context clearly references the "port already in use" warning message from BUG-T6 so users can cross-reference. +- [ ] AC2: Entry includes diagnostic commands to identify the process holding the port (e.g., `lsof -i :` or `ps aux | grep mcpbridge`). +- [ ] AC3: Entry includes cleanup steps to kill the stale process. +- [ ] AC4: Entry notes that multiple wrapper processes can coexist (different ports or restarts) and advises verifying the correct PID. +- [ ] AC5: No code changes are required — docs-only change. + +--- + +## 4. Implementation Plan + +### 4.1 New section in `docs/troubleshooting.md` + +Insert a new section after the existing "Uptime still shows 1h 0m 0s" entry (which covers stale uvx cache), since they are closely related topics. + +**Section title:** `### "Web UI port N is already in use"` + +**Content outline:** +1. Symptom — show the exact warning/error strings from the source code +2. Cause — stale wrapper process from a previous run, a crashed client restart, or a parallel instance on the same port +3. Diagnosis — `lsof` / `ps` commands to find the PID +4. Recovery — kill the process and restart +5. Note about multiple processes on different ports + +--- + +## 5. Dependencies + +- BUG-T6 source code in `src/mcpbridge_wrapper/__main__.py` (already merged to main) +- Existing `docs/troubleshooting.md` structure (already read) + +--- + +## 6. Out of Scope + +- No code changes to the wrapper +- No changes to test suite +- No changes to other docs + +--- +**Archived:** 2026-02-15 +**Verdict:** PASS diff --git a/SPECS/ARCHIVE/FU-BUG-T6-1_Document_stale_process_cleanup/FU-BUG-T6-1_Validation_Report.md b/SPECS/ARCHIVE/FU-BUG-T6-1_Document_stale_process_cleanup/FU-BUG-T6-1_Validation_Report.md new file mode 100644 index 00000000..66397a6c --- /dev/null +++ b/SPECS/ARCHIVE/FU-BUG-T6-1_Document_stale_process_cleanup/FU-BUG-T6-1_Validation_Report.md @@ -0,0 +1,42 @@ +# FU-BUG-T6-1 Validation Report + +**Task:** Document stale-process cleanup for Web UI port collisions +**Date:** 2026-02-15 +**Branch:** feature/FU-BUG-T6-1-stale-process-troubleshooting +**Verdict:** PASS + +--- + +## Quality Gates + +| Gate | Command | Result | +|------|---------|--------| +| Linting | `ruff check src/` | ✅ All checks passed | +| Tests | `pytest` | ✅ 369 passed, 5 skipped, 3 warnings | +| Coverage | `pytest --cov` | ✅ 96.2% (requirement: ≥ 90%) | +| Type checking | `mypy src/` | — (not configured) | + +--- + +## Acceptance Criteria + +| # | Criterion | Status | +|---|-----------|--------| +| AC1 | Entry references the exact "port already in use" warning message from BUG-T6 | ✅ Both warning strings quoted verbatim | +| AC2 | Diagnostic commands to identify the process holding the port | ✅ `lsof -i TCP:$PORT -sTCP:LISTEN` and `ps aux | grep mcpbridge` | +| AC3 | Cleanup steps to kill the stale process | ✅ `kill ` and `pkill -f mcpbridge` | +| AC4 | Notes about multiple processes and verifying the correct PID | ✅ Note included at end of section | +| AC5 | Docs-only change (no code modifications) | ✅ Only `docs/troubleshooting.md` changed | + +--- + +## Changes Made + +- `docs/troubleshooting.md`: Added new section "Web UI port N is already in use" between the `zsh: no matches found` entry and the "Uptime still shows 1h 0m 0s" entry. + +The section covers: +1. Two symptom variants (bridge+webui mode and --web-ui-only mode) with exact warning text +2. Root cause explanation (stale process from crashed/restarted client) +3. `lsof` and `ps` diagnosis commands +4. `kill` and `pkill` recovery steps +5. Warning about multiple concurrent processes on different ports diff --git a/SPECS/ARCHIVE/FU-BUG-T6-1_Document_stale_process_cleanup/REVIEW_FU-BUG-T6-1_stale_process_cleanup.md b/SPECS/ARCHIVE/FU-BUG-T6-1_Document_stale_process_cleanup/REVIEW_FU-BUG-T6-1_stale_process_cleanup.md new file mode 100644 index 00000000..dad7c01c --- /dev/null +++ b/SPECS/ARCHIVE/FU-BUG-T6-1_Document_stale_process_cleanup/REVIEW_FU-BUG-T6-1_stale_process_cleanup.md @@ -0,0 +1,48 @@ +## REVIEW REPORT — FU-BUG-T6-1 stale-process cleanup documentation + +**Scope:** origin/main..HEAD (4 commits) +**Date:** 2026-02-15 +**Files changed:** `docs/troubleshooting.md` (docs only), SPECS artifacts + +--- + +### Summary Verdict + +- [x] Approve + +--- + +### Critical Issues + +None. + +--- + +### Secondary Issues + +None. + +--- + +### Architectural Notes + +- The new section correctly matches both warning variants emitted by `__main__.py` at lines 261–262 (bridge+webui mode) and lines 238–239 (`--web-ui-only` mode). Quoting the exact strings ensures users can match the output to the troubleshooting entry. +- Placement after the `zsh: no matches found` section and before the "Uptime still shows 1h 0m 0s" section is logical — all three are Web UI operational issues grouped together. +- `pkill -f mcpbridge` is a broad kill-all approach. It is safe here because it targets `mcpbridge` process names and there are no other system processes with that name. The note about multiple processes on different ports adds appropriate caution. +- The `lsof -i TCP:$PORT -sTCP:LISTEN` command is macOS-specific, which is fine because this project targets macOS/Xcode exclusively. + +--- + +### Tests + +- This is a docs-only change; no test changes are required. +- Quality gate results at time of execute: + - `ruff check src/`: ✅ All checks passed + - `pytest`: ✅ 369 passed, 5 skipped + - Coverage: ✅ 96.2% (requirement ≥ 90%) + +--- + +### Next Steps + +No actionable findings. FOLLOW-UP step is skipped. diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index 66f02a58..03e8b6b3 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -1,6 +1,6 @@ # mcpbridge-wrapper Tasks Archive -**Last Updated:** 2026-02-14 (BUG-T7) +**Last Updated:** 2026-02-15 (FU-BUG-T6-1) ## Archived Tasks @@ -88,6 +88,7 @@ | BUG-T5 | [BUG-T5_Empty-content_tool_results_structuredContent/](BUG-T5_Empty-content_tool_results_structuredContent/) | 2026-02-14 | PASS | | BUG-T6 | [BUG-T6_WebUI_Port_Collision/](BUG-T6_WebUI_Port_Collision/) | 2026-02-14 | PASS | | BUG-T7 | [BUG-T7_Resources_Error_Normalization/](BUG-T7_Resources_Error_Normalization/) | 2026-02-14 | PASS | +| FU-BUG-T6-1 | [FU-BUG-T6-1_Document_stale_process_cleanup/](FU-BUG-T6-1_Document_stale_process_cleanup/) | 2026-02-15 | PASS | ## Historical Artifacts @@ -140,6 +141,7 @@ | [REVIEW_BUG-T3_webui_only_mode.md](BUG-T3_webui_only_dashboard_mode/REVIEW_BUG-T3_webui_only_mode.md) | Review report for BUG-T3 | | [REVIEW_BUG-T5_structuredContent_empty_content.md](BUG-T5_Empty-content_tool_results_structuredContent/REVIEW_BUG-T5_structuredContent_empty_content.md) | Review report for BUG-T5 | | [REVIEW_BUG-T6_port_collision.md](BUG-T6_WebUI_Port_Collision/REVIEW_BUG-T6_port_collision.md) | Review report for BUG-T6 | +| [REVIEW_FU-BUG-T6-1_stale_process_cleanup.md](FU-BUG-T6-1_Document_stale_process_cleanup/REVIEW_FU-BUG-T6-1_stale_process_cleanup.md) | Review report for FU-BUG-T6-1 | ## Archive Log @@ -233,3 +235,5 @@ | 2026-02-14 | BUG-T5 | Archived REVIEW_BUG-T5_structuredContent_empty_content report | | 2026-02-14 | BUG-T6 | Archived WebUI_Port_Collision (PASS) | | 2026-02-14 | BUG-T6 | Archived REVIEW_BUG-T6_port_collision report | +| 2026-02-15 | FU-BUG-T6-1 | Archived Document_stale_process_cleanup (PASS) | +| 2026-02-15 | FU-BUG-T6-1 | Archived REVIEW_FU-BUG-T6-1_stale_process_cleanup report | diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index 57593830..8ddf9caf 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -4,15 +4,15 @@ The previously selected task has been archived. ## Recently Archived +- 2026-02-15 — FU-BUG-T6-1: Document stale-process cleanup for Web UI port collisions (PASS) - 2026-02-14 — BUG-T7: Unsupported `resources/*` methods can return non-standard error shape (PASS) - 2026-02-14 — BUG-T6: Web UI port collisions create unstable multi-process behavior (PASS) - 2026-02-14 — BUG-T5: Empty-content tool results can still violate strict `structuredContent` contract (PASS) - 2026-02-14 — BUG-T3: Web UI cannot stay available when MCP bridge initialization fails (PASS) - 2026-02-14 — BUG-T2: codex mcp add with Web UI extras fails in zsh (PASS) - 2026-02-13 — FU-P9-T2-2: Add troubleshooting guidance for stale uvx cache/process versions (PASS) -- 2026-02-13 — FU-P9-T4-1: Align publish_helper output with protected main branch workflow (PASS) ## Suggested Next Tasks -- BUG-T1: Kimi CLI MCP Connection Failure (P1, if applicable) -- FU-BUG-T6-1: Document stale-process cleanup in troubleshooting (P2) +- FU-BUG-T7-1: Cap `pending_methods` map to guard against unbounded growth (P3) +- BUG-T1: Kimi CLI MCP Connection Failure (P2, if applicable) diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index fafad3ec..5623ff61 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -1810,7 +1810,7 @@ Phase 9 Follow-up Backlog --- -#### FU-BUG-T6-1: Document stale-process cleanup for Web UI port collisions +#### ✅ FU-BUG-T6-1: Document stale-process cleanup for Web UI port collisions - **Description:** Add a troubleshooting entry explaining how to identify and kill stale wrapper/uvx processes occupying the Web UI port. Include diagnostic commands (e.g., `lsof -i :` or `ps aux | grep mcpbridge`) and cleanup steps. - **Priority:** P2 - **Dependencies:** BUG-T6 @@ -1818,9 +1818,9 @@ Phase 9 Follow-up Backlog - **Outputs/Artifacts:** - Updated `docs/troubleshooting.md` with stale-process cleanup section - **Acceptance Criteria:** - - [ ] Troubleshooting entry covers the "port already in use" warning message - - [ ] Commands for identifying and killing stale processes are included - - [ ] Relates the fix to the BUG-T6 warning text so users can cross-reference + - [x] Troubleshooting entry covers the "port already in use" warning message + - [x] Commands for identifying and killing stale processes are included + - [x] Relates the fix to the BUG-T6 warning text so users can cross-reference --- diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md index f55f58f0..ce993862 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md @@ -182,6 +182,49 @@ Alternative escaped form: codex mcp add xcode -- uvx --from mcpbridge-wrapper\\[webui\\] mcpbridge-wrapper --web-ui --web-ui-port 8080 ``` +## Error: "Web UI port N is already in use" + +**Symptom (bridge + Web UI mode):** Wrapper starts without a dashboard after printing: + +``` +Warning: Web UI port 8080 is already in use. Skipping Web UI startup — MCP bridge will run without the dashboard. +``` + +**Symptom (`--web-ui-only` mode):** Command exits with code 1 after printing: + +``` +Error: Web UI port 8080 is already in use. Stop the existing process and retry. +``` + +**Cause:** A stale wrapper process from a previous run (or a crashed client restart) is still occupying the port. Multiple processes can exist simultaneously — for example after a Cursor restart — because the old process is never explicitly stopped. + +**Diagnosis:** + +```bash +# Find the PID of the process listening on the Web UI port (default 8080) +PORT=8080 +lsof -i TCP:$PORT -sTCP:LISTEN + +# Alternatively, search by process name +ps aux | grep mcpbridge +``` + +Both commands show the PID in the second column (`PID`). + +**Recovery:** + +```bash +# Kill the stale process by PID +kill + +# Or kill all wrapper/bridge processes in one step +pkill -f mcpbridge +``` + +After stopping the stale process, restart your MCP client (Cursor / Zed / Claude Code) or re-run the `--web-ui-only` command and the port should now be free. + +**Note:** Multiple wrapper processes can run simultaneously on *different* ports. Make sure you identify the PID bound specifically to the port you want, not just any `mcpbridge` process. + ## 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/docs/troubleshooting.md b/docs/troubleshooting.md index 916edcee..0547655f 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -211,6 +211,51 @@ Alternative escaped form: codex mcp add xcode -- uvx --from mcpbridge-wrapper\\[webui\\] mcpbridge-wrapper --web-ui --web-ui-port 8080 ``` +### "Web UI port N is already in use" + +**Symptom (bridge + Web UI mode):** Wrapper starts without a dashboard after printing: + +``` +Warning: Web UI port 8080 is already in use. Skipping Web UI startup — MCP bridge will run without the dashboard. +``` + +**Symptom (`--web-ui-only` mode):** Command exits with code 1 after printing: + +``` +Error: Web UI port 8080 is already in use. Stop the existing process and retry. +``` + +**Cause:** A stale wrapper process from a previous run (or a crashed client restart) is still occupying the port. Multiple processes can exist simultaneously — for example after a Cursor restart — because the old process is never explicitly stopped. + +**Diagnosis:** + +```bash +# Find the PID of the process listening on the Web UI port (default 8080) +PORT=8080 +lsof -i TCP:$PORT -sTCP:LISTEN + +# Alternatively, search by process name +ps aux | grep mcpbridge +``` + +Both commands show the PID in the second column (`PID`). + +**Recovery:** + +```bash +# Kill the stale process by PID +kill + +# Or kill all wrapper/bridge processes in one step +pkill -f mcpbridge +``` + +After stopping the stale process, restart your MCP client (Cursor / Zed / Claude Code) or re-run the `--web-ui-only` command and the port should now be free. + +**Note:** Multiple wrapper processes can run simultaneously on *different* ports. Make sure you identify the PID bound specifically to the port you want, not just any `mcpbridge` process. + +--- + ### "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`).