Xcode MCP Server

Xcode MCP Server

AI アシスタント向けに、Xcode との包括的な統合機能を提供する MCP（Model Context Protocol）サーバーです。このサーバーを使うと、AI エージェントが Xcode プロジェクトを操作し、iOS シミュレーターを管理して、強化されたエラー処理と複数のプロジェクトタイプへの対応により、さまざまな Xcode 関連タスクを実行できます。

機能

プロジェクト管理

• アクティブなプロジェクトを設定し、詳細なプロジェクト情報を取得
• テンプレートから新しい Xcode プロジェクトを作成（iOS、macOS、watchOS、tvOS）
• ターゲットとグループを指定して Xcode プロジェクトにファイルを追加
• ワークスペースのドキュメントを解析して、関連するプロジェクトを検索
• プロジェクトとワークスペースで利用可能なスキームを一覧表示

ファイル操作

• さまざまなエンコーディングに対応してファイルを読み書き
• base64 エンコード／デコードでバイナリファイルを処理
• パターンと正規表現を使ってファイル内のテキストを検索
• ファイルの存在を確認し、ファイルのメタデータを取得
• ディレクトリー構造を自動的に作成

ビルドとテスト

• カスタマイズ可能なオプションでプロジェクトをビルド
• 詳細な失敗レポートとともにテストを実行
• 潜在的な問題がないかコードを分析
• ビルドディレクトリーをクリーンアップ
• 配布用にプロジェクトをアーカイブ

CocoaPods との統合

• プロジェクトで CocoaPods を初期化
• Pod をインストールおよび更新
• Pod の依存関係を追加および削除
• 任意の Pod コマンドを実行

Swift Package Manager

• 新しい Swift パッケージを初期化
• さまざまなバージョン要件でパッケージの依存関係を追加および削除
• パッケージを更新し、依存関係を解決
• DocC を使って Swift パッケージのドキュメントを生成
• Swift パッケージのテストとビルドを実行

iOS シミュレーターツール

• 詳細情報とともに利用可能なシミュレーターを一覧表示
• シミュレーターを起動およびシャットダウン
• シミュレーターにアプリをインストールして起動
• スクリーンショットを撮影し、動画を録画
• シミュレーターの設定と状態を管理

Xcode ユーティリティ

• xcrun 経由で Xcode コマンドを実行
• アセットカタログをコンパイル
• ソース画像からアプリアイコンセットを生成
• アプリのパフォーマンスをトレース
• App Store 提出用にアーカイブをエクスポートして検証
• 異なる Xcode バージョンを切り替え

インストール

前提条件

• Xcode 14.0 以降をインストールした macOS
• Node.js 16 以降
• npm または yarn
• Swift Package Manager 機能には Swift 5.5 以降
• CocoaPods（任意、CocoaPods との統合に必要）

セットアップ

オプション 1：自動セットアップ（推奨）

付属のセットアップスクリプトを使用すると、インストールと設定のプロセスを自動化できます。

# Make the script executable
chmod +x setup.sh

# Run the setup script
./setup.sh

セットアップスクリプトの処理内容：

1. 環境の確認：

   • macOS で実行していることを確認
   • Xcode がインストールされ、アクセス可能であることを確認
   • Node.js（v16 以降）と npm が利用可能であることを確認
   • Ruby がインストールされているか確認
   • CocoaPods のインストール状況を確認（未インストールの場合はインストールを提案）

2. 依存関係のインストール：

   • npm install を実行して、必要な Node.js パッケージをすべてインストール
   • npm run build を実行して、TypeScript コードをコンパイル

3. 設定：

   • .env ファイルが存在しない場合は作成
   • プロジェクトのベースディレクトリーを入力
   • デバッグログを有効にするか確認
   • 設定内容を保存

4. Claude Desktop との統合（任意）：

   • Claude Desktop 用にサーバーを設定するか確認
   • Claude Desktop の設定ファイルを作成または更新
   • サーバーを起動するための適切なコマンドと引数を設定

セットアップスクリプトを使うタイミング：

