Ios MCP Code Quality Server

iOS MCP代码质量服务器

一个多功能的iOS代码质量分析工具，可在两种模式下运行：

1. CLI工具：用于iOS测试和linting的直接命令行界面
2. MCP服务器：用于AI助手集成的模型上下文协议服务器

该工具提供全面的iOS代码质量分析和测试自动化功能，使开发人员能够直接使用Xcode测试、linter分析和通过结构化、可操作的报告对iOS项目进行详细反馈。

快速开始

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测试并进行详细的故障分析
• 📱 多种方案支持：测试不同的iOS项目配置
• 🔍 SwiftLint集成：自动Swift代码风格和质量检查
• 📊 结构化报告：清晰、可操作的反馈，包括文件位置和行号
• 🛠 构建错误检测：Xcode构建失败的智能解析
• 🔒 本地处理：为了安全起见，所有分析都在您的计算机上进行
• ⚡ 双模式操作：用作CLI工具或MCP服务器
• 💻 命令行接口：开发人员直接使用终端
• 🤖 AI助手就绪：MCP协议支持无缝AI集成

建筑

该工具以两种不同的智能检测模式运行：

命令行接口命令模式

• 激活：当提供命令行参数时
• 用法：通过终端命令或npx直接与开发人员交互
• 输出：用于脚本编写的可读或JSON格式
• 益处：执行速度快，可编写脚本，对CI/CD友好，无需安装npx

MCP服务器模式

• 激活：不提供参数时（默认）
• 用法：通过模型上下文协议集成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  --help    # Show help for specific command

命令

测试命令

运行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

测试命令选项：

• `--xcworkspace

`：.xcworkspace文件的路径

• `--xcodeproj

`：.xcodeproj文件的路径（需要xcworkspace或xcodeproj）

• --scheme ：测试方案名称（必填）
• --destination ：测试目标（默认：“平台=iOS模拟器”）
• --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 ：以逗号分隔的文件列表（必填）
• `--config-path

`：SwiftLint配置文件的路径

• --json：以JSON格式输出结果
• --verbose：启用详细日志记录

服务器命令

显式启动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服务器所需
• 项目：用于iOS项目构建和测试
• iOS模拟器：用于运行测试（或物理iOS设备）
• SwiftLint （可选）：用于代码质量分析

设置步骤

1. 克隆存储库：

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

1. 安装依赖项：

   npm install

1. 构建项目：

   npm run build

1. 启动服务器：

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

AI助手集成

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

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

配置

服务器通过环境变量支持多种配置选项：

配置示例：

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方案
• destination （可选）：测试目的地（模拟器/设备）

- 默认值： generic/platform=iOS Simulator

• tests （可选）：要运行的特定测试名称数组

- 格式： ['MyTarget/TestClass/testMethod', 'MyTarget/TestClass'] - 示例： ['MyAppTests/LoginTests/testValidLogin', 'MyAppUITests/HomeScreenTests']

• 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方案分析
• destination （可选）：测试目的地（模拟器/设备）

棉绒工具

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

使用示例

CLI使用示例

直接测试：

# 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. 对指定方案执行特定测试或所有测试
3. 验证测试名称并提供拼写错误建议
4. 解析构建和测试结果，并进行详细的故障分析
5. 提供带有文件位置和行号的结构化故障摘要

代码质量分析：

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

故障排除

常见问题

未找到CLI命令：

• 如果使用全局安装： npm install -g . 从项目目录
• 否则使用： node dist/index.js 从项目目录
• 验证构建已完成： 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连接问题：

• 验证服务器是否正在运行：使用以下命令检查进程是否在端口3000上处于活动状态 lsof -i :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. 分叉存储库
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. 打开拉取请求

开发指南

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

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

安全

• 所有处理都在您的机器上本地进行
• 未经明确配置，不会向外部服务发送任何数据
• 不要公开共享本地服务器终结点
• 保持依赖关系更新以解决安全漏洞

支持

• 问题:
• 讨论:
• 文档：此README和内联代码文档

______________________________________________________________________

由以下材料制成❤️ 面向iOS开发社区