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バージョンを切り替える

インストール

前提条件

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

セットアップスクリプトの機能:

環境検証：
- macOSで実行されているか確認します
- Xcodeがインストールされアクセス可能であることを確認する
- Node.js (v16+) と npm が利用可能であることを確認します
- Rubyのインストールをチェックする
- CocoaPods のインストールを確認します (インストールされていない場合はインストールを提案します)
依存関係のインストール:
- npm installを実行して、必要なすべての Node.js パッケージをインストールします。
- npm run buildを実行して TypeScript コードをコンパイルします。
構成設定:
- .envファイルが存在しない場合は作成します
- プロジェクトのベースディレクトリの入力を求めるプロンプト
- デバッグログを有効にするかどうかを尋ねます
- 設定を保存します
Claude デスクトップ統合(オプション):
- Claude Desktop 用のサーバーの構成を提案
- Claude Desktop 構成ファイルを作成または更新します
- サーバーを起動するための適切なコマンドと引数を設定します

セットアップスクリプトを使用する場合:

すべての前提条件が満たされていることを確認するための初回インストール
対話型プロンプトによるガイド付き構成が必要な場合
Claude Desktop統合を素早く設定したい場合
環境に必要なコンポーネントがすべて揃っていることを確認するには

スクリプトは、明確なプロンプトと役立つフィードバックを使用して構成プロセスをガイドします。

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

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

各インストール手順を明示的に制御したい
カスタム環境または非標準構成がある場合
CI/CDパイプラインまたは自動化環境で設定する場合
インストールプロセスの特定の側面をカスタマイズしたい
Node.jsプロジェクトに精通した経験豊富な開発者であること

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

リポジトリをクローンします。
git clone https://github.com/r-huijts/xcode-mcp-server.git cd xcode-mcp-server
前提条件を確認します (これらはインストールされている必要があります)。
- Xcode と Xcode コマンドラインツール
- Node.js v16以上
- npm
- Ruby（CocoaPodsサポート用）
- CocoaPods（オプション、ポッド関連機能用）
依存関係をインストールします:
npm install
プロジェクトをビルドします。
npm run build
設定ファイルを作成します。
# 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ファイルを編集して、希望する構成を設定します。
Claude Desktop 統合の場合 (オプション):
- ~/Library/Application Support/Claude/claude_desktop_config.jsonを編集または作成します。
- 以下の設定を追加します（必要に応じてパスを調整してください）：GXP6

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

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

ビルドエラー:
- 正しいNode.jsバージョン（v16以上）を使用していることを確認してください
- node_modulesを削除して、 npm installを再度実行してみてください。
- npx tsc --noEmitで TypeScript エラーをチェックする
- コード内のすべてのインポートが適切に解決されていることを確認する
不足している依存関係:
- モジュールが見つからないというエラーが表示された場合は、 npm install再度実行してください。
- ネイティブ依存関係の場合、Xcode コマンドラインツールが必要になる場合があります: xcode-select --install
権限の問題:
- インストールディレクトリへの書き込み権限があることを確認してください
- CocoaPodsのインストールには、 sudo gem install cocoapods使用する必要があるかもしれません。
設定の問題:
- .envファイルの形式とパスが正しいことを確認してください
- PROJECTS_BASE_DIRが既存のディレクトリを指していることを確認してください
- パスにエスケープが必要な特殊文字が含まれていないことを確認してください
クロードデスクトップ統合:
- Claude 構成のパスがindex.jsの正しい場所を指していることを確認します。
- 設定を変更した後、Claude Desktopを再起動します。
- Claude で使用する前にサーバーが稼働していることを確認してください

使用法

サーバーの起動

npm start

自動再起動を伴う開発モードの場合:

npm run dev

設定オプション

サーバーは次の 2 つの方法で構成できます。

.envファイル内の環境変数:
PROJECTS_BASE_DIR=/path/to/your/projects DEBUG=true ALLOWED_PATHS=/path/to/additional/allowed/directory PORT=8080
コマンドライン引数:
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アシスタントと互換性があります。接続するには：

Xcode MCPサーバーを起動する
AIアシスタントをサーバーURL（通常はhttp://localhost:3000 ）を使用するように構成します。
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プロジェクトと連携するための標準化されたインターフェースを提供します。サーバーアーキテクチャは、以下の主要コンポーネントで構成されています。

コアコンポーネント

サーバー実装: ツールの登録とリクエストの処理を扱うメインの MCP サーバー。
パス管理: 許可されたディレクトリに対してすべてのパスを検証することで、安全なファイルアクセスを保証します。
プロジェクト管理: さまざまな種類の Xcode プロジェクトを検出し、読み込み、管理します。
- 標準 Xcode プロジェクト (.xcodeproj)
- Xcode ワークスペース (.xcworkspace)
- Swift パッケージマネージャープロジェクト (Package.swift)
ディレクトリ状態: 相対パス解決のアクティブディレクトリコンテキストを維持します。
ツールレジストリ: さまざまな Xcode 操作の論理カテゴリにツールを整理します。

リクエストフロー

AI アシスタントがツール実行要求を MCP サーバーに送信します。
サーバーは要求パラメータと権限を検証します。
検証されたパラメータを使用して適切なツールハンドラーが呼び出されます。
ツールは、多くの場合ネイティブ Xcode コマンドを使用して、要求された操作を実行します。
結果はフォーマットされて AI アシスタントに返されます。
包括的なエラー処理により、トラブルシューティングに役立つ有益なフィードバックが提供されます。

安全機能

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

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

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

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

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

貢献

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

リポジトリをフォークする
機能ブランチを作成します（ git checkout -b feature/amazing-feature ）
変更をコミットします ( git commit -m 'Add some amazing feature' )
ブランチにプッシュする ( git push origin feature/amazing-feature )
プルリクエストを開く

開発ガイドライン

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

新しいツールの追加

サーバーに新しいツールを追加するには:

src/tools/ディレクトリ内の適切なカテゴリを特定します
Zodスキーマ検証を使用した既存のパターンを使用してツールを実装する
ツールをカテゴリのindex.tsファイルに登録する
特定のエラーメッセージでエラー処理を追加する
適切なドキュメントファイルにツールを文書化する

トラブルシューティング

よくある問題

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

デバッグ

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

ライセンス

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

謝辞

MCP SDK を提供してくれたモデルコンテキストプロトコルチームに感謝します。
TypeScriptとNode.jsで構築
Xcode コマンドラインツールと Swift パッケージマネージャーを使用します
サーバーの機能と堅牢性の向上にご協力いただいたすべての貢献者に感謝いたします。

Integrations