xcode-mcp (для агента pi)

---
name: xcode-mcp-for-pi-agent
description: Рекомендации по эффективному использованию инструментов Xcode MCP через CLI mcporter. Этот навык следует использовать, чтобы понимать, когда применять инструменты Xcode MCP, а когда стандартные инструменты. Xcode MCP расходует много токенов — используй его только для сборки, тестирования, симулятора, предпросмотра и диагностики SourceKit. Никогда не используй для операций чтения/записи файлов или grep. Используй этот навык всякий раз, когда работаешь с проектами Xcode, сборками iOS/macOS, предпросмотром SwiftUI или разработкой для платформ Apple.
---

# Рекомендации по использованию Xcode MCP

Доступ к инструментам Xcode MCP осуществляется через CLI `mcporter`, который связывает серверы MCP со стандартными инструментами командной строки. Этот навык определяет, когда использовать Xcode MCP, а когда предпочитать стандартные инструменты.

## Настройка

Xcode MCP должен быть настроен в `~/.mcporter/mcporter.json`:

```json
{
  "mcpServers": {
    "xcode": {
      "command": "xcrun",
      "args": ["mcpbridge"],
      "env": {}
    }
  }
}
```

Проверь соединение:
```bash
mcporter list xcode
```

---

## Вызов инструментов

Все инструменты Xcode MCP вызываются через mcporter:

```bash
# List available tools
mcporter list xcode

# Call a tool with key:value args
mcporter call xcode.<tool_name> param1:value1 param2:value2

# Call with function-call syntax
mcporter call 'xcode.<tool_name>(param1: "value1", param2: "value2")'
```

---

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

### Управление окнами и проектами
| Инструмент | Вызов mcporter | Расход токенов |
|------|---------------|------------|
| Получить список открытых окон Xcode (получить tabIdentifier) | `mcporter call xcode.XcodeListWindows` | Низкий ✓ |

### Операции сборки
| Инструмент | Вызов mcporter | Расход токенов |
|------|---------------|------------|
| Собрать проект Xcode | `mcporter call xcode.BuildProject` | Средний ✓ |
| Получить лог сборки с ошибками/предупреждениями | `mcporter call xcode.GetBuildLog` | Средний ✓ |
| Получить список проблем в Issue Navigator | `mcporter call xcode.XcodeListNavigatorIssues` | Низкий ✓ |

### Тестирование
| Инструмент | Вызов mcporter | Расход токенов |
|------|---------------|------------|
| Получить доступные тесты из плана тестирования | `mcporter call xcode.GetTestList` | Низкий ✓ |
| Запустить все тесты | `mcporter call xcode.RunAllTests` | Средний |
| Запустить конкретные тесты (предпочтительно) | `mcporter call xcode.RunSomeTests` | Средний ✓ |

### Предпросмотр и выполнение
| Инструмент | Вызов mcporter | Расход токенов |
|------|---------------|------------|
| Отрисовать снимок SwiftUI Preview | `mcporter call xcode.RenderPreview` | Средний ✓ |
| Выполнить фрагмент кода в контексте файла | `mcporter call xcode.ExecuteSnippet` | Средний ✓ |

### Диагностика
| Инструмент | Вызов mcporter | Расход токенов |
|------|---------------|------------|
| Получить диагностику компилятора для конкретного файла | `mcporter call xcode.XcodeRefreshCodeIssuesInFile` | Низкий ✓ |
| Получить диагностику SourceKit (все открытые файлы) | `mcporter call xcode.getDiagnostics` | Низкий ✓ |

### Документация
| Инструмент | Вызов mcporter | Расход токенов |
|------|---------------|------------|
| Поиск в документации Apple Developer | `mcporter call xcode.DocumentationSearch` | Низкий ✓ |

### Файловые операции (ВЫСОКИЙ РАСХОД ТОКЕНОВ — НИКОГДА НЕ ИСПОЛЬЗОВАТЬ)
| Инструмент MCP | Использовать вместо него | Причина |
|----------|-------------|-----|
| `xcode.XcodeRead` | Инструмент `Read` / `cat` | Высокий расход токенов |
| `xcode.XcodeWrite` | Инструмент `Write` | Высокий расход токенов |
| `xcode.XcodeUpdate` | Инструмент `Edit` | Высокий расход токенов |
| `xcode.XcodeGrep` | `rg` / `grep` | Высокий расход токенов |
| `xcode.XcodeGlob` | `find` / `glob` | Высокий расход токенов |
| `xcode.XcodeLS` | Команда `ls` | Высокий расход токенов |
| `xcode.XcodeRM` | Команда `rm` | Высокий расход токенов |
| `xcode.XcodeMakeDir` | Команда `mkdir` | Высокий расход токенов |
| `xcode.XcodeMV` | Команда `mv` | Высокий расход токенов |

