Xcode Diagnostics MCP 插件

一个用于从 Xcode 构建日志中提取和查看错误和警告的 MCP（模型控制协议）插件。

概述

该插件实现 Model Control Protocol（MCP）规范，为任何兼容的 AI 助手提供 Xcode 诊断功能。它连接到 Xcode 的构建系统，从中提取、解析并显示来自 Swift 项目的诊断信息（错误和警告）。它帮助 AI 助手快速识别代码中的问题，而无需手动搜索构建日志。

请注意，由于这在日志级别上工作，因此在运行此工具之前，Xcode 必须已经尝试过构建。

前置条件

• macOS 操作系统
• 安装了 Xcode
• Python 3.6 或更高版本

安装

从 PyPI 安装

安装 MCP 插件的最简单方法：

pip install mcp-xcode-diagnostics

从 GitHub 安装

可以直接从 GitHub 安装：

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

从源代码安装

要从源代码安装：

1. 克隆或下载此存储库
2. 使用 pip 安装插件：
   bash 复制代码

   cd mcp-xcode-diagnostics
   pip install .

插件现在可以与任何与之兼容的客户端一起使用。

特性

• 列出所有包含构建日志在 DerivedData 中的 Xcode 项目
• 提取特定项目最新构建日志中的错误和警告
• 分析复杂的诊断信息，包括相关注释和修复建议
• 提供每个问题的详细信息，包括文件路径、行号和错误消息
• 优化捕获 Swift 并发相关的警告

支持的诊断类型

插件可以检测并显示多种 Xcode 诊断信息，包括：

错误

• 语法错误（例如，“缺少花括号”或“缺少表达式”）
• 类型错误（例如，“无法将 X 类型的值转换为预期的 Y 参数类型”）
• 未解析的标识符和缺失的导入
• 协议符合性错误
• 泛型参数推断失败
• 访问控制违规

警告

• 未使用的变量、常量和结果
• 隐式的精度可能丢失的强制类型转换
• 冗余代码或不必要的表达式
• 弃用警告
• 字符串插值问题
• Swift 并发警告，包括：
  • 并行化不可访问的全局共享可变状态警告
  • 主演员隔离警告
  • 协议符合并发警告
  • 演员隔离违规
  • Swift 6 语言模式兼容性警告

注解和修复建议

• 提供更多上下文的关联注解
• 提出动议代码修改以解决问题的修复建议
• 展示有问题代码的代码片段

限制

• 运行时日志中的二进制/序列化格式可能无法完全解析
• 某些高度专业化的诊断格式可能无法识别
• 非常大的构建日志可能会被截断
• 项目特定的自定义诊断可能无法正确定位

MCP 工具

该插件提供了两个主要的 MCP 工具：

get_xcode_projects

列出 DerivedData 目录中所有包含构建日志的 Xcode 项目。

参数：无

get_project_diagnostics

从特定项目的最新构建日志中获取诊断信息。

参数：

• project_dir_name：DerivedData 中该项目的目录名（例如，'ProjectName-hash'）
• include_warnings：是否除了错误还包括警告（默认：True）

调试信息

出于调试目的，插件将原始日志输出保存到以下位置：

• /tmp/xcode-mcp-debug.log - 主应用程序日志
• /tmp/xcode-diagnostic-raw.log - Xcode 活动日志的原始输出

示例输出

{
  "success": true,
  "log_file": "/path/to/build.xcactivitylog",
  "timestamp": "2025-03-11T12:34:56.789",
  "errors": [
    {
      "type": "error",
      "message": "未解析的标识符 'NonExistentType' 的使用",
      "file_path": "/path/to/MyFile.swift",
      "line_number": 42,
      "column": 15,
      "code": "    let x: NonExistentType = value",
      "notes": []
    }
  ],
  "warnings": [
    {
      "type": "warning",
      "message": "静态属性 'sharedInstance' 不是线程安全的，因为它是非孤立的全局共享可变状态；在 Swift 6 语言模式下这是一个错误。",
      "file_path": "/path/to/SharedManager.swift",
      "line_number": 10,
      "column": 16,
      "code": "    static var sharedInstance: SharedManager?",
      "notes": [
        {
          "type": "note",
          "message": "将 'sharedInstance' 转换为 'let' 常量，使并发共享状态成为不可变状态。",
          "file_path": "/path/to/SharedManager.swift",
          "line_number": 10,
          "column": 16
        }
      ]
    }
  ],
  "error_count": 1,
  "warning_count": 1
}

测试

插件包含一组测试以验证解析功能：

# 运行所有测试
python -m unittest test_xcode_diagnostics.py

许可证

该项目在 MIT 许可证下可用。