• すべての前提条件を満たしていることを確認するための初回インストール時
• 対話形式のプロンプトに従って設定したい場合
• Claude Desktop との統合をすばやくセットアップしたい場合
• 必要なコンポーネントがすべて環境に揃っているか確認したい場合

スクリプトは、わかりやすいプロンプトと役立つフィードバックを表示しながら、設定の手順を案内します。

オプション 2：手動セットアップ

手動セットアップを使用する場合：

• 各インストール手順を明示的に管理したい場合
• カスタム環境または標準以外の設定を使用している場合
• CI/CD パイプラインや自動化された環境でセットアップする場合
• インストールプロセスの特定の部分をカスタマイズしたい場合
• Node.js プロジェクトに精通した経験豊富な開発者の場合

手動でインストールするには、次の手順に従ってください。

1. リポジトリをクローンします。

   git clone https://github.com/r-huijts/xcode-mcp-server.git
   cd xcode-mcp-server
   

2. 前提条件を確認します（以下がインストールされている必要があります）。

   • Xcode および Xcode Command Line Tools
   • Node.js v16 以降
   • npm
   • Ruby（CocoaPods のサポート用）
   • CocoaPods（任意。pod 関連機能用）

3. 依存関係をインストールします。

   npm install
   

4. プロジェクトをビルドします。

   npm run build
   

5. 設定ファイルを作成します。

   # Option A: Start with the example configuration
   cp .env.example .env
   
   # Option B: Create a minimal configuration
   echo "PROJECTS_BASE_DIR=/path/to/your/projects" > .env
   echo "DEBUG=false" >> .env
   

   .env ファイルを編集して、希望する設定を指定します。

6. Claude Desktop と統合する場合（任意）：

   • ~/Library/Application Support/Claude/claude_desktop_config.json を編集または作成します
   • 次の設定を追加します（必要に応じてパスを調整してください）。

   {
     "mcpServers": {
       "xcode": {
         "command": "node",
         "args": ["/path/to/xcode-mcp-server/dist/index.js"]
       }
     }
   }
   

セットアップのトラブルシューティング

よくあるセットアップの問題：

1. ビルドエラー：

   • 正しい Node.js バージョン（v16 以上）がインストールされていることを確認します
   • node_modules を削除してから、もう一度 npm install を実行してみます
   • npx tsc --noEmit で TypeScript のエラーを確認します
   • コード内のすべてのインポートが正しく解決されることを確認します

2. 依存関係の不足：

   • モジュールが見つからないというエラーが表示された場合は、もう一度 npm install を実行します
   • ネイティブ依存関係には、Xcode Command Line Tools が必要な場合があります：xcode-select --install

3. 権限の問題：

   • インストールディレクトリへの書き込み権限があることを確認します
   • CocoaPods のインストールには、sudo gem install cocoapods の実行が必要な場合があります

4. 設定の問題：

   • .env ファイルの形式が正しく、有効なパスが指定されていることを確認します
   • PROJECTS_BASE_DIR が既存のディレクトリを指していることを確認します
   • パスにエスケープが必要な特殊文字が含まれていないか確認します

5. Claude Desktop との統合：

   • Claude の設定で指定したパスが、index.js の正しい場所を指していることを確認します
   • 設定を変更した後、Claude Desktop を再起動します
   • Claude で使用する前に、サーバーが実行中であることを確認します

使用方法

サーバーの起動

npm start

自動再起動を有効にした開発モードの場合：

npm run dev

設定オプション

サーバーは次の 2 つの方法で設定できます。

1. .env ファイル内の環境変数：

   PROJECTS_BASE_DIR=/path/to/your/projects
   DEBUG=true
   ALLOWED_PATHS=/path/to/additional/allowed/directory
   PORT=8080
   

2. コマンドライン引数：

   npm start -- --projects-dir=/path/to/your/projects --port=8080
   

主な設定パラメーター

