Xcode MCP

🚀 Xcode MCP Server

Xcode開発の自動化を目的とした包括的なモデルコンテキストプロトコル（MCP）サーバーです。プロジェクト管理、ビルド、テスト、シミュレーター制御、クラッシュレポート、アセット管理、ローカライズ、AIによるワークフローなど、115以上のツールを提供します。

✨ 主な機能

• 112の直接Xcodeツール - 一般的なタスクを高速で1ステップで実行できます。
• 3つのLangGraphサブエージェントツール - 推論と状態管理を備えた多段階ワークフローです。
• 21の新ツール - クラッシュレポート、アセット管理、ローカライズ、シミュレーターの機能強化などが含まれます。
• 統合サーバー - すべての機能を統合した単一のMCPサーバーです。
• トークン最適化 - キャッシュと圧縮により、トークンを30 - 40%削減します。
• 高度に詳細なスキーマ - 例と検証機能を備えた包括的なJSONスキーマです。
• ペルソナシステム - 異なるユースケースに合わせてエージェントのペルソナを設定できます。

📋 目次

• クイックスタート
• インストール
• 設定
• 使用方法
• ツールリファレンス
• アーキテクチャ
• ペルソナ
• トラブルシューティング
• 開発

🚀 クイックスタート

前提条件

• macOS（Xcodeツールの場合）
• Python 3.11以上
• Conda（推奨）またはpip
• Xcodeコマンドラインツール

インストール

# リポジトリをクローン
git clone <repository-url>
cd xcode-mcp

# conda環境を作成
conda env create -f environment.yml
conda activate xcode-mcp

# またはpipを使用
pip install -r requirements.txt

Cursorの設定

~/.cursor/mcp.jsonに以下を追加します。

{
  "mcpServers": {
    "xcode-mcp": {
      "command": "/path/to/miniconda3/envs/xcode-mcp/bin/python",
      "args": [
        "/path/to/xcode-mcp/run_unified_mcp.py"
      ],
      "env": {
        "DEEPSEEK_API_KEY": "your-api-key-here"
      }
    }
  }
}

MCPサーバーを読み込むために、Cursorを再起動してください。

📦 インストール

方法1: 自動セットアップスクリプト

./setup.sh

このスクリプトは以下を行います。

• conda環境を作成
• 依存関係をインストール
• インストールを検証
• サーバーをテスト

方法2: 手動インストール

# conda環境を作成
conda env create -f environment.yml
conda activate xcode-mcp

# インストールを検証
python -c "from src.unified_mcp_server import UnifiedMCPServer; print('✅ インストール成功')"

依存関係

主要な依存関係は以下の通りです。

• fastapi - HTTPサーバー（オプション）
• pydantic - データ検証
• langgraph - サブエージェントワークフロー（オプション）
• langchain - LLM統合（オプション）

完全なリストはenvironment.ymlを参照してください。

⚙️ 設定

環境変数

# LLMプロバイダーのAPIキー
export DEEPSEEK_API_KEY="your-deepseek-key"
export OPENAI_API_KEY="your-openai-key"  # オプション

# モデル選択
export DEFAULT_MODEL="ollama:qwen3-coder:30b"  # または "deepseek:deepseek-coder"

MCP設定

サーバーは~/.cursor/mcp.jsonを通じて設定されます。信頼性のために絶対パスを使用してください。

{
  "mcpServers": {
    "xcode-mcp": {
      "command": "/Users/username/miniconda3/envs/xcode-mcp/bin/python",
      "args": ["/Users/username/Projects/xcode-mcp/run_unified_mcp.py"],
      "env": {
        "DEEPSEEK_API_KEY": "your-key"
      }
    }
  }
}

💻 使用例

直接ツール

単純な1ステップ操作には直接ツールを使用します。

list_projectsツールを使用
build_projectツールを "MyApp" スキームで使用
run_testsツールを使用

LangGraphサブエージェントツール

複雑な多段階ワークフローにはLangGraphツールを使用します。

langgraph_agentを "Set up my development environment" プロンプトで使用
langgraph_workflowを "Build, test, and generate report" ワークフローで使用

