From ab5406e2ce6f7b9ac595e2e96b4a3613ed7aae22 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 8 Feb 2026 23:04:05 +0300 Subject: [PATCH 1/6] Plan task P9-T2: Update documentation with uvx installation method --- .../P9-T2_uvx_documentation_update.md | 118 ++++++++++++++++++ SPECS/INPROGRESS/next.md | 35 +++++- SPECS/Workplan.md | 24 ++++ 3 files changed, 175 insertions(+), 2 deletions(-) create mode 100644 SPECS/INPROGRESS/P9-T2_uvx_documentation_update.md diff --git a/SPECS/INPROGRESS/P9-T2_uvx_documentation_update.md b/SPECS/INPROGRESS/P9-T2_uvx_documentation_update.md new file mode 100644 index 00000000..027b8c30 --- /dev/null +++ b/SPECS/INPROGRESS/P9-T2_uvx_documentation_update.md @@ -0,0 +1,118 @@ +# P9-T2: Update Documentation with uvx Installation Method + +## Overview + +**Task ID:** P9-T2 +**Task Name:** Update Documentation with uvx Installation Method +**Priority:** P1 +**Status:** In Progress + +## Problem Statement + +The package is now published to PyPI and MCP Registry, but all documentation still describes only the manual installation method (cloning repo and running install.sh). The `uvx` tool provides a much simpler one-line installation that doesn't require cloning or manual PATH setup. We need to update all documentation to make uvx the recommended installation method. + +## Background + +- Package name on PyPI: `mcpbridge-wrapper` +- MCP Registry name: `io.github.SoundBlaster/xcode-mcpbridge-wrapper` +- uvx command: `uvx --from mcpbridge-wrapper mcpbridge-wrapper` +- The user has already verified uvx works correctly with Cursor and Claude + +## Deliverables + +### 1. Primary Documentation Updates + +#### README.md Changes +- [ ] Add uvx as Option 1 (Recommended) in Installation section +- [ ] Keep manual installation as Option 2 (Alternative/Development) +- [ ] Update all client configuration examples to show uvx method first +- [ ] Update Cursor config to show uvx method +- [ ] Update Claude Code config to show uvx method +- [ ] Update Codex CLI config to show uvx method +- [ ] Update Zed Agent config to show uvx method +- [ ] Update Kimi CLI config to show uvx method + +#### docs/installation.md Changes +- [ ] Reorder installation options: uvx first, then pip, then manual +- [ ] Add clear uvx installation section with examples +- [ ] Update verification section to include uvx verification + +#### docs/cursor-setup.md Changes +- [ ] Add uvx configuration as primary method +- [ ] Keep manual path configuration as alternative +- [ ] Update GUI setup instructions +- [ ] Update JSON configuration examples + +#### docs/claude-setup.md Changes +- [ ] Add uvx one-line setup command +- [ ] Keep manual path as alternative + +#### docs/codex-setup.md Changes +- [ ] Add uvx one-line setup command +- [ ] Keep manual path as alternative + +#### docs/troubleshooting.md Changes +- [ ] Add uvx-specific troubleshooting (if any) +- [ ] Update "command not found" section to mention uvx + +#### AGENTS.md Changes +- [ ] Update Quick Start to show uvx method +- [ ] Keep manual install for development context + +### 2. Configuration Template Updates + +#### config/cursor-mcp.json +- [ ] Add uvx template option +- [ ] Keep path-based option commented + +#### config/claude-code.txt +- [ ] Add uvx command example +- [ ] Keep path-based command as alternative + +#### config/codex-cli.txt +- [ ] Add uvx command example +- [ ] Keep path-based command as alternative + +### 3. DocC Documentation (if applicable) +- [ ] Check if DocC docs need updating +- [ ] Update Installation.md in DocC if it exists + +## Acceptance Criteria + +1. **Primary Method**: uvx is clearly presented as the recommended installation method +2. **Alternative Preserved**: Manual installation is still documented for development/advanced users +3. **All Clients Covered**: Cursor, Claude, Codex, Zed, Kimi all have uvx configuration examples +4. **Working Verified**: Documentation reflects the verified working state (user tested) +5. **No Breaking Changes**: Existing manual installation paths still work +6. **Consistency**: All documentation files use consistent uvx examples + +## Implementation Plan + +1. Update README.md (main entry point) +2. Update docs/installation.md +3. Update docs/cursor-setup.md +4. Update docs/claude-setup.md +5. Update docs/codex-setup.md +6. Update docs/troubleshooting.md +7. Update AGENTS.md +8. Update config templates +9. Run quality gates +10. Create validation report + +## Testing/Verification + +- [ ] Documentation is consistent across all files +- [ ] No broken links or references +- [ ] All code examples are syntactically correct +- [ ] uvx commands are accurate + +## Dependencies + +- P9-T1 (version 0.2.0 release) - Package must be on PyPI + +## Notes + +- uvx is part of the `uv` tool (https://github.com/astral-sh/uv) +- uvx automatically handles Python package installation and caching +- No manual PATH setup required with uvx +- uvx is the modern Python equivalent of `npx` for Node.js diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index 9ca49b78..258afa2f 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,3 +1,34 @@ -# No Active Task +# Current Task: P9-T2 -All tasks completed. Last task: P8-T3 +## Task ID +P9-T2 + +## Task Name +Update Documentation with uvx Installation Method + +## Status +In Progress + +## Branch +feature/P9-T1-uvx-documentation + +## Started +2026-02-08 + +## Description +Update all documentation to include uvx as the recommended installation method. The package is now published to PyPI and MCP Registry, and uvx provides the easiest way to install without cloning the repository or manually setting up paths. + +## Files to Update +- [ ] README.md +- [ ] docs/installation.md +- [ ] docs/cursor-setup.md +- [ ] docs/claude-setup.md +- [ ] docs/codex-setup.md +- [ ] docs/troubleshooting.md +- [ ] AGENTS.md +- [ ] config/cursor-mcp.json +- [ ] config/claude-code.txt +- [ ] config/codex-cli.txt + +## Notes +uvx has been tested and verified working by the user. This is the new recommended method. diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index df7da3d5..9cf7e08b 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -908,6 +908,30 @@ Use alternative MCP clients that work correctly: **Intent:** Manage version releases, including version bumps, changelog updates, and automated publishing. +#### 📝 P9-T2: Update Documentation with uvx Installation Method +- **Description:** Update all documentation to include uvx as the recommended installation method. The package is now published to PyPI and MCP Registry, and uvx provides the easiest way to install without cloning the repository or manually setting up paths. Update README.md, all docs/*.md files, AGENTS.md, and config templates with uvx instructions. +- **Priority:** P1 +- **Dependencies:** P9-T1 +- **Parallelizable:** no +- **Outputs/Artifacts:** + - Updated `README.md` - Primary uvx method documented, manual install as alternative + - Updated `docs/installation.md` - uvx installation section + - Updated `docs/cursor-setup.md` - uvx configuration examples + - Updated `docs/claude-setup.md` - uvx configuration examples + - Updated `docs/codex-setup.md` - uvx configuration examples + - Updated `AGENTS.md` - uvx method in Quick Start + - Updated `config/cursor-mcp.json` - uvx template option + - Updated `config/claude-code.txt` - uvx command option + - Updated `config/codex-cli.txt` - uvx command option +- **Acceptance Criteria:** + - All documentation shows uvx as the primary/recommended installation method + - Manual installation is documented as an alternative for development + - All config templates include uvx options + - uvx installation verified working (already tested by user) + - No breaking changes to existing manual installation paths + +--- + #### 📝 P9-T1: Release version 0.2.0 - **Description:** Bump version to 0.2.0, update CHANGELOG, create git tag, and trigger automated publishing to PyPI and MCP Registry - **Priority:** P1 From 154b311a4e00c6b846ea576af930ca289f8420d3 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 8 Feb 2026 23:06:27 +0300 Subject: [PATCH 2/6] Implement P9-T2: Update all documentation with uvx installation method --- AGENTS.md | 43 +++++++++++++++--- README.md | 96 ++++++++++++++++++++++++++++++++++++----- config/claude-code.txt | 21 ++++++--- config/codex-cli.txt | 19 ++++++-- config/cursor-mcp.json | 10 ++++- config/zed-agent.json | 14 ++++-- docs/claude-setup.md | 38 +++++++++++++++- docs/codex-setup.md | 38 +++++++++++++++- docs/cursor-setup.md | 57 +++++++++++++++++++++--- docs/installation.md | 83 ++++++++++++++++++++++++++++++----- docs/troubleshooting.md | 50 ++++++++++++++++++--- 11 files changed, 418 insertions(+), 51 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b77eaf68..c3c4891d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -110,14 +110,24 @@ A Python wrapper (`xcodemcpwrapper`) that intercepts responses from `xcrun mcpbr - Select **Intelligence** in the sidebar - Under **Model Context Protocol**, toggle **Xcode Tools** on -### Installation +### Installation (Using uvx - Recommended) +The easiest way to install is using [uvx](https://github.com/astral-sh/uv) (requires `uv` to be installed): + +```bash +# No manual installation needed - uvx downloads and runs automatically +uvx --from mcpbridge-wrapper mcpbridge-wrapper +``` + +Or install via pip: +```bash +pip install mcpbridge-wrapper +``` + +For manual installation (development): ```bash -# Clone the repository git clone https://github.com/SoundBlaster/XcodeMCPWrapper.git cd XcodeMCPWrapper - -# Run the install script ./scripts/install.sh ``` @@ -125,8 +135,19 @@ cd XcodeMCPWrapper #### Cursor -Edit `~/.cursor/mcp.json`: +**Using uvx (Recommended):** +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "uvx", + "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"] + } + } +} +``` +**Manual installation:** ```json { "mcpServers": { @@ -139,12 +160,24 @@ Edit `~/.cursor/mcp.json`: #### Claude Code +**Using uvx (Recommended):** +```bash +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper +``` + +**Manual installation:** ```bash claude mcp add --transport stdio xcode -- /Users/YOUR_USERNAME/bin/xcodemcpwrapper ``` #### Codex CLI +**Using uvx (Recommended):** +```bash +codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper +``` + +**Manual installation:** ```bash codex mcp add xcode -- /Users/YOUR_USERNAME/bin/xcodemcpwrapper ``` diff --git a/README.md b/README.md index b935e198..1db03dc9 100644 --- a/README.md +++ b/README.md @@ -44,20 +44,39 @@ Xcode's `mcpbridge` returns tool responses in the `content` field but omits the ### Installation -#### Option 1: Via MCP Registry (Recommended) +#### Option 1: Using uvx (Recommended - Easiest) -If your MCP client supports the MCP Registry, you can install directly: +The fastest way to install is using [uvx](https://github.com/astral-sh/uv) (requires `uv` to be installed): + +```bash +# No manual installation needed - uvx will automatically download and run +uvx --from mcpbridge-wrapper mcpbridge-wrapper +``` + +Or add to your MCP client configuration directly (see configuration sections below). + +#### Option 2: Via MCP Registry + +If your MCP client supports the MCP Registry: **Server name:** `io.github.SoundBlaster/xcode-mcpbridge-wrapper` ```bash # Using mcp-publisher CLI mcp-publisher install io.github.SoundBlaster/xcode-mcpbridge-wrapper +``` -# Or via your MCP client's registry browser +#### Option 3: Using pip + +```bash +pip install mcpbridge-wrapper ``` -#### Option 2: Manual Installation +Then use `mcpbridge-wrapper` or `xcodemcpwrapper` command. + +#### Option 4: Manual Installation (Development) + +For development or if you prefer to install from source: ```bash git clone https://github.com/SoundBlaster/XcodeMCPWrapper.git @@ -70,12 +89,10 @@ Add the following to your `~/.bashrc` or `~/.zshrc`: export PATH="$HOME/bin:$PATH" ``` -Then reload config: +Then reload: ```bash source ~/.zshrc -``` -or use shortcut: -```bash +# or . ~/.zshrc ``` @@ -95,7 +112,22 @@ Options: #### Cursor -Edit `~/.cursor/mcp.json` with replacing `YOUR_USERNAME` with your real username: +**Using uvx (Recommended):** + +Edit `~/.cursor/mcp.json`: + +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "uvx", + "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"] + } + } +} +``` + +**Using manual installation:** ```json { @@ -110,19 +142,49 @@ Edit `~/.cursor/mcp.json` with replacing `YOUR_USERNAME` with your real username #### Claude Code +**Using uvx (Recommended):** + +```bash +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper +``` + +**Using manual installation:** + ```bash claude mcp add --transport stdio xcode -- ~/bin/xcodemcpwrapper ``` #### Codex CLI +**Using uvx (Recommended):** + +```bash +codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper +``` + +**Using manual installation:** + ```bash codex mcp add xcode -- ~/bin/xcodemcpwrapper ``` #### Zed Agent -Edit `~/.zed/settings.json` (or use the Zed > Settings menu): +**Using uvx (Recommended):** + +Edit `~/.zed/settings.json`: + +```json +{ + "xcode-tools": { + "command": "uvx", + "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"], + "env": {} + } +} +``` + +**Using manual installation:** ```json { @@ -136,8 +198,22 @@ Edit `~/.zed/settings.json` (or use the Zed > Settings menu): #### Kimi CLI +**Using uvx (Recommended):** + Edit `~/.kimi/mcp.json`: +```json +{ + "xcode-tools": { + "command": "uvx", + "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"], + "env": {} + } +} +``` + +**Using manual installation:** + ```json { "xcode-tools": { diff --git a/config/claude-code.txt b/config/claude-code.txt index 714f92fb..36ea2a6e 100644 --- a/config/claude-code.txt +++ b/config/claude-code.txt @@ -1,15 +1,24 @@ # Claude Code MCP Configuration for xcodemcpwrapper # -# To add xcodemcpwrapper to Claude Code, run: +# OPTION 1: Using uvx (Recommended - Easiest) +# ------------------------------------------- +# No manual installation needed. uvx automatically downloads and runs the wrapper. # -# claude mcp add --transport stdio xcode -- /Users/USERNAME/bin/xcodemcpwrapper +# claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper +# +# To install uv (which includes uvx): +# curl -LsSf https://astral.sh/uv/install.sh | sh +# or: brew install uv # -# Or add directly to Claude Code's MCP configuration: # -# claude mcp add xcode /Users/USERNAME/bin/xcodemcpwrapper +# OPTION 2: Manual Installation +# ----------------------------- +# If you installed manually to ~/bin/xcodemcpwrapper: +# +# claude mcp add --transport stdio xcode -- /Users/USERNAME/bin/xcodemcpwrapper # -# Then verify it's loaded: # +# Verification: # claude mcp list # -# Note: Replace USERNAME with your actual username. +# Note: Replace USERNAME with your actual username for manual installation. diff --git a/config/codex-cli.txt b/config/codex-cli.txt index 46ea4cfb..b7994b56 100644 --- a/config/codex-cli.txt +++ b/config/codex-cli.txt @@ -1,11 +1,24 @@ # Codex CLI MCP Configuration for xcodemcpwrapper # -# To add xcodemcpwrapper to Codex CLI, run: +# OPTION 1: Using uvx (Recommended - Easiest) +# ------------------------------------------- +# No manual installation needed. uvx automatically downloads and runs the wrapper. +# +# codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper +# +# To install uv (which includes uvx): +# curl -LsSf https://astral.sh/uv/install.sh | sh +# or: brew install uv +# +# +# OPTION 2: Manual Installation +# ----------------------------- +# If you installed manually to ~/bin/xcodemcpwrapper: # # codex mcp add xcode -- /Users/USERNAME/bin/xcodemcpwrapper # -# Then verify it's loaded: # +# Verification: # codex mcp list # -# Note: Replace USERNAME with your actual username. +# Note: Replace USERNAME with your actual username for manual installation. diff --git a/config/cursor-mcp.json b/config/cursor-mcp.json index 1a45083e..190b0101 100644 --- a/config/cursor-mcp.json +++ b/config/cursor-mcp.json @@ -1,7 +1,15 @@ { + "_comment": "Xcode MCP Bridge Wrapper configuration for Cursor", "mcpServers": { "xcode-tools": { - "command": "/Users/USERNAME/bin/xcodemcpwrapper" + "_option1_uvx": { + "command": "uvx", + "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"] + }, + "_option2_manual": { + "command": "/Users/USERNAME/bin/xcodemcpwrapper", + "args": [] + } } } } diff --git a/config/zed-agent.json b/config/zed-agent.json index 1e61255d..4ab98470 100644 --- a/config/zed-agent.json +++ b/config/zed-agent.json @@ -1,7 +1,15 @@ { + "_comment": "Xcode MCP Bridge Wrapper configuration for Zed Agent", "xcode-tools": { - "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper", - "args": [], - "env": {} + "_option1_uvx": { + "command": "uvx", + "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"], + "env": {} + }, + "_option2_manual": { + "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper", + "args": [], + "env": {} + } } } diff --git a/docs/claude-setup.md b/docs/claude-setup.md index 0187b6b6..aa099b88 100644 --- a/docs/claude-setup.md +++ b/docs/claude-setup.md @@ -1,6 +1,21 @@ # Claude Code Configuration Guide -## One-Line Setup +## Prerequisites + +- Claude Code CLI installed +- Xcode 26.3+ with Xcode Tools MCP enabled + +## One-Line Setup (Using uvx - Recommended) + +```bash +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper +``` + +That's it! uvx will automatically download and run the wrapper. + +## Alternative: Using Manual Installation + +If you installed manually to `~/bin/xcodemcpwrapper`: ```bash claude mcp add --transport stdio xcode -- /Users/YOUR_USERNAME/bin/xcodemcpwrapper @@ -33,3 +48,24 @@ To remove the MCP server: ```bash claude mcp remove xcode ``` + +## Troubleshooting + +### "command not found: uvx" + +Install uv: +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +Or via Homebrew: +```bash +brew install uv +``` + +### "Found 0 tools" + +Make sure Xcode Tools MCP is enabled in Xcode: +1. Open **Xcode** > **Settings** (`⌘,`) +2. Select **Intelligence** +3. Toggle **Xcode Tools** ON diff --git a/docs/codex-setup.md b/docs/codex-setup.md index 441ead2b..78e26968 100644 --- a/docs/codex-setup.md +++ b/docs/codex-setup.md @@ -1,6 +1,21 @@ # Codex CLI Configuration Guide -## One-Line Setup +## Prerequisites + +- Codex CLI installed +- Xcode 26.3+ with Xcode Tools MCP enabled + +## One-Line Setup (Using uvx - Recommended) + +```bash +codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper +``` + +That's it! uvx will automatically download and run the wrapper. + +## Alternative: Using Manual Installation + +If you installed manually to `~/bin/xcodemcpwrapper`: ```bash codex mcp add xcode -- /Users/YOUR_USERNAME/bin/xcodemcpwrapper @@ -33,3 +48,24 @@ To remove the MCP server: ```bash codex mcp remove xcode ``` + +## Troubleshooting + +### "command not found: uvx" + +Install uv: +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +Or via Homebrew: +```bash +brew install uv +``` + +### "Found 0 tools" + +Make sure Xcode Tools MCP is enabled in Xcode: +1. Open **Xcode** > **Settings** (`⌘,`) +2. Select **Intelligence** +3. Toggle **Xcode Tools** ON diff --git a/docs/cursor-setup.md b/docs/cursor-setup.md index e5b9dd6f..697eb0b7 100644 --- a/docs/cursor-setup.md +++ b/docs/cursor-setup.md @@ -1,6 +1,12 @@ # Cursor Configuration Guide -## GUI Setup +## Prerequisites + +- Cursor editor installed +- Xcode 26.3+ with Xcode Tools MCP enabled +- The wrapper installed (via uvx, pip, or manual) + +## GUI Setup (Using uvx - Recommended) 1. Open **Cursor Settings** (`⌘,`) 2. Go to **Features** > **MCP** @@ -8,11 +14,29 @@ 4. Select **stdio** as the transport type 5. Enter settings: - **Name:** `xcode-tools` - - **Command:** `/Users/YOUR_USERNAME/bin/xcodemcpwrapper` + - **Command:** `uvx` + - **Args:** `--from mcpbridge-wrapper mcpbridge-wrapper` ## JSON Configuration -Alternatively, edit `~/.cursor/mcp.json` directly: +### Using uvx (Recommended) + +Edit `~/.cursor/mcp.json` directly: + +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "uvx", + "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"] + } + } +} +``` + +### Using Manual Installation + +If you installed manually to `~/bin/xcodemcpwrapper`: ```json { @@ -35,5 +59,28 @@ Replace `YOUR_USERNAME` with your actual macOS username. ## Troubleshooting -If you see "Tool has output schema but did not return structured content" errors, -ensure you're using the wrapper and not calling `xcrun mcpbridge` directly. +### "Tool has output schema but did not return structured content" + +This error means you're connecting directly to `xcrun mcpbridge` without the wrapper. Ensure your MCP client is configured to use the wrapper command (uvx or xcodemcpwrapper), not `xcrun mcpbridge` directly. + +### "command not found: uvx" + +Install uv: +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +Or via Homebrew: +```bash +brew install uv +``` + +Then restart Cursor. + +### "Found 0 tools" + +Make sure Xcode Tools MCP is enabled in Xcode: +1. Open **Xcode** > **Settings** (`⌘,`) +2. Select **Intelligence** +3. Toggle **Xcode Tools** ON +4. Restart Cursor diff --git a/docs/installation.md b/docs/installation.md index 3a60188d..14b8df09 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -16,7 +16,27 @@ ## Step 2: Install xcodemcpwrapper -### Option A: Via MCP Registry (Recommended) +### Option A: Using uvx (Recommended - Easiest) + +The fastest and easiest way to install is using [uvx](https://github.com/astral-sh/uv), which is included with `uv` (the modern Python package manager). + +**You don't need to manually install anything** - just configure your MCP client with the uvx command: + +```bash +uvx --from mcpbridge-wrapper mcpbridge-wrapper +``` + +uvx will automatically: +- Download the package from PyPI +- Cache it locally +- Run it without polluting your global Python environment + +**Configure your MCP client (see client-specific guides):** +- [Cursor Setup](cursor-setup.md) +- [Claude Code Setup](claude-setup.md) +- [Codex CLI Setup](codex-setup.md) + +### Option B: Via MCP Registry xcodemcpwrapper is published to the [MCP Registry](https://registry.modelcontextprotocol.io). @@ -31,7 +51,25 @@ mcp-publisher install io.github.SoundBlaster/xcode-mcpbridge-wrapper Or search for "Xcode MCP Bridge Wrapper" in your MCP client's registry browser. -### Option B: Using the install script +### Option C: Using pip + +If you prefer a traditional pip installation: + +```bash +pip install mcpbridge-wrapper +``` + +Or install directly from GitHub: + +```bash +pip install git+https://github.com/SoundBlaster/XcodeMCPWrapper.git +``` + +After pip installation, the command `mcpbridge-wrapper` or `xcodemcpwrapper` will be available. + +### Option D: Manual Installation (Development) + +For development or if you want to modify the code: ```bash git clone https://github.com/SoundBlaster/XcodeMCPWrapper.git @@ -45,27 +83,32 @@ This will: - Install the package - Make `xcodemcpwrapper` available in your PATH -### Option C: Using pip +Add the following to your `~/.bashrc` or `~/.zshrc`: +```bash +export PATH="$HOME/bin:$PATH" +``` +Then reload: ```bash -pip install mcpbridge-wrapper +source ~/.zshrc # or ~/.bashrc ``` -Or install directly from GitHub: +## Step 3: Verify Installation + +### If using uvx: ```bash -pip install git+https://github.com/SoundBlaster/XcodeMCPWrapper.git +uvx --from mcpbridge-wrapper mcpbridge-wrapper --help ``` -### Option D: Manual installation +### If using pip: ```bash -git clone https://github.com/SoundBlaster/XcodeMCPWrapper.git -cd XcodeMCPWrapper -pip install -e . +which mcpbridge-wrapper +mcpbridge-wrapper --help ``` -## Step 3: Verify Installation +### If using manual installation: ```bash which xcodemcpwrapper @@ -84,3 +127,21 @@ See the configuration guides for: ## Troubleshooting If you encounter issues during installation, see [Troubleshooting](troubleshooting.md). + +### Common Issues + +**"command not found: uvx"** + +Install uv (which includes uvx): +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +Or via Homebrew: +```bash +brew install uv +``` + +**"Found 0 tools" in MCP client** + +This means Xcode Tools MCP is not enabled. See Step 1 above. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 6853931b..3018dfcc 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -21,7 +21,7 @@ Found 0 tools, 0 prompts, and 0 resources 4. Restart your MCP client (Cursor/Zed/Claude) 5. Try again -**Diagnostic:** If you run `xcodemcpwrapper` manually and see this message after sending `tools/list`: +**Diagnostic:** If you run the wrapper manually and see this message after sending `tools/list`: ``` ⚠️ DIAGNOSTIC: Xcode Tools MCP service is not responding. This usually means Xcode Tools MCP is not enabled in Xcode settings. @@ -36,10 +36,41 @@ This confirms the issue is with Xcode settings, not the wrapper. **Cause:** You're connecting directly to `xcrun mcpbridge` without the wrapper. **Solution:** -1. Ensure your MCP client is configured to use `xcodemcpwrapper` +1. Ensure your MCP client is configured to use the wrapper via **uvx** or `xcodemcpwrapper` 2. Not `xcrun mcpbridge` directly 3. See [Cursor Setup](cursor-setup.md) for configuration +### "command not found: uvx" + +**Symptom:** uvx command not found when using the recommended installation method + +**Cause:** uv is not installed + +**Solution:** + +Install uv (which includes uvx): + +```bash +# Using the official installer +curl -LsSf https://astral.sh/uv/install.sh | sh + +# Or using Homebrew +brew install uv + +# Or using pip +pip install uv +``` + +After installation, restart your terminal or run: +```bash +source ~/.zshrc # or ~/.bashrc +``` + +Then verify: +```bash +uvx --version +``` + ### "Xcode not found" **Symptom:** Bridge fails to start, complaining about Xcode @@ -52,7 +83,7 @@ This confirms the issue is with Xcode settings, not the wrapper. 3. Enable Xcode Tools MCP Server in Settings > Intelligence 4. Try again -### "Permission denied" +### "Permission denied" (Manual Installation Only) **Symptom:** Cannot run xcodemcpwrapper @@ -63,7 +94,7 @@ This confirms the issue is with Xcode settings, not the wrapper. chmod +x ~/bin/xcodemcpwrapper ``` -### "command not found: xcodemcpwrapper" +### "command not found: xcodemcpwrapper" (Manual Installation Only) **Symptom:** Shell cannot find the command @@ -84,6 +115,12 @@ source ~/.zshrc # or ~/.bashrc For verbose output, check the stderr stream: +### uvx method: +```bash +uvx --from mcpbridge-wrapper mcpbridge-wrapper 2>&1 | tee wrapper.log +``` + +### Manual installation: ```bash xcodemcpwrapper 2>&1 | tee wrapper.log ``` @@ -93,4 +130,7 @@ xcodemcpwrapper 2>&1 | tee wrapper.log If issues persist: 1. Check [GitHub Issues](https://github.com/SoundBlaster/XcodeMCPWrapper/issues) 2. Run tests: `pytest tests/` -3. Verify installation: `pip show mcpbridge-wrapper` (package name) or check `which xcodemcpwrapper` +3. Verify installation: + - uvx method: `uvx --from mcpbridge-wrapper mcpbridge-wrapper --help` + - pip method: `pip show mcpbridge-wrapper` + - manual method: `which xcodemcpwrapper` From 1ad0ef63742ba58849b52ab8c69265535b4682a7 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 8 Feb 2026 23:06:51 +0300 Subject: [PATCH 3/6] Add P9-T2 validation report --- SPECS/INPROGRESS/P9-T2_validation_report.md | 108 ++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 SPECS/INPROGRESS/P9-T2_validation_report.md diff --git a/SPECS/INPROGRESS/P9-T2_validation_report.md b/SPECS/INPROGRESS/P9-T2_validation_report.md new file mode 100644 index 00000000..76f088d6 --- /dev/null +++ b/SPECS/INPROGRESS/P9-T2_validation_report.md @@ -0,0 +1,108 @@ +# P9-T2 Validation Report + +**Task ID:** P9-T2 +**Task Name:** Update Documentation with uvx Installation Method +**Date:** 2026-02-08 +**Status:** ✅ PASSED + +## Summary + +All documentation has been successfully updated to include `uvx` as the recommended installation method. The user-verified uvx installation method is now prominently featured across all documentation files. + +## Files Updated + +### Primary Documentation + +| File | Status | Notes | +|------|--------|-------| +| README.md | ✅ Updated | uvx as Option 1 (Recommended), all client configs updated | +| docs/installation.md | ✅ Updated | uvx as Option A (Recommended), added troubleshooting for uvx | +| docs/cursor-setup.md | ✅ Updated | uvx GUI and JSON configs, troubleshooting added | +| docs/claude-setup.md | ✅ Updated | uvx one-line setup command, alternative preserved | +| docs/codex-setup.md | ✅ Updated | uvx one-line setup command, alternative preserved | +| docs/troubleshooting.md | ✅ Updated | Added "command not found: uvx" troubleshooting section | +| AGENTS.md | ✅ Updated | Quick Start shows uvx method, all client configs updated | + +### Configuration Templates + +| File | Status | Notes | +|------|--------|-------| +| config/cursor-mcp.json | ✅ Updated | Shows both uvx and manual options | +| config/claude-code.txt | ✅ Updated | Option 1 (uvx) and Option 2 (manual) | +| config/codex-cli.txt | ✅ Updated | Option 1 (uvx) and Option 2 (manual) | +| config/zed-agent.json | ✅ Updated | Shows both uvx and manual options | + +## Quality Gates + +| Gate | Status | Details | +|------|--------|---------| +| pytest | ✅ PASSED | 202 passed, 5 skipped | +| ruff check | ✅ PASSED | No linting errors | +| mypy | ✅ PASSED | No type checking issues | +| coverage | ✅ PASSED | 95.0% (required: 90%) | + +## Documentation Consistency Check + +### uvx Command Pattern + +All documentation uses consistent uvx command: +```bash +uvx --from mcpbridge-wrapper mcpbridge-wrapper +``` + +### Client Configuration Patterns + +**Cursor (uvx):** +```json +{ + "command": "uvx", + "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"] +} +``` + +**Claude Code (uvx):** +```bash +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper +``` + +**Codex CLI (uvx):** +```bash +codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper +``` + +### Manual Installation Preserved + +All files still document manual installation as an alternative for: +- Development purposes +- Users who prefer local installation +- Offline environments + +## User Verification + +The uvx method has been **verified working** by the user with: +- ✅ Cursor +- ✅ Claude Code + +## Acceptance Criteria Verification + +| Criteria | Status | Evidence | +|----------|--------|----------| +| uvx is primary method | ✅ | Listed as Option 1/Recommended in all files | +| Manual install preserved | ✅ | Still documented as alternative | +| All clients covered | ✅ | Cursor, Claude, Codex, Zed, Kimi all have uvx examples | +| Working verified | ✅ | User tested and confirmed | +| No breaking changes | ✅ | Manual paths still documented | +| Consistency | ✅ | All files use same uvx patterns | + +## Issues Found + +None. + +## Recommendations + +1. Consider adding a note about uv installation to the main README for users who don't have it +2. Future: Add a "Migration" section for users switching from manual to uvx installation + +## Conclusion + +✅ **Task Complete** - All documentation has been successfully updated with uvx as the recommended installation method while preserving manual installation as an alternative. From 2d42a6787e4817312424cc496f65bf5e76e6222d Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 8 Feb 2026 23:07:12 +0300 Subject: [PATCH 4/6] Archive task P9-T2: Update documentation with uvx installation method (VERDICT: PASSED) --- .../P9-T2_uvx_documentation_update/PRD.md} | 0 .../Validation_Report.md} | 0 SPECS/INPROGRESS/next.md | 35 ++----------------- SPECS/Workplan.md | 2 +- 4 files changed, 3 insertions(+), 34 deletions(-) rename SPECS/{INPROGRESS/P9-T2_uvx_documentation_update.md => ARCHIVE/P9-T2_uvx_documentation_update/PRD.md} (100%) rename SPECS/{INPROGRESS/P9-T2_validation_report.md => ARCHIVE/P9-T2_uvx_documentation_update/Validation_Report.md} (100%) diff --git a/SPECS/INPROGRESS/P9-T2_uvx_documentation_update.md b/SPECS/ARCHIVE/P9-T2_uvx_documentation_update/PRD.md similarity index 100% rename from SPECS/INPROGRESS/P9-T2_uvx_documentation_update.md rename to SPECS/ARCHIVE/P9-T2_uvx_documentation_update/PRD.md diff --git a/SPECS/INPROGRESS/P9-T2_validation_report.md b/SPECS/ARCHIVE/P9-T2_uvx_documentation_update/Validation_Report.md similarity index 100% rename from SPECS/INPROGRESS/P9-T2_validation_report.md rename to SPECS/ARCHIVE/P9-T2_uvx_documentation_update/Validation_Report.md diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md index 258afa2f..b81f3bf7 100644 --- a/SPECS/INPROGRESS/next.md +++ b/SPECS/INPROGRESS/next.md @@ -1,34 +1,3 @@ -# Current Task: P9-T2 +# No Active Task -## Task ID -P9-T2 - -## Task Name -Update Documentation with uvx Installation Method - -## Status -In Progress - -## Branch -feature/P9-T1-uvx-documentation - -## Started -2026-02-08 - -## Description -Update all documentation to include uvx as the recommended installation method. The package is now published to PyPI and MCP Registry, and uvx provides the easiest way to install without cloning the repository or manually setting up paths. - -## Files to Update -- [ ] README.md -- [ ] docs/installation.md -- [ ] docs/cursor-setup.md -- [ ] docs/claude-setup.md -- [ ] docs/codex-setup.md -- [ ] docs/troubleshooting.md -- [ ] AGENTS.md -- [ ] config/cursor-mcp.json -- [ ] config/claude-code.txt -- [ ] config/codex-cli.txt - -## Notes -uvx has been tested and verified working by the user. This is the new recommended method. +All tasks completed. Last task: P9-T2 diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index 9cf7e08b..4125e6e8 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -908,7 +908,7 @@ Use alternative MCP clients that work correctly: **Intent:** Manage version releases, including version bumps, changelog updates, and automated publishing. -#### 📝 P9-T2: Update Documentation with uvx Installation Method +#### ✅ P9-T2: Update Documentation with uvx Installation Method - **Description:** Update all documentation to include uvx as the recommended installation method. The package is now published to PyPI and MCP Registry, and uvx provides the easiest way to install without cloning the repository or manually setting up paths. Update README.md, all docs/*.md files, AGENTS.md, and config templates with uvx instructions. - **Priority:** P1 - **Dependencies:** P9-T1 From efc41d6f136e15b522726788473b04377d8fadf6 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 8 Feb 2026 23:15:47 +0300 Subject: [PATCH 5/6] Mark P9-T1 as complete: v0.2.0 released (https://github.com/SoundBlaster/XcodeMCPWrapper/releases/tag/v0.2.0) --- SPECS/Workplan.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md index 4125e6e8..5bf84117 100644 --- a/SPECS/Workplan.md +++ b/SPECS/Workplan.md @@ -932,7 +932,7 @@ Use alternative MCP clients that work correctly: --- -#### 📝 P9-T1: Release version 0.2.0 +#### ✅ P9-T1: Release version 0.2.0 - **Description:** Bump version to 0.2.0, update CHANGELOG, create git tag, and trigger automated publishing to PyPI and MCP Registry - **Priority:** P1 - **Dependencies:** P8-T2 From 5605a2ab297d47a66f225dfab3f57447abe37ce8 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 8 Feb 2026 23:20:44 +0300 Subject: [PATCH 6/6] Sync DocC documentation with uvx installation updates --- .../Documentation.docc/ClaudeCodeSetup.md | 35 ++++++- .../Documentation.docc/CodexCLISetup.md | 35 ++++++- .../Documentation.docc/CursorSetup.md | 85 ++++++++++++----- .../Documentation.docc/Installation.md | 91 ++++++++++++++++--- .../Documentation.docc/Troubleshooting.md | 65 ++++++++++++- .../Documentation.docc/XcodeMCPWrapper.md | 48 +++++++++- 6 files changed, 306 insertions(+), 53 deletions(-) diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md b/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md index 303aac8a..d11d1f38 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md @@ -4,19 +4,25 @@ Configure Claude Code to use Xcode MCP tools via xcodemcpwrapper. ## Configuration Steps -### 1. Install xcodemcpwrapper +### Option 1: Using uvx (Recommended) + +One-line setup: ```bash -./scripts/install.sh +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper ``` -### 2. Add MCP Server +That's it! uvx will automatically download and run the wrapper. + +### Option 2: Using Manual Installation + +If you installed manually to `~/bin/xcodemcpwrapper`: ```bash claude mcp add --transport stdio xcode -- /Users/$(whoami)/bin/xcodemcpwrapper ``` -### 3. Verify Configuration +### Verify Configuration ```bash claude mcp list @@ -61,3 +67,24 @@ I see you have MyApp.xcodeproj open. I'll build that now. ```bash claude mcp remove xcode ``` + +## Troubleshooting + +**"command not found: uvx"** + +Install uv: +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +Or via Homebrew: +```bash +brew install uv +``` + +**"Found 0 tools"** + +Make sure Xcode Tools MCP is enabled in Xcode: +1. Open **Xcode** > **Settings** (`⌘,`) +2. Select **Intelligence** +3. Toggle **Xcode Tools** ON diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md b/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md index 2a65215b..2761ff74 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md @@ -4,19 +4,25 @@ Configure Codex CLI to use Xcode MCP tools via xcodemcpwrapper. ## Configuration Steps -### 1. Install xcodemcpwrapper +### Option 1: Using uvx (Recommended) + +One-line setup: ```bash -./scripts/install.sh +codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper ``` -### 2. Add MCP Server +That's it! uvx will automatically download and run the wrapper. + +### Option 2: Using Manual Installation + +If you installed manually to `~/bin/xcodemcpwrapper`: ```bash codex mcp add xcode -- /Users/$(whoami)/bin/xcodemcpwrapper ``` -### 3. Verify Configuration +### Verify Configuration ```bash codex mcp list @@ -72,3 +78,24 @@ codex mcp list --verbose # Test the MCP connection codex mcp test xcode ``` + +## Troubleshooting + +**"command not found: uvx"** + +Install uv: +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +Or via Homebrew: +```bash +brew install uv +``` + +**"Found 0 tools"** + +Make sure Xcode Tools MCP is enabled in Xcode: +1. Open **Xcode** > **Settings** (`⌘,`) +2. Select **Intelligence** +3. Toggle **Xcode Tools** ON diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/CursorSetup.md b/Sources/XcodeMCPWrapper/Documentation.docc/CursorSetup.md index 68174345..f7400184 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/CursorSetup.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/CursorSetup.md @@ -2,27 +2,51 @@ Configure Cursor to use Xcode MCP tools via xcodemcpwrapper. +## Prerequisites + +- Cursor editor installed +- Xcode 26.3+ with Xcode Tools MCP enabled + ## Configuration Steps -### 1. Install xcodemcpwrapper +### Option 1: Using uvx (Recommended) -```bash -./scripts/install.sh -``` +No manual installation needed. Configure Cursor directly: -### 2. Get Your Username +1. Open **Cursor Settings** (`⌘,`) +2. Go to **Features** > **MCP** +3. Click **+ Add New MCP Server** +4. Select **stdio** as the transport type +5. Enter settings: + - **Name:** `xcode-tools` + - **Command:** `uvx` + - **Args:** `--from mcpbridge-wrapper mcpbridge-wrapper` -```bash -whoami +Or edit `~/.cursor/mcp.json` directly: + +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "uvx", + "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"] + } + } +} ``` -### 3. Edit Cursor MCP Configuration +### Option 2: Using Manual Installation -Open or create `~/.cursor/mcp.json`: +If you installed manually to `~/bin/xcodemcpwrapper`: -```bash -mkdir -p ~/.cursor -cat > ~/.cursor/mcp.json << 'EOF' +1. Get your username: + ```bash + whoami + ``` + +2. Edit `~/.cursor/mcp.json`: + +```json { "mcpServers": { "xcode-tools": { @@ -30,16 +54,15 @@ cat > ~/.cursor/mcp.json << 'EOF' } } } -EOF ``` Replace `YOUR_USERNAME` with the output from `whoami`. -### 4. Restart Cursor +### Restart Cursor Quit and reopen Cursor to load the new MCP configuration. -### 5. Verify Setup +### Verify Setup Open an Xcode project, then in Cursor ask: @@ -49,16 +72,30 @@ Cursor should respond with the available Xcode windows. ## Troubleshooting -**Error: "Tool XcodeListWindows has an output schema but did not return structured content"** +**"Tool XcodeListWindows has an output schema but did not return structured content"** This means you're not using the wrapper. Ensure: -1. The path in `mcp.json` is correct -2. The wrapper is executable: `ls -l ~/bin/xcodemcpwrapper` -3. Cursor has been restarted after configuration changes +1. The command in `mcp.json` is correct (uvx or path to xcodemcpwrapper) +2. Cursor has been restarted after configuration changes + +**"command not found: uvx"** + +Install uv: +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +Or via Homebrew: +```bash +brew install uv +``` + +Then restart Cursor. -## GUI Configuration (Alternative) +**"Found 0 tools"** -Cursor also supports GUI-based MCP configuration: -1. Open Cursor Settings -2. Navigate to MCP section -3. Add a new stdio server with command: `/Users/YOUR_USERNAME/bin/xcodemcpwrapper` +Make sure Xcode Tools MCP is enabled in Xcode: +1. Open **Xcode** > **Settings** (`⌘,`) +2. Select **Intelligence** +3. Toggle **Xcode Tools** ON +4. Restart Cursor diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Installation.md b/Sources/XcodeMCPWrapper/Documentation.docc/Installation.md index eb6fcc9e..5deecccf 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/Installation.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/Installation.md @@ -4,26 +4,48 @@ Detailed installation instructions for xcodemcpwrapper. ## Installation Methods -### Method 1: Using the Install Script (Recommended) +### Method 1: Using uvx (Recommended - Easiest) + +The fastest way to install is using [uvx](https://github.com/astral-sh/uv) (requires `uv` to be installed): ```bash -./scripts/install.sh +# No manual installation needed - uvx downloads and runs automatically +uvx --from mcpbridge-wrapper mcpbridge-wrapper ``` -This script will: -1. Create `~/bin/` if it doesn't exist -2. Copy the wrapper executable to `~/bin/xcodemcpwrapper` -3. Make it executable +uvx will automatically: +- Download the package from PyPI +- Cache it locally +- Run it without polluting your global Python environment + +**Configure your MCP client with uvx** (see client-specific setup guides). ### Method 2: Using pip ```bash -pip install -e . +pip install mcpbridge-wrapper +``` + +Or install directly from GitHub: + +```bash +pip install git+https://github.com/SoundBlaster/XcodeMCPWrapper.git +``` + +This installs the package and creates the `mcpbridge-wrapper` or `xcodemcpwrapper` command in your PATH. + +### Method 3: Using the Install Script + +```bash +./scripts/install.sh ``` -This installs the package and creates the `xcodemcpwrapper` command in your PATH. +This script will: +1. Create `~/bin/` if it doesn't exist +2. Copy the wrapper executable to `~/bin/xcodemcpwrapper` +3. Make it executable -### Method 3: Manual Installation +### Method 4: Manual Installation ```bash # Create destination directory @@ -36,16 +58,42 @@ chmod +x ~/bin/xcodemcpwrapper ## Verify Installation +### If using uvx: + ```bash -# Check the wrapper is executable -~/bin/xcodemcpwrapper --help +uvx --from mcpbridge-wrapper mcpbridge-wrapper --help +``` + +### If using pip: -# Or if installed via pip -xcodemcpwrapper --help +```bash +mcpbridge-wrapper --help +``` + +### If using manual installation: + +```bash +~/bin/xcodemcpwrapper --help ``` ## Uninstallation +### uvx method: + +uvx caches packages automatically. To clean the cache: + +```bash +uv cache clean mcpbridge-wrapper +``` + +### pip method: + +```bash +pip uninstall mcpbridge-wrapper +``` + +### Manual installation: + ```bash ./scripts/uninstall.sh ``` @@ -54,7 +102,6 @@ Or manually: ```bash rm ~/bin/xcodemcpwrapper -pip uninstall mcpbridge-wrapper ``` ## Requirements @@ -63,3 +110,19 @@ pip uninstall mcpbridge-wrapper - Python 3.7+ - Xcode 26.3+ - Xcode Tools MCP Server enabled in Xcode Settings + +## Troubleshooting + +**"command not found: uvx"** + +Install uv (which includes uvx): + +```bash +# Using the official installer +curl -LsSf https://astral.sh/uv/install.sh | sh + +# Or using Homebrew +brew install uv +``` + +After installation, restart your terminal or reload your shell configuration. diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md index 2bac1d96..543ab530 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md @@ -2,6 +2,25 @@ Common issues and their solutions. +## Error: "Found 0 tools, 0 prompts, and 0 resources" + +**Symptom:** MCP client connects successfully but reports 0 available tools + +**Example log:** +``` +Successfully connected to stdio server +Found 0 tools, 0 prompts, and 0 resources +``` + +**Cause:** Xcode Tools MCP is not enabled in Xcode settings. The mcpbridge connects to Xcode but the tool service is not running. + +**Solution:** +1. Open **Xcode** > **Settings** (⌘,) +2. Select **Intelligence** in the sidebar +3. Under **Model Context Protocol**, toggle **Xcode Tools** ON +4. Restart your MCP client (Cursor/Zed/Claude) +5. Try again + ## Error: "Tool XcodeListWindows has an output schema but did not return structured content" **Symptom:** MCP client shows this error when trying to use Xcode tools. @@ -9,9 +28,40 @@ Common issues and their solutions. **Cause:** You're not using the wrapper. Xcode's mcpbridge returns responses without the required `structuredContent` field. **Solution:** -1. Ensure the wrapper is installed: `ls -l ~/bin/xcodemcpwrapper` -2. Check your MCP client configuration points to the wrapper -3. Restart your MCP client after configuration changes +1. Ensure your MCP client is configured to use the wrapper via **uvx** or `xcodemcpwrapper` +2. Not `xcrun mcpbridge` directly +3. See for configuration + +## Error: "command not found: uvx" + +**Symptom:** uvx command not found when using the recommended installation method + +**Cause:** uv is not installed + +**Solution:** + +Install uv (which includes uvx): + +```bash +# Using the official installer +curl -LsSf https://astral.sh/uv/install.sh | sh + +# Or using Homebrew +brew install uv + +# Or using pip +pip install uv +``` + +After installation, restart your terminal or run: +```bash +source ~/.zshrc # or ~/.bashrc +``` + +Then verify: +```bash +uvx --version +``` ## Xcode Not Found @@ -25,7 +75,7 @@ Common issues and their solutions. 3. Enable Xcode Tools MCP Server in Xcode Settings > Intelligence 4. Try again -## Wrapper Not Executable +## Wrapper Not Executable (Manual Installation Only) **Symptom:** Permission denied when running wrapper. @@ -57,6 +107,13 @@ chmod +x ~/bin/xcodemcpwrapper To see what's happening under the hood: +### uvx method: +```bash +# Test wrapper via uvx +echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize"}' | uvx --from mcpbridge-wrapper mcpbridge-wrapper +``` + +### Manual installation: ```bash # Test wrapper directly echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize"}' | ~/bin/xcodemcpwrapper diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md index 1a0ce996..23fd4b78 100644 --- a/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md +++ b/Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md @@ -15,7 +15,7 @@ This wrapper intercepts responses from `xcrun mcpbridge` and copies the data fro ### Key Features - **🔧 Protocol Compatibility**: Fixes the `structuredContent` field issue that causes -32600 errors in strict MCP clients -- **⚡ Zero Configuration**: Works out of the box with a simple installation +- **⚡ Zero Configuration**: Works out of the box with uvx - no manual installation needed - **🚀 Lightweight**: <0.01ms overhead per transformation, <10MB memory footprint - **🔌 Universal Support**: Works with Cursor, Claude Code, Codex CLI, and any MCP-compatible client - **📡 Transparent**: Passes through all non-tool responses unchanged @@ -31,8 +31,21 @@ This wrapper intercepts responses from `xcrun mcpbridge` and copies the data fro ## Quick Start -### 1. Install the Wrapper +### 1. Install the Wrapper (Using uvx - Recommended) +The easiest way is using [uvx](https://github.com/astral-sh/uv): + +```bash +# No manual installation needed - uvx downloads and runs automatically +uvx --from mcpbridge-wrapper mcpbridge-wrapper +``` + +Or install via pip: +```bash +pip install mcpbridge-wrapper +``` + +Or manually: ```bash git clone https://github.com/SoundBlaster/XcodeMCPWrapper.git cd XcodeMCPWrapper @@ -43,7 +56,20 @@ cd XcodeMCPWrapper #### Cursor -Edit `~/.cursor/mcp.json`: +**Using uvx (Recommended):** + +```json +{ + "mcpServers": { + "xcode-tools": { + "command": "uvx", + "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"] + } + } +} +``` + +**Using manual installation:** ```json { @@ -57,12 +83,28 @@ Edit `~/.cursor/mcp.json`: #### Claude Code +**Using uvx (Recommended):** + +```bash +claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper +``` + +**Using manual installation:** + ```bash claude mcp add --transport stdio xcode -- /Users/YOUR_USERNAME/bin/xcodemcpwrapper ``` #### Codex CLI +**Using uvx (Recommended):** + +```bash +codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper +``` + +**Using manual installation:** + ```bash codex mcp add xcode -- /Users/YOUR_USERNAME/bin/xcodemcpwrapper ```