Xcodemcp

🚀 XcodeMCP

XcodeMCPは、JavaScript for Automation (JXA) を通じて直接Xcodeを制御するModel Context Protocol (MCP) サーバーです。MCPサーバーとしても、スタンドアロンのCLIとしても利用可能です。

🚀 クイックスタート

XcodeMCPを使用するには、まず必要な環境を整える必要があります。以下の要件を満たしていることを確認してください。

要件

• XcodeがインストールされたmacOS
• Node.js 18以上
• XCLogParser (推奨): brew install xclogparser

インストール方法

クイックインストール

以下のリンクを使用してクイックインストールすることができます。

XCLogParserは推奨ですが、必須ではありません。

brew install xclogparser

npmからのインストール

npxで直接実行する場合:

npx -y xcodemcp@latest

または、グローバルにインストールする場合:

npm install -g xcodemcp

MCP設定

MCP設定に追加するには、以下のようにします。

{
  "mcpServers": {
    "xcodemcp": {
      "command": "npx",
      "args": ["-y", "xcodemcp@latest"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Claude Code CLI設定

コマンドラインを使用してClaude CodeにXcodeMCPを追加するには、以下のコマンドを実行します。

claude mcp add-json XcodeMCP '{
  "command": "npx",
  "args": ["-y", "xcodemcp@latest"],
  "env": {
    "LOG_LEVEL": "INFO"
  }
}'

開発環境設定

ローカル開発のためには、以下の手順を実行します。

git clone https://github.com/lapfelix/XcodeMCP.git
cd XcodeMCP
npm install

# 開発モードで実行 (TypeScript)
npm run dev:ts

# または、コンパイルして実行
npm run build
npm start

✨ 主な機能

• JavaScript for Automationを通じて直接Xcodeを制御します（xcodebuild CLIではなく）。
• Xcode内でプロジェクトを開き、ビルド、実行、テスト、デバッグを行います。
• XCLogParser を使用して、正確なエラー位置を持つビルドログを解析します。
• 包括的な環境検証とヘルスチェックを提供します。
• オプションの依存関係が欠落している場合でも、適切に機能を低下させます。
• 新機能: 100% MCPサーバーと機能が同等のCLIを搭載しています。

📦 インストール

CLIのインストール

CLIを使用するには、グローバルにインストールします。

npm install -g xcodemcp

💻 使用例

基本的な使用法

# ヘルプと利用可能なツールを表示
xcodecontrol --help

# フラグを使用してツールを実行
xcodecontrol build --xcodeproj /path/to/Project.xcodeproj --scheme MyScheme

# 特定のツールのヘルプを取得
xcodecontrol build --help

# フラグの代わりにJSON入力を使用
xcodecontrol build --json-input '{"xcodeproj": "/path/to/Project.xcodeproj", "scheme": "MyScheme"}'

# 結果をJSON形式で出力
xcodecontrol --json health-check

パス解決

CLIは、利便性のために絶対パスと相対パスの両方をサポートしています。

# 絶対パス (従来の方法)
xcodecontrol build --xcodeproj /Users/dev/MyApp/MyApp.xcodeproj --scheme MyApp

# 相対パス (v2.0.0からの新機能)
xcodecontrol build --xcodeproj MyApp.xcodeproj --scheme MyApp
xcodecontrol build --xcodeproj ../OtherProject/OtherProject.xcodeproj --scheme OtherApp

# ファイルパスでも動作します
xcodecontrol open-file --filePath src/ViewController.swift --lineNumber 42

相対パスは、現在の作業ディレクトリから解決されるため、プロジェクトディレクトリ内で作業する際に非常に便利です。

詳細度の制御

詳細度フラグを使用して、ログ出力を制御します。

# 詳細モード (INFOとDEBUGログを表示)
xcodecontrol -v build --xcodeproj /path/to/Project.xcodeproj --scheme MyScheme

# 安静モード (エラーのみ表示)
xcodecontrol -q test --xcodeproj /path/to/Project.xcodeproj

# デフォルトモード (警告とエラーのみ表示)
xcodecontrol run --xcodeproj /path/to/Project.xcodeproj --scheme MyScheme

ツール名のマッピング

CLIコマンドは、アンダースコアの代わりにケバブケースを使用します。

• xcode_build → build
• xcode_test → test
• xcode_run → run
• xcode_health_check → health-check
• xcresult_browse → xcresult-browse
• find_xcresults → find-xcresults

📚 ドキュメント

利用可能なツール

プロジェクト管理

• xcode_open_project - プロジェクトとワークスペースを開く
• xcode_get_workspace_info - ワークスペースの状態と詳細を取得
• xcode_get_projects - ワークスペース内のプロジェクトを一覧表示
• xcode_open_file - オプションで行番号を指定してファイルを開く

ビルド操作

• xcode_build - 詳細なエラー解析を伴うビルド
• xcode_clean - ビルドアーティファクトをクリーンアップ
• xcode_test - オプションの引数を指定してテストを実行
• xcode_run - アクティブなスキームを実行
• xcode_debug - デバッグセッションを開始
• xcode_stop - 現在の操作を停止

設定

• xcode_get_schemes - 利用可能なスキームを一覧表示
• xcode_set_active_scheme - アクティブなスキームを切り替え
• xcode_get_run_destinations - シミュレーターとデバイスを一覧表示

XCResult解析

• xcresult_browse - テスト結果を閲覧し、失敗を分析
• xcresult_browser_get_console - 特定のテストのコンソール出力を取得
• xcresult_summary - テスト結果の概要をすばやく取得
• xcresult_get_screenshot - テスト失敗からスクリーンショットを抽出
• xcresult_get_ui_hierarchy - タイムスタンプを指定して、AIが読み取り可能なJSON形式でUI階層を取得
• xcresult_get_ui_element - インデックスで特定のUI要素の詳細なプロパティを取得
• xcresult_list_attachments - テストのすべての添付ファイルを一覧表示
• xcresult_export_attachment - テスト結果から特定の添付ファイルをエクスポート

診断

• xcode_health_check - 環境検証とトラブルシューティング

XCResult解析機能

XcodeMCPは、Xcodeのテスト結果（.xcresultファイル）を分析するための包括的なツールを提供し、テスト失敗のデバッグや価値ある情報の抽出を容易にします。

テスト結果分析

• 結果の閲覧: テスト階層をナビゲートし、合格/不合格の状態を表示し、詳細なテスト情報を調べます。
• コンソールログ: 正確なタイムスタンプ付きでコンソール出力とテストアクティビティを抽出し、デバッグに役立てます。
• クイックサマリー: 合格率、失敗数、実行時間などの概要統計情報を取得します。

ビジュアルデバッグ

• スクリーンショットの抽出: ビデオ添付ファイルからffmpegフレーム抽出を使用して、テスト失敗からPNGスクリーンショットを抽出します。
• タイムスタンプの精度: テスト実行中の特定の瞬間のUI状態をキャプチャするために、正確なタイムスタンプを指定します。

UI階層分析

• AIが読み取り可能な形式: 単一文字のプロパティ（t=タイプ、l=ラベル、f=フレーム、c=子要素、j=インデックス）を持つ圧縮JSONとしてUI階層を抽出します。
• タイムスタンプの選択: 指定されたタイムスタンプに最も近いUI階層キャプチャを自動的に見つけます。
• 要素の詳細分析: インデックス参照を使用して、任意のUI要素の完全な詳細を取得し、アクセシビリティプロパティやフレーム情報を含みます。
• サイズの最適化: 完全な階層データと比較して75%以上のサイズ削減を実現しながら、すべての重要な情報を保持します。

添付ファイルの管理

• 完全なインベントリ: 任意のテストのすべての添付ファイル（スクリーンショット、ビデオ、デバッグ説明、UI階層）を一覧表示します。
• 選択的なエクスポート: インデックスまたはタイプで特定の添付ファイルをエクスポートします。
• スマートな検出: 異なる添付ファイルタイプを自動的に識別し、分類します。

使用例

# テスト結果を閲覧
xcresult_browse "/path/to/TestResults.xcresult"

# コンソール出力を取得して失敗のタイムスタンプを見つける
xcresult_browser_get_console "/path/to/TestResults.xcresult" "MyTest/testMethod()"

# 特定のタイムスタンプでのUI階層を取得 (AIが読み取り可能なスリムバージョン)
xcresult_get_ui_hierarchy "/path/to/TestResults.xcresult" "MyTest/testMethod()" 45.25

# 完全なUI階層を取得 (サイズ警告あり)
xcresult_get_ui_hierarchy "/path/to/TestResults.xcresult" "MyTest/testMethod()" 45.25 true

# 特定のUI要素の詳細なプロパティを取得
xcresult_get_ui_element "/path/to/ui_hierarchy_full.json" 15

# 失敗ポイントでのスクリーンショットを抽出
xcresult_get_screenshot "/path/to/TestResults.xcresult" "MyTest/testMethod()" 30.71

設定

ログ設定

XcodeMCPは、デバッグと監視を支援するために、構成可能なログをサポートしています。

環境変数

• LOG_LEVEL: ログの詳細度を制御します（デフォルト: INFO）

  • SILENT: ログ出力を無効にします。
  • ERROR: エラーメッセージのみを表示します。
  • WARN: 警告とエラーを表示します。
  • INFO: 一般的な操作情報を表示します（推奨）。
  • DEBUG: 詳細な診断情報を表示します。

• XCODEMCP_LOG_FILE: ログを書き込むオプションのファイルパスです。

  • ログはstderrに加えて指定されたファイルにも書き込まれます。
  • 親ディレクトリは自動的に作成されます。
  • 例: /tmp/xcodemcp.log または ~/Library/Logs/xcodemcp.log

• XCODEMCP_CONSOLE_LOGGING: コンソール出力を有効/無効にします（デフォルト: true）

  • false に設定すると、stderrログを無効にします（ファイルログのみを使用する場合に便利）

例

デバッグログとファイル出力:

{
  "mcpServers": {
    "xcodemcp": {
      "command": "npx",
      "args": ["-y", "xcodemcp@latest"],
      "env": {
        "LOG_LEVEL": "DEBUG",
        "XCODEMCP_LOG_FILE": "~/Library/Logs/xcodemcp.log"
      }
    }
  }
}

サイレントモード (ログなし):

{
  "mcpServers": {
    "xcodemcp": {
      "command": "npx", 
      "args": ["-y", "xcodemcp@latest"],
      "env": {
        "LOG_LEVEL": "SILENT"
      }
    }
  }
}

ファイルのみのログ:

{
  "mcpServers": {
    "xcodemcp": {
      "command": "npx",
      "args": ["-y", "xcodemcp@latest"], 
      "env": {
        "LOG_LEVEL": "INFO",
        "XCODEMCP_LOG_FILE": "/tmp/xcodemcp.log",
        "XCODEMCP_CONSOLE_LOGGING": "false"
      }
    }
  }
}

すべてのログは、タイムスタンプとログレベルが適切にフォーマットされ、stderr出力はMCPプロトコルと互換性を維持します。

トラブルシューティング

XCLogParserが見つからない場合

XCLogParserがインストールされているにもかかわらず、見つからないという警告が表示される場合は、以下の手順を試してください。

1. インストールを確認する

   which xclogparser
   xclogparser version
   

2. 一般的な問題と解決策

   • PATHの問題: which xclogparser が何も返さない場合、インストールディレクトリをPATHに追加します。

     # Intel MacのHomebrewの場合
     export PATH="/usr/local/bin:$PATH"
     
     # Apple Silicon MacのHomebrewの場合
     export PATH="/opt/homebrew/bin:$PATH"
     

   • 誤ったコマンド: 古いドキュメントでは xclogparser --version が参照されている場合がありますが、正しいコマンドは xclogparser version （ダッシュなし）です。

   • パーミッションの問題: xclogparserが実行可能であることを確認します。

     chmod +x $(which xclogparser)
     

3. 環境検証: ヘルスチェックを実行して詳細な診断を取得します。

   echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "xcode_health_check", "arguments": {}}}' | npx xcodemcp
   

注意: XcodeMCPはXCLogParserなしでも動作しますが、ビルドエラー解析は制限されます。

出力例

エラー付きのビルド

❌ BUILD FAILED (2 errors)

ERRORS:
  • /path/HandsDownApp.swift:7:18: Expected 'func' keyword in instance method declaration
  • /path/MenuBarManager.swift:98:13: Invalid redeclaration of 'toggleItem'

ヘルスチェック

✅ All systems operational

✅ OS: macOS environment detected
✅ XCODE: Xcode found at /Applications/Xcode.app (version 16.4)
✅ XCLOGPARSER: XCLogParser found (XCLogParser 0.2.41)
✅ OSASCRIPT: JavaScript for Automation (JXA) is available
✅ PERMISSIONS: Xcode automation permissions are working