---

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

### 1. Изменение кода и сборка
```
1. Найти код         → rg "pattern" --type swift
2. Прочитать файл    → Инструмент Read / cat
3. Изменить файл     → Инструмент Edit
4. Проверить синтаксис → mcporter call xcode.getDiagnostics
5. Собрать           → mcporter call xcode.BuildProject
6. Проверить ошибки  → mcporter call xcode.GetBuildLog (если сборка не удалась)
```

### 2. Написание и запуск тестов
```
1. Прочитать файл теста → Инструмент Read / cat
2. Написать/изменить тест → Инструмент Edit
3. Получить список тестов → mcporter call xcode.GetTestList
4. Запустить тесты    → mcporter call xcode.RunSomeTests (конкретные тесты)
5. Проверить результаты → Просмотреть вывод тестов
```

### 3. Предпросмотр SwiftUI
```
1. Изменить представление → Инструмент Edit
2. Отрисовать предпросмотр → mcporter call xcode.RenderPreview
3. Повторять          → Повторять по необходимости
```

### 4. Отладка
```
1. Проверить диагностику → mcporter call xcode.getDiagnostics
2. Собрать проект      → mcporter call xcode.BuildProject
3. Получить лог сборки → mcporter call xcode.GetBuildLog severity:error
4. Исправить проблемы → Инструмент Edit
5. Пересобрать         → mcporter call xcode.BuildProject
```

### 5. Поиск в документации
```
1. Искать документацию → mcporter call xcode.DocumentationSearch query:"SwiftUI NavigationStack"
2. Изучить результаты  → Использовать сведения при реализации
```

---

## Резервные команды (когда MCP или mcporter недоступны)

Если Xcode MCP отключён, mcporter не установлен или соединение не работает, используй эти команды xcodebuild напрямую:

### Команды сборки
```bash
# Debug build (simulator) - replace <SchemeName> with your project's scheme
xcodebuild -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build

# Release build (device)
xcodebuild -scheme <SchemeName> -configuration Release -sdk iphoneos build

# Build with workspace (for CocoaPods projects)
xcodebuild -workspace <ProjectName>.xcworkspace -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build

# Build with project file
xcodebuild -project <ProjectName>.xcodeproj -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build

# List available schemes
xcodebuild -list
```

### Команды тестирования
```bash
# Run all tests
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
  -destination "platform=iOS Simulator,name=iPhone 16" \
  -configuration Debug

# Run specific test class
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
  -destination "platform=iOS Simulator,name=iPhone 16" \
  -only-testing:<TestTarget>/<TestClassName>

# Run specific test method
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
  -destination "platform=iOS Simulator,name=iPhone 16" \
  -only-testing:<TestTarget>/<TestClassName>/<testMethodName>

# Run with code coverage
xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \
  -configuration Debug -enableCodeCoverage YES

# List available simulators
xcrun simctl list devices available
```

### Чистая сборка
```bash
xcodebuild clean -scheme <SchemeName>
```

---

## Краткая справка

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

### НИКОГДА НЕ ИСПОЛЬЗУЙ Xcode MCP для:
- ❌ `xcode.XcodeRead` → Используй инструмент `Read` / `cat`
- ❌ `xcode.XcodeWrite` → Используй инструмент `Write`
- ❌ `xcode.XcodeUpdate` → Используй инструмент `Edit`
- ❌ `xcode.XcodeGrep` → Используй `rg` или `grep`
- ❌ `xcode.XcodeGlob` → Используй `find` / `glob`
- ❌ `xcode.XcodeLS` → Используй команду `ls`
- ❌ Файловые операции → Используй стандартные инструменты

---

## Сводка эффективности расхода токенов

| Операция | Лучший выбор | Расход токенов |
|-----------|-------------|--------------|
| Быстрая проверка синтаксиса | `mcporter call xcode.getDiagnostics` | 🟢 Низкий |
| Полная сборка | `mcporter call xcode.BuildProject` | 🟡 Средний |
| Запуск конкретных тестов | `mcporter call xcode.RunSomeTests` | 🟡 Средний |
| Запуск всех тестов | `mcporter call xcode.RunAllTests` | 🟠 Высокий |
| Чтение файла | Инструмент `Read` / `cat` | 🟢 Низкий |
| Изменение файла | Инструмент `Edit` | 🟢 Низкий |
| Поиск по коду | `rg` / `grep` | 🟢 Низкий |
| Список файлов | `ls` / `find` | 🟢 Низкий |