diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index 9eba511e..1019ff5f 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -1,11 +1,12 @@ # mcpbridge-wrapper Tasks Archive -**Last Updated:** 2026-03-01 (P2-T5 archived) +**Last Updated:** 2026-03-01 (P1-T4 archived) ## Archived Tasks | Task ID | Folder | Archived | Verdict | |---------|--------|----------|---------| +| P1-T4 | [P1-T4_Update_docs_broker_robustness/](P1-T4_Update_docs_broker_robustness/) | 2026-03-01 | PASS | | P2-T5 | [P2-T5_Warn_when_broker_lacks_web_ui/](P2-T5_Warn_when_broker_lacks_web_ui/) | 2026-03-01 | PASS | | P2-T4 | [P2-T4_Surface_broker_unavailability_as_JSONRPC_error/](P2-T4_Surface_broker_unavailability_as_JSONRPC_error/) | 2026-03-01 | PASS | | P2-T3 | [P2-T3_Fix_double_spawn_race_condition/](P2-T3_Fix_double_spawn_race_condition/) | 2026-03-01 | PASS | @@ -171,6 +172,7 @@ | Folder | Description | |--------|-------------| | [_Historical/](_Historical/) | Non-task artifacts | +| [P1-T4_Update_docs_broker_robustness/REVIEW_P1-T4_docs_broker_robustness.md](P1-T4_Update_docs_broker_robustness/REVIEW_P1-T4_docs_broker_robustness.md) | Review report for P1-T4 | ### Historical Files @@ -300,6 +302,7 @@ | Date | Task ID | Action | |------|---------|--------| +| 2026-03-01 | P1-T4 | Archived Update docs to reflect broker robustness improvements (PASS) | | 2026-03-01 | P2-T3 | Archived Fix double-spawn race condition when MCP client toggles rapidly (PASS) | | 2026-03-01 | P2-T1 | Archived Replace --broker-spawn/--broker-connect with single --broker flag (PASS) | | 2026-03-01 | P2-T2 | Archived Self-healing stale socket and PID file recovery (PASS) | diff --git a/SPECS/ARCHIVE/P1-T4_Update_docs_broker_robustness/P1-T4_Update_docs_broker_robustness.md b/SPECS/ARCHIVE/P1-T4_Update_docs_broker_robustness/P1-T4_Update_docs_broker_robustness.md new file mode 100644 index 00000000..7b78f186 --- /dev/null +++ b/SPECS/ARCHIVE/P1-T4_Update_docs_broker_robustness/P1-T4_Update_docs_broker_robustness.md @@ -0,0 +1,75 @@ +# P1-T4 — Update docs to reflect broker robustness improvements (P2-T1 – P2-T5) + +**Status:** In Progress +**Priority:** P2 +**Dependencies:** P2-T1, P2-T2, P2-T4, P2-T5 (all completed 2026-03-01) +**Branch:** feature/P1-T4-docs-broker-robustness + +--- + +## Background + +Phase 2 broker robustness tasks shipped four user-visible behaviour changes that the existing documentation does not reflect: + +| Task | Change | +|------|--------| +| P2-T1 | `--broker` flag introduced as the single recommended proxy mode (auto-detects connect vs spawn). `--broker-spawn` and `--broker-connect` become legacy aliases. | +| P2-T2 | `--broker` / `--broker-spawn` now detect and remove stale socket/PID files automatically before spawning. Manual cleanup is only needed for `--broker-connect`. | +| P2-T4 | When the broker is unreachable, the proxy writes a JSON-RPC `-32001` error response to stdout instead of silently hanging. | +| P2-T5 | When `--broker --web-ui` is used but the running daemon was started without `--web-ui`, the proxy prints an actionable warning to stderr. | + +The README was already updated to use `--broker` everywhere (completed in P2-T1). The individual `docs/` files and their DocC mirrors were not. + +--- + +## Scope + +### Files to update + +| File | Changes needed | +|------|---------------| +| `docs/broker-mode.md` | Add `--broker` to mode table; update topology, client examples, migration, and limitations sections | +| `docs/troubleshooting.md` | Update "Could not connect" entry (JSON-RPC error + auto-recovery note); update "Stale recovery" entry; add "Warning: broker without --web-ui" entry; update rollback entry | +| `docs/cursor-setup.md` | Replace broker mode section with `--broker` primary / `--broker-connect` advanced; update migration note | +| `docs/claude-setup.md` | Same as cursor-setup | +| `docs/codex-setup.md` | Same as cursor-setup | +| `Sources/.../CursorSetup.md` | DocC mirror of cursor-setup changes | +| `Sources/.../ClaudeCodeSetup.md` | DocC mirror of claude-setup changes | +| `Sources/.../CodexCLISetup.md` | DocC mirror of codex-setup changes | +| `Sources/.../Troubleshooting.md` | DocC mirror of troubleshooting changes | + +### Files NOT in scope + +- `README.md` — already updated (P2-T1) +- Source code — documentation-only task +- `docs/webui-setup.md`, `docs/architecture.md` — no relevant changes in P2-T1–T5 + +--- + +## Deliverables + +1. **9 updated markdown files** — all doc and DocC changes applied +2. **`SPECS/INPROGRESS/P1-T4_Validation_Report.md`** — quality gate results + +--- + +## Acceptance Criteria + +- [ ] `docs/broker-mode.md` mode table includes `--broker` as primary recommended flag +- [ ] `--broker-connect` and `--broker-spawn` described as legacy aliases in broker-mode.md +- [ ] Broker mode limitations section no longer says stale files require manual cleanup +- [ ] `docs/troubleshooting.md` "Could not connect" entry shows JSON-RPC -32001 error format +- [ ] `docs/troubleshooting.md` "Stale recovery" entry notes auto-recovery for `--broker` +- [ ] `docs/troubleshooting.md` contains new "Warning: broker running without --web-ui" entry +- [ ] All three client setup docs show `--broker` as the recommended broker option +- [ ] DocC sync check passes: `make doccheck-all` exits 0 +- [ ] `ruff check src/` passes (no source changes, should be clean) +- [ ] `pytest` passes (no source changes, should be clean) + +--- + +## Implementation Notes + +- All doc changes are documentation-only; no Python source files are modified. +- The DocC files in `Sources/XcodeMCPWrapper/Documentation.docc/` are mirrors of the `docs/` files; the project's `make doccheck-all` gate enforces their sync. +- The `--broker-spawn` and `--broker-connect` flags remain valid (backwards-compatible aliases); docs should note this rather than omit them entirely. diff --git a/SPECS/ARCHIVE/P1-T4_Update_docs_broker_robustness/P1-T4_Validation_Report.md b/SPECS/ARCHIVE/P1-T4_Update_docs_broker_robustness/P1-T4_Validation_Report.md new file mode 100644 index 00000000..32cd4a19 --- /dev/null +++ b/SPECS/ARCHIVE/P1-T4_Update_docs_broker_robustness/P1-T4_Validation_Report.md @@ -0,0 +1,47 @@ +# P1-T4 Validation Report + +**Task:** Update docs to reflect broker robustness improvements (P2-T1 – P2-T5) +**Date:** 2026-03-01 +**Verdict:** PASS + +--- + +## Quality Gates + +| Gate | Result | Detail | +|------|--------|--------| +| `pytest` | ✅ PASS | 737 passed, 5 skipped, 2 warnings | +| `ruff check src/` | ✅ PASS | All checks passed | +| `pytest --cov` | ✅ PASS | 91.3% coverage (≥90% required) | +| `make doccheck-all` | ✅ PASS | DocC sync verified across all scopes | + +--- + +## Files Changed + +| File | Change summary | +|------|---------------| +| `docs/broker-mode.md` | Added `--broker` to mode table; updated topology, Web UI note, client examples (Cursor/Zed/Claude/Codex), migration and rollback sections; rewrote Limitations to note auto-recovery | +| `docs/troubleshooting.md` | Updated "Could not connect" (JSON-RPC error + auto-recovery note); updated "Stale recovery" (auto for `--broker`); added "Warning: broker without --web-ui" entry; updated rollback entry | +| `docs/cursor-setup.md` | Merged two broker sections into `--broker` primary + `--broker-connect` advanced; updated migration note and troubleshooting entry | +| `docs/claude-setup.md` | Same pattern as cursor-setup | +| `docs/codex-setup.md` | Same pattern as cursor-setup | +| `Sources/.../CursorSetup.md` | DocC mirror of cursor-setup changes | +| `Sources/.../ClaudeCodeSetup.md` | DocC mirror of claude-setup changes | +| `Sources/.../CodexCLISetup.md` | DocC mirror of codex-setup changes | +| `Sources/.../Troubleshooting.md` | DocC mirror of troubleshooting changes including new web-UI mismatch entry | + +--- + +## Acceptance Criteria + +- [x] `docs/broker-mode.md` mode table includes `--broker` as primary recommended flag +- [x] `--broker-connect` and `--broker-spawn` described as legacy aliases in broker-mode.md +- [x] Broker mode limitations section no longer says stale files require manual cleanup +- [x] `docs/troubleshooting.md` "Could not connect" entry shows JSON-RPC -32001 error format +- [x] `docs/troubleshooting.md` "Stale recovery" entry notes auto-recovery for `--broker` +- [x] `docs/troubleshooting.md` contains new "Warning: broker running without --web-ui" entry +- [x] All three client setup docs show `--broker` as the recommended broker option +- [x] DocC sync check passes: `make doccheck-all` exits 0 +- [x] `ruff check src/` passes +- [x] `pytest` passes diff --git a/SPECS/ARCHIVE/P1-T4_Update_docs_broker_robustness/REVIEW_P1-T4_docs_broker_robustness.md b/SPECS/ARCHIVE/P1-T4_Update_docs_broker_robustness/REVIEW_P1-T4_docs_broker_robustness.md new file mode 100644 index 00000000..27d5b55e --- /dev/null +++ b/SPECS/ARCHIVE/P1-T4_Update_docs_broker_robustness/REVIEW_P1-T4_docs_broker_robustness.md @@ -0,0 +1,78 @@ +## REVIEW REPORT — P1-T4 docs broker robustness + +**Scope:** origin/main..HEAD (5 commits) +**Files:** 9 markdown files (5 docs/, 4 DocC mirrors) +**Date:** 2026-03-01 + +--- + +### Summary Verdict +- [ ] Approve +- [x] Approve with comments +- [ ] Request changes +- [ ] Block + +All primary acceptance criteria are met. Two minor gaps found — one missed update in `docs/troubleshooting.md` and one out-of-scope file pair that are now inconsistent. + +--- + +### Critical Issues + +None. + +--- + +### Secondary Issues + +**[Medium] `docs/troubleshooting.md` "MCP tools are green, but dashboard is unreachable" section not updated** + +Lines 309 and 334 still reference `--broker-spawn` as the primary flag: + +``` +- `--broker-connect` never starts a dashboard by itself; `--broker-spawn --web-ui` only starts one when it must spawn a host. +``` + +``` +3. **Unified broker single-config:** use `--broker-spawn --web-ui --web-ui-config ` in all clients… +``` + +The DocC mirror (`Sources/.../Troubleshooting.md`) was correctly updated to `--broker` for both of these lines during EXECUTE, but the `docs/troubleshooting.md` source was not. This creates a sync divergence between the two files that `make doccheck-all` does not catch (the check enforces that docs → DocC updates happen together, but does not detect the reverse). + +**Fix:** Update both occurrences in `docs/troubleshooting.md` to match the DocC mirror. + +--- + +**[Low] `docs/webui-setup.md` and its DocC mirror `WebUIDashboard.md` not updated** + +Both files still use `--broker-spawn` in their multi-agent setup examples (lines 101 and 107 in each): + +``` +use `--broker-spawn --web-ui --web-ui-config ` across Cursor/Zed/Claude/Codex +``` + +These files were explicitly excluded from scope in the P1-T4 PRD ("docs/webui-setup.md — no relevant changes in P2-T1–T5"). However, the guidance is now inconsistent with all other broker docs that use `--broker`. + +**Fix:** Update `docs/webui-setup.md` and `Sources/.../WebUIDashboard.md` to use `--broker` in multi-agent examples in a follow-up task. + +--- + +### Architectural Notes + +- The `--broker-spawn` legacy alias correctly remains visible in the docs in backward-compat contexts (rollback instructions, stale-recovery notes, "Warning: broker without --web-ui" cause explanation). These references are accurate and should not be removed. +- DocC sync enforcement (`make doccheck-all`) catches docs→DocC divergence but not DocC→docs divergence. The medium finding above was only caught by manual grep. The sync script could be enhanced to check both directions, but that is out of scope here. + +--- + +### Tests + +- `pytest`: 737 passed, 5 skipped — no regressions (documentation-only change) +- `ruff check src/`: clean — no source changes +- `pytest --cov`: 91.3% — above 90% threshold +- `make doccheck-all`: passed — DocC mirrors in sync for all changed `docs/` files + +--- + +### Next Steps + +1. **Follow-up task (Medium):** Fix 2 remaining `--broker-spawn` references in `docs/troubleshooting.md` "MCP tools are green" section. +2. **Follow-up task (Low):** Update `docs/webui-setup.md` and `Sources/.../WebUIDashboard.md` multi-agent examples to use `--broker`. diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index cd7e93bb..ca805305 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,9 +1,10 @@ # No Active Task -**Status:** Idle — P2-T5 archived. Select the next task from `SPECS/Workplan.md`. +**Status:** Idle — P1-T4 archived. Select the next task from `SPECS/Workplan.md`. ## Recently Archived +- **P1-T4** — Update docs to reflect broker robustness improvements (2026-03-01, PASS) - **P2-T5** — Warn or restart daemon when --web-ui requested but running broker lacks it (2026-03-01, PASS) - **P2-T4** — Surface broker unavailability as JSON-RPC error instead of silent timeout (2026-03-01, PASS) - **P2-T3** — Fix double-spawn race condition when MCP client toggles rapidly (2026-03-01, PASS) diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index 5a547bc6..22ab98ca 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -54,6 +54,52 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m - [x] `README.md` presents broker setup before alternative/manual setup in MCP settings examples for Cursor, Claude Code, and Codex CLI - [x] The MCP example sections use consistent wording and ordering so users can follow the broker-first path without ambiguity +#### ✅ P1-T4: Update docs to reflect broker robustness improvements (P2-T1 – P2-T5) +- **Status:** ✅ Completed (2026-03-01) +- **Description:** The docs/broker-mode.md, docs/troubleshooting.md, docs/cursor-setup.md, docs/claude-setup.md, and docs/codex-setup.md (plus their DocC mirrors) still reference the old `--broker-spawn`/`--broker-connect` flags as primary options, describe stale-socket cleanup as manual, and omit the new `--broker` flag (P2-T1), auto-recovery behaviour (P2-T2), JSON-RPC -32001 error response (P2-T4), and the web-UI mismatch warning (P2-T5). Update all five docs + four DocC files to reflect the current behaviour. +- **Priority:** P2 +- **Dependencies:** P2-T1, P2-T2, P2-T4, P2-T5 +- **Parallelizable:** yes +- **Outputs/Artifacts:** + - `docs/broker-mode.md` — mode table, topology, examples, limitations updated + - `docs/troubleshooting.md` — stale-recovery, connect-timeout, web-UI mismatch entries updated + - `docs/cursor-setup.md`, `docs/claude-setup.md`, `docs/codex-setup.md` — broker examples updated + - `Sources/XcodeMCPWrapper/Documentation.docc/` — four mirror files synced +- **Acceptance Criteria:** + - [ ] `--broker` appears as the recommended flag in all broker sections + - [ ] `--broker-connect`/`--broker-spawn` demoted to legacy/advanced entries + - [ ] Stale-socket recovery described as automatic for `--broker`/`--broker-spawn` + - [ ] Troubleshooting entry for JSON-RPC -32001 error present + - [ ] New troubleshooting entry for "Warning: broker is running without --web-ui" present + - [ ] DocC sync check passes (`make doccheck-all`) + +#### ⬜ P1-T5: Fix missed --broker-spawn references in troubleshooting.md "MCP tools are green" section +- **Status:** ⬜ Pending +- **Description:** Two lines in `docs/troubleshooting.md` "MCP tools are green, but dashboard is unreachable" section still say `--broker-spawn` where they should say `--broker`. The DocC mirror (`Sources/.../Troubleshooting.md`) was correctly updated in P1-T4 but the docs source was missed. Found during P1-T4 review (medium severity). +- **Priority:** P2 +- **Dependencies:** P1-T4 +- **Parallelizable:** yes +- **Outputs/Artifacts:** + - `docs/troubleshooting.md` — 2 occurrences updated in "MCP tools are green" section +- **Acceptance Criteria:** + - [ ] `docs/troubleshooting.md` line "only starts one when it must spawn a host" uses `--broker --web-ui` + - [ ] `docs/troubleshooting.md` "Unified broker single-config" solution option uses `--broker --web-ui` + - [ ] `make doccheck-all` passes (mirrors stay in sync) + +#### ⬜ P1-T6: Update webui-setup.md and DocC mirror to use --broker in multi-agent examples +- **Status:** ⬜ Pending +- **Description:** `docs/webui-setup.md` and `Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md` still use `--broker-spawn` in their multi-agent broker setup examples. These files were out of scope for P1-T4 but are now inconsistent with all other broker docs. Found during P1-T4 review (low severity). +- **Priority:** P3 +- **Dependencies:** P1-T4 +- **Parallelizable:** yes +- **Outputs/Artifacts:** + - `docs/webui-setup.md` — multi-agent examples updated to `--broker` + - `Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md` — mirror synced +- **Acceptance Criteria:** + - [ ] `docs/webui-setup.md` multi-agent broker example uses `--broker` + - [ ] DocC mirror updated to match + - [ ] `make doccheck-all` passes + ### Phase 2: Broker Robustness #### ✅ P2-T1: Replace --broker-spawn/--broker-connect with single --broker flag diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md b/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md index fb20adf6..87565cb9 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md @@ -24,16 +24,16 @@ claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' ### Option 1C: Using Broker Mode (Optional) -Connect to an already-running broker: +`--broker` auto-detects: connects if a daemon is running, spawns one otherwise. Stale socket/PID files from a crashed daemon are cleaned up automatically. ```bash -claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker ``` -Best-effort auto-spawn mode: +Advanced — connect-only (no auto-spawn): ```bash -claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-spawn +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect ``` ### Option 2: Using Manual Installation @@ -62,7 +62,7 @@ Replace `/path/to/XcodeMCPWrapper` with the actual path to your cloned repositor ### Migration and Rollback -- Migration: add `--broker-connect` or `--broker-spawn` to your `claude mcp add` command. +- Migration: add `--broker` to your `claude mcp add` command. - Rollback: remove broker flags and re-run the command. ### Verify Configuration @@ -134,5 +134,4 @@ Make sure Xcode Tools MCP is enabled in Xcode: **"Could not connect to broker socket ... within 10.0s"** -Broker mode could not reach a ready socket. Verify broker status or remove -broker flags to return to direct mode. +Broker mode could not reach a ready socket. If using `--broker`, stale files are cleaned up automatically; verify broker status or remove broker flags to return to direct mode. diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md b/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md index d465f6d7..de185495 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md @@ -24,16 +24,16 @@ codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper - ### Option 1C: Using Broker Mode (Optional) -Connect to an already-running broker: +`--broker` auto-detects: connects if a daemon is running, spawns one otherwise. Stale socket/PID files from a crashed daemon are cleaned up automatically. ```bash -codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect +codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker ``` -Best-effort auto-spawn mode: +Advanced — connect-only (no auto-spawn): ```bash -codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-spawn +codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect ``` ### Option 2: Using Manual Installation @@ -62,7 +62,7 @@ Replace `/path/to/XcodeMCPWrapper` with the actual path to your cloned repositor ### Migration and Rollback -- Migration: add `--broker-connect` or `--broker-spawn` to your `codex mcp add` command. +- Migration: add `--broker` to your `codex mcp add` command. - Rollback: remove broker flags and re-run the command. ### Verify Configuration @@ -145,5 +145,4 @@ Make sure Xcode Tools MCP is enabled in Xcode: **"Could not connect to broker socket ... within 10.0s"** -Broker mode could not reach a ready socket. Verify broker status or remove -broker flags to return to direct mode. +Broker mode could not reach a ready socket. If using `--broker`, stale files are cleaned up automatically; verify broker status or remove broker flags to return to direct mode. diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/CursorSetup.md b/Sources/XcodeMCPWrapper/Documentation.docc/CursorSetup.md index 310d2c9d..a899bb7f 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/CursorSetup.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/CursorSetup.md @@ -109,7 +109,7 @@ Replace `/path/to/XcodeMCPWrapper` with the actual path to your cloned repositor ### Option 4: Using Broker Mode (Optional) -Connect mode: +`--broker` auto-detects: connects if a daemon is running, spawns one otherwise. Stale socket/PID files from a crashed daemon are cleaned up automatically. ```json { @@ -120,14 +120,14 @@ Connect mode: "--from", "mcpbridge-wrapper", "mcpbridge-wrapper", - "--broker-connect" + "--broker" ] } } } ``` -Best-effort auto-spawn mode: +Advanced — connect-only (no auto-spawn, manage daemon lifecycle yourself): ```json { @@ -138,14 +138,14 @@ Best-effort auto-spawn mode: "--from", "mcpbridge-wrapper", "mcpbridge-wrapper", - "--broker-spawn" + "--broker-connect" ] } } } ``` -Migration: add `--broker-connect` or `--broker-spawn` to existing args. +Migration: add `--broker` to existing args. Rollback: remove broker flags and restart Cursor. ### Restart Cursor @@ -192,8 +192,7 @@ Make sure Xcode Tools MCP is enabled in Xcode: **"Could not connect to broker socket ... within 10.0s"** -The broker socket is not ready. Use `--broker-connect` with an explicitly -started broker host, or remove broker flags to return to direct mode. +The broker socket is not ready. If using `--broker`, stale files are cleaned up automatically; verify broker status or remove broker flags to return to direct mode. **"Web UI still shows old behavior after an upgrade"** diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md index 2170c13a..a055277d 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md @@ -272,7 +272,7 @@ Prefer `kill` (`SIGTERM`) first; use `kill -9` only when the process does not ex - MCP can stay healthy even if Web UI startup is skipped. - Only one process can own a given Web UI `host:port`. - Dashboard starts in a direct-mode owner (`--web-ui`) or a broker host (`--broker-daemon --web-ui`). -- `--broker-connect` never starts a dashboard by itself; `--broker-spawn --web-ui` only starts one when it must spawn a host. +- `--broker-connect` never starts a dashboard by itself; `--broker --web-ui` only starts one when it must spawn a host. - If dashboard bind fails (port already in use), wrapper logs a warning and continues MCP without dashboard hosting. - A healthy MCP status does not guarantee an active dashboard listener on the expected port. @@ -297,7 +297,7 @@ If step 1 returns no listener, no process currently owns the dashboard port. 1. **Single dashboard owner (direct mode):** keep `--web-ui` on one client config only. 2. **Use separate dashboard ports:** assign unique `--web-ui-port` values per process. -3. **Unified broker single-config:** use `--broker-spawn --web-ui --web-ui-config ` in all clients so one spawned host owns the dashboard. +3. **Unified broker single-config:** use `--broker --web-ui --web-ui-config ` in all clients so one spawned host owns the dashboard. 4. **Dedicated host pattern:** run one `--broker-daemon --web-ui` process, keep clients on `--broker-connect`, and monitor `~/.mcpbridge_wrapper/broker.log`. 5. **Standalone diagnostics:** run `--web-ui-only` when you need dashboard-only debugging independent from MCP startup. @@ -378,16 +378,46 @@ The second value should be larger. ## Error: "Could not connect to broker socket ... within 10.0s" -**Symptom:** Broker mode exits with a timeout waiting for `broker.sock`. +**Symptom:** Broker mode prints a JSON-RPC error and exits: + +```json +{"jsonrpc":"2.0","id":null,"error":{"code":-32001,"message":"Broker unavailable: Could not connect to broker socket ... within 10.0s"}} +``` **Cause:** Broker process is not running, or socket state is stale. +**Note:** When using `--broker` or `--broker-spawn`, stale socket/PID files are detected and removed automatically. Manual cleanup is only needed with `--broker-connect`. + **Solution:** ```bash PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; SOCK="$HOME/.mcpbridge_wrapper/broker.sock"; if [ -f "$PID_FILE" ] && kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then echo "broker running"; else echo "broker not running"; fi; ls -l "$SOCK" 2>/dev/null || echo "socket missing" ``` +If broker is not running, switch to `--broker` (auto-detects and spawns) or start it manually and use `--broker-connect`. + +## Warning: "broker is running without --web-ui on port N" + +**Symptom:** After connecting in broker mode, a warning appears on stderr: + +```text +Warning: broker is running without --web-ui on port 8080. Restart the broker to enable the dashboard. + Hint: stop the running broker (rm ~/.mcpbridge_wrapper/broker.sock ~/.mcpbridge_wrapper/broker.pid) then reconnect with --broker --web-ui. +``` + +**Cause:** You passed `--broker --web-ui` but the already-running broker daemon was started without `--web-ui`. The proxy detects the mismatch via a TCP port probe and prints this warning. The MCP session continues normally. + +**Solution:** Stop the running broker and reconnect: + +```bash +PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid" +SOCK="$HOME/.mcpbridge_wrapper/broker.sock" +[ -f "$PID_FILE" ] && kill "$(cat "$PID_FILE")" 2>/dev/null || true +rm -f "$PID_FILE" "$SOCK" +``` + +Then restart your MCP client. The next connection will spawn a fresh daemon that includes the dashboard. + ## Error: "Broker already running (PID ...)" **Symptom:** Explicit broker startup fails because an existing broker lock is active. @@ -400,6 +430,10 @@ PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; if [ -f "$PID_FILE" ]; then kill ## Stale broker lock/socket recovery +When using `--broker` or `--broker-spawn`, stale socket/PID files are detected automatically and removed before spawning a fresh daemon. No manual cleanup is required in normal use. + +If you are using `--broker-connect` (connect-only, no auto-spawn) and a crash has left orphaned files, clean them explicitly: + ```bash PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; SOCK="$HOME/.mcpbridge_wrapper/broker.sock"; if [ -f "$PID_FILE" ] && ! kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then rm -f "$PID_FILE"; fi; if [ -S "$SOCK" ]; then rm -f "$SOCK"; fi ``` @@ -435,7 +469,7 @@ rm -f ~/.mcpbridge_wrapper/broker.pid ~/.mcpbridge_wrapper/broker.sock ## Rollback to direct mode -1. Remove `--broker-connect` / `--broker-spawn` from MCP config args. +1. Remove `--broker`, `--broker-connect`, or `--broker-spawn` from MCP config args. 2. Restart the MCP client. 3. Stop and clean broker state: diff --git a/docs/broker-mode.md b/docs/broker-mode.md index 9d8d1598..c58c7937 100644 --- a/docs/broker-mode.md +++ b/docs/broker-mode.md @@ -9,8 +9,9 @@ Broker mode lets short-lived MCP client processes share a single long-lived upst |------|------| | *(none — default)* | `direct`: each wrapper process launches its own upstream bridge. | | `--broker-daemon` | **Daemon host**: long-lived process that owns the upstream bridge and accepts client connections on a Unix socket. Start this once, then point clients at it. | -| `--broker-connect` | **Proxy**: connects to an already-running broker socket and forwards stdio. | -| `--broker-spawn` | **Proxy + auto-start**: same as `--broker-connect`, but also spawns a broker daemon if none is available. | +| `--broker` | **Proxy + auto-detect** *(recommended)*: connects to a running broker if one is alive, spawns a new daemon otherwise. Automatically recovers stale socket/PID files left by a crashed daemon. | +| `--broker-connect` | **Proxy**: connects to an already-running broker socket and forwards stdio. Legacy alias — use `--broker` for new configs. | +| `--broker-spawn` | **Proxy + auto-start**: legacy alias for `--broker`. | Use broker mode when you want lower process churn across repeated MCP client restarts. @@ -19,14 +20,14 @@ Use broker mode when you want lower process churn across repeated MCP client res Recommended topology for multiple agents/clients: 1. **Unified single-config (recommended):** use the same client args everywhere: - `--broker-spawn --web-ui --web-ui-config `. + `--broker --web-ui --web-ui-config `. 2. **Dedicated host alternative:** run one explicit broker host with `--broker-daemon --web-ui` and configure clients with `--broker-connect`. Web UI behavior in broker modes: - `--broker-daemon --web-ui` starts broker + dashboard in one host process. -- `--broker-spawn --web-ui` forwards Web UI flags to the spawned daemon when auto-start is needed. +- `--broker --web-ui` forwards Web UI flags to the spawned daemon when auto-start is needed; if a broker is already running without `--web-ui`, a warning is printed to stderr. - `--broker-connect` never starts a dashboard by itself. - Only one process can own a given Web UI `host:port`. - If dashboard bind fails (for example port already in use), broker transport continues and only dashboard startup is skipped. @@ -62,11 +63,11 @@ nohup uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper \ Then configure MCP clients with `--broker-connect` (see client examples below). -`--broker-spawn` is available as a best-effort alternative that auto-starts the daemon when needed (including dashboard args): +`--broker` is the recommended alternative that auto-detects: connects if a broker is alive, spawns otherwise (including dashboard args): ```bash uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper \ - --broker-spawn --web-ui --web-ui-config "$HOME/.config/xcodemcpwrapper/webui.json" + --broker --web-ui --web-ui-config "$HOME/.config/xcodemcpwrapper/webui.json" ``` ### Status @@ -123,7 +124,7 @@ Use the same args in every client. The first client that needs auto-spawn starts "--from", "mcpbridge-wrapper[webui]", "mcpbridge-wrapper", - "--broker-spawn", + "--broker", "--web-ui", "--web-ui-config", "/Users/YOUR_USERNAME/.config/xcodemcpwrapper/webui.json" @@ -144,7 +145,7 @@ Use the same args in every client. The first client that needs auto-spawn starts "--from", "mcpbridge-wrapper[webui]", "mcpbridge-wrapper", - "--broker-spawn", + "--broker", "--web-ui", "--web-ui-config", "/Users/YOUR_USERNAME/.config/xcodemcpwrapper/webui.json" @@ -160,7 +161,7 @@ Use the same args in every client. The first client that needs auto-spawn starts ```bash claude mcp add --transport stdio xcode -- \ uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper \ - --broker-spawn --web-ui --web-ui-config "$HOME/.config/xcodemcpwrapper/webui.json" + --broker --web-ui --web-ui-config "$HOME/.config/xcodemcpwrapper/webui.json" ``` ### Codex CLI @@ -168,7 +169,7 @@ claude mcp add --transport stdio xcode -- \ ```bash codex mcp add xcode -- \ uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper \ - --broker-spawn --web-ui --web-ui-config "$HOME/.config/xcodemcpwrapper/webui.json" + --broker --web-ui --web-ui-config "$HOME/.config/xcodemcpwrapper/webui.json" ``` ### Dedicated host + connect-only alternative @@ -179,7 +180,7 @@ If you prefer explicit host lifecycle management, start one `--broker-daemon --w 1. Back up your current MCP client configuration. 2. Choose one rollout pattern: - - Unified config: set clients to `--broker-spawn --web-ui --web-ui-config `. + - Unified config: set clients to `--broker --web-ui --web-ui-config `. - Dedicated host: start `--broker-daemon --web-ui` once and set clients to `--broker-connect`. 3. Restart each MCP client. 4. Run a first MCP request and verify broker files exist: @@ -189,7 +190,7 @@ If you prefer explicit host lifecycle management, start one `--broker-daemon --w ## Rollback to direct mode -1. Remove `--broker-connect` / `--broker-spawn` from MCP config args. +1. Remove `--broker`, `--broker-connect`, or `--broker-spawn` from MCP config args. 2. Restart the MCP client. 3. Stop any running broker process and remove stale files: @@ -205,8 +206,7 @@ rm -f "$PID_FILE" "$SOCK" ## Limitations - Broker mode currently uses local Unix socket paths and is intended for single-user local workflows. -- If a stale PID or socket file remains after a crash, clean it up before reconnecting. -- Auto-spawn may fail if a ready socket is not created in time; use `--broker-connect` with an explicitly started broker host in that case. +- `--broker` and `--broker-spawn` automatically detect and remove stale socket/PID files left by a crashed daemon before spawning a new one. Manual cleanup is only needed when using `--broker-connect` (connect-only mode), which does not perform the liveness check. ## Security boundary diff --git a/docs/claude-setup.md b/docs/claude-setup.md index 61c30471..ab621920 100644 --- a/docs/claude-setup.md +++ b/docs/claude-setup.md @@ -23,16 +23,16 @@ claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' ## Optional: One-Line Setup in Broker Mode -Connect to an already-running broker: +`--broker` auto-detects: connects if a daemon is running, spawns one otherwise. Stale socket/PID files from a crashed daemon are cleaned up automatically. ```bash -claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker ``` -Auto-spawn broker if needed: +Advanced — connect to an already-running broker only (no auto-spawn): ```bash -claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-spawn +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect ``` ## Alternative: Using Manual Installation @@ -69,8 +69,7 @@ Replace `/path/to/XcodeMCPWrapper` with the actual path to your cloned repositor ## Migration and Rollback -- Migration: update the existing `claude mcp add ...` command to include either - `--broker-connect` or `--broker-spawn`, then re-add the server. +- Migration: update the existing `claude mcp add ...` command to include `--broker`, then re-add the server. - Rollback: remove broker flags from the command and run `claude mcp add ...` again to restore direct mode. - Stop stale broker artifacts during rollback if needed: @@ -130,5 +129,4 @@ Make sure Xcode Tools MCP is enabled in Xcode: ### "Could not connect to broker socket ... within 10.0s" -Broker mode could not reach a ready broker socket. Verify broker status from -the broker mode guide, or rollback to direct mode by removing broker flags. +Broker mode could not reach a ready broker socket. If using `--broker`, stale files are cleaned up automatically; verify broker status from the [broker mode guide](broker-mode.md), or rollback to direct mode by removing broker flags. diff --git a/docs/codex-setup.md b/docs/codex-setup.md index f6de0a06..43d83a72 100644 --- a/docs/codex-setup.md +++ b/docs/codex-setup.md @@ -23,16 +23,16 @@ codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper - ## Optional: One-Line Setup in Broker Mode -Connect to an already-running broker: +`--broker` auto-detects: connects if a daemon is running, spawns one otherwise. Stale socket/PID files from a crashed daemon are cleaned up automatically. ```bash -codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect +codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker ``` -Auto-spawn broker if needed: +Advanced — connect to an already-running broker only (no auto-spawn): ```bash -codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-spawn +codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect ``` ## Alternative: Using Manual Installation @@ -69,8 +69,7 @@ Replace `/path/to/XcodeMCPWrapper` with the actual path to your cloned repositor ## Migration and Rollback -- Migration: update the existing `codex mcp add ...` command to include either - `--broker-connect` or `--broker-spawn`, then re-add the server. +- Migration: update the existing `codex mcp add ...` command to include `--broker`, then re-add the server. - Rollback: remove broker flags and run `codex mcp add ...` again for direct mode. - Stop stale broker artifacts during rollback if needed: @@ -129,5 +128,4 @@ Make sure Xcode Tools MCP is enabled in Xcode: ### "Could not connect to broker socket ... within 10.0s" -Broker mode could not reach a ready broker socket. Verify broker status from -the broker mode guide, or rollback to direct mode by removing broker flags. +Broker mode could not reach a ready broker socket. If using `--broker`, stale files are cleaned up automatically; verify broker status from the [broker mode guide](broker-mode.md), or rollback to direct mode by removing broker flags. diff --git a/docs/cursor-setup.md b/docs/cursor-setup.md index c4e6838f..acd03031 100644 --- a/docs/cursor-setup.md +++ b/docs/cursor-setup.md @@ -54,7 +54,9 @@ Edit `~/.cursor/mcp.json` directly: } ``` -### Using uvx in Broker Mode (Connect to existing broker) +### Using uvx in Broker Mode (Recommended) + +`--broker` auto-detects: connects if a daemon is running, spawns one otherwise. Stale socket/PID files from a crashed daemon are cleaned up automatically. ```json { @@ -65,14 +67,16 @@ Edit `~/.cursor/mcp.json` directly: "--from", "mcpbridge-wrapper", "mcpbridge-wrapper", - "--broker-connect" + "--broker" ] } } } ``` -### Using uvx in Broker Mode (Auto-spawn broker) +### Using uvx in Broker Mode (Connect-only, advanced) + +Use `--broker-connect` only when you manage the broker daemon lifecycle yourself: ```json { @@ -83,7 +87,7 @@ Edit `~/.cursor/mcp.json` directly: "--from", "mcpbridge-wrapper", "mcpbridge-wrapper", - "--broker-spawn" + "--broker-connect" ] } } @@ -150,8 +154,7 @@ Replace `/path/to/XcodeMCPWrapper` with the actual path to your cloned repositor ## Migration and Rollback -- Migration to broker mode: add either `--broker-connect` or `--broker-spawn` - to your existing `args`, then restart Cursor. +- Migration to broker mode: add `--broker` to your existing `args`, then restart Cursor. - Rollback to direct mode: remove broker flags from `args` and restart Cursor. - After rollback, stop stale broker state files if needed: @@ -198,11 +201,7 @@ Make sure Xcode Tools MCP is enabled in Xcode: ### "Could not connect to broker socket ... within 10.0s" -Broker mode could not reach a ready broker socket. Confirm broker process -state, then either: - -- switch to `--broker-connect` and run a dedicated broker host, or -- remove broker flags to rollback to direct mode. +Broker mode could not reach a ready broker socket. If using `--broker`, it will have already attempted stale-file recovery; confirm the broker process state with the [broker mode guide](broker-mode.md). To rollback, remove broker flags from `args` and restart Cursor. ### Web UI still shows old behavior after an upgrade diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index ac1c05b8..e2876f1e 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -306,7 +306,7 @@ Prefer `kill` (`SIGTERM`) first; use `kill -9` only when the process does not ex - MCP can stay healthy even if Web UI startup is skipped. - Only one process can own a given Web UI `host:port`. - Dashboard starts in a direct-mode owner (`--web-ui`) or a broker host (`--broker-daemon --web-ui`). -- `--broker-connect` never starts a dashboard by itself; `--broker-spawn --web-ui` only starts one when it must spawn a host. +- `--broker-connect` never starts a dashboard by itself; `--broker --web-ui` only starts one when it must spawn a host. - If dashboard bind fails (port already in use), wrapper logs a warning and continues MCP without dashboard hosting. - A healthy MCP status does not guarantee an active dashboard listener on the expected port. @@ -331,7 +331,7 @@ If step 1 returns no listener, no process currently owns the dashboard port. 1. **Single dashboard owner (direct mode):** keep `--web-ui` on one client config only. 2. **Use separate dashboard ports:** assign unique `--web-ui-port` values per process. -3. **Unified broker single-config:** use `--broker-spawn --web-ui --web-ui-config ` in all clients so one spawned host owns the dashboard. +3. **Unified broker single-config:** use `--broker --web-ui --web-ui-config ` in all clients so one spawned host owns the dashboard. 4. **Dedicated host pattern:** run one `--broker-daemon --web-ui` process, keep clients on `--broker-connect`, and monitor `~/.mcpbridge_wrapper/broker.log`. 5. **Standalone diagnostics:** run `--web-ui-only` when you need dashboard-only debugging independent from MCP startup. @@ -417,22 +417,52 @@ The second value should be larger. ### "Could not connect to broker socket ... within 10.0s" -**Symptom:** Broker mode command exits with: +**Symptom:** Broker mode prints a JSON-RPC error to the client: -```text -Error: Could not connect to broker socket ... within 10.0s +```json +{"jsonrpc":"2.0","id":null,"error":{"code":-32001,"message":"Broker unavailable: Could not connect to broker socket ... within 10.0s"}} ``` +Or exits with the error text in logs. + **Cause:** The broker socket is missing or not ready. +**Note:** When using `--broker` or `--broker-spawn`, stale socket/PID files from a crashed daemon are detected and removed automatically. Manual cleanup is only needed if you are using `--broker-connect` (connect-only mode). + **Solution:** ```bash PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; SOCK="$HOME/.mcpbridge_wrapper/broker.sock"; if [ -f "$PID_FILE" ] && kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then echo "broker running"; else echo "broker not running"; fi; ls -l "$SOCK" 2>/dev/null || echo "socket missing" ``` -If broker is not running, start it (or use `--broker-spawn`). If the socket is stale, -remove stale files and retry. +If broker is not running, switch to `--broker` (auto-detects and spawns) or start it manually and use `--broker-connect`. + +### "Warning: broker is running without --web-ui on port N" + +**Symptom:** After connecting in broker mode, a warning appears on stderr: + +```text +Warning: broker is running without --web-ui on port 8080. Restart the broker to enable the dashboard. + Hint: stop the running broker (rm ~/.mcpbridge_wrapper/broker.sock ~/.mcpbridge_wrapper/broker.pid) then reconnect with --broker --web-ui. +``` + +**Cause:** You passed `--broker --web-ui` (or `--broker-spawn --web-ui`) but the broker daemon that is already running was started *without* `--web-ui`. The wrapper detects that port `8080` (or your configured port) is not accepting connections and prints this actionable warning. The MCP session continues normally. + +**Solution:** + +Stop the running broker and reconnect so the new daemon starts with the dashboard enabled: + +```bash +# Stop the running broker +PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid" +SOCK="$HOME/.mcpbridge_wrapper/broker.sock" +[ -f "$PID_FILE" ] && kill "$(cat "$PID_FILE")" 2>/dev/null || true +rm -f "$PID_FILE" "$SOCK" +``` + +Then restart your MCP client (Cursor / Zed / Claude Code). On the next connection `--broker --web-ui` will spawn a fresh daemon that includes the dashboard. + +--- ### "Broker already running (PID ...)" @@ -454,7 +484,9 @@ PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; if [ -f "$PID_FILE" ]; then kill ### Stale broker lock/socket recovery -If a crash leaves orphaned files, clean them explicitly: +When using `--broker` or `--broker-spawn`, stale socket/PID files are detected automatically: the proxy checks whether the socket is actually accepting connections and, if not, removes the stale files and spawns a fresh daemon. No manual cleanup is required in normal use. + +If you are using `--broker-connect` (connect-only, no auto-spawn) and a crash has left orphaned files, clean them explicitly: ```bash PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; SOCK="$HOME/.mcpbridge_wrapper/broker.sock"; if [ -f "$PID_FILE" ] && ! kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then rm -f "$PID_FILE"; fi; if [ -S "$SOCK" ]; then rm -f "$SOCK"; fi @@ -491,7 +523,7 @@ rm -f ~/.mcpbridge_wrapper/broker.pid ~/.mcpbridge_wrapper/broker.sock ### Rollback to direct mode (verified flow) -1. Remove `--broker-connect` or `--broker-spawn` from your MCP config command args. +1. Remove `--broker`, `--broker-connect`, or `--broker-spawn` from your MCP config command args. 2. Restart the MCP client. 3. Stop and clean broker state: