Руководство по Xcode MCP

---
name: xcode-mcp
description: Правила эффективного использования инструментов Xcode MCP. Помогает выбрать между ними и обычными инструментами. Xcode MCP расходует много токенов: применяйте его для сборки, тестов, симулятора, предпросмотра и диагностики SourceKit. Не используйте его для чтения, записи файлов и поиска по ним.
---

# Правила использования Xcode MCP

Инструменты Xcode MCP расходуют много токенов. Этот навык объясняет, когда они нужны, а когда лучше выбрать обычные инструменты.

## Полный справочник инструментов Xcode MCP

### Окна и проекты
| Инструмент | Назначение | Расход токенов |
|------|-------------|------------|
| `mcp__xcode__XcodeListWindows` | Показать открытые окна Xcode и получить tabIdentifier | Низкий ✓ |

### Сборка
| Инструмент | Назначение | Расход токенов |
|------|-------------|------------|
| `mcp__xcode__BuildProject` | Собрать проект Xcode | Средний ✓ |
| `mcp__xcode__GetBuildLog` | Получить журнал сборки с ошибками и предупреждениями | Средний ✓ |
| `mcp__xcode__XcodeListNavigatorIssues` | Показать проблемы в Issue Navigator | Низкий ✓ |

### Тестирование
| Инструмент | Назначение | Расход токенов |
|------|-------------|------------|
| `mcp__xcode__GetTestList` | Получить список доступных тестов из плана | Низкий ✓ |
| `mcp__xcode__RunAllTests` | Запустить все тесты | Средний |
| `mcp__xcode__RunSomeTests` | Запустить выбранные тесты; предпочтительный вариант | Средний ✓ |

### Предпросмотр и выполнение
| Инструмент | Назначение | Расход токенов |
|------|-------------|------------|
| `mcp__xcode__RenderPreview` | Создать снимок предпросмотра SwiftUI | Средний ✓ |
| `mcp__xcode__ExecuteSnippet` | Выполнить фрагмент кода в контексте файла | Средний ✓ |

### Диагностика
| Инструмент | Назначение | Расход токенов |
|------|-------------|------------|
| `mcp__xcode__XcodeRefreshCodeIssuesInFile` | Получить диагностику компилятора для конкретного файла | Низкий ✓ |
| `mcp__ide__getDiagnostics` | Получить диагностику SourceKit для всех открытых файлов | Низкий ✓ |

### Документация
| Инструмент | Назначение | Расход токенов |
|------|-------------|------------|
| `mcp__xcode__DocumentationSearch` | Искать в документации Apple Developer | Низкий ✓ |

### Операции с файлами (БОЛЬШОЙ РАСХОД ТОКЕНОВ — НЕ ИСПОЛЬЗОВАТЬ)
| Инструмент | Альтернатива | Причина |
|------|-------------|-----|
| `mcp__xcode__XcodeRead` | Инструмент `Read` | Большой расход токенов |
| `mcp__xcode__XcodeWrite` | Инструмент `Write` | Большой расход токенов |
| `mcp__xcode__XcodeUpdate` | Инструмент `Edit` | Большой расход токенов |
| `mcp__xcode__XcodeGrep` | Инструмент `rg` / `Grep` | Большой расход токенов |
| `mcp__xcode__XcodeGlob` | Инструмент `Glob` | Большой расход токенов |
| `mcp__xcode__XcodeLS` | Команда `ls` | Большой расход токенов |
| `mcp__xcode__XcodeRM` | Команда `rm` | Большой расход токенов |
| `mcp__xcode__XcodeMakeDir` | Команда `mkdir` | Большой расход токенов |
| `mcp__xcode__XcodeMV` | Команда `mv` | Большой расход токенов |

---

## Рекомендуемые сценарии

### 1. Правка кода и сборка
```
1. Поиск по коду       → rg "pattern" --type swift
2. Чтение файла        → инструмент Read
3. Правка файла        → инструмент Edit
4. Проверка синтаксиса → mcp__ide__getDiagnostics
5. Сборка              → mcp__xcode__BuildProject
6. Проверка ошибок     → mcp__xcode__GetBuildLog (если сборка не удалась)
```

### 2. Написание и запуск тестов
```
1. Чтение файла тестов   → инструмент Read
2. Написание/правка теста → инструмент Edit
3. Список тестов         → mcp__xcode__GetTestList
4. Запуск тестов         → mcp__xcode__RunSomeTests (выбранные тесты)
5. Проверка результата   → просмотр вывода тестов
```

