ios-mcp-code-quality-server

iOS MCP Code Quality Server 是一个 iOS 代码质量分析与测试自动化工具，可在命令行工具（CLI）与 Model Context Protocol（MCP）服务器两种模式间智能切换。其目标是为开发者与 AI 助手提供对 Xcode 测试、代码检查（linter）分析以及 iOS 项目结构化反馈的统一入口。

用途与定位 该工具同时服务两类使用方式。一是开发者直接在终端中运行，用于执行 iOS 测试与代码检查，可脚本化、适合 CI/CD；二是作为 MCP 服务器接入 AI 助手，让 AI 助手能够运行 Xcode 测试、执行 linter 分析，并以结构化、可操作的形式返回报告。

主要能力

• iOS 测试执行：运行 Xcode 测试，并提供详细的失败分析。
• 多 scheme 支持：可按不同 iOS 项目配置进行测试。
• SwiftLint 集成：自动化 Swift 代码风格与质量检查（目前支持的 linter 为 SwiftLint）。
• 结构化报告：输出清晰、可操作的反馈，包含文件位置与行号。
• 构建错误检测：智能解析 Xcode 构建失败。
• 本地处理：所有分析均在本地机器完成，保障安全。
• 双模式运行：既可作 CLI 工具，也可作 MCP 服务器。
• AI 助手就绪：支持 MCP 协议，便于与 AI 助手集成。

模式与行为 工具会根据是否传入命令行参数自动判断模式：

• CLI 模式：当提供命令行参数时激活，面向终端直接交互，可输出人类可读或 JSON 格式，便于脚本处理；优势是执行快、可脚本化、对 CI/CD 友好，并且配合 npx 无需安装。
• MCP 服务器模式：当不提供参数时默认激活，用于通过 MCP 协议与 AI 助手集成，输出供 AI 消费的结构化 MCP 响应；优势是支持 AI 驱动的分析、上下文建议与交互式调试。

使用方式（CLI） 推荐通过 npx 直接运行，无需安装。也可选择全局安装以在多个项目中使用；提示使用 npx 可确保始终使用最新版本而无需全局安装。 运行 iOS 测试并获取完整分析：

• --xcworkspace <path>：.xcworkspace 文件路径。
• --xcodeproj <path>：.xcodeproj 文件路径（xcworkspace 或 xcodeproj 至少需提供其一）。
• --scheme <name>：测试用的 scheme 名称（必填）。
• --destination <destination>：测试目标（默认 "platform=iOS Simulator"）。
• --json：以 JSON 格式输出结果。
• --verbose：启用详细日志。 对指定文件运行 SwiftLint 分析：
• --changed-files <files>：要检查的文件列表，逗号分隔（必填）。
• --config-path <path>：SwiftLint 配置文件路径。 显式启动 MCP 服务器模式。

MCP 服务器安装与启动 依赖环境：Node.js 18+（运行 MCP 服务器所必需）、Xcode（用于 iOS 项目构建与测试）、iOS 模拟器（用于运行测试，或使用物理 iOS 设备）、SwiftLint（可选，用于代码质量分析）。 步骤：克隆仓库（git clone https://github.com/a-25/ios-mcp-code-quality-server.git 与 cd ios-mcp-code-quality-server）；安装依赖 npm install；构建项目 npm run build；启动服务器 npm start（或显式 node dist/index.js server）。服务器启动后监听 http://localhost:3000，准备接收 MCP 请求。

AI 助手集成 可将该 MCP 服务器配置给 AI 助手（如 Claude、Copilot 等）。服务器支持通过环境变量进行若干配置选项，示例配置与环境变量（含默认值）在项目中提供。

工具与能力（MCP） iOS 测试执行工具：执行 iOS 测试并提供详细失败分析，支持运行特定测试。参数包括：

• xcodeproj（可选）：Xcode 项目文件路径。
• xcworkspace（可选）：Xcode 工作区文件路径。 注意：xcodeproj 或 xcworkspace 必须提供至少一个。
• scheme（必填）：要测试的 Xcode scheme。
• destination（可选）：测试目标（模拟器/设备），默认值 generic/platform=iOS Simulator。
• tests（可选）：要运行的特定测试名称数组。格式：['MyTarget/TestClass/testMethod', 'MyTarget/TestClass']；示例：['MyAppTests/LoginTests/testValidLogin', 'MyAppUITests/HomeScreenTests']。
• target（可选）：测试执行上下文的 target 参数，可用于指定不同的测试环境或配置。 示例响应涵盖：成功（所有测试通过）、构建错误（编译问题）、测试错误（测试已构建但失败）三类情况。 列出测试工具：发现并列出 iOS 项目中的所有可用测试，参数包括 scheme（可选）与 destination（可选）。 代码检查工具：对 iOS 项目执行 lint 分析，目前支持的 linter 为 SwiftLint。

CLI 使用示例场景

• 直接测试。
• 代码质量分析。
• 开发工作流。

AI 助手使用（MCP 模式） 运行测试时，AI 助手将使用增强的测试工具：通过 list-tests 工具发现可用测试；执行指定 scheme 的特定测试或全部测试；校验测试名称并对拼写错误提供建议；解析构建与测试结果并给出详细失败分析；提供带文件位置与行号的结构化失败摘要。

适用场景

• 开发者在本地终端快速执行 iOS 测试与 SwiftLint 检查。
• 在 CI/CD 中脚本化调用测试与检查并获取 JSON 输出。
• 将测试与代码质量分析能力接入 AI 助手，实现交互式调试与上下文建议。
• 需要本地处理、不外传代码与测试数据的团队。

限制与注意事项

• 需要 Node.js 18+、Xcode、iOS 模拟器（或物理设备）；SwiftLint 为可选依赖，如需代码质量分析需自行安装。
• 在模拟器或真机上运行测试，destination 需可用。
• 该工具在本地运行，所有处理在本机完成；除非显式配置，不会将数据发送到外部服务。不要公开分享本地服务器端点。
• MCP 服务器默认监听 3000 端口。

故障排查（项目提供）

• CLI 命令未找到：若为全局安装，在项目目录执行 npm install -g .；否则在项目目录使用 node dist/index.js <command>；确认已完成构建 npm run build。
• 服务器无法启动：检查 3000 端口是否可用（lsof -i :3000）；确认 Node.js 18+（node --version）；确认依赖已安装（npm list）。
• 测试无法运行：确认已安装 Xcode 且命令行工具可用；确认指定的 scheme 存在；确认目标设备/模拟器可用（xcrun simctl list devices）；CLI 模式下确认 xcworkspace/xcodeproj 路径正确可访问。
• SwiftLint 不工作：安装 SwiftLint（brew install swiftlint）；验证安装（swiftlint version）；CLI 模式下确认 changed-files 路径正确且文件存在。
• MCP 连接问题：确认服务器正在运行（lsof -i :3000 检查进程）；检查 AI 助手的 MCP 配置；查看服务器日志中的连接错误；可启用详细日志用于排查。

贡献与许可 项目欢迎贡献，流程为：Fork 仓库、创建功能分支（git checkout -b feature/amazing-feature）、修改并添加测试、确保所有测试通过（npm test）、提交（git commit -m 'Add amazing feature'）、推送分支（git push origin feature/amazing-feature）、发起 Pull Request。开发准则包括：为新功能编写测试、遵循 TypeScript 最佳实践、API 变更时更新文档、尽可能保持向后兼容。项目采用 MIT 许可证，详见 LICENSE 文件。