A versatile iOS code quality analysis tool that operates in two modes: 1. CLI Tool: Direct command-line interface for iOS testing and linting 2. MCP Server: Model Context Protocol server for AI assistant integration This tool provides comprehensive iOS code quality analysis and test automation capabilities, enabling both direct developer usage and AI assistant integration for Xcode tests, linter a
Add this skill
npx mdskills install a-25/ios-mcp-code-quality-serverDual-mode iOS testing and linting tool with comprehensive MCP integration and clear CLI documentation
1# iOS MCP Code Quality Server23A versatile iOS code quality analysis tool that operates in two modes:41. **CLI Tool**: Direct command-line interface for iOS testing and linting52. **MCP Server**: Model Context Protocol server for AI assistant integration67This tool provides comprehensive iOS code quality analysis and test automation capabilities, enabling both direct developer usage and AI assistant integration for Xcode tests, linter analysis, and detailed feedback on iOS projects through structured, actionable reports.8910111213## Quick Start1415### CLI Mode (Direct Usage with npx - Recommended)1617**Use instantly without installation:**1819```bash20# Run iOS tests21npx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests2223# Run SwiftLint analysis24npx ios-mcp-code-quality-server lint --changed-files "ViewController.swift,Model.swift"2526# Show help27npx ios-mcp-code-quality-server --help28```2930### Alternative: Install Globally (Optional)3132For frequent use across multiple projects, you can install globally:3334```bash35npm install -g ios-mcp-code-quality-server3637# Then use the full name (following MCP conventions)38ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests39ios-mcp-code-quality-server lint --changed-files "ViewController.swift,Model.swift"40```4142> **💡 Tip:** Using `npx` is recommended as it ensures you always use the latest version without global installs.4344### MCP Server Mode (AI Assistant Integration)4546```bash47# Start as MCP server (no arguments)48npx ios-mcp-code-quality-server4950# Or explicitly start server mode51npx ios-mcp-code-quality-server server52```5354The server will start on `http://localhost:3000` and be ready to receive MCP requests.5556## Features5758- **🧪 iOS Test Execution**: Run Xcode tests with detailed failure analysis59- **📱 Multiple Schemes Support**: Test different iOS project configurations60- **🔍 SwiftLint Integration**: Automated Swift code style and quality checking61- **📊 Structured Reporting**: Clear, actionable feedback with file locations and line numbers62- **🛠 Build Error Detection**: Intelligent parsing of Xcode build failures63- **🔒 Local Processing**: All analysis happens on your machine for security64- **⚡ Dual Mode Operation**: Use as CLI tool or MCP server65- **💻 Command Line Interface**: Direct terminal usage for developers66- **🤖 AI Assistant Ready**: MCP protocol support for seamless AI integration6768## Architecture6970This tool operates in two distinct modes with intelligent detection:7172### CLI Mode73- **Activation**: When command-line arguments are provided74- **Usage**: Direct developer interaction via terminal commands or npx75- **Output**: Human-readable or JSON format for scripting76- **Benefits**: Fast execution, scriptable, CI/CD friendly, no installation required with npx7778### MCP Server Mode79- **Activation**: When no arguments are provided (default)80- **Usage**: AI assistant integration via Model Context Protocol81- **Output**: Structured MCP responses for AI consumption82- **Benefits**: AI-powered analysis, contextual suggestions, interactive debugging8384**Simple Mode Detection:**85```bash86# MCP Server Mode (no arguments)87npx ios-mcp-code-quality-server # → Starts MCP server88ios-mcp-code-quality-server # → Starts MCP server (if globally installed)8990# CLI Mode (arguments provided)91npx ios-mcp-code-quality-server --help # → CLI help92npx ios-mcp-code-quality-server test --help # → CLI test help93npx ios-mcp-code-quality-server lint --changed-files="file.swift" # → CLI lint94```9596## CLI Usage9798### No Installation Required99100Use `npx` to run the CLI directly without installation:101102```bash103npx ios-mcp-code-quality-server --help # Show all available commands104npx ios-mcp-code-quality-server <command> --help # Show help for specific command105```106107### Commands108109#### Test Command110Run iOS tests with comprehensive analysis:111112```bash113# Basic usage114npx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests115116# With specific destination117npx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests \118 --destination "platform=iOS Simulator,name=iPhone 15"119120# Using Xcode project instead of workspace121npx ios-mcp-code-quality-server test --xcodeproj MyApp.xcodeproj --scheme MyAppTests122123# Get JSON output for script integration124npx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests --json125126# Verbose logging for debugging127npx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests --verbose128```129130**Test Command Options:**131- `--xcworkspace <path>`: Path to .xcworkspace file132- `--xcodeproj <path>`: Path to .xcodeproj file (either xcworkspace or xcodeproj required)133- `--scheme <name>`: Scheme name for testing (required)134- `--destination <destination>`: Test destination (default: "platform=iOS Simulator")135- `--json`: Output results in JSON format136- `--verbose`: Enable verbose logging137138#### Lint Command139Run SwiftLint analysis on specific files:140141```bash142# Lint specific files143npx ios-mcp-code-quality-server lint --changed-files "ViewController.swift,Model.swift"144145# With custom SwiftLint configuration146npx ios-mcp-code-quality-server lint --changed-files "*.swift" --config-path .swiftlint.yml147148# Get JSON output149npx ios-mcp-code-quality-server lint --changed-files "ViewController.swift" --json150151# Verbose output152npx ios-mcp-code-quality-server lint --changed-files "*.swift" --verbose153```154155**Lint Command Options:**156- `--changed-files <files>`: Comma-separated list of files to lint (required)157- `--config-path <path>`: Path to SwiftLint configuration file158- `--json`: Output results in JSON format159- `--verbose`: Enable verbose logging160161#### Server Command162Start MCP server mode explicitly:163164```bash165# Start server on default port (3000)166npx ios-mcp-code-quality-server server167168# Start server on custom port169npx ios-mcp-code-quality-server server --port 8080170171# Server with custom settings172PORT=3001 LOG_LEVEL=debug npx ios-mcp-code-quality-server server173```174175### CLI Examples176177```bash178# Complete iOS project test workflow179npx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests --verbose180181# Quick SwiftLint check on modified files182git diff --name-only | grep "\.swift$" | xargs -I {} npx ios-mcp-code-quality-server lint --changed-files {}183184# CI/CD integration with JSON output185npx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests --json > test-results.json186187# Check specific Swift files before commit188npx ios-mcp-code-quality-server lint --changed-files "LoginViewController.swift,UserModel.swift" --config-path .swiftlint.yml189```190191## MCP Server Installation192193### Prerequisites194195- **Node.js 18+**: Required for running the MCP server196- **Xcode**: For iOS project building and testing197- **iOS Simulator**: For running tests (or physical iOS device)198- **SwiftLint** (optional): For code quality analysis199200### Setup Steps2012021. **Clone the repository:**203 ```bash204 git clone https://github.com/a-25/ios-mcp-code-quality-server.git205 cd ios-mcp-code-quality-server206 ```2072082. **Install dependencies:**209 ```bash210 npm install211 ```2122133. **Build the project:**214 ```bash215 npm run build216 ```2172184. **Start the server:**219 ```bash220 npm start221 # or explicitly222 node dist/index.js server223 ```224225### AI Assistant Integration226227Configure your AI assistant (Claude, Copilot, etc.) to use this MCP server:228229```json230{231 "mcpServers": {232 "ios-code-quality": {233 "url": "http://localhost:3000",234 "timeout": 30000235 }236 }237}238```239240## Configuration241242The server supports several configuration options through environment variables:243244| Variable | Description | Default |245|----------|-------------|---------|246| `PORT` | Server port | `3000` |247| `NODE_ENV` | Environment mode | `development` |248| `LOG_LEVEL` | Logging verbosity | `info` |249250Example configuration:251```bash252export PORT=8080253export LOG_LEVEL=debug254npm start255# or for CLI mode:256PORT=8080 LOG_LEVEL=debug npx ios-mcp-code-quality-server server257```258259### Configuration260261Environment variables (with defaults):262263```bash264# Server Configuration265PORT=3000266NODE_ENV=development267LOG_LEVEL=info268269# MCP Server Identity270MCP_SERVER_NAME=ios-mcp-code-quality-server271MCP_SERVER_VERSION=0.1.0272273# Security Settings274ALLOWED_HOSTS=127.0.0.1,localhost,127.0.0.1:3000,localhost:3000275RATE_LIMIT_WINDOW_MS=60000276RATE_LIMIT_MAX_REQUESTS=100277278# Performance Settings279SESSION_CLEANUP_INTERVAL_MS=300000280MAX_CONCURRENT_TASKS=5281```282283## Tools & Capabilities284285### Test Tool286Executes iOS tests and provides detailed failure analysis with support for running specific tests.287288**Parameters:**289- `xcodeproj` (optional): Path to Xcode project file290- `xcworkspace` (optional): Path to Xcode workspace file291- **Note**: Either `xcodeproj` or `xcworkspace` parameter is mandatory (at least one must be provided)292- `scheme` (required): Xcode scheme to test293- `destination` (optional): Test destination (simulator/device)294 - Default value: `generic/platform=iOS Simulator`295- `tests` (optional): Array of specific test names to run296 - Format: `['MyTarget/TestClass/testMethod', 'MyTarget/TestClass']`297 - Examples: `['MyAppTests/LoginTests/testValidLogin', 'MyAppUITests/HomeScreenTests']`298- `target` (optional): Target parameter for test execution context299 - Can be used to specify different test environments or configurations300301**Example Responses:**302303**Success Case (all tests passed):**304```json305{306 "content": [307 {308 "type": "text",309 "text": "✅ All tests passed."310 }311 ]312}313```314315**Build Errors Case (compilation issues):**316```json317{318 "content": [319 {320 "type": "text",321 "text": "❌ Build failed. Please provide the code for the failing test and the class/function under test for better AI suggestions."322 }323 ]324}325```326327**Test Errors Case (tests built but failed):**328```json329{330 "content": [331 {332 "type": "text",333 "text": "❌ Test failed. Please provide the code for the failing test and the class/function under test for better AI suggestions."334 }335 ]336}337```338339### List Tests Tool340Discovers and lists all available tests in the iOS project.341342**Parameters:**343- `xcodeproj` (optional): Path to Xcode project file344- `xcworkspace` (optional): Path to Xcode workspace file345- **Note**: Either `xcodeproj` or `xcworkspace` parameter is mandatory (at least one must be provided)346- `scheme` (optional): Xcode scheme to analyze347- `destination` (optional): Test destination (simulator/device)348349### Lint Tool350Performs lint analysis on your iOS project. Currently supported linters: [SwiftLint](https://github.com/realm/SwiftLint)351352## Usage Examples353354### CLI Usage Examples355356**Direct Testing:**357```bash358# Run all tests in a scheme359npx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests360361# Run tests with specific simulator362npx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests \363 --destination "platform=iOS Simulator,name=iPhone 15 Pro"364365# Get machine-readable output for CI/CD366npx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests --json367```368369**Code Quality Analysis:**370```bash371# Lint specific files372npx ios-mcp-code-quality-server lint --changed-files "LoginView.swift,UserModel.swift"373374# Lint with custom config375npx ios-mcp-code-quality-server lint --changed-files "*.swift" --config-path .swiftlint.yml376377# Git workflow integration378git diff --name-only HEAD~1 | grep "\.swift$" | tr '\n' ',' | \379 npx ios-mcp-code-quality-server lint --changed-files380```381382**Development Workflow:**383```bash384# Pre-commit hook example385#!/bin/sh386changed_swift_files=$(git diff --cached --name-only --diff-filter=ACM | grep "\.swift$" | tr '\n' ',' | sed 's/,$//')387if [ -n "$changed_swift_files" ]; then388 npx ios-mcp-code-quality-server lint --changed-files "$changed_swift_files" || exit 1389fi390```391392### AI Assistant Usage (MCP Mode)393394**Running Tests with AI Assistant:**395396```397"Can you run the tests for the LoginFeature scheme and tell me what failed?"398```399400```401"Run only the LoginTests for the MyApp scheme"402```403404```405"List all available tests in my project and then run the failing ones"406```407408The AI assistant will use the enhanced test tools to:4091. Discover available tests using the list-tests tool4102. Execute specific tests or all tests for the specified scheme4113. Validate test names and provide suggestions for typos4124. Parse build and test results with detailed failure analysis4135. Provide structured summaries of failures with file locations and line numbers414415**Code Quality Analysis:**416417```418"Please analyze the code quality of my iOS project using SwiftLint"419```420421## Troubleshooting422423### Common Issues424425**CLI command not found:**426- If using global install: `npm install -g .` from the project directory427- Otherwise use: `node dist/index.js <command>` from the project directory428- Verify build completed: `npm run build`429430**Server won't start:**431- Check that port 3000 is available: `lsof -i :3000`432- Ensure Node.js 18+ is installed: `node --version`433- Verify dependencies are installed: `npm list`434435**Tests fail to run:**436- Ensure Xcode is installed and command line tools are available437- Check that the specified scheme exists in your project438- Verify the destination device/simulator is available: `xcrun simctl list devices`439- For CLI mode: ensure xcworkspace/xcodeproj paths are correct and accessible440441**SwiftLint not working:**442- Install SwiftLint: `brew install swiftlint`443- Verify installation: `swiftlint version`444- For CLI mode: ensure changed-files paths are correct and files exist445446**MCP Connection Issues:**447- Verify the server is running: check that the process is active on port 3000 with `lsof -i :3000`448- Check AI assistant MCP configuration449- Review server logs for connection errors450451### Debug Mode452453Enable detailed logging for troubleshooting:454455**CLI Mode:**456```bash457npx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests --verbose458```459460**MCP Server Mode:**461```bash462export LOG_LEVEL=debug463npm start464# or465LOG_LEVEL=debug npx ios-mcp-code-quality-server server466```467468## Development469470### Running Tests471472```bash473# Run all tests474npm test475476# Run with coverage477npm run test:coverage478```479480### Code Quality481482```bash483# Run linter484npm run lint485486# Fix linting issues487npm run lint:fix488489# Type checking490npm run type-check491```492493### Building494495```bash496npm run build497```498499## Contributing500501We welcome contributions! Please follow these steps:5025031. Fork the repository5042. Create a feature branch: `git checkout -b feature/amazing-feature`5053. Make your changes and add tests5064. Ensure all tests pass: `npm test`5075. Commit your changes: `git commit -m 'Add amazing feature'`5086. Push to your branch: `git push origin feature/amazing-feature`5097. Open a Pull Request510511### Development Guidelines512513- Write tests for new features514- Follow TypeScript best practices515- Update documentation for API changes516- Ensure backwards compatibility when possible517518## License519520This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.521522## Security523524- All processing happens locally on your machine525- No data is sent to external services without explicit configuration526- Do not share your local server endpoint publicly527- Keep dependencies updated to address security vulnerabilities528529## Support530531- **Issues**: [GitHub Issues](https://github.com/a-25/ios-mcp-code-quality-server/issues)532- **Discussions**: [GitHub Discussions](https://github.com/a-25/ios-mcp-code-quality-server/discussions)533- **Documentation**: This README and inline code documentation534535---536537Made with ❤️ for the iOS development community
Full transparency — inspect the skill content before installing.