Xcode 诊断 MCP 插件

一个用于从 Xcode 构建日志中提取和查看错误与警告的 MCP（Model Control Protocol）插件。

概述

此插件实现了 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”）
• 类型错误（例如，“cannot convert value of type X to expected argument type 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": "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 because it is nonisolated global shared mutable state; this is an error in the Swift 6 language mode",
      "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 to make 'Sendable' shared state immutable",
          "file_path": "/path/to/SharedManager.swift",
          "line_number": 10,
          "column": 16
        }
      ]
    }
  ],
  "error_count": 1,
  "warning_count": 1
}

测试

该插件包括一个测试套件来验证解析功能：

# Run all tests
python -m unittest test_xcode_diagnostics.py

许可证

本项目遵循 MIT 许可证。