ios-mcp-code-quality-server

iOS MCP Code Quality Server is an iOS code quality analysis and test automation tool that intelligently switches between two modes: command-line tool (CLI) and Model Context Protocol (MCP) server. Its goal is to provide developers and AI assistants with a unified entry point for Xcode tests, linter analysis, and structured feedback on iOS projects.

Purpose and Positioning The tool serves two usage modes at the same time. First, developers can run it directly in the terminal to execute iOS tests and code inspections; it is scriptable and suitable for CI/CD. Second, it can be connected as an MCP server to AI assistants, enabling AI assistants to run Xcode tests, perform linter analysis, and return reports in a structured, actionable form.

Main Capabilities

• iOS test execution: Run Xcode tests and provide detailed failure analysis.
• Multi-scheme support: Test according to different iOS project configurations.
• SwiftLint integration: Automate Swift code style and quality checks (the currently supported linter is SwiftLint).
• Structured reports: Output clear, actionable feedback, including file locations and line numbers.
• Build error detection: Intelligently parse Xcode build failures.
• Local processing: All analysis is completed on the local machine, ensuring security.
• Dual-mode operation: Can be used as both a CLI tool and an MCP server.
• AI assistant ready: Supports the MCP protocol, making integration with AI assistants easy.

Modes and Behavior The tool automatically determines the mode based on whether command-line arguments are passed:

• CLI mode: Activated when command-line arguments are provided, oriented toward direct terminal interaction, and can output human-readable or JSON format for easy script processing; its advantages are fast execution, scriptability, friendliness to CI/CD, and no installation required when used with npx.
• MCP server mode: Activated by default when no arguments are provided, used for integration with AI assistants through the MCP protocol, and outputs structured MCP responses for AI consumption; its advantages are AI-driven analysis, contextual suggestions, and interactive debugging.

Usage (CLI) It is recommended to run directly through npx without installation. Global installation is also optional for use across multiple projects; note that using npx ensures the latest version is always used without global installation. Run iOS tests and get a full analysis:

• --xcworkspace <path>: Path to the .xcworkspace file.
• --xcodeproj <path>: Path to the .xcodeproj file (at least one of xcworkspace or xcodeproj must be provided).
• --scheme <name>: Scheme name used for testing (required).
• --destination <destination>: Test destination (default "platform=iOS Simulator").
• --json: Output results in JSON format.
• --verbose: Enable verbose logging. Run SwiftLint analysis on specified files:
• --changed-files <files>: List of files to check, comma-separated (required).
• --config-path <path>: Path to the SwiftLint configuration file. Explicitly start MCP server mode.

MCP Server Installation and Startup Dependencies: Node.js 18+ (required to run the MCP server), Xcode (for building and testing iOS projects), iOS Simulator (for running tests, or use a physical iOS device), SwiftLint (optional, for code quality analysis). Steps: Clone the repository (git clone https://github.com/a-25/ios-mcp-code-quality-server.git and cd ios-mcp-code-quality-server); install dependencies with npm install; build the project with npm run build; start the server with npm start (or explicitly node dist/index.js server). After the server starts, it listens on http://localhost:3000，准备接收 MCP request.

AI assistant integration This MCP server can be configured for AI assistants (such as Claude, Copilot, etc.). The server supports several configuration options via environment variables. Example configuration and environment variables (including default values) are provided in the project.

Tools and capabilities (MCP) iOS test execution tool: Executes iOS tests and provides detailed failure analysis, with support for running specific tests. Parameters include:

• xcodeproj (optional): Path to the Xcode project file.
• xcworkspace (optional): Path to the Xcode workspace file. Note: At least one of xcodeproj or xcworkspace must be provided.
• scheme (required): The Xcode scheme to test.
• destination (optional): The test destination (simulator/device), default value generic/platform=iOS Simulator.
• tests (optional): An array of specific test names to run. Format: ['MyTarget/TestClass/testMethod', 'MyTarget/TestClass']; example: ['MyAppTests/LoginTests/testValidLogin', 'MyAppUITests/HomeScreenTests'].
• target (optional): The target parameter for the test execution context, which can be used to specify a different test environment or configuration. Example responses cover three cases: success (all tests pass), build error (compilation issues), and test error (tests built but failed). List tests tool: Discovers and lists all available tests in an iOS project. Parameters include scheme (optional) and destination (optional). Code inspection tool: Performs lint analysis on an iOS project. The currently supported linter is SwiftLint.

CLI usage example scenarios

• Direct testing.
• Code quality analysis.
• Development workflow.

AI assistant usage (MCP mode) When running tests, the AI assistant will use enhanced testing tools: discover available tests via the list-tests tool; execute specific tests or all tests for a specified scheme; validate test names and provide suggestions for spelling errors; parse build and test results and provide detailed failure analysis; provide file locations and lineStructured failure summary for issue #.

Use cases

• Developers quickly run iOS tests and SwiftLint checks in a local terminal.
• Scripted invocation of tests and checks in CI/CD with JSON output.
• Connect test and code quality analysis capabilities to AI assistants for interactive debugging and contextual suggestions.
• Teams that need local processing without sending code and test data externally.

Limitations and considerations

• Requires Node.js 18+, Xcode, and an iOS simulator (or physical device); SwiftLint is an optional dependency and must be installed separately if code quality analysis is needed.
• To run tests on a simulator or real device, the destination must be available.
• This tool runs locally, and all processing is done on the local machine; unless explicitly configured, it will not send data to external services. Do not publicly share the local server endpoint.
• The MCP server listens on port 3000 by default.

Troubleshooting (provided by the project)

• CLI command not found: if installed globally, run npm install -g . in the project directory; otherwise use node dist/index.js <command> in the project directory; confirm the build has completed with npm run build.
• Server fails to start: check whether port 3000 is available (lsof -i :3000); confirm Node.js 18+ (node --version); confirm dependencies are installed (npm list).
• Tests cannot run: confirm Xcode is installed and command line tools are available; confirm the specified scheme exists; confirm the target device/simulator is available (xcrun simctl list devices); in CLI mode, confirm the xcworkspace/xcodeproj path is correct and accessible.
• SwiftLint does not work: install SwiftLint (brew install swiftlint); verify the installation (swiftlint version); in CLI mode, confirm the changed-files path is correct and the files exist.
• MCP connection issues: confirm the server is running (use lsof -i :3000 to check the process); check the AI assistant's MCP configuration; review the server logs for connection errors; verbose logging can be enabled for troubleshooting.

Contributing and license The project welcomes contributions, and the process is: fork the repository, create a featurebranch (git checkout -b feature/amazing-feature), make changes and add tests, ensure all tests pass (npm test), commit (git commit -m 'Add amazing feature'), push the branch (git push origin feature/amazing-feature), and open a Pull Request. Development guidelines include: write tests for new features, follow TypeScript best practices, update documentation when APIs change, and maintain backward compatibility whenever possible. The project uses the MIT license, see the LICENSE file for details.