diff --git a/README.md b/README.md index 9791b274..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. @@ -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": { 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/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 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 new file mode 100644 index 00000000..4d3b5926 --- /dev/null +++ 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 @@ -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 diff --git a/SPECS/ARCHIVE/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first/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 new file mode 100644 index 00000000..eed243e2 --- /dev/null +++ b/SPECS/ARCHIVE/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first/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. diff --git a/SPECS/ARCHIVE/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first/REVIEW_P1-T3.md b/SPECS/ARCHIVE/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first/REVIEW_P1-T3.md new file mode 100644 index 00000000..cbab3177 --- /dev/null +++ b/SPECS/ARCHIVE/P1-T3_Improve_MCP_settings_examples_in_README_to_present_broker_setup_first/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. diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index c588e56a..9912f8b6 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,12 +1,3 @@ -# No Active Task +# Next Task: — (none selected) -## Recently Archived - -- **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) - -## Suggested Next Tasks - -- **None** — All tasks completed (2/2) +**Status:** Idle — P1-T3 archived. Select the next task from `SPECS/Workplan.md`. diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index ee1f6c53..b10455a8 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -40,3 +40,16 @@ 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 +- **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 +- **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:** + - [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 diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md index b62ff08f..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. @@ -195,9 +211,73 @@ To remove xcodemcpwrapper from your system: #### Cursor -For **uvx** setup (recommended), see **Cursor Quick Setup** above. +Broker setup examples are listed first. + +**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 manual installation:** +**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 +289,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 { @@ -222,42 +302,121 @@ For **uvx** setup (recommended), see **Cursor Quick Setup** above. } ``` +**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 -**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 (Direct mode, optional):** +Requires installing with `./scripts/install.sh --webui` (or equivalent `.[webui]` dependencies). ```bash -claude mcp add --transport stdio xcode -- /Users/YOUR_USERNAME/bin/xcodemcpwrapper +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 -**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 (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 -- /Users/YOUR_USERNAME/bin/xcodemcpwrapper +codex mcp add xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper --web-ui --web-ui-port 8080 ``` ### 3. Enable Xcode Tools