{"id":50534636,"url":"https://github.com/a-25/ios-mcp-code-quality-server","last_synced_at":"2026-06-20T10:01:06.144Z","repository":{"id":306740419,"uuid":"1027061807","full_name":"a-25/ios-mcp-code-quality-server","owner":"a-25","description":"This server enables AI assistants to run Xcode tests, perform linter analysis, and provide detailed feedback on iOS projects through structured, actionable reports.","archived":false,"fork":false,"pushed_at":"2025-09-21T19:59:51.000Z","size":100072,"stargazers_count":1,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-21T20:34:46.763Z","etag":null,"topics":["autotest","linter","model-context-protocol-server","swift","swiftlint","xcode"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/a-25.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-27T08:20:03.000Z","updated_at":"2025-09-21T19:34:19.000Z","dependencies_parsed_at":"2025-07-27T11:19:24.061Z","dependency_job_id":"0f435ddc-89c5-41c8-abab-917efe697e27","html_url":"https://github.com/a-25/ios-mcp-code-quality-server","commit_stats":null,"previous_names":["a-25/ios-mcp-code-quality-server"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/a-25/ios-mcp-code-quality-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-25%2Fios-mcp-code-quality-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-25%2Fios-mcp-code-quality-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-25%2Fios-mcp-code-quality-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-25%2Fios-mcp-code-quality-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/a-25","download_url":"https://codeload.github.com/a-25/ios-mcp-code-quality-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a-25%2Fios-mcp-code-quality-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34565244,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["autotest","linter","model-context-protocol-server","swift","swiftlint","xcode"],"created_at":"2026-06-03T16:00:32.418Z","updated_at":"2026-06-20T10:01:06.137Z","avatar_url":"https://github.com/a-25.png","language":"TypeScript","funding_links":[],"categories":["📦 Other"],"sub_categories":[],"readme":"# iOS MCP Code Quality Server\n\nA versatile iOS code quality analysis tool that operates in two modes:\n1. **CLI Tool**: Direct command-line interface for iOS testing and linting\n2. **MCP Server**: Model Context Protocol server for AI assistant integration\n\nThis 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.\n\n![License](https://img.shields.io/github/license/a-25/ios-mcp-code-quality-server)\n![Tests](https://img.shields.io/github/actions/workflow/status/a-25/ios-mcp-code-quality-server/test.yml)\n![Node Version](https://img.shields.io/node/v/ios-mcp-code-quality-server)\n\n## Quick Start\n\n### CLI Mode (Direct Usage with npx - Recommended)\n\n**Use instantly without installation:**\n\n```bash\n# Run iOS tests\nnpx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests\n\n# Run SwiftLint analysis\nnpx ios-mcp-code-quality-server lint --changed-files \"ViewController.swift,Model.swift\"\n\n# Show help\nnpx ios-mcp-code-quality-server --help\n```\n\n### Alternative: Install Globally (Optional)\n\nFor frequent use across multiple projects, you can install globally:\n\n```bash\nnpm install -g ios-mcp-code-quality-server\n\n# Then use the full name (following MCP conventions)\nios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests\nios-mcp-code-quality-server lint --changed-files \"ViewController.swift,Model.swift\"\n```\n\n\u003e **💡 Tip:** Using `npx` is recommended as it ensures you always use the latest version without global installs.\n\n### MCP Server Mode (AI Assistant Integration)\n\n```bash\n# Start as MCP server (no arguments)\nnpx ios-mcp-code-quality-server\n\n# Or explicitly start server mode\nnpx ios-mcp-code-quality-server server\n```\n\nThe server will start on `http://localhost:3000` and be ready to receive MCP requests.\n\n## Features\n\n- **🧪 iOS Test Execution**: Run Xcode tests with detailed failure analysis\n- **📱 Multiple Schemes Support**: Test different iOS project configurations  \n- **🔍 SwiftLint Integration**: Automated Swift code style and quality checking\n- **📊 Structured Reporting**: Clear, actionable feedback with file locations and line numbers\n- **🛠 Build Error Detection**: Intelligent parsing of Xcode build failures\n- **🔒 Local Processing**: All analysis happens on your machine for security\n- **⚡ Dual Mode Operation**: Use as CLI tool or MCP server\n- **💻 Command Line Interface**: Direct terminal usage for developers\n- **🤖 AI Assistant Ready**: MCP protocol support for seamless AI integration\n\n## Architecture\n\nThis tool operates in two distinct modes with intelligent detection:\n\n### CLI Mode\n- **Activation**: When command-line arguments are provided\n- **Usage**: Direct developer interaction via terminal commands or npx\n- **Output**: Human-readable or JSON format for scripting\n- **Benefits**: Fast execution, scriptable, CI/CD friendly, no installation required with npx\n\n### MCP Server Mode  \n- **Activation**: When no arguments are provided (default)\n- **Usage**: AI assistant integration via Model Context Protocol\n- **Output**: Structured MCP responses for AI consumption\n- **Benefits**: AI-powered analysis, contextual suggestions, interactive debugging\n\n**Simple Mode Detection:**\n```bash\n# MCP Server Mode (no arguments)\nnpx ios-mcp-code-quality-server          # → Starts MCP server\nios-mcp-code-quality-server              # → Starts MCP server (if globally installed)\n\n# CLI Mode (arguments provided)  \nnpx ios-mcp-code-quality-server --help           # → CLI help\nnpx ios-mcp-code-quality-server test --help      # → CLI test help\nnpx ios-mcp-code-quality-server lint --changed-files=\"file.swift\"  # → CLI lint\n```\n\n## CLI Usage\n\n### No Installation Required\n\nUse `npx` to run the CLI directly without installation:\n\n```bash\nnpx ios-mcp-code-quality-server --help              # Show all available commands\nnpx ios-mcp-code-quality-server \u003ccommand\u003e --help    # Show help for specific command\n```\n\n### Commands\n\n#### Test Command\nRun iOS tests with comprehensive analysis:\n\n```bash\n# Basic usage\nnpx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests\n\n# With specific destination\nnpx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests \\\n  --destination \"platform=iOS Simulator,name=iPhone 15\"\n\n# Using Xcode project instead of workspace\nnpx ios-mcp-code-quality-server test --xcodeproj MyApp.xcodeproj --scheme MyAppTests\n\n# Get JSON output for script integration\nnpx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests --json\n\n# Verbose logging for debugging\nnpx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests --verbose\n```\n\n**Test Command Options:**\n- `--xcworkspace \u003cpath\u003e`: Path to .xcworkspace file\n- `--xcodeproj \u003cpath\u003e`: Path to .xcodeproj file (either xcworkspace or xcodeproj required)\n- `--scheme \u003cname\u003e`: Scheme name for testing (required)\n- `--destination \u003cdestination\u003e`: Test destination (default: \"platform=iOS Simulator\")\n- `--json`: Output results in JSON format\n- `--verbose`: Enable verbose logging\n\n#### Lint Command\nRun SwiftLint analysis on specific files:\n\n```bash\n# Lint specific files\nnpx ios-mcp-code-quality-server lint --changed-files \"ViewController.swift,Model.swift\"\n\n# With custom SwiftLint configuration\nnpx ios-mcp-code-quality-server lint --changed-files \"*.swift\" --config-path .swiftlint.yml\n\n# Get JSON output\nnpx ios-mcp-code-quality-server lint --changed-files \"ViewController.swift\" --json\n\n# Verbose output\nnpx ios-mcp-code-quality-server lint --changed-files \"*.swift\" --verbose\n```\n\n**Lint Command Options:**\n- `--changed-files \u003cfiles\u003e`: Comma-separated list of files to lint (required)\n- `--config-path \u003cpath\u003e`: Path to SwiftLint configuration file\n- `--json`: Output results in JSON format\n- `--verbose`: Enable verbose logging\n\n#### Server Command\nStart MCP server mode explicitly:\n\n```bash\n# Start server on default port (3000)\nnpx ios-mcp-code-quality-server server\n\n# Start server on custom port\nnpx ios-mcp-code-quality-server server --port 8080\n\n# Server with custom settings\nPORT=3001 LOG_LEVEL=debug npx ios-mcp-code-quality-server server\n```\n\n### CLI Examples\n\n```bash\n# Complete iOS project test workflow\nnpx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests --verbose\n\n# Quick SwiftLint check on modified files\ngit diff --name-only | grep \"\\.swift$\" | xargs -I {} npx ios-mcp-code-quality-server lint --changed-files {}\n\n# CI/CD integration with JSON output\nnpx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests --json \u003e test-results.json\n\n# Check specific Swift files before commit\nnpx ios-mcp-code-quality-server lint --changed-files \"LoginViewController.swift,UserModel.swift\" --config-path .swiftlint.yml\n```\n\n## MCP Server Installation\n\n### Prerequisites\n\n- **Node.js 18+**: Required for running the MCP server\n- **Xcode**: For iOS project building and testing\n- **iOS Simulator**: For running tests (or physical iOS device)\n- **SwiftLint** (optional): For code quality analysis\n\n### Setup Steps\n\n1. **Clone the repository:**\n   ```bash\n   git clone https://github.com/a-25/ios-mcp-code-quality-server.git\n   cd ios-mcp-code-quality-server\n   ```\n\n2. **Install dependencies:**\n   ```bash\n   npm install\n   ```\n\n3. **Build the project:**\n   ```bash\n   npm run build\n   ```\n\n4. **Start the server:**\n   ```bash\n   npm start\n   # or explicitly\n   node dist/index.js server\n   ```\n\n### AI Assistant Integration\n\nConfigure your AI assistant (Claude, Copilot, etc.) to use this MCP server:\n\n```json\n{\n  \"mcpServers\": {\n    \"ios-code-quality\": {\n      \"url\": \"http://localhost:3000\",\n      \"timeout\": 30000\n    }\n  }\n}\n```\n\n## Configuration\n\nThe server supports several configuration options through environment variables:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `PORT` | Server port | `3000` |\n| `NODE_ENV` | Environment mode | `development` |\n| `LOG_LEVEL` | Logging verbosity | `info` |\n\nExample configuration:\n```bash\nexport PORT=8080\nexport LOG_LEVEL=debug\nnpm start\n# or for CLI mode:\nPORT=8080 LOG_LEVEL=debug npx ios-mcp-code-quality-server server\n```\n\n### Configuration\n\nEnvironment variables (with defaults):\n\n```bash\n# Server Configuration\nPORT=3000\nNODE_ENV=development\nLOG_LEVEL=info\n\n# MCP Server Identity\nMCP_SERVER_NAME=ios-mcp-code-quality-server\nMCP_SERVER_VERSION=0.1.0\n\n# Security Settings\nALLOWED_HOSTS=127.0.0.1,localhost,127.0.0.1:3000,localhost:3000\nRATE_LIMIT_WINDOW_MS=60000\nRATE_LIMIT_MAX_REQUESTS=100\n\n# Performance Settings\nSESSION_CLEANUP_INTERVAL_MS=300000\nMAX_CONCURRENT_TASKS=5\n```\n\n## Tools \u0026 Capabilities\n\n### Test Tool\nExecutes iOS tests and provides detailed failure analysis with support for running specific tests.\n\n**Parameters:**\n- `xcodeproj` (optional): Path to Xcode project file\n- `xcworkspace` (optional): Path to Xcode workspace file\n- **Note**: Either `xcodeproj` or `xcworkspace` parameter is mandatory (at least one must be provided)\n- `scheme` (required): Xcode scheme to test\n- `destination` (optional): Test destination (simulator/device)\n  - Default value: `generic/platform=iOS Simulator`\n- `tests` (optional): Array of specific test names to run\n  - Format: `['MyTarget/TestClass/testMethod', 'MyTarget/TestClass']`\n  - Examples: `['MyAppTests/LoginTests/testValidLogin', 'MyAppUITests/HomeScreenTests']`\n- `target` (optional): Target parameter for test execution context\n  - Can be used to specify different test environments or configurations\n\n**Example Responses:**\n\n**Success Case (all tests passed):**\n```json\n{\n  \"content\": [\n    {\n      \"type\": \"text\", \n      \"text\": \"✅ All tests passed.\"\n    }\n  ]\n}\n```\n\n**Build Errors Case (compilation issues):**\n```json\n{\n  \"content\": [\n    {\n      \"type\": \"text\", \n      \"text\": \"❌ Build failed. Please provide the code for the failing test and the class/function under test for better AI suggestions.\"\n    }\n  ]\n}\n```\n\n**Test Errors Case (tests built but failed):**\n```json\n{\n  \"content\": [\n    {\n      \"type\": \"text\", \n      \"text\": \"❌ Test failed. Please provide the code for the failing test and the class/function under test for better AI suggestions.\"\n    }\n  ]\n}\n```\n\n### List Tests Tool\nDiscovers and lists all available tests in the iOS project.\n\n**Parameters:**\n- `xcodeproj` (optional): Path to Xcode project file\n- `xcworkspace` (optional): Path to Xcode workspace file\n- **Note**: Either `xcodeproj` or `xcworkspace` parameter is mandatory (at least one must be provided)\n- `scheme` (optional): Xcode scheme to analyze\n- `destination` (optional): Test destination (simulator/device)\n\n### Lint Tool\nPerforms lint analysis on your iOS project. Currently supported linters: [SwiftLint](https://github.com/realm/SwiftLint)\n\n## Usage Examples\n\n### CLI Usage Examples\n\n**Direct Testing:**\n```bash\n# Run all tests in a scheme\nnpx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests\n\n# Run tests with specific simulator\nnpx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests \\\n  --destination \"platform=iOS Simulator,name=iPhone 15 Pro\"\n\n# Get machine-readable output for CI/CD\nnpx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests --json\n```\n\n**Code Quality Analysis:**\n```bash\n# Lint specific files\nnpx ios-mcp-code-quality-server lint --changed-files \"LoginView.swift,UserModel.swift\"\n\n# Lint with custom config\nnpx ios-mcp-code-quality-server lint --changed-files \"*.swift\" --config-path .swiftlint.yml\n\n# Git workflow integration\ngit diff --name-only HEAD~1 | grep \"\\.swift$\" | tr '\\n' ',' | \\\n  npx ios-mcp-code-quality-server lint --changed-files\n```\n\n**Development Workflow:**\n```bash\n# Pre-commit hook example\n#!/bin/sh\nchanged_swift_files=$(git diff --cached --name-only --diff-filter=ACM | grep \"\\.swift$\" | tr '\\n' ',' | sed 's/,$//')\nif [ -n \"$changed_swift_files\" ]; then\n  npx ios-mcp-code-quality-server lint --changed-files \"$changed_swift_files\" || exit 1\nfi\n```\n\n### AI Assistant Usage (MCP Mode)\n\n**Running Tests with AI Assistant:**\n\n```\n\"Can you run the tests for the LoginFeature scheme and tell me what failed?\"\n```\n\n```\n\"Run only the LoginTests for the MyApp scheme\"\n```\n\n```\n\"List all available tests in my project and then run the failing ones\"\n```\n\nThe AI assistant will use the enhanced test tools to:\n1. Discover available tests using the list-tests tool\n2. Execute specific tests or all tests for the specified scheme\n3. Validate test names and provide suggestions for typos\n4. Parse build and test results with detailed failure analysis\n5. Provide structured summaries of failures with file locations and line numbers\n\n**Code Quality Analysis:**\n\n```\n\"Please analyze the code quality of my iOS project using SwiftLint\"\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**CLI command not found:**\n- If using global install: `npm install -g .` from the project directory\n- Otherwise use: `node dist/index.js \u003ccommand\u003e` from the project directory\n- Verify build completed: `npm run build`\n\n**Server won't start:**\n- Check that port 3000 is available: `lsof -i :3000`\n- Ensure Node.js 18+ is installed: `node --version`\n- Verify dependencies are installed: `npm list`\n\n**Tests fail to run:**\n- Ensure Xcode is installed and command line tools are available\n- Check that the specified scheme exists in your project\n- Verify the destination device/simulator is available: `xcrun simctl list devices`\n- For CLI mode: ensure xcworkspace/xcodeproj paths are correct and accessible\n\n**SwiftLint not working:**\n- Install SwiftLint: `brew install swiftlint`\n- Verify installation: `swiftlint version`\n- For CLI mode: ensure changed-files paths are correct and files exist\n\n**MCP Connection Issues:**\n- Verify the server is running: check that the process is active on port 3000 with `lsof -i :3000`\n- Check AI assistant MCP configuration\n- Review server logs for connection errors\n\n### Debug Mode\n\nEnable detailed logging for troubleshooting:\n\n**CLI Mode:**\n```bash\nnpx ios-mcp-code-quality-server test --xcworkspace MyApp.xcworkspace --scheme MyAppTests --verbose\n```\n\n**MCP Server Mode:**\n```bash\nexport LOG_LEVEL=debug\nnpm start\n# or\nLOG_LEVEL=debug npx ios-mcp-code-quality-server server\n```\n\n## Development\n\n### Running Tests\n\n```bash\n# Run all tests\nnpm test\n\n# Run with coverage\nnpm run test:coverage\n```\n\n### Code Quality\n\n```bash\n# Run linter\nnpm run lint\n\n# Fix linting issues\nnpm run lint:fix\n\n# Type checking\nnpm run type-check\n```\n\n### Building\n\n```bash\nnpm run build\n```\n\n## Contributing\n\nWe welcome contributions! Please follow these steps:\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes and add tests\n4. Ensure all tests pass: `npm test`\n5. Commit your changes: `git commit -m 'Add amazing feature'`\n6. Push to your branch: `git push origin feature/amazing-feature`\n7. Open a Pull Request\n\n### Development Guidelines\n\n- Write tests for new features\n- Follow TypeScript best practices\n- Update documentation for API changes\n- Ensure backwards compatibility when possible\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Security\n\n- All processing happens locally on your machine\n- No data is sent to external services without explicit configuration\n- Do not share your local server endpoint publicly\n- Keep dependencies updated to address security vulnerabilities\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/a-25/ios-mcp-code-quality-server/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/a-25/ios-mcp-code-quality-server/discussions)\n- **Documentation**: This README and inline code documentation\n\n---\n\nMade with ❤️ for the iOS development community","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa-25%2Fios-mcp-code-quality-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fa-25%2Fios-mcp-code-quality-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa-25%2Fios-mcp-code-quality-server/lists"}