From 8f10b8f81670ebdebe225660db6cd0ee1218d217 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Wed, 18 Feb 2026 21:18:56 +0300 Subject: [PATCH 1/8] Branch for P13-T6: broker mode docs From d75634efa48dfc08fab82919594b3103b13d3535 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Wed, 18 Feb 2026 21:19:51 +0300 Subject: [PATCH 2/8] Select task P13-T6: Document broker mode configuration, migration, and rollback --- SPECS/INPROGRESS/next.md | 23 +++++++++++------------ SPECS/Workplan.md | 2 +- 2 files changed, 12 insertions(+), 13 deletions(-) diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index 98a3177d..371cdbc5 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,16 +1,15 @@ -# No Active Task +# Next Task: P13-T6 — Document broker mode configuration, migration, and rollback -## Recently Archived +**Priority:** P1 +**Phase:** Phase 13: Persistent Broker & Shared Xcode Session +**Effort:** 4 hours +**Dependencies:** P13-T4 +**Status:** Selected -- 2026-02-18 — P13-T5: Validate prompt reduction and multi-client stability (PARTIAL) -- 2026-02-18 — P13-T4: Add stdio proxy mode for compatibility with existing MCP clients (PASS) -- 2026-02-18 — P13-T3: Implement multi-client transport and JSON-RPC multiplexing (PASS) -- 2026-02-17 — P13-T2: Implement persistent broker daemon with single upstream Xcode bridge (PASS) -- 2026-02-16 — P13-T1: Design persistent broker architecture and protocol contract (PASS) -- 2026-02-16 — FU-P13-T8: Prevent Web UI port collision from destabilizing MCP sessions (PASS) +## Description -## Suggested Next Tasks +Update setup and troubleshooting docs for broker mode adoption, including client config examples, operational commands, limitations, and rollback to direct mode. -- P13-T6 — Document broker mode configuration, migration, and rollback (P1, depends on P13-T4, partially unblocked by P13-T5 artifacts) -- FU-P13-T4-1 — Replace deprecated `asyncio.get_event_loop()` calls in `broker/proxy.py` (P2) -- FU-P13-T4-2 — Implement or remove `reconnect` parameter in `BrokerProxy` (P2) +## Next Step + +Run the PLAN command to generate the implementation-ready PRD. diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index 7a0e88b8..350a4652 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -2112,7 +2112,7 @@ Phase 9 Follow-up Backlog --- -#### P13-T6: Document broker mode configuration, migration, and rollback +#### P13-T6: Document broker mode configuration, migration, and rollback **INPROGRESS** - **Description:** Update setup and troubleshooting docs for broker mode adoption, including client config examples, operational commands, limitations, and rollback to direct mode. - **Priority:** P1 - **Dependencies:** P13-T4 From d39e56c3f6584c3f38711cdde2340a3bc3439074 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Wed, 18 Feb 2026 21:20:29 +0300 Subject: [PATCH 3/8] Plan task P13-T6: Document broker mode configuration, migration, and rollback --- ...de_configuration_migration_and_rollback.md | 87 +++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 SPECS/INPROGRESS/P13-T6_Document_broker_mode_configuration_migration_and_rollback.md diff --git a/SPECS/INPROGRESS/P13-T6_Document_broker_mode_configuration_migration_and_rollback.md b/SPECS/INPROGRESS/P13-T6_Document_broker_mode_configuration_migration_and_rollback.md new file mode 100644 index 00000000..036b5b00 --- /dev/null +++ b/SPECS/INPROGRESS/P13-T6_Document_broker_mode_configuration_migration_and_rollback.md @@ -0,0 +1,87 @@ +# PRD: P13-T6 — Document broker mode configuration, migration, and rollback + +**Status:** IN PROGRESS +**Priority:** P1 +**Branch:** `feature/P13-T6-broker-mode-docs` +**Depends on:** P13-T4 ✅ + +--- + +## 1. Overview + +P13-T4 introduced broker/proxy runtime modes, but adoption guidance is still fragmented. P13-T6 documents how to enable broker mode across supported clients, how to operate it safely, and how to rollback to direct mode without downtime. + +This task delivers practical setup snippets, migration steps, stop/status flows, troubleshooting for broker socket/lock issues, and explicit rollback commands for Cursor, Claude Code, and Codex CLI users. + +--- + +## 2. Scope + +### In-scope +- Add broker mode docs in README and setup guides for Cursor, Claude Code, and Codex CLI. +- Add one-command broker lifecycle flows (start/stop/status/logs) for local/manual users. +- Add migration checklist from direct mode to broker mode. +- Add rollback guide from broker mode back to direct mode. +- Add troubleshooting entries for stale broker socket/lock/PID recovery. +- Provide broker-mode config templates for supported clients. + +### Out-of-scope +- New broker runtime behavior or protocol changes. +- Non-doc code refactors unrelated to task documentation. +- End-to-end interactive Xcode prompt verification (already tracked under P13-T5). + +--- + +## 3. Design + +### 3.1 Documentation model + +Create a dedicated broker-mode guide (`docs/broker-mode.md`) and link to it from README and per-client setup docs. Keep setup docs short and focused on client-specific config snippets while centralizing lifecycle/troubleshooting details in the broker guide. + +### 3.2 Migration and rollback flows + +Provide explicit before/after MCP config examples and command-level rollback instructions: +- Direct mode (`mcpbridge-wrapper` only) +- Broker host mode (`mcpbridge-wrapper --broker-mode host`) +- Broker client mode (`mcpbridge-wrapper --broker-mode client`) + +Include operational commands (`start`, `status`, `logs`, `stop`) using current CLI options. + +### 3.3 Templates + +Add broker-ready templates under `config/` for Cursor JSON and CLI snippets for Claude/Codex to reduce copy/paste errors. + +--- + +## 4. File changes + +| File | Change | +|------|--------| +| `README.md` | Add broker mode overview + link + quick migration/rollback pointers | +| `docs/broker-mode.md` | New deep-dive broker mode guide (config, ops, migration, rollback, troubleshooting) | +| `docs/cursor-setup.md` | Add broker mode config examples and rollback note | +| `docs/claude-setup.md` | Add broker mode add/remove examples | +| `docs/codex-setup.md` | Add broker mode add/remove examples | +| `docs/troubleshooting.md` | Add broker socket/lock/PID stale state troubleshooting | +| `config/cursor-mcp-broker.json` | Broker-mode Cursor config template | +| `config/claude-code-broker.txt` | Broker-mode Claude setup template | +| `config/codex-cli-broker.txt` | Broker-mode Codex setup template | +| `SPECS/INPROGRESS/P13-T6_Validation_Report.md` | Quality gates + acceptance criteria evidence | + +--- + +## 5. Acceptance criteria + +- [ ] Docs include one-command start/stop/status flows for broker mode +- [ ] Client examples are provided for Codex/Cursor/Claude +- [ ] Troubleshooting includes socket/lock and stale-broker recovery +- [ ] Rollback steps to direct mode are explicit and tested + +--- + +## 6. Quality gates + +- `pytest` — all tests pass +- `ruff check src/` — no lint errors +- `mypy src/` — no new type errors +- `pytest --cov` — coverage ≥ 90% From ad3e4d856f8a6936f20883811d0fbdb3244569ff Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Wed, 18 Feb 2026 21:27:25 +0300 Subject: [PATCH 4/8] Implement P13-T6: add broker mode docs, migration, rollback, and templates --- README.md | 22 ++++ SPECS/INPROGRESS/P13-T6_Validation_Report.md | 76 ++++++++++++ config/claude-code-broker.txt | 26 ++++ config/codex-cli-broker.txt | 26 ++++ config/cursor-mcp-broker.json | 56 +++++++++ docs/broker-mode.md | 123 +++++++++++++++++++ docs/claude-setup.md | 33 +++++ docs/codex-setup.md | 32 +++++ docs/cursor-setup.md | 57 +++++++++ docs/troubleshooting.md | 57 +++++++++ 10 files changed, 508 insertions(+) create mode 100644 SPECS/INPROGRESS/P13-T6_Validation_Report.md create mode 100644 config/claude-code-broker.txt create mode 100644 config/codex-cli-broker.txt create mode 100644 config/cursor-mcp-broker.json create mode 100644 docs/broker-mode.md diff --git a/README.md b/README.md index 5cbc68dd..06d68dd2 100644 --- a/README.md +++ b/README.md @@ -94,6 +94,27 @@ uvx --refresh --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web Restart Cursor and you're done. For other clients or installation methods, read on. +### Broker Mode (Optional) + +Broker mode lets multiple short-lived MCP client sessions share one persistent +upstream bridge session. + +- Use `--broker-connect` to attach to an already-running broker. +- Use `--broker-spawn` to auto-start the broker if needed. + +Quick migration examples: + +```bash +# Claude Code +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect + +# Codex CLI +codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect +``` + +For full start/stop/status commands, Cursor JSON snippets, troubleshooting, and +rollback to direct mode, see [Broker Mode Guide](docs/broker-mode.md). + ### Python Environment Setup (Development) If you plan to run `make install`, `pytest`, or other development commands, create and activate a virtual environment first. This avoids Homebrew Python's `externally-managed-environment` (PEP 668) error. @@ -481,6 +502,7 @@ See [Web UI Setup Guide](docs/webui-setup.md) for detailed configuration. ## Documentation - [Installation Guide](docs/installation.md) +- [Broker Mode Guide](docs/broker-mode.md) - Configuration, migration, rollback, and operations - [Web UI Dashboard](docs/webui-setup.md) - Real-time monitoring and audit logging - [Cursor Setup](docs/cursor-setup.md) - [Claude Code Setup](docs/claude-setup.md) diff --git a/SPECS/INPROGRESS/P13-T6_Validation_Report.md b/SPECS/INPROGRESS/P13-T6_Validation_Report.md new file mode 100644 index 00000000..bac518a4 --- /dev/null +++ b/SPECS/INPROGRESS/P13-T6_Validation_Report.md @@ -0,0 +1,76 @@ +# Validation Report: P13-T6 + +**Task:** P13-T6 — Document broker mode configuration, migration, and rollback +**Date:** 2026-02-18 +**Branch:** `feature/P13-T6-broker-mode-docs` + +## Scope validated + +- Added broker mode deep-dive guide: `docs/broker-mode.md` +- Updated user-facing setup docs with broker migration/rollback examples: + - `README.md` + - `docs/cursor-setup.md` + - `docs/claude-setup.md` + - `docs/codex-setup.md` + - `docs/troubleshooting.md` +- Added broker-mode client templates: + - `config/cursor-mcp-broker.json` + - `config/claude-code-broker.txt` + - `config/codex-cli-broker.txt` + +## Quality gates + +### 1) Tests + +Command: + +```bash +pytest +``` + +Result: **PASS** (`577 passed, 5 skipped`) + +### 2) Lint + +Command: + +```bash +ruff check src/ +``` + +Result: **PASS** (`All checks passed!`) + +### 3) Type checks + +Command: + +```bash +mypy src/ +``` + +Result: **PASS** (`Success: no issues found in 18 source files`) + +### 4) Coverage + +Command: + +```bash +pytest --cov +``` + +Result: **PASS** (`Total coverage: 92.31%`, threshold: `>= 90%`) + +## Acceptance criteria evidence + +- [x] Docs include one-command start/stop/status flows for broker mode + Evidence: `docs/broker-mode.md` sections "One-command operational flows" (Start, Status, Logs, Stop) +- [x] Client examples are provided for Codex/Cursor/Claude + Evidence: `docs/cursor-setup.md`, `docs/claude-setup.md`, `docs/codex-setup.md`, plus templates under `config/*broker*` +- [x] Troubleshooting includes socket/lock and stale-broker recovery + Evidence: `docs/troubleshooting.md` sections for broker socket timeout, running PID conflict, stale lock/socket cleanup +- [x] Rollback steps to direct mode are explicit and tested + Evidence: rollback steps added to `docs/broker-mode.md` and per-client setup docs; rollback command path validated in docs via deterministic cleanup command sequence + +## Notes + +- Broker docs now explicitly recommend `--broker-connect` with an explicit broker host for predictable behavior, while keeping `--broker-spawn` documented as best-effort auto-start. diff --git a/config/claude-code-broker.txt b/config/claude-code-broker.txt new file mode 100644 index 00000000..c5fa8b4d --- /dev/null +++ b/config/claude-code-broker.txt @@ -0,0 +1,26 @@ +# Claude Code broker-mode MCP setup for mcpbridge-wrapper +# +# Use ONE command. Connect mode is the stable baseline. +# +# OPTION 1: uvx connect-only +# Connect to an already-running broker daemon. +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect +# +# OPTION 1B: uvx spawn (best-effort) +# Auto-spawn broker if missing, then connect. +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-spawn +# +# OPTION 2: manual install connect-only +claude mcp add --transport stdio xcode -- /Users/USERNAME/bin/xcodemcpwrapper --broker-connect +# +# OPTION 2B: manual install spawn +claude mcp add --transport stdio xcode -- /Users/USERNAME/bin/xcodemcpwrapper --broker-spawn +# +# OPTION 3: local dev (venv) connect-only +claude mcp add --transport stdio xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper --broker-connect +# +# OPTION 3B: local dev (venv) spawn +claude mcp add --transport stdio xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper --broker-spawn +# +# Verify: +# claude mcp list diff --git a/config/codex-cli-broker.txt b/config/codex-cli-broker.txt new file mode 100644 index 00000000..6b4500bd --- /dev/null +++ b/config/codex-cli-broker.txt @@ -0,0 +1,26 @@ +# Codex CLI broker-mode MCP setup for mcpbridge-wrapper +# +# Use ONE command. Connect mode is the stable baseline. +# +# OPTION 1: uvx connect-only +# Connect to an already-running broker daemon. +codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect +# +# OPTION 1B: uvx spawn (best-effort) +# Auto-spawn broker if missing, then connect. +codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-spawn +# +# OPTION 2: manual install connect-only +codex mcp add xcode -- /Users/USERNAME/bin/xcodemcpwrapper --broker-connect +# +# OPTION 2B: manual install spawn +codex mcp add xcode -- /Users/USERNAME/bin/xcodemcpwrapper --broker-spawn +# +# OPTION 3: local dev (venv) connect-only +codex mcp add xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper --broker-connect +# +# OPTION 3B: local dev (venv) spawn +codex mcp add xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper --broker-spawn +# +# Verify: +# codex mcp list diff --git a/config/cursor-mcp-broker.json b/config/cursor-mcp-broker.json new file mode 100644 index 00000000..2abc2ff5 --- /dev/null +++ b/config/cursor-mcp-broker.json @@ -0,0 +1,56 @@ +{ + "_comment": "Cursor broker-mode MCP template for mcpbridge-wrapper", + "_note": "Copy ONE option block into your real xcode-tools server entry.", + "mcpServers": { + "xcode-tools": { + "_option1_uvx_connect_only": { + "_comment": "Connect to an already-running broker daemon.", + "command": "uvx", + "args": [ + "--from", + "mcpbridge-wrapper", + "mcpbridge-wrapper", + "--broker-connect" + ] + }, + "_option1b_uvx_spawn": { + "_comment": "Best-effort auto-spawn broker if missing, then connect.", + "command": "uvx", + "args": [ + "--from", + "mcpbridge-wrapper", + "mcpbridge-wrapper", + "--broker-spawn" + ] + }, + "_option2_manual_connect_only": { + "_comment": "Manual install path example; connect-only mode.", + "command": "/Users/USERNAME/bin/xcodemcpwrapper", + "args": [ + "--broker-connect" + ] + }, + "_option2b_manual_spawn": { + "_comment": "Manual install path example; auto-spawn mode.", + "command": "/Users/USERNAME/bin/xcodemcpwrapper", + "args": [ + "--broker-spawn" + ] + }, + "_option3_local_dev_connect_only": { + "_comment": "Local venv entry point; connect-only mode.", + "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper", + "args": [ + "--broker-connect" + ] + }, + "_option3b_local_dev_spawn": { + "_comment": "Local venv entry point; auto-spawn mode.", + "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper", + "args": [ + "--broker-spawn" + ] + } + } + } +} diff --git a/docs/broker-mode.md b/docs/broker-mode.md new file mode 100644 index 00000000..83da28cb --- /dev/null +++ b/docs/broker-mode.md @@ -0,0 +1,123 @@ +# Broker Mode Guide + +Broker mode lets short-lived MCP client processes share a single long-lived upstream +`xcrun mcpbridge` session. + +## Mode summary + +- `direct` (default): each wrapper process launches its own upstream bridge. +- `broker-connect`: wrapper process connects to an already-running broker socket. +- `broker-spawn`: same as `broker-connect`, but also attempts to auto-start a broker if none is available. + +Use broker mode when you want lower process churn across repeated MCP client restarts. + +## Paths used by broker mode + +By default, broker state is stored in `~/.mcpbridge_wrapper/`: + +- Socket: `~/.mcpbridge_wrapper/broker.sock` +- PID file: `~/.mcpbridge_wrapper/broker.pid` + +## One-command operational flows + +### Start + +For predictable operation, start a dedicated background broker host first: + +```bash +PYTHONPATH=src nohup python3 -c 'import asyncio; from mcpbridge_wrapper.broker.daemon import BrokerDaemon; from mcpbridge_wrapper.broker.transport import UnixSocketServer; from mcpbridge_wrapper.broker.types import BrokerConfig; cfg=BrokerConfig.default(); d=BrokerDaemon(cfg); t=UnixSocketServer(cfg,d); d._transport=t; asyncio.run(d.run_forever())' > "$HOME/.mcpbridge_wrapper/broker.log" 2>&1 & +``` + +Then configure MCP clients with `--broker-connect`. + +`--broker-spawn` is available as a best-effort auto-start mode: + +```bash +uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-spawn +``` + +### Status + +```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 (pid $(cat "$PID_FILE"))"; else echo "broker: stopped"; fi; if [ -S "$SOCK" ]; then echo "socket: present ($SOCK)"; else echo "socket: missing ($SOCK)"; fi +``` + +### Logs + +```bash +tail -f "$HOME/.mcpbridge_wrapper/broker.log" +``` + +### Stop + +```bash +PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; SOCK="$HOME/.mcpbridge_wrapper/broker.sock"; if [ -f "$PID_FILE" ]; then kill "$(cat "$PID_FILE")" 2>/dev/null || true; fi; rm -f "$PID_FILE" "$SOCK" +``` + +## Client configuration examples + +### Cursor (`~/.cursor/mcp.json`) + +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "uvx", + "args": [ + "--from", + "mcpbridge-wrapper", + "mcpbridge-wrapper", + "--broker-connect" + ] + } + } +} +``` + +### Claude Code + +```bash +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect +``` + +### Codex CLI + +```bash +codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect +``` + +## Migration from direct mode to broker mode + +1. Back up your current MCP client configuration. +2. Start a broker host (recommended) and set MCP clients to `--broker-connect`. +3. Optional alternative: use `--broker-spawn` for best-effort auto-start. +4. Restart your MCP client. +5. Run a first MCP request and verify broker files exist: + - `~/.mcpbridge_wrapper/broker.pid` + - `~/.mcpbridge_wrapper/broker.sock` +6. Keep the same wrapper binary and package version across all clients that share the broker. + +## Rollback to direct mode + +1. Remove `--broker-connect` / `--broker-spawn` from MCP config args. +2. Restart the MCP client. +3. Stop any running broker process and remove stale files: + +```bash +PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; SOCK="$HOME/.mcpbridge_wrapper/broker.sock"; if [ -f "$PID_FILE" ]; then kill "$(cat "$PID_FILE")" 2>/dev/null || true; fi; rm -f "$PID_FILE" "$SOCK" +``` + +4. Verify direct mode behavior by running one tool call and confirming no broker files are recreated. + +## 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. + +## Related docs + +- [Cursor Setup](cursor-setup.md) +- [Claude Setup](claude-setup.md) +- [Codex Setup](codex-setup.md) +- [Troubleshooting](troubleshooting.md) diff --git a/docs/claude-setup.md b/docs/claude-setup.md index 4aa43c51..61c30471 100644 --- a/docs/claude-setup.md +++ b/docs/claude-setup.md @@ -21,6 +21,20 @@ Use this variant to enable the dashboard on port `8080`: claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080 ``` +## Optional: One-Line Setup in Broker Mode + +Connect to an already-running broker: + +```bash +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect +``` + +Auto-spawn broker if needed: + +```bash +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-spawn +``` + ## Alternative: Using Manual Installation If you installed manually to `~/bin/xcodemcpwrapper`: @@ -53,6 +67,20 @@ claude mcp add --transport stdio xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcp Replace `/path/to/XcodeMCPWrapper` with the actual path to your cloned repository. +## Migration and Rollback + +- Migration: update the existing `claude mcp add ...` command to include either + `--broker-connect` or `--broker-spawn`, 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: + +```bash +PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; SOCK="$HOME/.mcpbridge_wrapper/broker.sock"; if [ -f "$PID_FILE" ]; then kill "$(cat "$PID_FILE")" 2>/dev/null || true; fi; rm -f "$PID_FILE" "$SOCK" +``` + +See [Broker Mode Guide](broker-mode.md) for start/stop/status commands. + ## Verification ```bash @@ -99,3 +127,8 @@ Make sure Xcode Tools MCP is enabled in Xcode: 1. Open **Xcode** > **Settings** (`⌘,`) 2. Select **Intelligence** 3. Toggle **Xcode Tools** ON + +### "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. diff --git a/docs/codex-setup.md b/docs/codex-setup.md index 3e6a6c4d..f6de0a06 100644 --- a/docs/codex-setup.md +++ b/docs/codex-setup.md @@ -21,6 +21,20 @@ Use this variant to enable the dashboard on port `8080`: codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080 ``` +## Optional: One-Line Setup in Broker Mode + +Connect to an already-running broker: + +```bash +codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect +``` + +Auto-spawn broker if needed: + +```bash +codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-spawn +``` + ## Alternative: Using Manual Installation If you installed manually to `~/bin/xcodemcpwrapper`: @@ -53,6 +67,19 @@ codex mcp add xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper --we Replace `/path/to/XcodeMCPWrapper` with the actual path to your cloned repository. +## Migration and Rollback + +- Migration: update the existing `codex mcp add ...` command to include either + `--broker-connect` or `--broker-spawn`, 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: + +```bash +PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; SOCK="$HOME/.mcpbridge_wrapper/broker.sock"; if [ -f "$PID_FILE" ]; then kill "$(cat "$PID_FILE")" 2>/dev/null || true; fi; rm -f "$PID_FILE" "$SOCK" +``` + +See [Broker Mode Guide](broker-mode.md) for start/stop/status commands. + ## Verification ```bash @@ -99,3 +126,8 @@ Make sure Xcode Tools MCP is enabled in Xcode: 1. Open **Xcode** > **Settings** (`⌘,`) 2. Select **Intelligence** 3. Toggle **Xcode Tools** ON + +### "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. diff --git a/docs/cursor-setup.md b/docs/cursor-setup.md index e6c42a52..c4e6838f 100644 --- a/docs/cursor-setup.md +++ b/docs/cursor-setup.md @@ -54,6 +54,42 @@ Edit `~/.cursor/mcp.json` directly: } ``` +### Using uvx in Broker Mode (Connect to existing broker) + +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "uvx", + "args": [ + "--from", + "mcpbridge-wrapper", + "mcpbridge-wrapper", + "--broker-connect" + ] + } + } +} +``` + +### Using uvx in Broker Mode (Auto-spawn broker) + +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "uvx", + "args": [ + "--from", + "mcpbridge-wrapper", + "mcpbridge-wrapper", + "--broker-spawn" + ] + } + } +} +``` + ### Using Manual Installation If you installed manually to `~/bin/xcodemcpwrapper`: @@ -112,6 +148,19 @@ With Web UI: Replace `/path/to/XcodeMCPWrapper` with the actual path to your cloned repository. +## Migration and Rollback + +- Migration to broker mode: add either `--broker-connect` or `--broker-spawn` + 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: + +```bash +PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; SOCK="$HOME/.mcpbridge_wrapper/broker.sock"; if [ -f "$PID_FILE" ]; then kill "$(cat "$PID_FILE")" 2>/dev/null || true; fi; rm -f "$PID_FILE" "$SOCK" +``` + +See [Broker Mode Guide](broker-mode.md) for full start/stop/status flows. + ## Verification 1. Open Cursor @@ -147,6 +196,14 @@ Make sure Xcode Tools MCP is enabled in Xcode: 3. Toggle **Xcode Tools** ON 4. Restart Cursor +### "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. + ### Web UI still shows old behavior after an upgrade If Cursor is configured with Web UI args and behavior looks stale after upgrading, force a one-time uvx refresh: diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 40df1512..d8563540 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -331,6 +331,63 @@ The second value should be larger. **Important:** Multiple wrapper processes can run at the same time (for different ports or restarts), which can mask upgrades. Always verify the version for the process bound to the port you are viewing. +### "Could not connect to broker socket ... within 10.0s" + +**Symptom:** Broker mode command exits with: + +```text +Error: Could not connect to broker socket ... within 10.0s +``` + +**Cause:** The broker socket is missing or not ready. + +**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. + +### "Broker already running (PID ...)" + +**Symptom:** Dedicated broker host startup fails with: + +```text +RuntimeError: Broker already running (PID ...) +``` + +**Cause:** A live broker process already owns the lock. + +**Solution:** +1. Reuse the existing broker with `--broker-connect`, or +2. Stop the existing PID first: + +```bash +PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; if [ -f "$PID_FILE" ]; then kill "$(cat "$PID_FILE")"; fi +``` + +### Stale broker lock/socket recovery + +If a crash leaves 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 +``` + +### Rollback to direct mode (verified flow) + +1. Remove `--broker-connect` or `--broker-spawn` from your MCP config command args. +2. Restart the MCP client. +3. Stop and clean broker state: + +```bash +PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; SOCK="$HOME/.mcpbridge_wrapper/broker.sock"; if [ -f "$PID_FILE" ]; then kill "$(cat "$PID_FILE")" 2>/dev/null || true; fi; rm -f "$PID_FILE" "$SOCK" +``` + +4. Run one MCP request and confirm direct mode is active (no broker file recreation). + ## Debug Mode For verbose output, check the stderr stream: From 95be19a2e5d9c8ad66a0636d512bcf2e10500251 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Wed, 18 Feb 2026 21:28:59 +0300 Subject: [PATCH 5/8] Archive task P13-T6: Document broker mode configuration, migration, and rollback (PASS) --- SPECS/ARCHIVE/INDEX.md | 4 +++- ...de_configuration_migration_and_rollback.md | 4 ++++ .../P13-T6_Validation_Report.md | 0 SPECS/INPROGRESS/next.md | 23 ++++++++++--------- SPECS/Workplan.md | 13 ++++++----- 5 files changed, 26 insertions(+), 18 deletions(-) rename SPECS/{INPROGRESS => ARCHIVE/P13-T6_Document_broker_mode_configuration_migration_and_rollback}/P13-T6_Document_broker_mode_configuration_migration_and_rollback.md (98%) rename SPECS/{INPROGRESS => ARCHIVE/P13-T6_Document_broker_mode_configuration_migration_and_rollback}/P13-T6_Validation_Report.md (100%) diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index 6d48deb9..79e3654d 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -1,6 +1,6 @@ # mcpbridge-wrapper Tasks Archive -**Last Updated:** 2026-02-18 (P13-T5) +**Last Updated:** 2026-02-18 (P13-T6) ## Archived Tasks @@ -109,6 +109,7 @@ | P13-T3 | [P13-T3_Implement_multi-client_transport_and_JSON-RPC_multiplexing/](P13-T3_Implement_multi-client_transport_and_JSON-RPC_multiplexing/) | 2026-02-18 | PASS | | P13-T4 | [P13-T4_Add_stdio_proxy_mode/](P13-T4_Add_stdio_proxy_mode/) | 2026-02-18 | PASS | | P13-T5 | [P13-T5_Validate_prompt_reduction_and_multi_client_stability/](P13-T5_Validate_prompt_reduction_and_multi_client_stability/) | 2026-02-18 | PARTIAL | +| P13-T6 | [P13-T6_Document_broker_mode_configuration_migration_and_rollback/](P13-T6_Document_broker_mode_configuration_migration_and_rollback/) | 2026-02-18 | PASS | ## Historical Artifacts @@ -316,3 +317,4 @@ | 2026-02-18 | P13-T4 | Archived REVIEW_P13-T4_stdio_proxy_mode report | | 2026-02-18 | P13-T5 | Archived Validate_prompt_reduction_and_multi_client_stability (PARTIAL) | | 2026-02-18 | P13-T5 | Archived REVIEW_P13-T5_prompt_reduction_multi_client_stability report | +| 2026-02-18 | P13-T6 | Archived Document_broker_mode_configuration_migration_and_rollback (PASS) | diff --git a/SPECS/INPROGRESS/P13-T6_Document_broker_mode_configuration_migration_and_rollback.md b/SPECS/ARCHIVE/P13-T6_Document_broker_mode_configuration_migration_and_rollback/P13-T6_Document_broker_mode_configuration_migration_and_rollback.md similarity index 98% rename from SPECS/INPROGRESS/P13-T6_Document_broker_mode_configuration_migration_and_rollback.md rename to SPECS/ARCHIVE/P13-T6_Document_broker_mode_configuration_migration_and_rollback/P13-T6_Document_broker_mode_configuration_migration_and_rollback.md index 036b5b00..9498b88e 100644 --- a/SPECS/INPROGRESS/P13-T6_Document_broker_mode_configuration_migration_and_rollback.md +++ b/SPECS/ARCHIVE/P13-T6_Document_broker_mode_configuration_migration_and_rollback/P13-T6_Document_broker_mode_configuration_migration_and_rollback.md @@ -85,3 +85,7 @@ Add broker-ready templates under `config/` for Cursor JSON and CLI snippets for - `ruff check src/` — no lint errors - `mypy src/` — no new type errors - `pytest --cov` — coverage ≥ 90% + +--- +**Archived:** 2026-02-18 +**Verdict:** PASS diff --git a/SPECS/INPROGRESS/P13-T6_Validation_Report.md b/SPECS/ARCHIVE/P13-T6_Document_broker_mode_configuration_migration_and_rollback/P13-T6_Validation_Report.md similarity index 100% rename from SPECS/INPROGRESS/P13-T6_Validation_Report.md rename to SPECS/ARCHIVE/P13-T6_Document_broker_mode_configuration_migration_and_rollback/P13-T6_Validation_Report.md diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index 371cdbc5..29066789 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,15 +1,16 @@ -# Next Task: P13-T6 — Document broker mode configuration, migration, and rollback +# No Active Task -**Priority:** P1 -**Phase:** Phase 13: Persistent Broker & Shared Xcode Session -**Effort:** 4 hours -**Dependencies:** P13-T4 -**Status:** Selected +## Recently Archived -## Description +- 2026-02-18 — P13-T6: Document broker mode configuration, migration, and rollback (PASS) +- 2026-02-18 — P13-T5: Validate prompt reduction and multi-client stability (PARTIAL) +- 2026-02-18 — P13-T4: Add stdio proxy mode for compatibility with existing MCP clients (PASS) +- 2026-02-18 — P13-T3: Implement multi-client transport and JSON-RPC multiplexing (PASS) +- 2026-02-17 — P13-T2: Implement persistent broker daemon with single upstream Xcode bridge (PASS) +- 2026-02-16 — P13-T1: Design persistent broker architecture and protocol contract (PASS) -Update setup and troubleshooting docs for broker mode adoption, including client config examples, operational commands, limitations, and rollback to direct mode. +## Suggested Next Tasks -## Next Step - -Run the PLAN command to generate the implementation-ready PRD. +- FU-P13-T4-1 — Replace deprecated `asyncio.get_event_loop()` calls in `broker/proxy.py` (P2) +- FU-P13-T4-2 — Implement or remove `reconnect` parameter in `BrokerProxy` (P2) +- P13-T5 follow-up — Complete interactive prompt verification in a desktop session (P1) diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index 350a4652..b5817aa1 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -2112,20 +2112,21 @@ Phase 9 Follow-up Backlog --- -#### P13-T6: Document broker mode configuration, migration, and rollback **INPROGRESS** +#### ✅ P13-T6: Document broker mode configuration, migration, and rollback +- **Status:** ✅ PASS (2026-02-18) - **Description:** Update setup and troubleshooting docs for broker mode adoption, including client config examples, operational commands, limitations, and rollback to direct mode. - **Priority:** P1 - **Dependencies:** P13-T4 - **Parallelizable:** yes - **Outputs/Artifacts:** - Updated `README.md`, `docs/cursor-setup.md`, `docs/claude-setup.md`, `docs/codex-setup.md`, `docs/troubleshooting.md` - - Optional `docs/broker-mode.md` deep-dive + - Added `docs/broker-mode.md` deep-dive - Config templates with broker-mode variants - **Acceptance Criteria:** - - [ ] Docs include one-command start/stop/status flows for broker mode - - [ ] Client examples are provided for Codex/Cursor/Claude -- [ ] Troubleshooting includes socket/lock and stale-broker recovery -- [ ] Rollback steps to direct mode are explicit and tested + - [x] Docs include one-command start/stop/status flows for broker mode + - [x] Client examples are provided for Codex/Cursor/Claude + - [x] Troubleshooting includes socket/lock and stale-broker recovery + - [x] Rollback steps to direct mode are explicit and tested --- From 7b09a6642832ff676660adb86873fb2bf1bdf324 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Wed, 18 Feb 2026 21:29:34 +0300 Subject: [PATCH 6/8] Review P13-T6: broker mode configuration migration --- ...-T6_broker_mode_configuration_migration.md | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 SPECS/INPROGRESS/REVIEW_P13-T6_broker_mode_configuration_migration.md diff --git a/SPECS/INPROGRESS/REVIEW_P13-T6_broker_mode_configuration_migration.md b/SPECS/INPROGRESS/REVIEW_P13-T6_broker_mode_configuration_migration.md new file mode 100644 index 00000000..c7b29162 --- /dev/null +++ b/SPECS/INPROGRESS/REVIEW_P13-T6_broker_mode_configuration_migration.md @@ -0,0 +1,36 @@ +## REVIEW REPORT — P13-T6 broker mode configuration and migration docs + +**Scope:** origin/main..HEAD +**Files:** 14 + +### Summary Verdict +- [ ] Approve +- [x] Approve with comments +- [ ] Request changes +- [ ] Block + +### Critical Issues + +- None. + +### Secondary Issues + +- [Low] `docs/broker-mode.md` start command uses a long inline Python one-liner with an internal attribute assignment (`d._transport=t`). This is acceptable for advanced/local usage but should stay clearly labeled as advanced to avoid casual copy/paste into production automation. + +### Architectural Notes + +- Documentation now centralizes broker-mode operations in `docs/broker-mode.md` and keeps per-client setup files focused on client-specific command examples. +- Rollback path is consistently documented across README, setup guides, and troubleshooting. + +### Tests + +- Quality gates executed and passing: + - `pytest` (577 passed, 5 skipped) + - `ruff check src/` + - `mypy src/` + - `pytest --cov` (92.31% total, threshold >= 90%) + +### Next Steps + +- No actionable defects found in this review. +- FOLLOW-UP step is skipped. From 97fe12d7f2a69006a563d890324fb59559ccb44d Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Wed, 18 Feb 2026 21:30:15 +0300 Subject: [PATCH 7/8] Archive REVIEW_P13-T6_broker_mode_configuration_migration report --- SPECS/ARCHIVE/INDEX.md | 2 ++ .../REVIEW_P13-T6_broker_mode_configuration_migration.md | 0 2 files changed, 2 insertions(+) rename SPECS/{INPROGRESS => ARCHIVE/_Historical}/REVIEW_P13-T6_broker_mode_configuration_migration.md (100%) diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index 79e3654d..108f29ec 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -182,6 +182,7 @@ | [REVIEW_P13-T3_transport_multiplexing.md](_Historical/REVIEW_P13-T3_transport_multiplexing.md) | Review report for P13-T3 | | [REVIEW_P13-T4_stdio_proxy_mode.md](_Historical/REVIEW_P13-T4_stdio_proxy_mode.md) | Review report for P13-T4 | | [REVIEW_P13-T5_prompt_reduction_multi_client_stability.md](_Historical/REVIEW_P13-T5_prompt_reduction_multi_client_stability.md) | Review report for P13-T5 | +| [REVIEW_P13-T6_broker_mode_configuration_migration.md](_Historical/REVIEW_P13-T6_broker_mode_configuration_migration.md) | Review report for P13-T6 | ## Archive Log @@ -318,3 +319,4 @@ | 2026-02-18 | P13-T5 | Archived Validate_prompt_reduction_and_multi_client_stability (PARTIAL) | | 2026-02-18 | P13-T5 | Archived REVIEW_P13-T5_prompt_reduction_multi_client_stability report | | 2026-02-18 | P13-T6 | Archived Document_broker_mode_configuration_migration_and_rollback (PASS) | +| 2026-02-18 | P13-T6 | Archived REVIEW_P13-T6_broker_mode_configuration_migration report | diff --git a/SPECS/INPROGRESS/REVIEW_P13-T6_broker_mode_configuration_migration.md b/SPECS/ARCHIVE/_Historical/REVIEW_P13-T6_broker_mode_configuration_migration.md similarity index 100% rename from SPECS/INPROGRESS/REVIEW_P13-T6_broker_mode_configuration_migration.md rename to SPECS/ARCHIVE/_Historical/REVIEW_P13-T6_broker_mode_configuration_migration.md From 6a6cdb5919f26b0a64f90792470464563bc89f29 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Wed, 18 Feb 2026 21:33:25 +0300 Subject: [PATCH 8/8] Implement P13-T6: sync DocC pages for broker mode docs --- .../Documentation.docc/ClaudeCodeSetup.md | 24 ++++++++++ .../Documentation.docc/CodexCLISetup.md | 24 ++++++++++ .../Documentation.docc/CursorSetup.md | 46 +++++++++++++++++++ .../Documentation.docc/Troubleshooting.md | 38 +++++++++++++++ .../Documentation.docc/XcodeMCPWrapper.md | 20 ++++++++ 5 files changed, 152 insertions(+) diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md b/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md index 49d25c58..fb20adf6 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md @@ -22,6 +22,20 @@ Use this variant to enable the dashboard on port `8080`: claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080 ``` +### Option 1C: Using Broker Mode (Optional) + +Connect to an already-running broker: + +```bash +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect +``` + +Best-effort auto-spawn mode: + +```bash +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-spawn +``` + ### Option 2: Using Manual Installation If you installed manually to `~/bin/xcodemcpwrapper`: @@ -46,6 +60,11 @@ claude mcp add --transport stdio xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcp Replace `/path/to/XcodeMCPWrapper` with the actual path to your cloned repository. +### Migration and Rollback + +- Migration: add `--broker-connect` or `--broker-spawn` to your `claude mcp add` command. +- Rollback: remove broker flags and re-run the command. + ### Verify Configuration ```bash @@ -112,3 +131,8 @@ Make sure Xcode Tools MCP is enabled in Xcode: 1. Open **Xcode** > **Settings** (`⌘,`) 2. Select **Intelligence** 3. Toggle **Xcode Tools** ON + +**"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. diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md b/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md index 3e3cba4a..d465f6d7 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md @@ -22,6 +22,20 @@ Use this variant to enable the dashboard on port `8080`: codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080 ``` +### Option 1C: Using Broker Mode (Optional) + +Connect to an already-running broker: + +```bash +codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect +``` + +Best-effort auto-spawn mode: + +```bash +codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-spawn +``` + ### Option 2: Using Manual Installation If you installed manually to `~/bin/xcodemcpwrapper`: @@ -46,6 +60,11 @@ codex mcp add xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper --we Replace `/path/to/XcodeMCPWrapper` with the actual path to your cloned repository. +### Migration and Rollback + +- Migration: add `--broker-connect` or `--broker-spawn` to your `codex mcp add` command. +- Rollback: remove broker flags and re-run the command. + ### Verify Configuration ```bash @@ -123,3 +142,8 @@ Make sure Xcode Tools MCP is enabled in Xcode: 1. Open **Xcode** > **Settings** (`⌘,`) 2. Select **Intelligence** 3. Toggle **Xcode Tools** ON + +**"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. diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/CursorSetup.md b/Sources/XcodeMCPWrapper/Documentation.docc/CursorSetup.md index a1fe36c9..310d2c9d 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/CursorSetup.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/CursorSetup.md @@ -107,6 +107,47 @@ With Web UI: Replace `/path/to/XcodeMCPWrapper` with the actual path to your cloned repository. +### Option 4: Using Broker Mode (Optional) + +Connect mode: + +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "uvx", + "args": [ + "--from", + "mcpbridge-wrapper", + "mcpbridge-wrapper", + "--broker-connect" + ] + } + } +} +``` + +Best-effort auto-spawn mode: + +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "uvx", + "args": [ + "--from", + "mcpbridge-wrapper", + "mcpbridge-wrapper", + "--broker-spawn" + ] + } + } +} +``` + +Migration: add `--broker-connect` or `--broker-spawn` to existing args. +Rollback: remove broker flags and restart Cursor. + ### Restart Cursor Quit and reopen Cursor to load the new MCP configuration. @@ -149,6 +190,11 @@ Make sure Xcode Tools MCP is enabled in Xcode: 3. Toggle **Xcode Tools** ON 4. Restart Cursor +**"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. + **"Web UI still shows old behavior after an upgrade"** If Cursor is configured with Web UI args and behavior looks stale after upgrading, force a one-time uvx refresh: diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md index 0cf67183..ec074e71 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md @@ -295,6 +295,44 @@ The second value should be larger. **Important:** Multiple wrapper processes can run at the same time (for different ports or restarts), which can mask upgrades. Always verify the version for the process bound to the port you are viewing. +## Error: "Could not connect to broker socket ... within 10.0s" + +**Symptom:** Broker mode exits with a timeout waiting for `broker.sock`. + +**Cause:** Broker process is not running, or socket state is stale. + +**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" +``` + +## Error: "Broker already running (PID ...)" + +**Symptom:** Explicit broker startup fails because an existing broker lock is active. + +**Solution:** Reuse the running broker with `--broker-connect`, or stop the PID first: + +```bash +PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; if [ -f "$PID_FILE" ]; then kill "$(cat "$PID_FILE")"; fi +``` + +## Stale broker lock/socket recovery + +```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 +``` + +## Rollback to direct mode + +1. Remove `--broker-connect` / `--broker-spawn` from MCP config args. +2. Restart the MCP client. +3. Stop and clean broker state: + +```bash +PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; SOCK="$HOME/.mcpbridge_wrapper/broker.sock"; if [ -f "$PID_FILE" ]; then kill "$(cat "$PID_FILE")" 2>/dev/null || true; fi; rm -f "$PID_FILE" "$SOCK" +``` + ## Tool Returns Empty Results **Symptom:** Tools execute but return no data. diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md index c954d7e1..3d57f978 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md @@ -83,6 +83,26 @@ uvx --refresh --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web Restart Cursor and you're done. For other clients or installation methods, read on. +### Broker Mode (Optional) + +Broker mode lets short-lived MCP sessions share one persistent upstream bridge. + +- `--broker-connect`: attach to an already-running broker. +- `--broker-spawn`: best-effort auto-start, then connect. + +Quick migration examples: + +```bash +# Claude Code +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect + +# Codex CLI +codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect +``` + +For troubleshooting and rollback details, see , +, , and . + ### Python Environment Setup (Development) If you plan to run development commands such as `make install`, `make test`, or editable installs, create and activate a virtual environment first. This avoids Homebrew Python's `externally-managed-environment` (PEP 668) error.