Xcode Diagnostics MCP Plugin

Плагин для протокола MCP (Model Control Protocol), который извлекает ошибки и предупреждения из логов сборки Xcode. Предназначен для использования с AI-ассистентами: помогает быстро находить проблемы в коде без ручного просмотра логов. Работает на уровне логов, поэтому перед запуском убедитесь, что Xcode уже выполнил сборку проекта.

Предварительные требования

• macOS
• Установленный Xcode
• Python 3.6+

Установка

Из PyPI (рекомендуемый способ)

pip install mcp-xcode-diagnostics

Из GitHub

pip install git+https://github.com/leftspin/mcp-xcode-diagnostics.git

Из исходников

1. Склонируйте репозиторий и перейдите в каталог mcp-xcode-diagnostics
2. Выполните:

pip install .

После установки плагин становится доступен любому MCP-совместимому клиенту.

Возможности

• Показывает список всех Xcode-проектов, для которых есть логи сборки в DerivedData
• Извлекает ошибки и предупреждения из последнего лога сборки выбранного проекта
• Разбирает сложные диагностические сообщения, включая сопутствующие заметки и предложения по исправлению (fix-it)
• Предоставляет детали по каждой проблеме: путь к файлу, номер строки, текст ошибки
• Оптимизирован для перехвата предупреждений, связанных с конкурентностью в Swift

Поддерживаемые типы диагностики

Ошибки:

• Синтаксические ошибки (например, expected '{')
• Ошибки типов (например, cannot convert value of type X to expected argument type Y)
• Неразрешённые идентификаторы и пропущенные импорты
• Ошибки соответствия протоколам
• Неудачи вывода обобщённых параметров
• Нарушения контроля доступа

Предупреждения:

• Неиспользуемые переменные, константы и результаты
• Неявные преобразования с потерей точности
• Избыточный код
• Предупреждения об устаревших API
• Проблемы с интерполяцией строк
• Предупреждения конкурентности Swift, в том числе:
  • Неизолированное глобальное изменяемое состояние
  • Нарушения изоляции Main Actor
  • Проблемы конкурентности при соответствии протоколам
  • Нарушения изоляции акторов
  • Несовместимость с режимом Swift 6

Заметки и предложения по исправлению (fix-it):

• Дополнительный контекст к ошибкам и предупреждениям
• Предлагаемые изменения кода
• Фрагменты кода с проблемным местом

Ограничения

• Бинарные/сериализованные форматы в логах времени выполнения могут разбираться не полностью
• Некоторые узкоспециализированные форматы диагностики могут не распознаваться
• Очень большие логи сборки могут быть обрезаны
• Специфичные для проекта пользовательские диагностики могут неправильно классифицироваться

MCP-инструменты

Плагин предоставляет два инструмента:

get_xcode_projects

Выводит список всех Xcode-проектов, для которых есть логи в DerivedData.

Параметры: нет

get_project_diagnostics

Возвращает диагностическую информацию из последнего лога сборки указанного проекта.

Параметры:

• project_dir_name (строка, обязательный) — имя каталога проекта в DerivedData (например, ProjectName-hash)
• include_warnings (булево, необязательный, по умолчанию True) — включать ли предупреждения вместе с ошибками

Пример вывода

{
  "success": true,
  "log_file": "/path/to/build.xcactivitylog",
  "timestamp": "2025-03-11T12:34:56.789",
  "errors": [
    {
      "type": "error",
      "message": "use of unresolved identifier 'NonExistentType'",
      "file_path": "/path/to/MyFile.swift",
      "line_number": 42,
      "column": 15,
      "code": "let x: NonExistentType = value",
      "notes": []
    }
  ],
  "warnings": [
    {
      "type": "warning",
      "message": "static property 'sharedInstance' is not concurrency-safe...",
      "file_path": "/path/to/SharedManager.swift",
      "line_number": 10,
      "column": 16,
      "code": "static var sharedInstance: SharedManager?",
      "notes": [
        {
          "type": "note",
          "message": "convert 'sharedInstance' to a 'let' constant...",
          "file_path": "/path/to/SharedManager.swift",
          "line_number": 10,
          "column": 16
        }
      ]
    }
  ],
  "error_count": 1,
  "warning_count": 1
}

Отладка

Для отладки плагин сохраняет сырые логи в:

• /tmp/xcode-mcp-debug.log — основные логи приложения
• /tmp/xcode-diagnostic-raw.log — сырой вывод из логов активности Xcode

Тестирование

python -m unittest test_xcode_diagnostics.py

Лицензия

Проект распространяется под лицензией MIT.