• PROJECTS_BASE_DIR / --projects-dir：プロジェクトのベースディレクトリ（必須）
• ALLOWED_PATHS / --allowed-paths：アクセスを許可する追加ディレクトリ（カンマ区切り）
• PORT / --port：サーバーを実行するポート（デフォルト：3000）
• DEBUG / --debug：デバッグログを有効にする（デフォルト：false）
• LOG_LEVEL / --log-level：ログレベルを設定する（デフォルト：info）

AI アシスタントへの接続

このサーバーは Model Context Protocol（MCP）を実装しているため、このプロトコルをサポートするさまざまな AI アシスタントと互換性があります。接続するには：

1. Xcode MCP サーバーを起動します
2. サーバーの URL（通常は http://localhost:3000）を使用するように AI アシスタントを設定します
3. AI アシスタントが、サーバーから提供されるすべての Xcode ツールにアクセスできるようになります

ツールのドキュメント

利用可能なすべてのツールとその使用方法の概要については、ツールの概要を参照してください。

詳しい使用例とベストプラクティスについては、ユーザーガイドを参照してください。

よくあるワークフロー

新しいプロジェクトのセットアップ

// Create a new iOS app project
await tools.create_xcode_project({
  name: "MyAwesomeApp",
  template: "ios-app",
  outputDirectory: "~/Projects",
  organizationName: "My Organization",
  organizationIdentifier: "com.myorganization",
  language: "swift",
  includeTests: true,
  setAsActive: true
});

// Add a Swift Package dependency
await tools.add_swift_package({
  url: "https://github.com/Alamofire/Alamofire.git",
  version: "from: 5.0.0"
});

ファイルの操作

// Read a file with specific encoding
const fileContent = await tools.read_file({
  filePath: "MyAwesomeApp/AppDelegate.swift",
  encoding: "utf-8"
});

// Write to a file
await tools.write_file({
  path: "MyAwesomeApp/NewFile.swift",
  content: "import Foundation\n\nclass NewClass {}\n",
  createIfMissing: true
});

// Search for text in files
const searchResults = await tools.search_in_files({
  directory: "MyAwesomeApp",
  pattern: "*.swift",
  searchText: "class",
  isRegex: false
});

ビルドとテスト

// Build the project
await tools.build_project({
  scheme: "MyAwesomeApp",
  configuration: "Debug"
});

// Run tests
await tools.test_project({
  scheme: "MyAwesomeApp",
  testPlan: "MyAwesomeAppTests"
});

プロジェクト構成

xcode-mcp-server/
├── src/
│   ├── index.ts                 # Entry point
│   ├── server.ts                # MCP server implementation
│   ├── types/                   # Type definitions
│   │   └── index.ts             # Core type definitions
│   ├── utils/                   # Utility functions
│   │   ├── errors.js            # Error handling classes
│   │   ├── pathManager.ts       # Path validation and management
│   │   ├── project.js           # Project utilities
│   │   └── simulator.js         # Simulator utilities
│   └── tools/                   # Tool implementations
│       ├── project/             # Project management tools
│       │   └── index.ts         # Project creation, detection, file adding
│       ├── file/                # File operation tools
│       │   └── index.ts         # File reading, writing, searching
│       ├── build/               # Build and testing tools
│       │   └── index.ts         # Building, testing, analyzing
│       ├── cocoapods/           # CocoaPods integration
│       │   └── index.ts         # Pod installation and management
│       ├── spm/                 # Swift Package Manager tools
│       │   └── index.ts         # Package management and documentation
│       ├── simulator/           # iOS simulator tools
│       │   └── index.ts         # Simulator control and interaction
│       └── xcode/               # Xcode utilities
│           └── index.ts         # Xcode version management, asset tools
├── docs/                        # Documentation
│   ├── tools-overview.md        # Comprehensive tool documentation
│   └── user-guide.md            # Usage examples and best practices
├── tests/                       # Tests
└── dist/                        # Compiled code (generated)

仕組み

Xcode MCP サーバーは Model Context Protocol を使用して、AI モデルが Xcode プロジェクトとやり取りするための標準化されたインターフェースを提供します。サーバーのアーキテクチャは、いくつかの主要なコンポーネントで構成されています。