ペルソナを使用する場合

特殊な動作をするためにペルソナを適用します。

{
  "name": "langgraph_agent",
  "arguments": {
    "prompt": "Help me optimize my build",
    "persona": {
      "id": "build-optimizer",
      "role": "optimizer"
    }
  }
}

🛠️ ツールリファレンス

直接ツール（112個のツール）

v2.1.0の新機能

• クラッシュレポート（4つのツール）: symbolicate_crash_log, analyze_crash_log, get_crash_reports, export_crash_log
• アセット管理（5つのツール）: optimize_images, generate_app_icons, validate_asset_catalog, check_asset_sizes, manage_color_assets
• シミュレーターの機能強化（5つのツール）: set_simulator_location, get_simulator_logs, list_simulator_apps, simulate_network_conditions, clone_simulator
• ローカライズ（4つのツール）: extract_strings, validate_localizations, check_localization_coverage, list_localizations
• ビルドの機能強化（3つのツール）: set_build_number, set_version, analyze_build_time

元のツール（94個のツール）

プロジェクト管理

• list_projects - すべてのXcodeプロジェクトをリストする
• create_project - 新しいXcodeプロジェクトを作成する
• open_project - Xcodeでプロジェクトを開く
• list_schemes - 利用可能なビルドスキームをリストする
• switch_scheme - アクティブなスキームを変更する

ビルド

• build_project - プロジェクトをビルドする
• build_workspace - ワークスペースをビルドする
• clean_build - ビルドアーティファクトをクリーンする
• archive_project - アーカイブを作成する
• analyze_build - ビルドパフォーマンスを分析する

テスト

• run_tests - ユニットテストを実行する
• run_ui_tests - UIテストを実行する
• generate_test_report - テストレポートを生成する
• code_coverage_report - カバレッジレポートを取得する

シミュレーターとデバイス

• list_devices - 利用可能なシミュレーターをリストする
• boot_simulator - シミュレーターを起動する
• install_app - デバイスにアプリをインストールする
• launch_app - アプリを起動する

LLM統合

• get_llm_status - LLMサービスの状態を確認する
• configure_llm - LLMプロバイダーを設定する

完全なリストはschemas/xcode-mcp-tools.jsonを参照してください。

LangGraphツール（3つのツール）

langgraph_agent

推論と状態管理を備えた複雑なワークフロー用のサブエージェントです。

パラメーター:

• prompt（必須） - 自然言語のタスク説明
• model（オプション） - モデルの上書き（例: "ollama:qwen3-coder:30b"）
• persona（オプション） - ペルソナ設定

例:

langgraph_agentを "Verify my development environment and list all projects" プロンプトで使用

langgraph_workflow

自動ツールオーケストレーションを備えた多段階ワークフローを実行します。

パラメーター:

• workflow（必須） - ワークフロー説明
• context（オプション） - 追加のコンテキスト
• persona（オプション） - ペルソナ設定

例:

langgraph_workflowを "1. Clean build 2. Build project 3. Run tests 4. Generate report" ワークフローで使用

langgraph_status

LangGraphエージェントの状態と利用可能な機能を取得します。

🏗️ アーキテクチャ

統合サーバー

このプロジェクトは統合MCPサーバー（src/unified_mcp_server.py）を使用しており、以下を統合しています。

• 直接ツール - src/xcode_tools/からの94個のツール
• LangGraphツール - LangGraphを使用した3つのサブエージェントツール
• 最適化レイヤー - キャッシュ、圧縮、スキーマ最適化

プロジェクト構造

xcode-mcp/
├── src/
│   ├── unified_mcp_server.py    # メインの統合サーバー
│   ├── tool_registry.py          # ツール登録システム
│   ├── langgraph_agent.py        # LangGraphエージェントの実装
│   ├── llm_service.py            # LLMプロバイダーの抽象化
│   └── xcode_tools/              # ツールの実装
│       ├── project.py            # プロジェクト管理
│       ├── build.py              # ビルド操作
│       ├── testing.py            # テストツール
│       ├── simulator.py          # シミュレーター制御
│       └── ...
├── schemas/
│   ├── xcode-mcp-tools.json      # ツールスキーマ定義
│   ├── persona_schemas.json      # ペルソナスキーマ
│   └── persona_examples.json     # 事前設定されたペルソナ
├── tests/
│   └── test_unified_server.py    # 包括的なテストスイート
├── docs/                         # 追加のドキュメント
├── examples/                     # 使用例
├── run_unified_mcp.py            # サーバーのエントリーポイント
└── environment.yml               # Condaの依存関係

