Ios Mcp Code Quality Server

iOS MCP 代码质量服务

一款多功能 iOS 代码质量分析工具，支持两种模式：

1. CLI 工具：用于 iOS 测试和 lint 检查的直接命令行界面
2. MCP 服务：用于集成 AI 助手的 Model Context Protocol 服务

此工具提供全面的 iOS 代码质量分析和测试自动化功能，既支持开发者直接使用，也支持 AI 助手通过结构化、可操作的报告，对 iOS 项目执行 Xcode 测试、lint 分析并提供详细反馈。

快速开始

CLI 模式（直接使用 npx — 推荐）

无需安装，即刻使用：

# Run iOS tests
npx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests

# Run SwiftLint analysis
npx ios-mcp-code-quality-server lint --changed-files "ViewController.swift,Model.swift"

# Show help
npx ios-mcp-code-quality-server --help

替代方式：全局安装（可选）

如果要在多个项目中频繁使用，可以全局安装：

npm install -g ios-mcp-code-quality-server

# Then use the full name (following MCP conventions)
ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests
ios-mcp-code-quality-server lint --changed-files "ViewController.swift,Model.swift"

💡 提示： 建议使用 npx，这样无需全局安装，即可始终使用最新版本。

MCP 服务模式（集成 AI 助手）

# Start as MCP server (no arguments)
npx ios-mcp-code-quality-server

# Or explicitly start server mode
npx ios-mcp-code-quality-server server

服务将在 http://localhost:3000 上启动，并准备好接收 MCP 请求。

功能

• 🧪 iOS 测试执行：运行 Xcode 测试并详细分析失败原因
• 📱 多 Scheme 支持：测试不同的 iOS 项目配置
• 🔍 SwiftLint 集成：自动检查 Swift 代码风格和质量
• 📊 结构化报告：提供清晰、可操作的反馈，包含文件位置和行号
• 🛠 构建错误检测：智能解析 Xcode 构建失败信息
• 🔒 本地处理：所有分析均在本机上进行，确保安全
• ⚡ 双模式运行：可用作 CLI 工具或 MCP 服务
• 💻 命令行界面：供开发者直接在终端中使用
• 🤖 支持 AI 助手：支持 MCP 协议，可无缝集成 AI

架构

此工具以两种不同模式运行，并能智能检测模式：

CLI 模式

• 激活条件：提供命令行参数时
• 用法：开发者通过终端命令或 npx 直接交互
• 输出：适合阅读或脚本处理的人类可读格式或 JSON 格式
• 优势：执行快速、支持脚本化、适用于 CI/CD；使用 npx 无需安装

MCP 服务模式

• 激活条件：未提供任何参数时（默认）
• 用法：通过 Model Context Protocol 集成 AI 助手
• 输出：供 AI 使用的结构化 MCP 响应
• 优势：AI 驱动的分析、结合上下文的建议、交互式调试

简单的模式检测：

# MCP Server Mode (no arguments)
npx ios-mcp-code-quality-server          # → Starts MCP server
ios-mcp-code-quality-server              # → Starts MCP server (if globally installed)

# CLI Mode (arguments provided)  
npx ios-mcp-code-quality-server --help           # → CLI help
npx ios-mcp-code-quality-server test --help      # → CLI test help
npx ios-mcp-code-quality-server lint --changed-files="file.swift"  # → CLI lint

CLI 用法

无需安装

使用 npx 可直接运行 CLI，无需安装：

npx ios-mcp-code-quality-server --help              # Show all available commands
npx ios-mcp-code-quality-server <command> --help    # Show help for specific command

命令

Test 命令

运行 iOS 测试并进行全面分析：

# Basic usage
npx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests

# With specific destination
npx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests \
  --destination "platform=iOS Simulator,name=iPhone 15"

# Using Xcode project instead of workspace
npx ios-mcp-code-quality-server test --xcodeproj MyApp.xcodeproj --scheme MyAppTests

# Get JSON output for script integration
npx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests --json

# Verbose logging for debugging
npx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests --verbose

Test 命令选项：

• --xcworkspace <path>：.xcworkspace 文件的路径
• --xcodeproj <path>：.xcodeproj 文件的路径（必须指定 xcworkspace 或 xcodeproj 其中之一）
• --scheme <name>：用于测试的 Scheme 名称（必填）
• --destination <destination>：测试目标（默认值："platform=iOS Simulator"）
• --json：以 JSON 格式输出结果
• --verbose：启用详细日志

