P1-T3: Improve MCP settings examples in README to present broker setup first

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.
@@ -245,9 +261,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 +340,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 +353,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 +364,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 +378,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
 ```
@@ -424,7 +528,7 @@ Requires installing with `./scripts/install.sh --webui` (or equivalent `.[webui]
 }
 ```
 
-**Using local development (venv):**
+**Using local development (venv, direct mode):**
 ```json
 {
   "xcode-tools": {
@@ -435,7 +539,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": {

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 |

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

@@ -0,0 +1,69 @@
+# 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`.
+
+---
+**Archived:** 2026-03-01
+**Verdict:** PASS