Xcode MCP サーバー

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

特徴

プロジェクト管理

• アクティブなプロジェクトを設定し、詳細なプロジェクト情報を取得する

• テンプレートから新しい Xcode プロジェクトを作成する (iOS、macOS、watchOS、tvOS)

• ターゲットとグループを指定してXcodeプロジェクトにファイルを追加する

• ワークスペースドキュメントを解析して関連するプロジェクトを見つける

• プロジェクトとワークスペースで利用可能なスキームを一覧表示する

ファイル操作

• さまざまなエンコードをサポートするファイルの読み取り/書き込み

• base64エンコード/デコードでバイナリファイルを処理する

• パターンと正規表現を使用してファイル内のテキストコンテンツを検索する

• ファイルの存在を確認し、ファイルのメタデータを取得する

• ディレクトリ構造を自動的に作成する

ビルドとテスト

• カスタマイズ可能なオプションでプロジェクトを構築する

• 詳細な障害レポート付きのテストを実行する

• 潜在的な問題がないかコードを分析する

• ビルドディレクトリをクリーンにする

• 配布用アーカイブプロジェクト

CocoaPods 統合

• プロジェクトでCocoaPodsを初期化する

• ポッドのインストールと更新

• ポッドの依存関係の追加と削除

• 任意のポッドコマンドを実行する

Swift パッケージマネージャー

• 新しいSwiftパッケージを初期化する

• さまざまなバージョン要件を持つパッケージ依存関係を追加および削除します

• パッケージを更新し、依存関係を解決する

• DocC を使用して Swift パッケージのドキュメントを生成する

• テストを実行してSwiftパッケージをビルドする

iOSシミュレータツール

• 利用可能なシミュレータを詳細情報とともに一覧表示します

• シミュレータの起動とシャットダウン

• シミュレータにアプリをインストールして起動する

• スクリーンショットを撮り、ビデオを録画する

• シミュレータの設定と状態を管理する

Xcodeユーティリティ

• xcrun経由でXcodeコマンドを実行する

• 資産カタログをコンパイルする

• ソース画像からアプリのアイコンセットを生成する

• アプリのパフォーマンスをトレースする

• App Store への提出用にアーカイブをエクスポートして検証する

• 異なるXcodeバージョンを切り替える

Related MCP server: Xcode MCP Server

インストール

前提条件

• Xcode 14.0以降がインストールされたmacOS

• Node.js 16以上

• npmまたはyarn

• Swift パッケージ マネージャーの機能については 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 デスクトップ統合(オプション):

   • 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 コマンドラインツール

   • Node.js v16以上

   • npm

   • Ruby（CocoaPodsサポート用）

   • CocoaPods（オプション、ポッド関連機能用）

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を編集または作成します。

   • 以下の設定を追加します（必要に応じてパスを調整してください）：GXP6

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

一般的なセットアップの問題:

1. ビルドエラー:

   • 正しいNode.jsバージョン（v16以上）を使用していることを確認してください

   • node_modulesを削除して、 npm installを再度実行してみてください。

   • npx tsc --noEmitで TypeScript エラーをチェックする

   • コード内のすべてのインポートが適切に解決されていることを確認する

2. 不足している依存関係:

   • モジュールが見つからないというエラーが表示された場合は、 npm install再度実行してください。

   • ネイティブ依存関係の場合、Xcode コマンドラインツールが必要になる場合があります: xcode-select --install

3. 権限の問題:

   • インストールディレクトリへの書き込み権限があることを確認してください

   • CocoaPodsのインストールには、 sudo gem install cocoapods使用する必要があるかもしれません。

4. 設定の問題:

   • .envファイルの形式とパスが正しいことを確認してください

   • PROJECTS_BASE_DIRが既存のディレクトリを指していることを確認してください

   • パスにエスケープが必要な特殊文字が含まれていないことを確認してください

5. クロードデスクトップ統合:

   • 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アシスタントへの接続

サーバーはモデルコンテキストプロトコル（MCP）を実装しており、このプロトコルをサポートする様々なAIアシスタントと互換性があります。接続するには：

1. Xcode MCPサーバーを起動する

2. AIアシスタントをサーバーURL（通常はhttp://localhost:3000 ）を使用するように構成します。

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サーバーは、モデルコンテキストプロトコル（MCP）を使用して、AIモデルがXcodeプロジェクトと連携するための標準化されたインターフェースを提供します。サーバーアーキテクチャは、以下の主要コンポーネントで構成されています。

コアコンポーネント

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

2. パス管理: 許可されたディレクトリに対してすべてのパスを検証することで、安全なファイル アクセスを保証します。

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

   • 標準 Xcode プロジェクト (.xcodeproj)

   • Xcode ワークスペース (.xcworkspace)

   • Swift パッケージ マネージャー プロジェクト (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 を提供してくれたモデルコンテキストプロトコルチームに感謝します。

• TypeScriptとNode.jsで構築

• Xcode コマンドラインツールと Swift パッケージマネージャーを使用します

• サーバーの機能と堅牢性の向上にご協力いただいたすべての貢献者に感謝いたします。