Ios Mcp Code Quality Server

iOS MCP Code Quality Server

2 つのモードで動作する、多機能な iOS コード品質分析ツールです。

1. CLI ツール：iOS のテストとリントを直接実行するコマンドラインインターフェイス
2. MCP サーバー：AI アシスタントと連携するための Model Context Protocol サーバー

このツールは、包括的な iOS コード品質分析とテスト自動化機能を提供します。開発者が直接利用できるほか、AI アシスタントと連携して、Xcode テストやリンター分析を実行し、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 とシームレスに連携できます

アーキテクチャ

このツールは、インテリジェントな判定により、2 つの異なるモードで動作します。

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>：テストに使用するスキーム名（必須）
• --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>：リント対象ファイルのカンマ区切りリスト（必須）
• --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 アシスタントとの連携

この MCP サーバーを使用するように、AI アシスタント（Claude、Copilot など）を設定します：

{
  "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 スキーム
• 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 プロジェクトのリント分析を実行します。現在サポートされているリンター：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. list-tests ツールを使用して利用可能なテストを検出する
2. 指定されたスキームの特定のテスト、またはすべてのテストを実行する
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. リポジトリをフォークします
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 ライセンスの下でライセンスされています。詳細は LICENSE ファイルを参照してください。

セキュリティ

• すべての処理はお使いのマシン上でローカルに行われます
• 明示的に設定しない限り、外部サービスにデータが送信されることはありません
• ローカルサーバーのエンドポイントを公開しないでください
• セキュリティ上の脆弱性に対処するため、依存関係を最新の状態に保ってください

サポート

• 問題：GitHub Issues
• ディスカッション：GitHub Discussions
• ドキュメント：この README およびインラインコードドキュメント

---

iOS 開発コミュニティのために ❤️ を込めて作成