mcpbridge-wrapper 0.3.3
Python wrapper for xcrun mcpbridge that adds structuredContent to MCP responses
License: MIT
Requires Python: >=3.7
Keywords: mcp, xcode, cursor, mcpbridge, wrapper

# XcodeMCPWrapper - mcpbridge-wrapper

<!-- mcp-name: io.github.SoundBlaster/xcode-mcpbridge-wrapper -->

[![Python 3.7+](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Coverage](https://img.shields.io/badge/coverage-98%25-brightgreen.svg)](./SPECS/ARCHIVE/P5-T14_Code_Coverage/)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.SoundBlaster%2Fxcode--mcpbridge--wrapper-blue)](https://registry.modelcontextprotocol.io)

A Python wrapper that makes Xcode 26.3's MCP bridge compatible with Cursor and other strict MCP-spec-compliant clients.

## The Problem

Xcode's `mcpbridge` returns tool responses in the `content` field but omits the required `structuredContent` field when a tool declares an `outputSchema`. According to the MCP specification, when `outputSchema` is declared, responses **must** include `structuredContent`.

- ✅ Claude Code and Codex CLI work (they have special handling for Apple's responses)
- ❌ Cursor strictly follows the spec and rejects non-compliant responses

## The Solution

`mcpbridge-wrapper` intercepts responses from `xcrun mcpbridge` and copies the data from `content` into `structuredContent`, making Xcode's MCP tools fully compatible with all MCP clients.

```
┌─────────────┐    MCP Protocol    ┌──────────────────┐   MCP Protocol   ┌────────────┐    XPC    ┌─────────┐
│   Cursor    │ ◄────────────────► │ mcpbridge-wrapper│ ◄──────────────► │ mcpbridge  │ ◄───────► │  Xcode  │
│ (MCP Client)│                    │  (This Project)  │                  │  (Bridge)  │           │  (IDE)  │
└─────────────┘                    └──────────────────┘                  └────────────┘           └─────────┘
```

## Quick Start

### Prerequisites

- macOS with Xcode 26.3+
- Python 3.7+
- **Xcode Tools MCP Server enabled** (see below)

> ⚠️ **Important:** You MUST enable Xcode Tools MCP in Xcode settings:
> 1. Open **Xcode** > **Settings** (⌘,)
> 2. Select **Intelligence** in the sidebar
> 3. Under **Model Context Protocol**, toggle **Xcode Tools** ON
>
> If you see "Found 0 tools" in your MCP client logs, this setting is not enabled.

### Cursor Quick Setup

If you use **Cursor**, no installation is needed — just add this to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "xcode-tools": {
      "command": "uvx",
      "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"]
    }
  }
}
```

With Web UI dashboard (optional — adds real-time monitoring at http://localhost:8080):

```json
{
  "mcpServers": {
    "xcode-tools": {
      "command": "uvx",
      "args": [
        "--from",
        "mcpbridge-wrapper[webui]",
        "mcpbridge-wrapper",
        "--web-ui",
        "--web-ui-port",
        "8080"
      ]
    }
  }
}
```

Restart Cursor and you're done. For other clients or installation methods, read on.

### Python Environment Setup (Development)

If you plan to run `make install`, `pytest`, or other development commands, create and activate a virtual environment first. This avoids Homebrew Python's `externally-managed-environment` (PEP 668) error.

```bash
cd XcodeMCPWrapper
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
make install
```

Quick checks:

```bash
which python3
which pip
```

Both should point to `.venv/bin/...` while the environment is active.

### Installation

#### Option 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
# 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
```

#### Option 3: Using pip

```bash
python3 -m pip install mcpbridge-wrapper
```

Then use `mcpbridge-wrapper` or `xcodemcpwrapper` command.

#### Option 4: Manual Installation (via install script)

```bash
git clone https://github.com/SoundBlaster/XcodeMCPWrapper.git
cd XcodeMCPWrapper
./scripts/install.sh
```

The install script creates a virtual environment, installs the package, and places a wrapper at `~/bin/xcodemcpwrapper`.

If you plan to use `--web-ui` MCP args, install Web UI extras explicitly:

```bash
./scripts/install.sh --webui
```

Add the following to your `~/.bashrc` or `~/.zshrc`:
```bash
export PATH="$HOME/bin:$PATH"
```

Then reload:
```bash
source ~/.zshrc
# or
. ~/.zshrc
```

#### Option 5: Local Development (venv)

For development or if you want to run directly from the cloned repository:

```bash
git clone https://github.com/SoundBlaster/XcodeMCPWrapper.git
cd XcodeMCPWrapper
python3 -m venv .venv
source .venv/bin/activate
make install          # or: make install-webui (for Web UI support)
```

The entry point is `.venv/bin/mcpbridge-wrapper`. Use the **full absolute path** when configuring MCP clients (see configuration sections below).

### Uninstallation

To remove xcodemcpwrapper from your system:

```bash
./scripts/uninstall.sh
```

