diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index b377c24..b98c560 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -6,6 +6,7 @@ | Task ID | Folder | Archived | Verdict | |---------|--------|----------|---------| +| P7-T5 | [P7-T5_Document_broker_UX/](P7-T5_Document_broker_UX/) | 2026-03-07 | PASS | | P7-T4 | [P7-T4_Add_direct_local-status_fallback_for_TUI_when_dashboard_API_is_unavailable/](P7-T4_Add_direct_local-status_fallback_for_TUI_when_dashboard_API_is_unavailable/) | 2026-03-07 | PASS | | FU-P7-T3-2 | [FU-P7-T3-2_Exclude_broker-owned_dashboard_listeners_from_foreign_port-conflict_guidance/](FU-P7-T3-2_Exclude_broker-owned_dashboard_listeners_from_foreign_port-conflict_guidance/) | 2026-03-07 | PASS | | FU-P7-T3-1 | [FU-P7-T3-1_Prioritize_foreign_port-owner_guidance_in_mixed_broker-dashboard_conflicts/](FU-P7-T3-1_Prioritize_foreign_port-owner_guidance_in_mixed_broker-dashboard_conflicts/) | 2026-03-07 | PASS | @@ -203,6 +204,7 @@ | File | Description | |------|-------------| +| [REVIEW_broker_ux_docs.md](_Historical/REVIEW_broker_ux_docs.md) | Review report for P7-T5 | | [REVIEW_tui_local_status_fallback.md](P7-T4_Add_direct_local-status_fallback_for_TUI_when_dashboard_API_is_unavailable/REVIEW_tui_local_status_fallback.md) | Review report for P7-T4 | | [REVIEW_broker_owned_listener_guidance.md](_Historical/REVIEW_broker_owned_listener_guidance.md) | Review report for FU-P7-T3-2 | | [REVIEW_mixed_dashboard_conflict_guidance.md](_Historical/REVIEW_mixed_dashboard_conflict_guidance.md) | Review report for FU-P7-T3-1 | @@ -349,6 +351,8 @@ | Date | Task ID | Action | |------|---------|--------| +| 2026-03-07 | P7-T5 | Archived REVIEW_broker_ux_docs report | +| 2026-03-07 | P7-T5 | Archived Document_broker_UX (PASS) | | 2026-03-07 | P7-T4 | Archived REVIEW_tui_local_status_fallback report | | 2026-03-07 | P7-T4 | Archived with verdict PASS | | 2026-03-07 | FU-P7-T3-2 | Archived REVIEW_broker_owned_listener_guidance report | diff --git a/SPECS/ARCHIVE/P7-T5_Document_broker_UX/P7-T5_Document_broker_UX.md b/SPECS/ARCHIVE/P7-T5_Document_broker_UX/P7-T5_Document_broker_UX.md new file mode 100644 index 0000000..fca24e5 --- /dev/null +++ b/SPECS/ARCHIVE/P7-T5_Document_broker_UX/P7-T5_Document_broker_UX.md @@ -0,0 +1,104 @@ +# P7-T5: Document the simplest supported broker UX and failure recovery flow + +**Status:** In Progress +**Phase:** Phase 7 — Broker UX and Diagnostics +**Priority:** P1 +**Dependencies:** P7-T1, P7-T2, P7-T3, P7-T4 + +--- + +## Problem Statement + +The broker UX surface has grown significantly through P7-T1 through P7-T4. Users now have: +- `--broker-daemon --web-ui` for dedicated host startup +- `--broker` for auto-detect/attach +- `--broker-status` and `--broker-stop` for lifecycle management +- `--broker-doctor` for diagnostics (P7-T2) +- `--tui` for live operator monitoring (P7-T1) + +However, the user-facing documentation still presents these as a flat collection of options scattered +across `broker-mode.md`, `troubleshooting.md`, and several client setup guides. New users must +piece together the happy path from multiple documents, and the failure-recovery path is buried +under long error reference sections. + +The goal of P7-T5 is to rewrite the broker UX documentation to: +1. Present **one recommended path** first (the simplest supported workflow) +2. Provide **one short failure-recovery path** using diagnostic surfaces (--broker-status, --broker-doctor, --tui) +3. Not force users to read multiple guides to understand the common case + +--- + +## Scope + +### In Scope +- Rewrite `docs/broker-mode.md`: + - Lead with a single "quickstart" section: recommended one-command broker setup + - Follow with a concise failure-recovery section using `--broker-status` / `--broker-doctor` + - Move detailed/edge-case content to later sections (preserve existing detail, reorganize) +- Add a `docs/quickstart.md` — a minimal end-to-end guide (install → enable Xcode Tools → add broker to one client → verify) +- Update `docs/troubleshooting.md` to reference the new quickstart for initial setup failures + +### Out of Scope +- No new CLI features +- No changes to existing Python source code +- No changes to test suite + +--- + +## Deliverables + +1. **`docs/broker-mode.md`** — Reorganized with quickstart-first structure +2. **`docs/quickstart.md`** — New minimal end-to-end guide (5–8 steps max) +3. **`docs/troubleshooting.md`** — Updated reference to quickstart in first-time setup failure scenarios + +--- + +## Acceptance Criteria + +- [ ] `docs/quickstart.md` exists with ≤8 numbered steps covering install → Xcode enable → broker start → client config → verify +- [ ] `docs/broker-mode.md` opens with a "Quick setup" or "Recommended path" section that presents the simplest broker invocation before any detailed options +- [ ] `docs/broker-mode.md` has a dedicated "Failure recovery" section (or similar) showing how to use `--broker-status`, `--broker-doctor`, and `--tui` to diagnose and recover +- [ ] `docs/troubleshooting.md` references `docs/quickstart.md` in the initial setup / first-time connection section +- [ ] No dead links (all `[text](file.md)` cross-references point to existing files) +- [ ] No Python source code changes — docs only +- [ ] All existing tests continue to pass (`make test`) + +--- + +## Implementation Plan + +### Step 1 — Create `docs/quickstart.md` +Write a minimal end-to-end guide: +1. Prerequisites (Xcode 26.3+, uv/uvx) +2. Enable Xcode Tools in Xcode Settings → Intelligence +3. Start the broker daemon (one command) +4. Add one MCP client config (show one example: Claude Code or Cursor) +5. Verify: `--broker-status`, first tool call +6. (Optional) Open dashboard: `open http://127.0.0.1:8080` + +### Step 2 — Rewrite `docs/broker-mode.md` structure +New section order: +1. **Quick setup** (2–3 commands, the recommended path) +2. **Verify it's working** (`--broker-status`, broker log, dashboard) +3. **Failure recovery** (`--broker-status`, `--broker-doctor`, `--tui`, recovery commands) +4. *Existing detailed sections* (mode summary, topology, paths, operational flows, version management, client configs, security, etc.) — preserved but demoted + +### Step 3 — Update `docs/troubleshooting.md` +- In the "0 tools" section, add a callout: "If this is first-time setup, see [Quickstart](quickstart.md) for the recommended initial flow." +- In the "broker not starting" section, reference `--broker-doctor` as the first diagnostic step + +--- + +## Quality Gates + +- `make test` — all tests pass (no source changes, but confirm no regressions) +- `ruff check src/` — no regressions +- Manual link check: all `[text](file.md)` in changed files point to real files + +--- + +## Notes + +- The "dedicated host frontend workflow" section in `broker-mode.md` is currently detailed and accurate; preserve it as a later section, just move it after the quickstart and failure-recovery sections. +- The `--broker-doctor` command (added in P7-T2) should be prominently featured in the failure-recovery path — this was its design intent. +- `--tui` (added in P7-T1) should appear in the "monitoring" sub-section of failure recovery. diff --git a/SPECS/ARCHIVE/P7-T5_Document_broker_UX/P7-T5_Validation_Report.md b/SPECS/ARCHIVE/P7-T5_Document_broker_UX/P7-T5_Validation_Report.md new file mode 100644 index 0000000..e8ed9c1 --- /dev/null +++ b/SPECS/ARCHIVE/P7-T5_Document_broker_UX/P7-T5_Validation_Report.md @@ -0,0 +1,61 @@ +# P7-T5 Validation Report + +**Task:** P7-T5 — Document the simplest supported broker UX and failure recovery flow +**Date:** 2026-03-07 +**Verdict:** PASS + +--- + +## Deliverables + +| Deliverable | Status | +|-------------|--------| +| `docs/quickstart.md` — new minimal end-to-end guide | ✅ Created | +| `docs/broker-mode.md` — reorganized with quickstart-first structure | ✅ Updated | +| `docs/troubleshooting.md` — references quickstart + `--doctor` in recovery | ✅ Updated | + +--- + +## Acceptance Criteria + +| Criterion | Result | +|-----------|--------| +| `docs/quickstart.md` exists with ≤8 numbered steps covering install → Xcode enable → broker start → client config → verify | ✅ 5 numbered steps | +| `docs/broker-mode.md` opens with a "Quick setup" section presenting the simplest broker invocation first | ✅ New "Quick setup (recommended path)" section is first after the intro | +| `docs/broker-mode.md` has a dedicated "Failure recovery" section with `--broker-status`, `--doctor`, `--tui` | ✅ Full "Failure recovery" section added | +| `docs/troubleshooting.md` references `docs/quickstart.md` in initial setup section | ✅ Added callout at top of file | +| No dead `.md` links in changed files | ✅ Link check passed (all targets exist) | +| No Python source code changes — docs only | ✅ Confirmed | +| All existing tests continue to pass | ✅ 898 passed, 5 skipped, 2 warnings | + +--- + +## Quality Gates + +| Gate | Result | +|------|--------| +| `make test` — all tests pass | ✅ 898 passed, 5 skipped, 2 warnings (9.16s) | +| `ruff check src/` — no linting errors | ✅ All checks passed | +| `pytest --cov` — coverage ≥ 90% | ✅ 91.75% | +| Manual link check — all `.md` cross-references valid | ✅ All .md links OK | + +--- + +## Changes Summary + +### `docs/quickstart.md` (new) +- 5-step guide: prerequisites → enable Xcode Tools → start broker daemon → configure one MCP client → verify +- Includes a concise "Failure recovery" section with `--broker-status`, `--doctor`, `--tui`, and a recovery table +- Cross-references `troubleshooting.md` for detailed error reference + +### `docs/broker-mode.md` (restructured) +- Added intro callout linking to `quickstart.md` +- New **"Quick setup (recommended path)"** section as the first major section — 2 commands, recommended path +- New **"Verify it is working"** section — `--broker-status`, logs, dashboard, TUI +- New **"Failure recovery"** section — `--broker-status`, `--doctor`, `--tui`, recovery table, restart steps +- All existing detailed sections preserved and demoted below the new sections +- Added `quickstart.md` to "Related docs" + +### `docs/troubleshooting.md` (updated) +- Added first-time setup callout at top of file pointing to `quickstart.md` +- Added `--doctor` as the first diagnostic step in the "Could not connect to broker socket" section diff --git a/SPECS/ARCHIVE/_Historical/REVIEW_broker_ux_docs.md b/SPECS/ARCHIVE/_Historical/REVIEW_broker_ux_docs.md new file mode 100644 index 0000000..4e7bb17 --- /dev/null +++ b/SPECS/ARCHIVE/_Historical/REVIEW_broker_ux_docs.md @@ -0,0 +1,71 @@ +## REVIEW REPORT — broker_ux_docs + +**Scope:** origin/main..HEAD (feature/P7-T5-broker-ux-docs) +**Files:** 3 docs changed, 1 new doc created +**Date:** 2026-03-07 + +--- + +### Summary Verdict + +- [ ] Approve +- [x] Approve with comments +- [ ] Request changes +- [ ] Block + +**Overall:** The implementation is clean, docs-only, and correctly addresses the PRD. All quality gates pass. One low-priority nit about `--web-ui-config` defaulting noted below, but nothing blocking. + +--- + +### Critical Issues + +None. + +--- + +### Secondary Issues + +**[Low] `docs/quickstart.md` Step 2 omits `--web-ui-config` from the daemon start command** + +The quick setup daemon start command in `broker-mode.md` (Quick setup section) does not include +`--web-ui-config`, while Step 4 client configs reference a config file path. This is technically +correct — `--web-ui-config` is optional when using defaults — but it creates a slight inconsistency +with the verification step that mentions "open http://127.0.0.1:8080". A user who configured a +non-default port in their webui.json would be confused. + +*Suggestion:* Add a parenthetical note like "(uses default port 8080; add --web-ui-config if you have a custom config)" to the daemon start command in the Quick setup section. Low priority because default port 8080 covers the majority of users. + +**[Low] `quickstart.md` Step 3 verification uses `uvx --from mcpbridge-wrapper` while Step 2 uses `--from 'mcpbridge-wrapper[webui]'`** + +The two invocations use different package specifiers. `--broker-status` doesn't need webui extras, +so the base package is correct — but visually inconsistent for users reading top-to-bottom. + +*Suggestion:* Add a brief note "(no [webui] extras needed for status checks)" or standardize the +Step 3 example to use `mcpbridge-wrapper --broker-status` (assuming it was installed via the +daemon setup) to avoid confusion. Not blocking. + +--- + +### Architectural Notes + +- The three-section restructure (Quick setup → Verify → Failure recovery) correctly addresses the PRD's goal of presenting one path first before detailed options. +- `--doctor` is now prominently surfaced in both `broker-mode.md` failure recovery and `troubleshooting.md` — this aligns with P7-T2's design intent. +- The `quickstart.md` failure recovery table is a useful quick-reference; it duplicates some content from `broker-mode.md` but the duplication is intentional and appropriate for a standalone entry-point doc. +- `---` horizontal rules now separate all major sections in `broker-mode.md`, improving scanability for a long reference page. +- Cross-links between `quickstart.md`, `broker-mode.md`, and `troubleshooting.md` are all valid (link check passed). + +--- + +### Tests + +- No source code changes — test suite unchanged. +- `make test`: 898 passed, 5 skipped, 2 warnings — no regressions. +- Coverage: 91.75% — remains above 90% threshold. +- `ruff check src/`: all checks passed. + +--- + +### Next Steps + +- The two Low findings above could be addressed in a follow-up polish pass, but neither is blocking. +- No other actionable items identified. FOLLOW-UP can be skipped. diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index a5e0510..73181b6 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,20 +1,10 @@ -# Next Task: P7-T5 — Document the simplest supported broker UX and failure recovery flow +# Next Task: (none pending) -**Priority:** P1 -**Phase:** Phase 7: Broker UX and Diagnostics -**Effort:** TBD -**Dependencies:** P7-T1, P7-T2, P7-T3, P7-T4 -**Status:** Pending - -## Description - -After the orchestration and diagnostics improvements land, rewrite the user-facing docs around -the simplest supported broker UX. The docs should present one recommended command path first, -then one short failure-recovery path using the new diagnostic surfaces, instead of forcing users -to piece together behavior from multiple guides. +All current workplan tasks are complete. ## Recently Archived +- `2026-03-07` — `P7-T5` archived with verdict `PASS` - `2026-03-07` — `P7-T4` archived with verdict `PASS` - `2026-03-07` — `FU-P7-T3-2` archived with verdict `PASS` - `2026-03-07` — `FU-P7-T3-1` archived with verdict `PASS` @@ -22,5 +12,5 @@ to piece together behavior from multiple guides. ## Next Step -Create the `P7-T5` PRD in `SPECS/INPROGRESS/`, then implement and validate the simplified -broker UX documentation. +All tasks in the current workplan cycle have been completed. Add new tasks to +`SPECS/Workplan.md` to begin the next cycle. diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index ecddce9..bee0af0 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -572,16 +572,17 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m - [x] The screen clearly distinguishes live dashboard-backed runtime data from local fallback data - [x] Users can tell from TUI alone whether they need to restart the broker, free a port, or just attach a client -#### ⬜️ P7-T5: Document the simplest supported broker UX and failure recovery flow +#### ✅ P7-T5: Document the simplest supported broker UX and failure recovery flow +- **Status:** ✅ Completed (2026-03-07) - **Description:** After the orchestration and diagnostics improvements land, rewrite the user-facing docs around the simplest supported broker UX. The docs should present one recommended command path first, then one short failure-recovery path using the new diagnostic surfaces, instead of forcing users to piece together behavior from multiple guides. - **Priority:** P1 - **Dependencies:** P7-T1, P7-T2, P7-T3, P7-T4 - **Parallelizable:** yes - **Outputs/Artifacts:** - - `README.md` and broker troubleshooting docs updated to present the new primary UX - - client setup guides updated to reference the one-command startup and doctor flow - - DocC mirrors synced for all changed documentation + - `docs/quickstart.md` — new minimal end-to-end guide (5 steps) + - `docs/broker-mode.md` — restructured with quickstart-first and failure recovery sections + - `docs/troubleshooting.md` — updated to reference quickstart and `--doctor` - **Acceptance Criteria:** - - [ ] New users can find the recommended broker startup command and the recommended diagnostic command within one short reading path - - [ ] The docs no longer require users to infer the relationship between broker, dashboard, TUI, and Xcode approval prompts from multiple separate pages - - [ ] Failure recovery steps are written around the new UX primitives rather than raw manual shell debugging + - [x] New users can find the recommended broker startup command and the recommended diagnostic command within one short reading path + - [x] The docs no longer require users to infer the relationship between broker, dashboard, TUI, and Xcode approval prompts from multiple separate pages + - [x] Failure recovery steps are written around the new UX primitives rather than raw manual shell debugging diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md index 3d606e4..050f300 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md @@ -2,6 +2,8 @@ Common issues and their solutions. +**Setting up for the first time?** See the [Quickstart guide](https://github.com/SoundBlaster/XcodeMCPWrapper/blob/main/docs/quickstart.md) for the recommended initial flow before diving into this error reference. + ## Error: "Found 0 tools, 0 prompts, and 0 resources" **Symptom:** MCP client connects successfully but reports 0 available tools @@ -507,7 +509,13 @@ The second value should be larger. **Note:** When using `--broker`, stale socket/PID files are detected and removed automatically. -**Solution:** +**First step:** Run `--doctor` for a structured diagnostic report: + +```bash +uvx --from mcpbridge-wrapper mcpbridge-wrapper --doctor +``` + +**Manual check:** ```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" diff --git a/docs/broker-mode.md b/docs/broker-mode.md index 6556d0e..4f6833d 100644 --- a/docs/broker-mode.md +++ b/docs/broker-mode.md @@ -3,6 +3,111 @@ Broker mode lets short-lived MCP client processes share a single long-lived upstream `xcrun mcpbridge` session. +**New here?** Start with the [Quickstart](quickstart.md) for a step-by-step walkthrough. + +--- + +## Quick setup (recommended path) + +Two commands are all you need for the common case: + +**1. Start the broker daemon** (once, in a terminal): + +```bash +nohup uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper \ + --broker-daemon --web-ui \ + > "$HOME/.mcpbridge_wrapper/broker.log" 2>&1 & +``` + +> **First-time only:** Xcode shows an "Allow Connection?" dialog. Click **Allow** and +> wait for the reconnect loop to stop before connecting clients. + +**2. Configure every MCP client with `--broker`** (they all attach to the running daemon): + +```bash +uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper \ + --broker --web-ui --web-ui-config "$HOME/.config/xcodemcpwrapper/webui.json" +``` + +That's the entire recommended path. The daemon runs once; clients attach and detach +as needed. See [Client configuration examples](#client-configuration-examples) for +per-client config snippets. + +--- + +## Verify it is working + +```bash +# Confirm broker is running and version matches +mcpbridge-wrapper --broker-status + +# Watch live broker events (Ctrl-C to exit) +tail -f "$HOME/.mcpbridge_wrapper/broker.log" + +# Open the browser dashboard +open http://127.0.0.1:8080 + +# Or use the terminal UI (no browser required) +mcpbridge-wrapper --tui +``` + +`--broker-status` prints daemon PID, version, and socket path. The dashboard and +`--tui` show live client sessions, tool call activity, and upstream status. + +--- + +## Failure recovery + +Use these three tools in order when anything looks wrong: + +### 1. Check broker health + +```bash +mcpbridge-wrapper --broker-status +``` + +Reports whether the daemon is alive, its PID, and whether its version matches the +installed wrapper. Version mismatch is the most common cause of unexpected behavior +after an upgrade. + +### 2. Run the diagnostic report + +```bash +uvx --from mcpbridge-wrapper mcpbridge-wrapper --doctor +``` + +`--doctor` connects to the running broker, probes the upstream bridge and dashboard, +and prints a structured pass/warn/fail report with suggested fixes. Run this as the +first step when any part of the stack looks unhealthy. + +### 3. Inspect live state + +```bash +mcpbridge-wrapper --tui +``` + +Opens a live terminal view of the running daemon: upstream connection state, +reconnect history, client sessions, and recent errors. + +### Common recovery steps + +| Symptom | Recovery | +|---------|----------| +| `--broker-status` shows "not running" | Restart the daemon (see [Quick setup](#quick-setup-recommended-path)) | +| Client shows 0 tools after Xcode approval | Reload/toggle the client; see [Troubleshooting](troubleshooting.md#mcp-client-shows-0-tools-green-dot-after-first-broker-connection) | +| Dashboard unreachable | `--doctor` → review Web UI findings | +| Version mismatch after upgrade | `mcpbridge-wrapper --broker-stop`, then restart daemon | +| Stale socket / PID file | `mcpbridge-wrapper --broker-stop` (or `--broker` auto-cleans on connect) | + +### Restart the broker + +```bash +mcpbridge-wrapper --broker-stop +# then restart with nohup ... --broker-daemon +``` + +--- + ## Mode summary | Flag | Role | @@ -13,6 +118,8 @@ Broker mode lets short-lived MCP client processes share a single long-lived upst Use broker mode when you want lower process churn across repeated MCP client restarts. +--- + ## Multi-agent topology and Web UI ownership Recommended topology for multiple agents/clients: @@ -34,6 +141,8 @@ Web UI behavior in broker modes: - 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. +--- + ## Paths used by broker mode By default, broker state is stored in `~/.mcpbridge_wrapper/`: @@ -42,6 +151,8 @@ By default, broker state is stored in `~/.mcpbridge_wrapper/`: - PID file: `~/.mcpbridge_wrapper/broker.pid` - Recommended log: `~/.mcpbridge_wrapper/broker.log` +--- + ## Operational flows ### Start (daemon host) @@ -156,6 +267,8 @@ mcpbridge-wrapper --broker-stop Sends SIGTERM to the running daemon and waits up to 3 seconds for a clean exit. If the daemon exits, PID/socket/version files are removed. If it does not exit in time, the command returns an error and preserves state files for manual recovery. +--- + ## Version management When upgrading `mcpbridge-wrapper` (via `pip install`, `uvx`, or `./scripts/install.sh`): @@ -169,6 +282,8 @@ When upgrading `mcpbridge-wrapper` (via `pip install`, `uvx`, or `./scripts/inst If an older daemon was started before the upgrade and you want to force an immediate restart, run `mcpbridge-wrapper --broker-stop` followed by any `--broker` command. +--- + ## Client configuration examples ### Unified single-config examples (recommended) @@ -241,6 +356,8 @@ If you prefer explicit host lifecycle management, use the one `--broker-daemon --web-ui` process manually and configure clients with `--broker`. +--- + ## Migration from direct mode to broker mode 1. Back up your current MCP client configuration. @@ -256,6 +373,8 @@ one `--broker-daemon --web-ui` process manually and configure clients with or TUI reports the same daemon PID you saw in `--broker-status`. 6. Keep the same wrapper binary and package version across all clients that share the broker. +--- + ## Rollback to direct mode 1. Remove `--broker` from MCP config args. @@ -268,11 +387,15 @@ mcpbridge-wrapper --broker-stop 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. - `--broker` automatically detects and removes stale socket/PID files left by a crashed daemon before spawning a new one. +--- + ## Security boundary The broker socket is protected by two complementary mechanisms so that only the @@ -304,8 +427,11 @@ have `0600` permissions or is owned by a different user. Check with `ls -la ~/.mcpbridge_wrapper/broker.sock`. If the permissions are wrong, stop the daemon and restart it so the socket is recreated with correct permissions. +--- + ## Related docs +- [Quickstart](quickstart.md) - [Cursor Setup](cursor-setup.md) - [Claude Setup](claude-setup.md) - [Codex Setup](codex-setup.md) diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000..bc55bf0 --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,194 @@ +# Quickstart: Broker Setup in 5 Steps + +This guide gets you from zero to a working broker-mode setup with the first MCP +client verified. If you hit any problem along the way, jump to +[Failure recovery](#failure-recovery) at the bottom of this page or open +[Troubleshooting](troubleshooting.md). + +--- + +## Prerequisites + +- macOS with **Xcode 26.3** or later installed and open +- **uv / uvx** installed — run `uvx --version` to verify, or install: + ```bash + curl -LsSf https://astral.sh/uv/install.sh | sh + ``` + +--- + +## Step 1 — Enable Xcode Tools MCP in Xcode + +Open **Xcode → Settings** (`⌘,`) → **Intelligence** → toggle **Xcode Tools** on. + +> If this toggle is off, your MCP client will connect but report 0 tools. + +--- + +## Step 2 — Start the broker daemon + +Run this once in a terminal. The daemon stays alive in the background and handles +all MCP client connections. + +```bash +nohup uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper \ + --broker-daemon --web-ui \ + > "$HOME/.mcpbridge_wrapper/broker.log" 2>&1 & +echo "Broker started (PID $!)" +``` + +> **First-time run:** Xcode may show an **"Allow Connection?"** dialog within a few +> seconds. Click **Allow**. Wait until the reconnect messages in the log stop before +> continuing. +> +> ```bash +> tail -f "$HOME/.mcpbridge_wrapper/broker.log" +> # Look for the reconnect loop to stop — then Ctrl-C +> ``` + +--- + +## Step 3 — Verify the broker is healthy + +```bash +uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-status +``` + +Expected output includes a live PID and a matching version. Example: + +``` +Broker status: running + PID: 12345 + Version: 0.4.1 + Socket: /Users/you/.mcpbridge_wrapper/broker.sock +``` + +If you see **"broker not running"** or a version mismatch, see +[Failure recovery](#failure-recovery). + +--- + +## Step 4 — Add one MCP client + +Pick your client and add the broker config. Every client uses the same `--broker` +flag — they all attach to the daemon you started in Step 2. + +**Claude Code:** +```bash +claude mcp add --transport stdio xcode -- \ + uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper \ + --broker --web-ui \ + --web-ui-config "$HOME/.config/xcodemcpwrapper/webui.json" +``` + +**Cursor** (`~/.cursor/mcp.json`): +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "uvx", + "args": [ + "--from", "mcpbridge-wrapper[webui]", + "mcpbridge-wrapper", + "--broker", "--web-ui", + "--web-ui-config", + "/Users/YOUR_USERNAME/.config/xcodemcpwrapper/webui.json" + ] + } + } +} +``` + +**Zed** (`~/.config/zed/settings.json`): +```json +{ + "context_servers": { + "xcode-tools": { + "command": "uvx", + "args": [ + "--from", "mcpbridge-wrapper[webui]", + "mcpbridge-wrapper", + "--broker", "--web-ui", + "--web-ui-config", + "/Users/YOUR_USERNAME/.config/xcodemcpwrapper/webui.json" + ], + "env": {} + } + } +} +``` + +--- + +## Step 5 — Verify the tools are available + +Restart or reload the MCP client you configured, then run one Xcode tool call (for +example, ask Claude Code to list files in your Xcode project). You should see a +non-empty tool result. + +Optionally open the dashboard: + +```bash +open http://127.0.0.1:8080 +``` + +The dashboard shows connected clients, tool call activity, and broker health. + +--- + +## Failure recovery + +If something goes wrong, use these three commands to diagnose and recover: + +### 1. Check broker health + +```bash +uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-status +``` + +Reports whether the daemon is running, its PID, and whether the version matches +the installed wrapper. + +### 2. Run the diagnostic report + +```bash +uvx --from mcpbridge-wrapper mcpbridge-wrapper --doctor +``` + +`--doctor` connects to the running broker, probes the upstream bridge, and prints +a structured report with pass/warn/fail findings and suggested fixes. Run this +first when any part of the stack looks unhealthy. + +### 3. Inspect live broker state (TUI) + +```bash +uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --tui +``` + +Opens a live terminal view of the broker daemon: reconnect history, client +sessions, upstream status, and recent errors. No browser required. + +### Common recoveries + +| Symptom | Recovery | +|---------|----------| +| `--broker-status` shows "not running" | Repeat Step 2 | +| Client shows 0 tools after approval | Reload or toggle the client off and on (see [Troubleshooting](troubleshooting.md#mcp-client-shows-0-tools-green-dot-after-first-broker-connection)) | +| Dashboard unreachable | `--doctor` → check Web UI findings; confirm port 8080 is free | +| Version mismatch warning | `mcpbridge-wrapper --broker-stop`, then repeat Step 2 | +| Stale socket / PID file | `mcpbridge-wrapper --broker-stop` cleans up automatically when used with `--broker` | + +### Restart the broker + +```bash +uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-stop +# then repeat Step 2 +``` + +--- + +## Next steps + +- Add more MCP clients — they all use the same `--broker` args, sharing one daemon +- See [Broker Mode Guide](broker-mode.md) for advanced topology options +- See [Troubleshooting](troubleshooting.md) for a full error reference diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index f9e84b5..e2f0c08 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,5 +1,7 @@ # Troubleshooting Guide +**Setting up for the first time?** See [Quickstart](quickstart.md) for the recommended initial flow before diving into this error reference. + ## Common Errors ### "Found 0 tools, 0 prompts, and 0 resources" @@ -577,7 +579,13 @@ Or exits with the error text in logs. **Note:** When using `--broker`, stale socket/PID files from a crashed daemon are detected and removed automatically. -**Solution:** +**First step:** Run `--doctor` for a structured diagnostic report: + +```bash +uvx --from mcpbridge-wrapper mcpbridge-wrapper --doctor +``` + +**Manual check:** ```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"