Xcode 诊断 MCP 插件

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

概述

此插件实现了模型控制协议 (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 项目
• 从特定项目的最新构建日志中提取错误和警告
• 解析复杂的诊断信息，包括相关的注释和 Fix-it 建议
• 提供有关每个问题的详细信息，包括文件路径、行号和错误消息
• 针对捕获 Swift 并发相关的警告进行了优化

支持的诊断类型

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

错误

• 语法错误（例如，“expected '{'”或“expected expression”）
• 类型错误（例如，“cannot convert value of type X to expected argument type Y”）
• 未解析的标识符和缺失的导入
• 协议一致性错误
• 泛型参数推断失败
• 访问控制违规

警告

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

注释和 Fix-it 建议

• 提供有关错误和警告的附加上下文的相关注释
• 提供代码更改建议以解决问题的 Fix-it 建议
• 显示有问题代码的代码片段

局限性

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

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
}

测试

该插件包含一个测试套件，用于验证解析功能：

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

许可证

本项目根据 MIT 许可证提供。