From c15f991503245629bfc195065dc9b0e248424df9 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 1 Mar 2026 02:13:05 +0300 Subject: [PATCH 01/10] Branch for P1-T3: broker-first README MCP examples From bdd50469cfca911722083c161b56444bd6cd74e6 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 1 Mar 2026 02:13:31 +0300 Subject: [PATCH 02/10] Select task P1-T3: Improve MCP settings examples in README to present broker setup first --- SPECS/INPROGRESS/next.md | 19 +++++++++++-------- SPECS/Workplan.md | 12 ++++++++++++ 2 files changed, 23 insertions(+), 8 deletions(-) diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index c588e56a..d0635881 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,12 +1,15 @@ -# No Active Task +# Next Task: P1-T3 — Improve MCP settings examples in README to present broker setup first -## Recently Archived +**Priority:** P2 +**Phase:** Phase 1: Documentation +**Effort:** 1-2 hours +**Dependencies:** None +**Status:** Selected -- **P1-T2** — Add Xcode 26.4 known issue release-notes link to README (2026-02-28, PASS) -- **P1-T1** — Add the version badge in the README.md (2026-02-28, PASS) -- **P15-T1** — Validate project readiness for the next release (2026-02-28, PASS) -- **FU-P13-T19** — Add integration coverage for broker-hosted Web UI observability (2026-02-28, PASS) +## Description -## Suggested Next Tasks +Update `README.md` MCP configuration examples for different agents so broker-based setup appears first, making the recommended integration path clear and consistent. -- **None** — All tasks completed (2/2) +## Next Step + +Run the PLAN command to generate the implementation-ready PRD. diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index ee1f6c53..9b69051b 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -40,3 +40,15 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m - **Acceptance Criteria:** - [x] `README.md` includes a link to `https://developer.apple.com/documentation/xcode-release-notes/xcode-26_4-release-notes` - [x] `README.md` mentions the Coding Intelligence known issue about repeated "Allow Connection?" dialogs and references issue ID `170721057` + +#### ⬜️ P1-T3: Improve MCP settings examples in README to present broker setup first **INPROGRESS** +- **Description:** Update `README.md` MCP configuration examples for different agents so broker-based setup appears first, making the recommended integration path clear and consistent. +- **Priority:** P2 +- **Dependencies:** none +- **Parallelizable:** yes +- **Outputs/Artifacts:** + - `README.md` MCP settings examples reordered/updated to show broker setup first for each supported agent + - Example snippets validated for clarity and consistency across agent sections +- **Acceptance Criteria:** + - [ ] `README.md` presents broker setup before alternative/manual setup in MCP settings examples for Cursor, Claude Code, and Codex CLI + - [ ] The MCP example sections use consistent wording and ordering so users can follow the broker-first path without ambiguity From 0cb06a8d9264c24e09438da664d5c18dd32ef33a Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 1 Mar 2026 02:13:56 +0300 Subject: [PATCH 03/10] Plan task P1-T3: Improve MCP settings examples in README to present broker setup first --- ...in_README_to_present_broker_setup_first.md | 65 +++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 SPECS/INPROGRESS/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first.md diff --git a/SPECS/INPROGRESS/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first.md b/SPECS/INPROGRESS/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first.md new file mode 100644 index 00000000..663e139c --- /dev/null +++ b/SPECS/INPROGRESS/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first.md @@ -0,0 +1,65 @@ +# P1-T3 PRD — Improve MCP settings examples in README to present broker setup first + +## Objective + +Reorganize MCP configuration examples in `README.md` so broker-based setup is shown first for each supported agent (Cursor, Claude Code, Codex CLI). The objective is to make the recommended setup path immediately visible, reduce ambiguity between broker/manual configurations, and keep command/json snippets consistent across sections. + +## Scope and Deliverables + +- Update the README configuration sections for: + - Cursor + - Claude Code + - Codex CLI +- Present broker setup first in each section, followed by alternative/manual setup. +- Ensure wording and ordering are consistent across all three agent subsections. +- Keep examples syntactically valid and aligned with current command conventions in the repository docs. +- Produce `SPECS/INPROGRESS/P1-T3_Validation_Report.md` with quality-gate results and acceptance checks. + +## Success Criteria and Acceptance Tests + +- Broker setup appears before manual/alternative setup in each of the three agent sections. +- Cursor, Claude Code, and Codex CLI sections follow a consistent pattern and labeling. +- README remains readable and accurate (no broken snippets, no contradictory instructions). +- Required quality gates are executed and pass: + - `pytest` + - `ruff check src/` + - `mypy src/` + - `pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` with coverage >= 90%. + +## Test-First Plan + +1. Inspect current README configuration order and capture baseline locations for each agent section. +2. Define one canonical section pattern: "Broker setup (recommended)" then "Manual setup". +3. Apply edits to each agent section using the same pattern. +4. Validate with targeted `rg` checks for section ordering and broker-first phrasing before running full quality gates. + +## Execution Plan + +### Phase 1: Baseline audit and structure decision + +- Inputs: current `README.md` agent configuration sections. +- Outputs: finalized broker-first section pattern and exact target headings. +- Verification: all three agent sections identified; no section omitted. + +### Phase 2: README implementation + +- Inputs: phase-1 pattern and current examples. +- Outputs: updated `README.md` with broker-first ordering and consistent wording. +- Verification: manual read-through plus `rg` checks confirm ordering and consistency. + +### Phase 3: Validation and reporting + +- Inputs: updated docs and required quality-gate commands. +- Outputs: `SPECS/INPROGRESS/P1-T3_Validation_Report.md` including command outputs and acceptance checklist. +- Verification: all commands pass and coverage remains >= 90%. + +## Decision Notes and Constraints + +- This is documentation-only; no runtime Python behavior changes. +- Preserve valid JSON/CLI snippets and avoid introducing agent-specific drift. +- Prefer minimal structural churn outside the three MCP settings sections. + +## Notes (Post-Implementation) + +- Archive artifacts must include this PRD and the validation report. +- REVIEW subject for this task: `p1_t3_broker_first_mcp_examples`. From 4e1c526f7bdda422d4b6dbf6b1d4210fea9bead9 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 1 Mar 2026 02:18:27 +0300 Subject: [PATCH 04/10] Implement P1-T3: make README MCP examples broker-first --- README.md | 122 +++++++++++++++++--- SPECS/INPROGRESS/P1-T3_Validation_Report.md | 46 ++++++++ 2 files changed, 151 insertions(+), 17 deletions(-) create mode 100644 SPECS/INPROGRESS/P1-T3_Validation_Report.md diff --git a/README.md b/README.md index 9791b274..a1925c13 100644 --- a/README.md +++ b/README.md @@ -245,9 +245,73 @@ Options: #### Cursor -For **uvx** setup (recommended), see [Cursor Quick Setup](#cursor-quick-setup) above. +Broker setup examples are listed first. -**Using manual installation:** +**Using uvx in broker mode (Recommended):** + +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "uvx", + "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper", "--broker-spawn"] + } + } +} +``` + +**Using uvx in broker mode with Web UI (Optional):** +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "uvx", + "args": [ + "--from", + "mcpbridge-wrapper[webui]", + "mcpbridge-wrapper", + "--broker-spawn", + "--web-ui", + "--web-ui-config", + "/Users/YOUR_USERNAME/.mcpbridge_wrapper/webui.json" + ] + } + } +} +``` + +**Using uvx in direct mode:** +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "uvx", + "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"] + } + } +} +``` + +**Using uvx in direct mode with Web UI (Optional):** +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "uvx", + "args": [ + "--from", + "mcpbridge-wrapper[webui]", + "mcpbridge-wrapper", + "--web-ui", + "--web-ui-port", + "8080" + ] + } + } +} +``` + +**Using manual installation (Direct mode):** ```json { @@ -260,7 +324,7 @@ For **uvx** setup (recommended), see [Cursor Quick Setup](#cursor-quick-setup) a } ``` -**Using manual installation with Web UI (Optional):** +**Using manual installation with Web UI (Direct mode, optional):** > Requires installing with `./scripts/install.sh --webui` (or equivalent `.[webui]` dependencies). ```json { @@ -273,7 +337,7 @@ For **uvx** setup (recommended), see [Cursor Quick Setup](#cursor-quick-setup) a } ``` -**Using local development (venv):** +**Using local development (venv, direct mode):** ```json { "mcpServers": { @@ -284,7 +348,7 @@ For **uvx** setup (recommended), see [Cursor Quick Setup](#cursor-quick-setup) a } ``` -**Using local development with Web UI (Optional):** +**Using local development with Web UI (Direct mode, optional):** ```json { "mcpServers": { @@ -298,70 +362,94 @@ For **uvx** setup (recommended), see [Cursor Quick Setup](#cursor-quick-setup) a #### Claude Code -**Using uvx (Recommended):** +Broker setup examples are listed first. + +**Using uvx in broker mode (Recommended):** + +```bash +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-spawn +``` +**Using uvx in broker mode with Web UI (Optional):** +```bash +claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --broker-spawn --web-ui --web-ui-config "$HOME/.mcpbridge_wrapper/webui.json" +``` + +**Using uvx in direct mode:** ```bash claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper ``` -**Using uvx with Web UI (Optional):** +**Using uvx in direct mode with Web UI (Optional):** ```bash claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080 ``` -**Using manual installation:** +**Using manual installation (Direct mode):** ```bash claude mcp add --transport stdio xcode -- ~/bin/xcodemcpwrapper ``` -**Using manual installation with Web UI (Optional):** +**Using manual installation with Web UI (Direct mode, optional):** Requires installing with `./scripts/install.sh --webui` (or equivalent `.[webui]` dependencies). ```bash claude mcp add --transport stdio xcode -- ~/bin/xcodemcpwrapper --web-ui --web-ui-port 8080 ``` -**Using local development (venv):** +**Using local development (venv, direct mode):** ```bash claude mcp add --transport stdio xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper ``` -**Using local development with Web UI (Optional):** +**Using local development with Web UI (Direct mode, optional):** ```bash claude mcp add --transport stdio xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper --web-ui --web-ui-port 8080 ``` #### Codex CLI -**Using uvx (Recommended):** +Broker setup examples are listed first. + +**Using uvx in broker mode (Recommended):** +```bash +codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-spawn +``` + +**Using uvx in broker mode with Web UI (Optional):** +```bash +codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --broker-spawn --web-ui --web-ui-config "$HOME/.mcpbridge_wrapper/webui.json" +``` + +**Using uvx in direct mode:** ```bash codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper ``` -**Using uvx with Web UI (Optional):** +**Using uvx in direct mode with Web UI (Optional):** ```bash codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080 ``` -**Using manual installation:** +**Using manual installation (Direct mode):** ```bash codex mcp add xcode -- ~/bin/xcodemcpwrapper ``` -**Using manual installation with Web UI (Optional):** +**Using manual installation with Web UI (Direct mode, optional):** Requires installing with `./scripts/install.sh --webui` (or equivalent `.[webui]` dependencies). ```bash codex mcp add xcode -- ~/bin/xcodemcpwrapper --web-ui --web-ui-port 8080 ``` -**Using local development (venv):** +**Using local development (venv, direct mode):** ```bash codex mcp add xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper ``` -**Using local development with Web UI (Optional):** +**Using local development with Web UI (Direct mode, optional):** ```bash codex mcp add xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper --web-ui --web-ui-port 8080 ``` diff --git a/SPECS/INPROGRESS/P1-T3_Validation_Report.md b/SPECS/INPROGRESS/P1-T3_Validation_Report.md new file mode 100644 index 00000000..eed243e2 --- /dev/null +++ b/SPECS/INPROGRESS/P1-T3_Validation_Report.md @@ -0,0 +1,46 @@ +# Validation Report — P1-T3: Improve MCP settings examples in README to present broker setup first + +**Date:** 2026-03-01 +**Verdict:** PASS + +## Scope + +Updated `README.md` configuration examples for Cursor, Claude Code, and Codex CLI so broker-mode setup is shown first, followed by direct/manual alternatives with consistent ordering and labels. + +## Deliverables + +- `README.md` configuration section updated to broker-first ordering for: + - Cursor + - Claude Code + - Codex CLI +- Consistent section pattern across all three agents: + - broker mode (recommended) + - broker mode with Web UI (optional) + - direct mode alternatives + +## Acceptance Criteria Check + +- [x] `README.md` presents broker setup before alternative/manual setup in MCP settings examples for Cursor, Claude Code, and Codex CLI +- [x] MCP example sections use consistent wording and ordering so users can follow the broker-first path without ambiguity + +## Commands Executed + +- `pytest` (baseline environment check) +- `ruff check src/` +- `mypy src/` +- `TMPHOME=$(mktemp -d); HOME="$TMPHOME" PYTHONPATH=src pytest -q` +- `TMPHOME=$(mktemp -d); HOME="$TMPHOME" PYTHONPATH=src pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` + +## Results + +- `pytest` (baseline): FAIL in local environment due live user broker socket (`~/.mcpbridge_wrapper/broker.sock`) affecting `tests/unit/test_broker_stubs.py::test_run_raises_timeout_when_no_socket`. +- `ruff check src/`: PASS (`All checks passed!`) +- `mypy src/`: PASS (`Success: no issues found in 18 source files`) +- Isolated full test run: PASS (`715 passed, 5 skipped, 2 warnings`) +- Coverage: PASS (`Total coverage: 91.72%`, threshold 90%) + +## Notes + +- The baseline pytest failure was environmental (existing broker daemon on the workstation), not caused by task changes. +- Running tests with a temporary isolated `HOME` path avoids contamination from live broker runtime files and matches expected test isolation. +- Two deprecation warnings from `websockets.legacy`/`websockets.server.WebSocketServerProtocol` are pre-existing and non-blocking for this documentation-only task. From 11a949a22f91b718b9573a3e3e50e72e8a3f81d1 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 1 Mar 2026 02:28:49 +0300 Subject: [PATCH 05/10] Archive task P1-T3: Improve MCP settings examples in README to present broker setup first (PASS) Co-Authored-By: Claude Sonnet 4.6 --- SPECS/ARCHIVE/INDEX.md | 3 ++- ...es_in_README_to_present_broker_setup_first.md | 4 ++++ .../P1-T3_Validation_Report.md | 0 SPECS/INPROGRESS/next.md | 16 ++-------------- SPECS/Workplan.md | 7 ++++--- 5 files changed, 12 insertions(+), 18 deletions(-) rename SPECS/{INPROGRESS => ARCHIVE/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first}/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first.md (98%) rename SPECS/{INPROGRESS => ARCHIVE/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first}/P1-T3_Validation_Report.md (100%) diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index 9a70ce8d..b1992948 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -1,11 +1,12 @@ # mcpbridge-wrapper Tasks Archive -**Last Updated:** 2026-02-28 (P1-T2) +**Last Updated:** 2026-03-01 (P1-T3) ## Archived Tasks | Task ID | Folder | Archived | Verdict | |---------|--------|----------|---------| +| P1-T3 | [P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first/](P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first/) | 2026-03-01 | PASS | | P1-T2 | [P1-T2_Add_Xcode_26_4_known_issue_release_notes_link_to_README/](P1-T2_Add_Xcode_26_4_known_issue_release_notes_link_to_README/) | 2026-02-28 | PASS | | P1-T1 | [P1-T1_Add_the_version_badge_in_the_README/](P1-T1_Add_the_version_badge_in_the_README/) | 2026-02-28 | PASS | | P15-T1 | [P15-T1_Validate_project_readiness_for_the_next_release/](P15-T1_Validate_project_readiness_for_the_next_release/) | 2026-02-28 | PASS | diff --git a/SPECS/INPROGRESS/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first.md b/SPECS/ARCHIVE/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first.md similarity index 98% rename from SPECS/INPROGRESS/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first.md rename to SPECS/ARCHIVE/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first.md index 663e139c..4d3b5926 100644 --- a/SPECS/INPROGRESS/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first.md +++ b/SPECS/ARCHIVE/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first.md @@ -63,3 +63,7 @@ Reorganize MCP configuration examples in `README.md` so broker-based setup is sh - Archive artifacts must include this PRD and the validation report. - REVIEW subject for this task: `p1_t3_broker_first_mcp_examples`. + +--- +**Archived:** 2026-03-01 +**Verdict:** PASS diff --git a/SPECS/INPROGRESS/P1-T3_Validation_Report.md b/SPECS/ARCHIVE/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first/P1-T3_Validation_Report.md similarity index 100% rename from SPECS/INPROGRESS/P1-T3_Validation_Report.md rename to SPECS/ARCHIVE/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first/P1-T3_Validation_Report.md diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index d0635881..9912f8b6 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,15 +1,3 @@ -# Next Task: P1-T3 — Improve MCP settings examples in README to present broker setup first +# Next Task: — (none selected) -**Priority:** P2 -**Phase:** Phase 1: Documentation -**Effort:** 1-2 hours -**Dependencies:** None -**Status:** Selected - -## Description - -Update `README.md` MCP configuration examples for different agents so broker-based setup appears first, making the recommended integration path clear and consistent. - -## Next Step - -Run the PLAN command to generate the implementation-ready PRD. +**Status:** Idle — P1-T3 archived. Select the next task from `SPECS/Workplan.md`. diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index 9b69051b..b10455a8 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -41,7 +41,8 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m - [x] `README.md` includes a link to `https://developer.apple.com/documentation/xcode-release-notes/xcode-26_4-release-notes` - [x] `README.md` mentions the Coding Intelligence known issue about repeated "Allow Connection?" dialogs and references issue ID `170721057` -#### ⬜️ P1-T3: Improve MCP settings examples in README to present broker setup first **INPROGRESS** +#### ✅ P1-T3: Improve MCP settings examples in README to present broker setup first +- **Status:** ✅ Completed (2026-03-01) - **Description:** Update `README.md` MCP configuration examples for different agents so broker-based setup appears first, making the recommended integration path clear and consistent. - **Priority:** P2 - **Dependencies:** none @@ -50,5 +51,5 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m - `README.md` MCP settings examples reordered/updated to show broker setup first for each supported agent - Example snippets validated for clarity and consistency across agent sections - **Acceptance Criteria:** - - [ ] `README.md` presents broker setup before alternative/manual setup in MCP settings examples for Cursor, Claude Code, and Codex CLI - - [ ] The MCP example sections use consistent wording and ordering so users can follow the broker-first path without ambiguity + - [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 From 78a34a7602bf8c612b2cc145fc98d3310e5b191f Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 1 Mar 2026 02:31:16 +0300 Subject: [PATCH 06/10] Review P1-T3: broker-first MCP settings examples Co-Authored-By: Claude Sonnet 4.6 --- SPECS/INPROGRESS/REVIEW_P1-T3.md | 37 ++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 SPECS/INPROGRESS/REVIEW_P1-T3.md diff --git a/SPECS/INPROGRESS/REVIEW_P1-T3.md b/SPECS/INPROGRESS/REVIEW_P1-T3.md new file mode 100644 index 00000000..cbab3177 --- /dev/null +++ b/SPECS/INPROGRESS/REVIEW_P1-T3.md @@ -0,0 +1,37 @@ +## REVIEW REPORT — P1-T3: Broker-first MCP settings examples in README + +**Scope:** origin/main..HEAD +**Files:** 1 (`README.md`) + 5 SPECS bookkeeping files + +### Summary Verdict +- [ ] Approve +- [x] Approve with comments +- [ ] Request changes +- [ ] Block + +### Critical Issues + +None. + +### Secondary Issues + +- [Low] The Cursor section opens with the prose line "Broker setup examples are listed first." — Claude Code and Codex CLI sections use the same phrasing. The repetition is mildly redundant if a reader scans the whole section, but it is not harmful and aids per-section orientation. No action required unless a future pass standardises the intro sentences across agent sections. + +- [Nit] The Cursor broker-mode JSON example hard-codes the literal `/Users/YOUR_USERNAME/` in the `--web-ui-config` path, while the Claude Code and Codex CLI bash variants use the portable `$HOME` variable. This inconsistency is harmless in JSON (environment variables aren't expanded in JSON strings), so the placeholder is the correct approach. Document as an acknowledged inconsistency. + +### Architectural Notes + +- The change is purely documentation. No Python source, tests, or configuration files were modified. +- Broker-first ordering is now consistent across Cursor (JSON), Claude Code (bash), and Codex CLI (bash) sections, satisfying the PRD's acceptance criteria. +- The `direct mode` label added to existing manual/venv headings correctly disambiguates them from the new broker entries without breaking existing content. + +### Tests + +- No unit or integration tests are affected — this is a documentation-only change. +- Quality gates (pytest, ruff, mypy) are not applicable; all pass trivially on a docs-only diff. +- Coverage remains ≥ 90% (unchanged). + +### Next Steps + +- No blocker or high-severity findings. FOLLOW-UP is **skipped**. +- Future consideration (not actionable now): unify the section intro phrasing into a shared heading style as part of a broader README style pass. From c9e8393cfc4a5719724580cf7285942bc81ead24 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 1 Mar 2026 02:31:38 +0300 Subject: [PATCH 07/10] Archive REVIEW_P1-T3 report Co-Authored-By: Claude Sonnet 4.6 --- .../REVIEW_P1-T3.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename SPECS/{INPROGRESS => ARCHIVE/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first}/REVIEW_P1-T3.md (100%) diff --git a/SPECS/INPROGRESS/REVIEW_P1-T3.md b/SPECS/ARCHIVE/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first/REVIEW_P1-T3.md similarity index 100% rename from SPECS/INPROGRESS/REVIEW_P1-T3.md rename to SPECS/ARCHIVE/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first/REVIEW_P1-T3.md From 178378aba2e1e080b53cfb2f054f196084e27f68 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 1 Mar 2026 02:34:24 +0300 Subject: [PATCH 08/10] Sync DocC XcodeMCPWrapper.md with broker-first MCP examples Co-Authored-By: Claude Sonnet 4.6 --- .../Documentation.docc/XcodeMCPWrapper.md | 106 ++++++++++++++++-- 1 file changed, 97 insertions(+), 9 deletions(-) diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md index b62ff08f..599ce221 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md @@ -195,9 +195,73 @@ To remove xcodemcpwrapper from your system: #### Cursor -For **uvx** setup (recommended), see **Cursor Quick Setup** above. +Broker setup examples are listed first. -**Using manual installation:** +**Using uvx in broker mode (Recommended):** + +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "uvx", + "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper", "--broker-spawn"] + } + } +} +``` + +**Using uvx in broker mode with Web UI (Optional):** +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "uvx", + "args": [ + "--from", + "mcpbridge-wrapper[webui]", + "mcpbridge-wrapper", + "--broker-spawn", + "--web-ui", + "--web-ui-config", + "/Users/YOUR_USERNAME/.mcpbridge_wrapper/webui.json" + ] + } + } +} +``` + +**Using uvx in direct mode:** +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "uvx", + "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"] + } + } +} +``` + +**Using uvx in direct mode with Web UI (Optional):** +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "uvx", + "args": [ + "--from", + "mcpbridge-wrapper[webui]", + "mcpbridge-wrapper", + "--web-ui", + "--web-ui-port", + "8080" + ] + } + } +} +``` + +**Using manual installation (Direct mode):** ```json { @@ -209,7 +273,7 @@ For **uvx** setup (recommended), see **Cursor Quick Setup** above. } ``` -**Using manual installation with Web UI (Optional):** +**Using manual installation with Web UI (Direct mode, optional):** > Requires installing with `./scripts/install.sh --webui` (or equivalent `.[webui]` dependencies). ```json { @@ -224,18 +288,30 @@ For **uvx** setup (recommended), see **Cursor Quick Setup** above. #### Claude Code -**Using uvx (Recommended):** +Broker setup examples are listed first. + +**Using uvx in broker mode (Recommended):** +```bash +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-spawn +``` + +**Using uvx in broker mode with Web UI (Optional):** +```bash +claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --broker-spawn --web-ui --web-ui-config "$HOME/.mcpbridge_wrapper/webui.json" +``` + +**Using uvx in direct mode:** ```bash claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper ``` -**Using uvx with Web UI (Optional):** +**Using uvx in direct mode with Web UI (Optional):** ```bash claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080 ``` -**Using manual installation:** +**Using manual installation (Direct mode):** ```bash claude mcp add --transport stdio xcode -- /Users/YOUR_USERNAME/bin/xcodemcpwrapper @@ -243,18 +319,30 @@ claude mcp add --transport stdio xcode -- /Users/YOUR_USERNAME/bin/xcodemcpwrapp #### Codex CLI -**Using uvx (Recommended):** +Broker setup examples are listed first. + +**Using uvx in broker mode (Recommended):** + +```bash +codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-spawn +``` + +**Using uvx in broker mode with Web UI (Optional):** +```bash +codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --broker-spawn --web-ui --web-ui-config "$HOME/.mcpbridge_wrapper/webui.json" +``` +**Using uvx in direct mode:** ```bash codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper ``` -**Using uvx with Web UI (Optional):** +**Using uvx in direct mode with Web UI (Optional):** ```bash codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080 ``` -**Using manual installation:** +**Using manual installation (Direct mode):** ```bash codex mcp add xcode -- /Users/YOUR_USERNAME/bin/xcodemcpwrapper From 90b33a0969c2fded4a0e1b5ef83d349d31e08b5c Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 1 Mar 2026 02:39:27 +0300 Subject: [PATCH 09/10] Add missing venv examples and sync DocC with README broker-first changes - Add local development (venv, direct mode) sections to DocC for Cursor, Claude Code, and Codex CLI to match README content - Add missing manual installation with Web UI sections to Claude Code and Codex CLI in DocC - Fix manual installation paths in DocC to use ~/bin/ (matching README) - Apply consistent direct-mode label to Zed agent venv headings in README Co-Authored-By: Claude Sonnet 4.6 --- README.md | 4 +- .../Documentation.docc/XcodeMCPWrapper.md | 59 ++++++++++++++++++- 2 files changed, 59 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index a1925c13..aa7b39dd 100644 --- a/README.md +++ b/README.md @@ -512,7 +512,7 @@ Requires installing with `./scripts/install.sh --webui` (or equivalent `.[webui] } ``` -**Using local development (venv):** +**Using local development (venv, direct mode):** ```json { "xcode-tools": { @@ -523,7 +523,7 @@ Requires installing with `./scripts/install.sh --webui` (or equivalent `.[webui] } ``` -**Using local development with Web UI (Optional):** +**Using local development with Web UI (Direct mode, optional):** ```json { "xcode-tools": { diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md index 599ce221..6ce521ec 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md @@ -286,6 +286,29 @@ Broker setup examples are listed first. } ``` +**Using local development (venv, direct mode):** +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper" + } + } +} +``` + +**Using local development with Web UI (Direct mode, optional):** +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper", + "args": ["--web-ui", "--web-ui-port", "8080"] + } + } +} +``` + #### Claude Code Broker setup examples are listed first. @@ -314,7 +337,23 @@ claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' **Using manual installation (Direct mode):** ```bash -claude mcp add --transport stdio xcode -- /Users/YOUR_USERNAME/bin/xcodemcpwrapper +claude mcp add --transport stdio xcode -- ~/bin/xcodemcpwrapper +``` + +**Using manual installation with Web UI (Direct mode, optional):** +Requires installing with `./scripts/install.sh --webui` (or equivalent `.[webui]` dependencies). +```bash +claude mcp add --transport stdio xcode -- ~/bin/xcodemcpwrapper --web-ui --web-ui-port 8080 +``` + +**Using local development (venv, direct mode):** +```bash +claude mcp add --transport stdio xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper +``` + +**Using local development with Web UI (Direct mode, optional):** +```bash +claude mcp add --transport stdio xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper --web-ui --web-ui-port 8080 ``` #### Codex CLI @@ -345,7 +384,23 @@ codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper - **Using manual installation (Direct mode):** ```bash -codex mcp add xcode -- /Users/YOUR_USERNAME/bin/xcodemcpwrapper +codex mcp add xcode -- ~/bin/xcodemcpwrapper +``` + +**Using manual installation with Web UI (Direct mode, optional):** +Requires installing with `./scripts/install.sh --webui` (or equivalent `.[webui]` dependencies). +```bash +codex mcp add xcode -- ~/bin/xcodemcpwrapper --web-ui --web-ui-port 8080 +``` + +**Using local development (venv, direct mode):** +```bash +codex mcp add xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper +``` + +**Using local development with Web UI (Direct mode, optional):** +```bash +codex mcp add xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper --web-ui --web-ui-port 8080 ``` ### 3. Enable Xcode Tools From 6ce7c65892a942ece60880afa87a35ac4b5a19b8 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 1 Mar 2026 02:47:22 +0300 Subject: [PATCH 10/10] Make Quick Start Cursor Quick Setup broker-first Add broker-spawn as the recommended (first) config in the Cursor Quick Setup section of README and DocC. Rename "Broker Mode (Optional)" to "Broker Mode" to match the promoted recommendation. Retain direct mode as a labelled alternative. Co-Authored-By: Claude Sonnet 4.6 --- README.md | 24 +++++++++++++++---- .../Documentation.docc/XcodeMCPWrapper.md | 24 +++++++++++++++---- 2 files changed, 40 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index aa7b39dd..184f54a4 100644 --- a/README.md +++ b/README.md @@ -51,12 +51,14 @@ Xcode's `mcpbridge` returns tool responses in the `content` field but omits the If you use **Cursor**, no installation is needed — just add this to `~/.cursor/mcp.json`: +**Broker mode (Recommended):** + ```json { "mcpServers": { "xcode-tools": { "command": "uvx", - "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"] + "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper", "--broker-spawn"] } } } @@ -73,15 +75,29 @@ With Web UI dashboard (optional — adds real-time monitoring at http://localhos "--from", "mcpbridge-wrapper[webui]", "mcpbridge-wrapper", + "--broker-spawn", "--web-ui", - "--web-ui-port", - "8080" + "--web-ui-config", + "/Users/YOUR_USERNAME/.mcpbridge_wrapper/webui.json" ] } } } ``` +**Direct mode (Alternative):** + +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "uvx", + "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"] + } + } +} +``` + If you upgrade and want to confirm the currently running dashboard process version: ```bash @@ -99,7 +115,7 @@ 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 Broker mode lets multiple short-lived MCP client sessions share one persistent upstream bridge session. diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md index 6ce521ec..4eb22fb7 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md @@ -46,12 +46,14 @@ This wrapper intercepts responses from `xcrun mcpbridge` and copies the data fro If you use **Cursor**, no installation is needed — just add this to `~/.cursor/mcp.json`: +**Broker mode (Recommended):** + ```json { "mcpServers": { "xcode-tools": { "command": "uvx", - "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"] + "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper", "--broker-spawn"] } } } @@ -68,15 +70,29 @@ With Web UI dashboard (optional — adds real-time monitoring at http://localhos "--from", "mcpbridge-wrapper[webui]", "mcpbridge-wrapper", + "--broker-spawn", "--web-ui", - "--web-ui-port", - "8080" + "--web-ui-config", + "/Users/YOUR_USERNAME/.mcpbridge_wrapper/webui.json" ] } } } ``` +**Direct mode (Alternative):** + +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "uvx", + "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"] + } + } +} +``` + If you upgrade and want to confirm the currently running dashboard process version: ```bash @@ -94,7 +110,7 @@ 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 Broker mode lets short-lived MCP sessions share one persistent upstream bridge.