### 3. Предпросмотр SwiftUI
```
1. Правка представления → инструмент Edit
2. Предпросмотр          → mcp__xcode__RenderPreview
3. Доработка            → повторить при необходимости
```

### 4. Отладка
```
1. Диагностика      → mcp__ide__getDiagnostics (быстрая проверка синтаксиса)
2. Сборка проекта   → mcp__xcode__BuildProject
3. Журнал сборки    → mcp__xcode__GetBuildLog (severity: error)
4. Исправление      → инструмент Edit
5. Повторная сборка → mcp__xcode__BuildProject
```

### 5. Поиск в документации
```
1. Поиск документации → mcp__xcode__DocumentationSearch
2. Изучение результата → использовать сведения в реализации
```

---

## Запасные команды, если MCP недоступен

Если соединение с Xcode MCP отсутствует, используйте команды `xcodebuild`:

### Сборка
```bash
# Отладочная сборка для симулятора: замените <SchemeName> именем схемы проекта
xcodebuild -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build

# Релизная сборка для устройства
xcodebuild -scheme <SchemeName> -configuration Release -sdk iphoneos build

# Сборка через workspace (для проектов с CocoaPods)
xcodebuild -workspace <ProjectName>.xcworkspace -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build

# Сборка через файл проекта
xcodebuild -project <ProjectName>.xcodeproj -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build

# Список доступных схем
xcodebuild -list
```

### Тестирование
```bash
# Запуск всех тестов
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
  -destination "platform=iOS Simulator,name=iPhone 16" \
  -configuration Debug

# Запуск отдельного класса тестов
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
  -destination "platform=iOS Simulator,name=iPhone 16" \
  -only-testing:<TestTarget>/<TestClassName>

# Запуск отдельного тестового метода
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
  -destination "platform=iOS Simulator,name=iPhone 16" \
  -only-testing:<TestTarget>/<TestClassName>/<testMethodName>

# Запуск с измерением покрытия кода
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
  -configuration Debug -enableCodeCoverage YES

# Список доступных симуляторов
xcrun simctl list devices available
```

### Очистка перед сборкой
```bash
xcodebuild clean -scheme <SchemeName>

```

---

## Краткая памятка

### ИСПОЛЬЗУЙТЕ Xcode MCP ДЛЯ:
- ✅ `BuildProject` — сборки;
- ✅ `GetBuildLog` — просмотра ошибок сборки;
- ✅ `RunSomeTests` — запуска выбранных тестов;
- ✅ `GetTestList` — получения списка тестов;
- ✅ `RenderPreview` — предпросмотра SwiftUI;
- ✅ `ExecuteSnippet` — выполнения кода;
- ✅ `DocumentationSearch` — поиска по документации Apple;
- ✅ `XcodeListWindows` — получения tabIdentifier;
- ✅ `mcp__ide__getDiagnostics` — просмотра ошибок SourceKit.

### НЕ ИСПОЛЬЗУЙТЕ Xcode MCP ДЛЯ:
- ❌ `XcodeRead` → используйте `Read`;
- ❌ `XcodeWrite` → используйте `Write`;
- ❌ `XcodeUpdate` → используйте `Edit`;
- ❌ `XcodeGrep` → используйте `rg` или `Grep`;
- ❌ `XcodeGlob` → используйте `Glob`;
- ❌ `XcodeLS` → используйте команду `ls`;
- ❌ файловых операций → используйте обычные инструменты.

---

## Сводка по расходу токенов

| Операция | Лучший выбор | Расход токенов |
|-----------|-------------|--------------|
| Быстрая проверка синтаксиса | `mcp__ide__getDiagnostics` | 🟢 Низкий |
| Полная сборка | `mcp__xcode__BuildProject` | 🟡 Средний |
| Запуск выбранных тестов | `mcp__xcode__RunSomeTests` | 🟡 Средний |
| Запуск всех тестов | `mcp__xcode__RunAllTests` | 🟠 Высокий |
| Чтение файла | Инструмент `Read` | 🟠 Высокий |
| Правка файла | Инструмент `Edit` | 🟠 Высокий |
| Поиск по коду | `rg` / `Grep` | 🟢 Низкий |
| Список файлов | `ls` / `Glob` | 🟢 Низкий |