ツール登録

ツールは以下から自動的に登録されます。

1. JSONスキーマ（schemas/xcode-mcp-tools.json）
2. Python実装（src/xcode_tools/）
3. 動的な検出とマッピング

LangGraph統合

LangGraphツールは内部的に直接ツールを使用します。

• エージェントは自然言語のプロンプトを受け取ります。
• ステップに分解します。
• 適切な直接ツールを呼び出します。
• ステップ間で状態を維持します。
• 包括的な結果を返します。

👤 ペルソナ

ペルソナは、異なるユースケースに合わせた特殊なエージェントの動作を提供します。

利用可能なペルソナ

senior-ios-architect

• 役割: アーキテクト
• 専門分野: Swift、Xcode、アーキテクチャ、iOS、パフォーマンス
• スタイル: プロフェッショナル、詳細、エキスパートレベル
• 用途: アーキテクチャの決定、ベストプラクティス、デザインパターン

swift-mentor

• 役割: メンター
• 専門分野: Swift、Xcode、iOS、SwiftUI
• スタイル: 友好的、包括的、中級レベル
• 用途: 学習、教育、ステップバイステップガイダンス

build-optimizer

• 役割: オプティマイザー
• 専門分野: Xcode、パフォーマンス、CI/CD
• スタイル: 簡潔、適度、上級レベル
• 用途: ビルドパフォーマンス、最適化、CI/CD

test-specialist

• 役割: テスター
• 専門分野: テスト、Xcode、Swift、CI/CD
• スタイル: プロフェッショナル、詳細、上級レベル
• 用途: テスト戦略、カバレッジ、品質

ペルソナの使用方法

{
  "persona": {
    "id": "build-optimizer",
    "role": "optimizer",
    "expertise": ["xcode", "performance"],
    "communication_style": {
      "tone": "concise",
      "verbosity": "moderate",
      "technical_level": "advanced"
    }
  }
}

完全な例はschemas/persona_examples.jsonを参照してください。

🔧 トラブルシューティング

MCPサーバーが赤色になる場合

1. 設定を検証する

   python3 -m json.tool ~/.cursor/mcp.json
   

2. サーバーを手動でテストする

   python test_mcp_connection.py
   

3. 古いプロセスを終了する

   pkill -f "run_unified_mcp.py"
   

4. Cursorを再起動する

   • 完全に終了（Cmd+Q）
   • 5秒待つ
   • Cursorを再開する

5. 絶対Pythonパスを使用する ~/.cursor/mcp.jsonを更新して絶対パスを使用します。

   "command": "/path/to/miniconda3/envs/xcode-mcp/bin/python"
   

ツールが表示されない場合

1. Cursorでサーバーが緑色であることを確認する
2. ツールリストを検証する

   python -c "from src.unified_mcp_server import UnifiedMCPServer; s = UnifiedMCPServer(); print(len(s.registry.tools))"
   

3. Cursorを再起動する

LangGraphが機能しない場合

1. インストールを検証する

   conda activate xcode-mcp
   python -c "import langgraph; print('✅ LangGraphがインストールされています')"
   

2. 欠落している場合はインストールする

   pip install langgraph langchain langchain-core langchain-openai langchain-ollama
   

ツール実行エラーの場合

1. Xcode CLIツールを確認する

   xcodebuild -version
   

2. Xcode操作のパーミッションを検証する

3. schemas/xcode-mcp-tools.jsonのツール固有の要件を確認する

🧪 テスト

テストスイートを実行する

# 包括的なテスト
python tests/test_unified_server.py

# 接続テスト
python test_mcp_connection.py

期待される結果