Lint 命令

对指定文件运行 SwiftLint 分析：

# Lint specific files
npx ios-mcp-code-quality-server lint --changed-files "ViewController.swift,Model.swift"

# With custom SwiftLint configuration
npx ios-mcp-code-quality-server lint --changed-files "*.swift" --config-path .swiftlint.yml

# Get JSON output
npx ios-mcp-code-quality-server lint --changed-files "ViewController.swift" --json

# Verbose output
npx ios-mcp-code-quality-server lint --changed-files "*.swift" --verbose

Lint 命令选项：

• --changed-files <files>：要进行 lint 检查的文件列表，以逗号分隔（必填）
• --config-path <path>：SwiftLint 配置文件的路径
• --json：以 JSON 格式输出结果
• --verbose：启用详细日志

Server 命令

显式启动 MCP 服务模式：

# Start server on default port (3000)
npx ios-mcp-code-quality-server server

# Start server on custom port
npx ios-mcp-code-quality-server server --port 8080

# Server with custom settings
PORT=3001 LOG_LEVEL=debug npx ios-mcp-code-quality-server server

CLI 示例

# Complete iOS project test workflow
npx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests --verbose

# Quick SwiftLint check on modified files
git diff --name-only | grep "\.swift$" | xargs -I {} npx ios-mcp-code-quality-server lint --changed-files {}

# CI/CD integration with JSON output
npx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests --json > test-results.json

# Check specific Swift files before commit
npx ios-mcp-code-quality-server lint --changed-files "LoginViewController.swift,UserModel.swift" --config-path .swiftlint.yml

MCP 服务安装

前提条件

• Node.js 18+：运行 MCP 服务所需
• Xcode：用于构建和测试 iOS 项目
• iOS Simulator：用于运行测试（也可使用实体 iOS 设备）
• SwiftLint（可选）：用于代码质量分析

安装步骤

1. 克隆仓库：

   git clone https://github.com/a-25/ios-mcp-code-quality-server.git
   cd ios-mcp-code-quality-server
   

2. 安装依赖项：

   npm install
   

3. 构建项目：

   npm run build
   

4. 启动服务：

   npm start
   # or explicitly
   node dist/index.js server
   

AI 助手集成

配置 AI 助手（Claude、Copilot 等）以使用此 MCP 服务：

{
  "mcpServers": {
    "ios-code-quality": {
      "url": "http://localhost:3000",
      "timeout": 30000
    }
  }
}

配置

该服务支持通过环境变量进行多项配置：

变量	描述	默认值
PORT	服务端口	3000
NODE_ENV	环境模式	development
LOG_LEVEL	日志详细程度	info

配置示例：

export PORT=8080
export LOG_LEVEL=debug
npm start
# or for CLI mode:
PORT=8080 LOG_LEVEL=debug npx ios-mcp-code-quality-server server

配置

环境变量（含默认值）：

# Server Configuration
PORT=3000
NODE_ENV=development
LOG_LEVEL=info

# MCP Server Identity
MCP_SERVER_NAME=ios-mcp-code-quality-server
MCP_SERVER_VERSION=0.1.0

# Security Settings
ALLOWED_HOSTS=127.0.0.1,localhost,127.0.0.1:3000,localhost:3000
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX_REQUESTS=100

# Performance Settings
SESSION_CLEANUP_INTERVAL_MS=300000
MAX_CONCURRENT_TASKS=5

工具与功能

测试工具

运行 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 参数
  • 可用于指定不同的测试环境或配置

示例响应：

成功情况（所有测试均通过）：

{
  "content": [
    {
      "type": "text", 
      "text": "✅ All tests passed."
    }
  ]
}

构建错误情况（编译问题）：

{
  "content": [
    {
      "type": "text", 
      "text": "❌ Build failed. Please provide the code for the failing test and the class/function under test for better AI suggestions."
    }
  ]
}

测试错误情况（测试已构建但未通过）：

{
  "content": [
    {
      "type": "text", 
      "text": "❌ Test failed. Please provide the code for the failing test and the class/function under test for better AI suggestions."
    }
  ]
}

测试列表工具

发现并列出 iOS 项目中所有可用的测试。

参数：

