Xcode 诊断 MCP 插件

这是一个用于从 Xcode 构建日志中提取并查看错误和警告的 Model Control Protocol (MCP) 插件。

概述

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

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

预备条件

• macOS 操作系统
• 已安装 Xcode
• Python 3.6+

安装

从 PyPI 安装

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

pip install mcp-xcode-diagnostics

从 GitHub 安装

您可以直接从 GitHub 安装：

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

从源码安装

要从源码安装：

1. 克隆或下载此仓库
2. 使用 pip 安装插件：

   cd mcp-xcode-diagnostics
   pip install .
   

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

特性

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

支持的诊断类型

该插件可以检测并显示各种类型的 Xcode 诊断信息，包括：

错误

• 语法错误（例如，“expected '{'" 或 “expected expression”）
• 类型错误（例如，“无法将类型 X 转换为预期参数类型 Y”）
• 未解析的标识符和缺失的导入
• 协议一致性错误
• 泛型参数推断失败
• 访问控制违规

警告

• 未使用的变量、常量和结果
• 可能丢失精度的隐式转换
• 冗余代码或不必要的表达式
• 废弃警告
• 字符串插值问题
• Swift 并发警告，包括：
  • 非隔离全局共享可变状态警告
  • 主 actor 隔离警告
• 协议一致性并发警告
• actor 隔离违规
• 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' 常量以使 'Sendable' 共享状态不可变",
          "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 许可证下可用。