• ✅ 8/8のテストが合格
• ✅ 97個のツールが利用可能
• ✅ すべてのプロトコルが正常に動作
• ✅ サーバーが正しく応答する

🚀 開発

新しいツールの追加

1. スキーマに追加する（schemas/xcode-mcp-tools.json）:

   {
     "name": "my_new_tool",
     "description": "Tool description",
     "parameters": [...]
   }
   

2. 関数を実装する（src/xcode_tools/）:

   def my_new_tool(param1: str, param2: int) -> dict:
       # 実装
       return {"result": "..."}
   

3. テストする:

   python -c "from src.tool_registry import get_registry; r = get_registry(); print(r.execute_tool('my_new_tool', param1='test', param2=1))"
   

プロジェクトの組織

• コアサーバー: src/unified_mcp_server.py
• ツール登録: src/tool_registry.py
• ツールの実装: src/xcode_tools/
• スキーマ: schemas/
• テスト: tests/
• ドキュメント: docs/

パフォーマンス最適化

• スキーマキャッシュ: 5分のTTL
• レスポンスキャッシュ: 成功したレスポンスをキャッシュする
• コンパクトJSON: トークン使用量を削減する
• 遅延ロード: LangGraphは必要なときにのみロードする

📊 パフォーマンスメトリクス

• トークン削減: 最適化により30 - 40%削減
• メモリ使用量: 統合サーバーで50%削減
• レスポンス時間: キャッシュされたレスポンスで50%高速化
• スキーマロード: キャッシュにより80%高速化

📚 追加リソース

• ツールスキーマ: schemas/xcode-mcp-tools.json
• ペルソナスキーマ: schemas/persona_schemas.json
• ペルソナの例: schemas/persona_examples.json
• 使用例: examples/

🤝 コントリビューション

1. 既存のコード構造に従ってください。
2. 新機能にはテストを追加してください。
3. スキーマとドキュメントを更新してください。
4. 提出する前にテストスイートを実行してください。

📝 ライセンス

[ここにライセンスを追加]

🌐 ネットワークアクセス

MCPサーバーをネットワーク上の他のデバイスに公開するには、以下を実行します。

# ネットワークサーバーを起動（デフォルト: ポート8000）
python run_network_server.py

# カスタム設定で起動
MCP_HOST=0.0.0.0 MCP_PORT=8000 python run_network_server.py

# 認証付きで起動
MCP_API_KEY=your-secret-key MCP_REQUIRE_AUTH=true python run_network_server.py

エンドポイント:

• HTTP: http://YOUR_IP:8000/mcp
• WebSocket: ws://YOUR_IP:8000/ws
• ツールリスト: http://YOUR_IP:8000/tools
• ヘルスチェック: http://YOUR_IP:8000/health

完全なネットワーク設定ガイドはdocs/NETWORK_SETUP.mdを参照してください。これには以下が含まれます。

• 設定オプション
• 認証設定
• クライアントの例（Python、JavaScript、curl）
• セキュリティ上の考慮事項
• 本番環境でのデプロイ

🙏 謝辞

• モデルコンテキストプロトコル仕様
• LangGraphによるサブエージェントワークフロー
• Xcodeコマンドラインツール

バージョン: 2.1.0
最終更新日: 2025-01-XX
メンテナー: Eddikson Peña

🆕 v2.1.0の新機能

21の新ツールが追加されました

クラッシュレポート

• クラッシュログをシンボリック化して分析する
• クラッシュ情報を自動的に抽出する
• クラッシュレポートをエクスポートする

アセット管理

• 画像を自動的に最適化する
• アプリアイコンセットを生成する
• アセットカタログを検証する
• アセットサイズをチェックする

シミュレーターの機能強化

• GPS位置を設定する
• シミュレーターログを取得する
• インストールされたアプリをリストする
• シミュレーターを複製する

ローカライズ

• ローカライズ可能な文字列を抽出する
• 翻訳を検証する
• カバレッジ率をチェックする
• サポートされているロケールをリストする

ビルドの機能強化

• 特定のビルド/バージョン番号を設定する
• ビルド時間を分析する
• 強化されたバージョン管理

完全な詳細はDEPLOYMENT_SUMMARY.mdを参照してください。