Options:
- `--dry-run` or `-n`: Show what would be removed without removing
- `--yes` or `-y`: Skip confirmation prompt

### Configuration

#### Cursor

For **uvx** setup (recommended), see [Cursor Quick Setup](#cursor-quick-setup) above.

**Using manual installation:**

```json
{
  "mcpServers": {
    "xcode-tools": {
      "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
      "args": []
    }
  }
}
```

**Using manual installation with Web UI (Optional):**
> Requires installing with `./scripts/install.sh --webui` (or equivalent `.[webui]` dependencies).
```json
{
  "mcpServers": {
    "xcode-tools": {
      "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
      "args": ["--web-ui", "--web-ui-port", "8080"]
    }
  }
}
```

**Using local development (venv):**
```json
{
  "mcpServers": {
    "xcode-tools": {
      "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper"
    }
  }
}
```

**Using local development with Web UI (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):**

```bash
claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper
```

**Using uvx 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:**

```bash
claude mcp add --transport stdio xcode -- ~/bin/xcodemcpwrapper
```

**Using manual installation with Web UI (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):**
```bash
claude mcp add --transport stdio xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper
```

**Using local development with Web UI (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):**

```bash
codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper
```

**Using uvx 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:**

```bash
codex mcp add xcode -- ~/bin/xcodemcpwrapper
```

**Using manual installation with Web UI (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):**
```bash
codex mcp add xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper
```

**Using local development with Web UI (Optional):**
```bash
codex mcp add xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper --web-ui --web-ui-port 8080
```

#### Zed Agent

**Using uvx (Recommended):**

Edit `~/.zed/settings.json`:

```json
{
  "xcode-tools": {
    "command": "uvx",
    "args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"],
    "env": {}
  }
}
```

**Using uvx with Web UI (Optional):**
```json
{
  "xcode-tools": {
    "command": "uvx",
    "args": [
      "--from",
      "mcpbridge-wrapper[webui]",
      "mcpbridge-wrapper",
      "--web-ui",
      "--web-ui-port",
      "8080"
    ],
    "env": {}
  }
}
```

**Using manual installation:**

```json
{
  "xcode-tools": {
    "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
    "args": [],
    "env": {}
  }
}
```

**Using manual installation with Web UI (Optional):**
Requires installing with `./scripts/install.sh --webui` (or equivalent `.[webui]` dependencies).
```json
{
  "xcode-tools": {
    "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
    "args": ["--web-ui", "--web-ui-port", "8080"],
    "env": {}
  }
}
```

**Using local development (venv):**
```json
{
  "xcode-tools": {
    "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper",
    "args": [],
    "env": {}
  }
}
```

**Using local development with Web UI (Optional):**
```json
{
  "xcode-tools": {
    "command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper",
    "args": ["--web-ui", "--web-ui-port", "8080"],
    "env": {}
  }
}
```

#### 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": {
    "command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
    "args": [],
    "env": {}
  }
}
```

## Usage

Once configured, ask your AI assistant to use Xcode tools:

```
"Build my project"
"Run the tests"
"Find all Swift files in the project"
"Show me the build errors"
```

## Web UI Dashboard (Optional)

The wrapper includes an optional Web UI dashboard for real-time monitoring and audit logging:

```bash
# Start with Web UI
make webui

# Or directly
python -m mcpbridge_wrapper --web-ui --web-ui-port 8080
```

Features:
- **Real-time metrics**: RPS, latency percentiles (p50, p95, p99), error rates
- **Tool usage analytics**: Visual charts of most frequently used tools
- **Audit logging**: Persistent log of all MCP tool calls with export (JSON/CSV)
- **Request inspector**: Live log stream with filtering

Open http://localhost:8080 in your browser to view the dashboard.

See [Web UI Setup Guide](docs/webui-setup.md) for detailed configuration.

## Documentation

- [Installation Guide](docs/installation.md)
- [Web UI Dashboard](docs/webui-setup.md) - Real-time monitoring and audit logging
- [Cursor Setup](docs/cursor-setup.md)
- [Claude Code Setup](docs/claude-setup.md)
- [Codex CLI Setup](docs/codex-setup.md)
- [Troubleshooting](docs/troubleshooting.md)
- [Tools Reference](docs/tools-reference.md)
- [Architecture](docs/architecture.md)
- [Contributing](CONTRIBUTING.md) - Development guide and quality gates

## Development

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and contribution guidelines.

Quick quality gate check:

```bash
make test      # Run tests with coverage
make lint      # Run ruff linter
make typecheck # Run mypy type checker
```

Or run all gates:

```bash
make test && make lint && make typecheck
```

## Performance

- **Overhead:** <0.01ms per transformation
- **Memory:** <10MB footprint
- **Coverage:** 98.2% test coverage

## License

MIT License - see [LICENSE](LICENSE) for details.

## Acknowledgments

- Apple's Xcode team for the MCP bridge functionality
- The MCP protocol specification
- The Cursor, Claude, and Codex teams for AI-powered development tools