• xcodeproj（可选）：Xcode 项目文件的路径
• xcworkspace（可选）：Xcode 工作区文件的路径
• 注意：必须提供 xcodeproj 或 xcworkspace 参数之一（至少提供一个）
• scheme（可选）：要分析的 Xcode scheme
• destination（可选）：测试目标（模拟器/设备）

Lint 工具

对 iOS 项目执行 lint 分析。目前支持的 lint 工具：SwiftLint

使用示例

命令行使用示例

直接测试：

# Run all tests in a scheme
npx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests

# Run tests with specific simulator
npx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests \
  --destination "platform=iOS Simulator,name=iPhone 15 Pro"

# Get machine-readable output for CI/CD
npx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests --json

代码质量分析：

# Lint specific files
npx ios-mcp-code-quality-server lint --changed-files "LoginView.swift,UserModel.swift"

# Lint with custom config
npx ios-mcp-code-quality-server lint --changed-files "*.swift" --config-path .swiftlint.yml

# Git workflow integration
git diff --name-only HEAD~1 | grep "\.swift$" | tr '\n' ',' | \
  npx ios-mcp-code-quality-server lint --changed-files

开发工作流：

# Pre-commit hook example
#!/bin/sh
changed_swift_files=$(git diff --cached --name-only --diff-filter=ACM | grep "\.swift$" | tr '\n' ',' | sed 's/,$//')
if [ -n "$changed_swift_files" ]; then
  npx ios-mcp-code-quality-server lint --changed-files "$changed_swift_files" || exit 1
fi

AI 助手用法（MCP 模式）

使用 AI 助手运行测试：

"Can you run the tests for the LoginFeature scheme and tell me what failed?"

"Run only the LoginTests for the MyApp scheme"

"List all available tests in my project and then run the failing ones"

AI 助手将使用增强的测试工具来：

1. 使用测试列表工具发现可用测试
2. 执行指定 scheme 的特定测试或所有测试
3. 验证测试名称，并为拼写错误提供建议
4. 解析构建和测试结果，并提供详细的失败分析
5. 提供结构化的失败摘要，包括文件位置和行号

代码质量分析：

"Please analyze the code quality of my iOS project using SwiftLint"

故障排除

常见问题

找不到 CLI 命令：

• 如果使用全局安装：在项目目录中运行 npm install -g .
• 否则使用：在项目目录中运行 node dist/index.js <command>
• 确认构建已完成：npm run build

服务无法启动：

• 检查端口 3000 是否可用：lsof -i :3000
• 确认已安装 Node.js 18+：node --version
• 确认依赖已安装：npm list

测试无法运行：

• 确认已安装 Xcode，且命令行工具可用
• 检查指定的方案是否存在于项目中
• 确认目标设备/模拟器可用：xcrun simctl list devices
• 对于 CLI 模式：确保 xcworkspace/xcodeproj 路径正确且可访问

SwiftLint 无法运行：

• 安装 SwiftLint：brew install swiftlint
• 验证安装：swiftlint version
• 对于 CLI 模式：确保已更改文件的路径正确，且文件存在

MCP 连接问题：

• 确认服务正在运行：使用 lsof -i :3000 检查端口 3000 上的进程是否处于活动状态
• 检查 AI 助手的 MCP 配置
• 查看服务日志中的连接错误

调试模式

启用详细日志以排查问题：

CLI 模式：

npx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests --verbose

MCP 服务模式：

export LOG_LEVEL=debug
npm start
# or
LOG_LEVEL=debug npx ios-mcp-code-quality-server server

开发

运行测试

# Run all tests
npm test

# Run with coverage
npm run test:coverage

代码质量

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Type checking
npm run type-check

构建

npm run build

贡献

欢迎贡献！请按以下步骤操作：

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 进行更改并添加测试
4. 确保所有测试通过：npm test
5. 提交更改：git commit -m 'Add amazing feature'
6. 将更改推送到你的分支：git push origin feature/amazing-feature
7. 发起 Pull Request

开发指南

• 为新功能编写测试
• 遵循 TypeScript 最佳实践
• 更新 API 变更对应的文档
• 尽可能确保向后兼容

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

安全

• 所有处理都在你的本地计算机上进行
• 未经明确配置，不会向外部服务发送数据
• 请勿公开分享本地服务端点
• 保持依赖项为最新版本，以修复安全漏洞

支持

• 问题：GitHub Issues
• 讨论：GitHub Discussions
• 文档：此 README 和内联代码文档

---

为 iOS 开发社区倾情打造 ❤️