コアコンポーネント

1. サーバー実装：ツールの登録とリクエスト処理を担うメインの MCP サーバーです。

2. パス管理：すべてのパスを許可されたディレクトリと照合して検証し、安全なファイルアクセスを確保します。

3. プロジェクト管理：さまざまな種類の Xcode プロジェクトを検出、読み込み、管理します。

   • 標準の Xcode プロジェクト（.xcodeproj）
   • Xcode ワークスペース（.xcworkspace）
   • Swift Package Manager プロジェクト（Package.swift）

4. ディレクトリ状態：相対パスを解決するためのアクティブなディレクトリコンテキストを維持します。

5. ツールレジストリ：さまざまな Xcode 操作に対応する論理的なカテゴリにツールを整理します。

リクエストの流れ

1. AI アシスタントが MCP サーバーにツール実行リクエストを送信します。

2. サーバーがリクエストのパラメーターと権限を検証します。

3. 検証済みのパラメーターを使って、適切なツールハンドラーが呼び出されます。

4. ツールが要求された操作を実行します。多くの場合、ネイティブの Xcode コマンドを使用します。

5. 結果が整形され、AI アシスタントに返されます。

6. 包括的なエラー処理により、トラブルシューティングに役立つフィードバックが提供されます。

安全機能

• パス検証：すべてのファイル操作を許可されたディレクトリ内に制限します。
• エラー処理：詳細なエラーメッセージで問題の診断を支援します。
• パラメーター検証：Zod スキーマを使用して入力パラメーターを検証します。
• プロセス管理：適切なエラー処理を行いながら、外部プロセスを安全に実行します。

プロジェクトタイプのサポート

サーバーは、さまざまなプロジェクトタイプを適切に処理します。

• 標準プロジェクト：.xcodeproj を直接操作します
• ワークスペース：ワークスペース内の複数のプロジェクトを管理します
• SPM プロジェクト：Swift Package Manager 固有の操作を処理します

このアーキテクチャにより、AI アシスタントはセキュリティを維持し、詳細なフィードバックを提供しながら、あらゆるタイプの Xcode プロジェクトをシームレスに操作できます。

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add some amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

開発ガイドライン

• 既存のコードスタイルと構成に従ってください
• エラーメッセージを具体的にした包括的なエラー処理を追加してください
• 新しい機能のテストを作成してください
• 変更内容が反映されるようにドキュメントを更新してください
• さまざまなプロジェクトタイプ（標準、ワークスペース、SPM）との互換性を確保してください

新しいツールの追加

サーバーに新しいツールを追加するには、次の手順に従います。

1. src/tools/ ディレクトリ内の適切なカテゴリを特定します
2. 既存のパターンに従い、Zod スキーマ検証を使用してツールを実装します
3. カテゴリの index.ts ファイルにツールを登録します
4. エラーメッセージを具体的にしたエラー処理を追加します
5. 適切なドキュメントファイルにツールを記載します

トラブルシューティング

よくある問題

• パスアクセスエラー：アクセスしようとしているパスが許可されたディレクトリ内にあることを確認してください
• ビルドの失敗：Xcode コマンドラインツールがインストールされ、最新の状態であることを確認してください
• ツールが見つからない：ツール名が正しく、適切に登録されていることを確認してください
• パラメーター検証エラー：ツールのドキュメントでパラメーターの型と要件を確認してください

デバッグ

1. デバッグログを有効にしてサーバーを起動します：npm start -- --debug
2. コンソール出力で詳細なエラーメッセージを確認します
3. サーバーログでリクエストとレスポンスの詳細を確認します
4. ツール固有の問題については、ターミナルで同等の Xcode コマンドを直接実行してみてください

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルを参照してください。

謝辞

• MCP SDK を提供してくださった Model Context Protocol チームに感謝します
• TypeScript と Node.js を使用して構築されています
• Xcode コマンドラインツールと Swift Package Manager を使用しています
• サーバーの機能と堅牢性の向上に貢献してくださったすべての方に、特別な感謝を申し上げます