diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md index 6ffb40da..db203c88 100644 --- a/SPECS/ARCHIVE/INDEX.md +++ b/SPECS/ARCHIVE/INDEX.md @@ -1,11 +1,12 @@ # mcpbridge-wrapper Tasks Archive -**Last Updated:** 2026-03-01 (P2-T6 archived) +**Last Updated:** 2026-03-01 (P1-T8 archived) ## Archived Tasks | Task ID | Folder | Archived | Verdict | |---------|--------|----------|---------| +| P1-T8 | [P1-T8_Update_config_examples_for_broker_setup_first/](P1-T8_Update_config_examples_for_broker_setup_first/) | 2026-03-01 | PASS | | P2-T6 | [P2-T6_Remove_legacy_broker_connect_and_broker_spawn_flags/](P2-T6_Remove_legacy_broker_connect_and_broker_spawn_flags/) | 2026-03-01 | PASS | | P1-T7 | [P1-T7_Hide_README_version_badge_maintenance_note/](P1-T7_Hide_README_version_badge_maintenance_note/) | 2026-03-01 | PASS | | P1-T4 | [P1-T4_Update_docs_broker_robustness/](P1-T4_Update_docs_broker_robustness/) | 2026-03-01 | PASS | @@ -180,6 +181,7 @@ | File | Description | |------|-------------| +| [REVIEW_p1_t8_config_broker_setup_first.md](_Historical/REVIEW_p1_t8_config_broker_setup_first.md) | Review report for P1-T8 | | [REVIEW_P2-T5_webui_mismatch_warning.md](_Historical/REVIEW_P2-T5_webui_mismatch_warning.md) | Review report for P2-T5 | | [REVIEW_P2-T4_broker_unavailable_error.md](_Historical/REVIEW_P2-T4_broker_unavailable_error.md) | Review report for P2-T4 | | [REVIEW_P2-T3_spawn_lock.md](_Historical/REVIEW_P2-T3_spawn_lock.md) | Review report for P2-T3 | @@ -305,6 +307,8 @@ | Date | Task ID | Action | |------|---------|--------| +| 2026-03-01 | P1-T8 | Archived REVIEW_p1_t8_config_broker_setup_first report | +| 2026-03-01 | P1-T8 | Archived Update /config examples for broker setup first (PASS) | | 2026-03-01 | P2-T6 | Archived REVIEW_p2_t6_remove_legacy_broker_flags report | | 2026-03-01 | P2-T6 | Archived Remove legacy --broker-connect and --broker-spawn flags (PASS) | | 2026-03-01 | P1-T7 | Archived REVIEW_P1-T7_readme_badge_note report | diff --git a/SPECS/ARCHIVE/P1-T8_Update_config_examples_for_broker_setup_first/P1-T8_Update_config_examples_for_broker_setup_first.md b/SPECS/ARCHIVE/P1-T8_Update_config_examples_for_broker_setup_first/P1-T8_Update_config_examples_for_broker_setup_first.md new file mode 100644 index 00000000..b346d8f8 --- /dev/null +++ b/SPECS/ARCHIVE/P1-T8_Update_config_examples_for_broker_setup_first/P1-T8_Update_config_examples_for_broker_setup_first.md @@ -0,0 +1,65 @@ +# PRD: P1-T8 — Update /config examples for broker setup first + +## Overview + +`README.md` already presents broker setup first, but several standalone templates in +`config/` still lead with non-broker examples. This task aligns those templates +with current guidance by presenting broker-mode setup first for supported MCP +clients. + +## Problem Statement + +Users often copy from `config/` files directly. When non-broker examples appear +first, the docs and templates send mixed signals about the preferred setup path. +With `--broker` now the primary mode, templates should reflect that ordering. + +## Scope + +In scope: +- Reorder options in `config/cursor-mcp.json` and `config/zed-agent.json` so a + broker-mode configuration is listed first. +- Update `config/claude-code.txt` and `config/codex-cli.txt` so broker setup + commands are shown before non-broker alternatives. +- Keep command syntax compatible with current `--broker` guidance. + +Out of scope: +- Runtime behavior changes in Python source code. +- Changes to broker-specific template files that already lead with broker mode. + +## Deliverables + +| File(s) | Change | +|---|---| +| `config/cursor-mcp.json` | Broker option block moved to first position and labeled as recommended | +| `config/zed-agent.json` | Broker option block moved to first position and labeled as recommended | +| `config/claude-code.txt` | Broker command block added as first option | +| `config/codex-cli.txt` | Broker command block added as first option | + +## Acceptance Criteria + +- [ ] `config/cursor-mcp.json` presents a broker-mode option first in `xcode-tools` options. +- [ ] `config/zed-agent.json` presents a broker-mode option first in `xcode-tools` options. +- [ ] `config/claude-code.txt` lists a broker setup command before non-broker options. +- [ ] `config/codex-cli.txt` lists a broker setup command before non-broker options. +- [ ] Full quality gates pass: `pytest`, `ruff check src/`, `mypy src/`, `pytest --cov` (>= 90%). + +## Validation Plan + +1. Inspect option ordering in each updated config template. +2. Run `pytest`. +3. Run `ruff check src/`. +4. Run `mypy src/`. +5. Run `pytest --cov` and confirm coverage remains >= 90%. + +## Dependencies + +- P2-T6 + +## Risks + +Low. This is a documentation/template ordering change and does not alter runtime +logic. + +--- +**Archived:** 2026-03-01 +**Verdict:** PASS diff --git a/SPECS/ARCHIVE/P1-T8_Update_config_examples_for_broker_setup_first/P1-T8_Validation_Report.md b/SPECS/ARCHIVE/P1-T8_Update_config_examples_for_broker_setup_first/P1-T8_Validation_Report.md new file mode 100644 index 00000000..69d49dd5 --- /dev/null +++ b/SPECS/ARCHIVE/P1-T8_Update_config_examples_for_broker_setup_first/P1-T8_Validation_Report.md @@ -0,0 +1,54 @@ +# Validation Report: P1-T8 — Update /config examples for broker setup first + +**Date:** 2026-03-01 +**Verdict:** PASS + +## Summary + +Updated client configuration templates under `config/` so broker-mode setup appears first for Cursor, Zed, Claude Code, and Codex CLI examples. + +## Delivered Changes + +- `config/cursor-mcp.json` + - Added broker-first option blocks (`_option1_uvx_broker`, `_option1b_uvx_broker_web_ui`). + - Shifted non-broker options to `_option2*` and below. +- `config/zed-agent.json` + - Added broker-first option blocks (`_option1_uvx_broker`, `_option1b_uvx_broker_web_ui`). + - Shifted non-broker options to `_option2*` and below. +- `config/claude-code.txt` + - Added broker-mode command as `OPTION 1` and broker + Web UI as `OPTION 1B`. + - Moved non-broker alternatives to `OPTION 2` and below. +- `config/codex-cli.txt` + - Added broker-mode command as `OPTION 1` and broker + Web UI as `OPTION 1B`. + - Moved non-broker alternatives to `OPTION 2` and below. + +## Acceptance Criteria Check + +- [x] `config/cursor-mcp.json` presents a broker-mode option first in `xcode-tools` options. +- [x] `config/zed-agent.json` presents a broker-mode option first in `xcode-tools` options. +- [x] `config/claude-code.txt` lists a broker setup command before non-broker options. +- [x] `config/codex-cli.txt` lists a broker setup command before non-broker options. +- [x] Full quality gates pass: `pytest`, `ruff check src/`, `mypy src/`, `pytest --cov` (>= 90%). + +## Quality Gates + +1. `pytest` +- Result: PASS +- Evidence: `735 passed, 5 skipped` + +2. `ruff check src/` +- Result: PASS +- Evidence: `All checks passed!` + +3. `mypy src/` +- Result: PASS +- Evidence: `Success: no issues found in 18 source files` + +4. `pytest --cov` +- Result: PASS +- Evidence: `Required test coverage of 90.0% reached. Total coverage: 91.26%` + +## Notes + +- Initial `pytest` run failed due to environment import setup (`ModuleNotFoundError: mcpbridge_wrapper`). +- Resolved by installing the package in editable mode with `python3 -m pip install -e .`, then re-running quality gates successfully. diff --git a/SPECS/ARCHIVE/_Historical/REVIEW_p1_t8_config_broker_setup_first.md b/SPECS/ARCHIVE/_Historical/REVIEW_p1_t8_config_broker_setup_first.md new file mode 100644 index 00000000..da4e03e9 --- /dev/null +++ b/SPECS/ARCHIVE/_Historical/REVIEW_p1_t8_config_broker_setup_first.md @@ -0,0 +1,31 @@ +## REVIEW REPORT — P1-T8 Config Broker Setup First + +**Scope:** `origin/main..HEAD` +**Files:** 9 + +### Summary Verdict +- [x] Approve +- [ ] Approve with comments +- [ ] Request changes +- [ ] Block + +### Critical Issues +- None. + +### Secondary Issues +- None. + +### Architectural Notes +- Config templates now align with broker-first guidance already reflected in README/docs, reducing mismatch between direct template copy paths and documented recommendations. +- JSON template option ordering is explicit and keeps non-broker alternatives available for users that still need per-session mode. + +### Tests +- Quality gates were run and passed: + - `pytest` → `735 passed, 5 skipped` + - `ruff check src/` → pass + - `mypy src/` → pass + - `pytest --cov` → `91.26%` (>= 90%) + +### Next Steps +- No actionable follow-up items from this review. +- FOLLOW-UP step is skipped per FLOW rules. diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index a8c42db6..6d9a0541 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,9 +1,10 @@ # No Active Task -**Status:** Idle — P2-T6 archived. Select the next task from `SPECS/Workplan.md`. +**Status:** Idle — P1-T8 archived. Select the next task from `SPECS/Workplan.md`. ## Recently Archived +- **P1-T8** — Update /config examples for broker setup first (2026-03-01, PASS) - **P2-T6** — Remove legacy --broker-connect and --broker-spawn flags (2026-03-01, PASS) - **P1-T7** — Hide README version badge maintenance note (2026-03-01, PASS) - **P1-T4** — Update docs to reflect broker robustness improvements (2026-03-01, PASS) diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index ed639b7c..b269a953 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -112,6 +112,20 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m - [x] `README.md` no longer contains the exact string `Version badge maintenance: run make badge-version (or make badge-version-check in CI).` - [x] Version badge remains visible and functional after removing the maintenance note +#### ✅ P1-T8: Update /config examples for broker setup first +- **Status:** ✅ Completed (2026-03-01) +- **Description:** Update MCP client templates under `config/` so broker-mode setup is presented first and consistently framed as the recommended path. +- **Priority:** P1 +- **Dependencies:** P2-T6 +- **Parallelizable:** yes +- **Outputs/Artifacts:** + - `config/cursor-mcp.json` and `config/zed-agent.json` reordered to show broker-mode options before non-broker alternatives + - `config/claude-code.txt` and `config/codex-cli.txt` updated so broker commands appear before non-broker commands +- **Acceptance Criteria:** + - [x] Cursor and Zed config templates present a broker-mode option first + - [x] Claude Code and Codex CLI config templates present a broker command first + - [x] Broker-first guidance is consistent with existing `*-broker` templates and `--broker` usage + ### Phase 2: Broker Robustness #### ✅ P2-T1: Replace --broker-spawn/--broker-connect with single --broker flag diff --git a/config/claude-code.txt b/config/claude-code.txt index b793cce2..4f496687 100644 --- a/config/claude-code.txt +++ b/config/claude-code.txt @@ -1,14 +1,25 @@ # Claude Code MCP Configuration for xcodemcpwrapper # -# OPTION 1: Using uvx (Recommended - Easiest) -# ------------------------------------------- -# No manual installation needed. uvx automatically downloads and runs the wrapper. +# OPTION 1: Using uvx with broker mode (Recommended) +# --------------------------------------------------- +# Shares a single broker daemon across MCP clients and auto-starts it if needed. +# +# claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker +# +# OPTION 1B: Using uvx with broker mode + Web UI (Optional) +# ---------------------------------------------------------- +# Enable broker mode and host the dashboard on port 8080: +# +# claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --broker --web-ui --web-ui-port 8080 +# +# OPTION 2: Using uvx (Non-broker Alternative) +# --------------------------------------------- +# Starts an independent wrapper process per client session. # # claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper # -# OPTION 1B: Using uvx with Web UI (Optional) -# ------------------------------------------- -# Enable the Web UI dashboard on port 8080: +# OPTION 2B: Using uvx with Web UI (Non-broker, Optional) +# -------------------------------------------------------- # # claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080 # @@ -17,26 +28,26 @@ # or: brew install uv # # -# OPTION 2: Manual Installation +# OPTION 3: Manual Installation # ----------------------------- # If you installed manually to ~/bin/xcodemcpwrapper: # # claude mcp add --transport stdio xcode -- /Users/USERNAME/bin/xcodemcpwrapper # -# OPTION 2B: Manual Installation with Web UI (Optional) +# OPTION 3B: Manual Installation with Web UI (Optional) # ----------------------------------------------------- # Enable the Web UI dashboard on port 8080: # # claude mcp add --transport stdio xcode -- /Users/USERNAME/bin/xcodemcpwrapper --web-ui --web-ui-port 8080 # # -# OPTION 3: Local Development (from cloned repo with venv) +# OPTION 4: Local Development (from cloned repo with venv) # -------------------------------------------------------- # If you cloned the repo and installed via `make install` in a virtual environment: # # claude mcp add --transport stdio xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper # -# OPTION 3B: Local Development with Web UI (Optional) +# OPTION 4B: Local Development with Web UI (Optional) # ---------------------------------------------------- # Enable the Web UI dashboard on port 8080: # @@ -48,5 +59,5 @@ # Verification: # claude mcp list # -# Note: Replace USERNAME with your actual username for option 2. -# Note: Replace /path/to/XcodeMCPWrapper with your repo path for option 3. +# Note: Replace USERNAME with your actual username for option 3. +# Note: Replace /path/to/XcodeMCPWrapper with your repo path for option 4. diff --git a/config/codex-cli.txt b/config/codex-cli.txt index cff5cfa4..062747ea 100644 --- a/config/codex-cli.txt +++ b/config/codex-cli.txt @@ -1,14 +1,25 @@ # Codex CLI MCP Configuration for xcodemcpwrapper # -# OPTION 1: Using uvx (Recommended - Easiest) -# ------------------------------------------- -# No manual installation needed. uvx automatically downloads and runs the wrapper. +# OPTION 1: Using uvx with broker mode (Recommended) +# --------------------------------------------------- +# Shares a single broker daemon across MCP clients and auto-starts it if needed. +# +# codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker +# +# OPTION 1B: Using uvx with broker mode + Web UI (Optional) +# ---------------------------------------------------------- +# Enable broker mode and host the dashboard on port 8080: +# +# codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --broker --web-ui --web-ui-port 8080 +# +# OPTION 2: Using uvx (Non-broker Alternative) +# --------------------------------------------- +# Starts an independent wrapper process per client session. # # codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper # -# OPTION 1B: Using uvx with Web UI (Optional) -# ------------------------------------------- -# Enable the Web UI dashboard on port 8080: +# OPTION 2B: Using uvx with Web UI (Non-broker, Optional) +# -------------------------------------------------------- # # codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080 # @@ -17,26 +28,26 @@ # or: brew install uv # # -# OPTION 2: Manual Installation +# OPTION 3: Manual Installation # ----------------------------- # If you installed manually to ~/bin/xcodemcpwrapper: # # codex mcp add xcode -- /Users/USERNAME/bin/xcodemcpwrapper # -# OPTION 2B: Manual Installation with Web UI (Optional) +# OPTION 3B: Manual Installation with Web UI (Optional) # ----------------------------------------------------- # Enable the Web UI dashboard on port 8080: # # codex mcp add xcode -- /Users/USERNAME/bin/xcodemcpwrapper --web-ui --web-ui-port 8080 # # -# OPTION 3: Local Development (from cloned repo with venv) +# OPTION 4: Local Development (from cloned repo with venv) # -------------------------------------------------------- # If you cloned the repo and installed via `make install` in a virtual environment: # # codex mcp add xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper # -# OPTION 3B: Local Development with Web UI (Optional) +# OPTION 4B: Local Development with Web UI (Optional) # ---------------------------------------------------- # Enable the Web UI dashboard on port 8080: # @@ -48,5 +59,5 @@ # Verification: # codex mcp list # -# Note: Replace USERNAME with your actual username for option 2. -# Note: Replace /path/to/XcodeMCPWrapper with your repo path for option 3. +# Note: Replace USERNAME with your actual username for option 3. +# Note: Replace /path/to/XcodeMCPWrapper with your repo path for option 4. diff --git a/config/cursor-mcp.json b/config/cursor-mcp.json index e9be83cc..11794dd8 100644 --- a/config/cursor-mcp.json +++ b/config/cursor-mcp.json @@ -1,12 +1,34 @@ { "_comment": "Xcode MCP Bridge Wrapper configuration for Cursor", + "_note": "Broker-first template. Copy ONE option block into your real xcode-tools server entry.", "mcpServers": { "xcode-tools": { - "_option1_uvx": { + "_option1_uvx_broker": { + "command": "uvx", + "args": [ + "--from", + "mcpbridge-wrapper", + "mcpbridge-wrapper", + "--broker" + ] + }, + "_option1b_uvx_broker_web_ui": { + "command": "uvx", + "args": [ + "--from", + "mcpbridge-wrapper[webui]", + "mcpbridge-wrapper", + "--broker", + "--web-ui", + "--web-ui-port", + "8080" + ] + }, + "_option2_uvx": { "command": "uvx", "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"] }, - "_option1b_uvx_web_ui": { + "_option2b_uvx_web_ui": { "command": "uvx", "args": [ "--from", @@ -17,19 +39,19 @@ "8080" ] }, - "_option2_manual": { + "_option3_manual": { "command": "/Users/USERNAME/bin/xcodemcpwrapper", "args": [] }, - "_option2b_manual_web_ui": { + "_option3b_manual_web_ui": { "command": "/Users/USERNAME/bin/xcodemcpwrapper", "args": ["--web-ui", "--web-ui-port", "8080"] }, - "_option3_local_dev": { + "_option4_local_dev": { "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper", "args": [] }, - "_option3b_local_dev_web_ui": { + "_option4b_local_dev_web_ui": { "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper", "args": ["--web-ui", "--web-ui-port", "8080"] } diff --git a/config/zed-agent.json b/config/zed-agent.json index 195d9fe0..af7f37cc 100644 --- a/config/zed-agent.json +++ b/config/zed-agent.json @@ -1,12 +1,31 @@ { "_comment": "Xcode MCP Bridge Wrapper configuration for Zed Agent", + "_note": "Broker-first template. Copy ONE option block into your real xcode-tools entry.", "xcode-tools": { - "_option1_uvx": { + "_option1_uvx_broker": { + "command": "uvx", + "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper", "--broker"], + "env": {} + }, + "_option1b_uvx_broker_web_ui": { + "command": "uvx", + "args": [ + "--from", + "mcpbridge-wrapper[webui]", + "mcpbridge-wrapper", + "--broker", + "--web-ui", + "--web-ui-port", + "8080" + ], + "env": {} + }, + "_option2_uvx": { "command": "uvx", "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"], "env": {} }, - "_option1b_uvx_web_ui": { + "_option2b_uvx_web_ui": { "command": "uvx", "args": [ "--from", @@ -18,22 +37,22 @@ ], "env": {} }, - "_option2_manual": { + "_option3_manual": { "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper", "args": [], "env": {} }, - "_option2b_manual_web_ui": { + "_option3b_manual_web_ui": { "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper", "args": ["--web-ui", "--web-ui-port", "8080"], "env": {} }, - "_option3_local_dev": { + "_option4_local_dev": { "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper", "args": [], "env": {} }, - "_option3b_local_dev_web_ui": { + "_option4b_local_dev_web_ui": { "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper", "args": ["--web-ui", "--web-ui-port", "8080"], "env": {}