VentraGo Engineering Гайд

Appearance

Настройка Xcode MCP (mcpbridge) ​

Xcode 26.3+ поддерживает Model Context Protocol через встроенный mcpbridge (документация Apple). Это мост между внешними AI-агентами (Claude Code, Cursor, Codex) и Xcode — агент получает доступ к проекту, билдам, тестам и превью прямо из IDE.

Что это даёт ​

Без MCP агент работает только с файлами. С mcpbridge он может:

  • Собрать проект и получить структурированные ошибки (файл, строка, описание) — автоматический цикл «билд → фикс → билд»
  • Запустить тесты и получить результаты pass/fail с сообщениями об ошибках
  • Отрендерить SwiftUI-превью — агент буквально видит UI и может итеративно менять код
  • Искать по документации Apple — семантический поиск по документации и WWDC-сессиям (iOS 15–26)
  • Выполнить Swift-код в playground-режиме без создания файлов и полной сборки
  • Управлять проектом — просмотр структуры, файлов, таргетов, схем, изменение настроек билда

Архитектура ​

┌─────────────┐  MCP Protocol  ┌────────────┐  XPC  ┌─────────┐
│ Claude Code │ ◄────────────► │ mcpbridge  │ ◄────► │  Xcode  │
│ Cursor/etc  │                │  (Bridge)  │       │  (IDE)  │
└─────────────┘                └────────────┘       └─────────┘

mcpbridge транслирует MCP-запросы от агента в XPC-вызовы к Xcode. PID запущенного Xcode определяется автоматически.

Включение MCP в Xcode ​

  1. Открыть Xcode (>= 26.3)
  2. Settings (⌘ + ,) → вкладка Intelligence
  3. В секции Model Context Protocol включить Xcode Tools

Xcode Settings → Intelligence → Model Context Protocol

Подключение Claude Code ​

Команда (из корня проекта):

bash
claude mcp add --transport stdio xcode -- xcrun mcpbridge

Или вручную — создать .claude.json в корне проекта:

json
{
  "mcpServers": {
    "xcode-tools": {
      "command": "xcrun",
      "args": ["mcpbridge"]
    }
  }
}

Проверка:

bash
claude mcp list

Должен появиться xcode (или xcode-tools) со списком доступных инструментов.

Подключение Cursor ​

В Xcode 26.3 RC есть баг: ответы mcpbridge не содержат structuredContent, из-за чего Cursor ломается. Claude Code и Codex обрабатывают это корректно, а Cursor — нет. Обходное решение — обёртка mcpbridge-wrapper.

Установить uv (если ещё нет):

bash
brew install uv

Создать .cursor/mcp.json в корне проекта:

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

Когда баг починят — можно будет заменить на прямой вызов xcrun mcpbridge.

Подключение Codex ​

Создать .codex/config.toml в корне проекта:

toml
[mcp_servers.xcode-tools]
command = "xcrun"
args = ["mcpbridge"]

Или через CLI:

bash
codex mcp add xcode -- xcrun mcpbridge

Проверка ​

  1. Открыть проект в Xcode
  2. Запустить агента (Claude Code / Cursor / Codex)
  3. Xcode покажет диалог «Allow [agent] to access Xcode?» — разрешить
  4. Попросить агента собрать проект или показать структуру — если ответил с данными из Xcode, всё работает

Советы ​

  • Конфиг — per-project. Храните .claude.json / .cursor/mcp.json в корне конкретного проекта, а не глобально. Иначе Xcode будет спрашивать разрешение для каждого проекта, даже где MCP не нужен.
  • Порядок запуска. Сначала открываем проект в Xcode, потом запускаем агента. mcpbridge подключается к уже запущенному Xcode.
  • Создание новых проектов через MCP пока не поддерживается — только работа с существующими.