📱 MCP Server for iOS Simulator

📱 iOS Simulator 用 MCP サーバー

自然言語コマンドを通じて、LLM が iOS シミュレーターを操作できるようにする Model Context Protocol（MCP）サーバーです。

ℹ️ 概要

この MCP サーバーは、LLM と iOS シミュレーターをつなぐブリッジとして機能し、自然言語コマンドによる包括的な制御を可能にします。次のことができます。

詳しい使い方については、「インストール」および「サポートされているコマンド」のセクションをご覧ください。このサーバーは、MCP と直接連携させる方法と、スタンドアロンライブラリとして使う方法のどちらでも利用できます。

コンポーネントがどのように連携し、自然言語による iOS シミュレーターの制御を実現するかについては、「アーキテクチャ」セクションをご覧ください。実行フロー全体、コンポーネントのコントラクト、セッションモデルについては、ARCHITECTURE.mdをご覧ください。このリポジトリで作業するエージェントやコントリビューター向けのガイダンスは、AGENTS.mdに記載されています。

🎮 シミュレーターの制御

• シミュレーターのセッションを作成、管理
• シミュレーターの起動、シャットダウン、状態の監視
• 利用可能なシミュレーターと実行中のシミュレーターを一覧表示
• シミュレーターのウィンドウにフォーカス

📱 アプリケーションの管理

• iOS アプリケーションのインストール、管理
• アプリの起動、終了、アンインストール
• アプリの状態を監視し、インストールを確認
• アプリの権限と設定を管理

🖱️ UI の操作とテスト

• シミュレーターの UI を操作
• タップ、スワイプ、ボタン押下の操作を実行
• テキストやキーシーケンスを入力
• UI テスト用にアクセシビリティ要素にアクセス
• UI 操作の動画を録画

🛠️ 開発とデバッグ

• スクリーンショットとシステムログを取得
• アプリケーションをリアルタイムでデバッグ
• クラッシュログを監視、分析
• 動的ライブラリをインストールし、アプリデータを管理

⚡ 高度な機能

• その他の機能：
  • 位置情報のシミュレーション
  • メディアの挿入
  • URL スキームの処理
  • 連絡先データベースの管理
  • キーチェーン操作

詳しい使い方については、「インストール」および「サポートされているコマンド」のセクションをご覧ください。このサーバーは、MCP と直接連携させる方法と、スタンドアロンライブラリとして使う方法のどちらでも利用できます。

コンポーネントがどのように連携し、自然言語による iOS シミュレーターの制御を実現するかについては、「アーキテクチャ」セクションをご覧ください。

📋 必要条件

• macOS：iOS シミュレーターのサポートに必要です
• Node.js：v20.0.0 以上
• Homebrew：依存関係のインストールに必要です
• XCode：iOS シミュレーターがインストールされていること

🚀 インストール

このサーバーを最も簡単にインストールする方法は、Cline を利用することです。

1. Cline に次のように依頼します。

Add this mcp to cline https://github.com/InditexTech/mcp-server-simulator-ios-idb

2. Cline が依存関係の管理や設定を含むインストールプロセスを自動的に処理します。

または、手動でインストールすることもできます。

# Clone the repository
git clone https://github.com/InditexTech/mcp-server-simulator-ios-idb.git
cd mcp-server-simulator-ios-idb

# Create and activate Python virtual environment
python3 -m venv venv
source venv/bin/activate  # On Unix/macOS

# Install dependencies
npm install

# Build the project
npm run build

# Start the project
npm start

# Run tests
npm test

インストールプロセスでは、次の処理が自動的に行われます。

1. macOS を実行しているか確認
2. Homebrew を使って idb-companion をインストール
3. 仮想環境内に pip を使って fb-idb をインストール

注：サーバーの使用中は、仮想環境を有効にしたままにしてください。ターミナルを閉じて後で再度開いた場合は、npm startを実行する前にsource venv/bin/activateコマンドで仮想環境を再度有効にする必要があります。

🔌 MCP 連携

このサーバーを Claude やその他の LLM アシスタントと使用するには、次の手順に従います。

1. Claude Desktop の MCP 設定にサーバーを追加します。

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

2. LLM が自然言語コマンドを使って iOS シミュレーターを制御できるようになります。

create a simulator session with iPhone 14
install app /path/to/my-app.ipa
launch app com.example.myapp
tap at 100, 200
take a screenshot

📚 ライブラリとしての使用

このパッケージを、独自のプロジェクトでライブラリとして使用することもできます。

🔰 基本的な使い方

⚠️ インポート時の副作用：パッケージのエントリーポイント （'mcp-server-simulator-ios-idb'／dist/index.js）をインポートすると、モジュールの読み込み時にサーバーの起動 コードが実行されます。コンソール出力を上書きし、logs/ ディレクトリを作成し、SIGINT／SIGTERM／例外ハンドラーを登録し、MCP stdio サーバーを無条件に起動します。現在、無効にする方法はありません。パッケージのルートをインポートする場合はすべて対象となり、名前付きインポートでもブートストラップは無効になりません。トランスポートやシグナルに関する副作用なしでパーサー／オーケストレーター／マネージャーを使用するには、以下に示すようにコンパイル済みのコンポーネントモジュールをディープパスからインポートしてください（dist/...）。なお、dist/mcp/mcp-server.js をインポートすると MCP サーバーのシングルトンもブートストラップされるため、ライブラリとして使用する場合はこのパスを避けてください。パッケージで宣言されているのは "main" のみで（exports マップはありません）、ディープパスは通常どおり解決されます。

// Deep imports of compiled component modules: these do NOT trigger the
// package root startup (no MCP stdio server, no signal handlers).
import { MCPOrchestrator } from 'mcp-server-simulator-ios-idb/dist/orchestrator/MCPOrchestrator.js';
import { NLParser } from 'mcp-server-simulator-ios-idb/dist/parser/NLParser.js';
import { IDBManager } from 'mcp-server-simulator-ios-idb/dist/idb/IDBManager.js';

async function main() {
  // Compose the components (equivalent to createMCPServer internals)
  const idbManager = new IDBManager();
  const parser = new NLParser();
  const orchestrator = new MCPOrchestrator(parser, idbManager);

  // Process natural language commands

  // Create a simulator session
  const sessionResult = await orchestrator.processInstruction('create session');
  console.log(`Session created: ${sessionResult.data}`);

  // Interact with the simulator
  await orchestrator.processInstruction('tap at 100, 200');

  // Capture a screenshot
  const screenshotResult = await orchestrator.processInstruction('take screenshot');
  console.log(`Screenshot saved at: ${screenshotResult.data}`);
}

main().catch(console.error);

ℹ️ MCP サーバー自体（現在は src/mcp/mcp-server.ts で定義されており、パッケージのエントリーポイントから再エクスポートされていません）は、npm start または MCP クライアント設定を使って実際のサーバープロセスを実行する場合にのみ意味があります。createMCPServer() ファクトリーは、上記と同じ3つのコンポーネントを組み合わせるだけです。

🚀 高度な使い方

ディープインポートを使用して、個々のコンポーネントを直接利用することもできます。

import { IDBManager } from 'mcp-server-simulator-ios-idb/dist/idb/IDBManager.js';

// Create instance and use it directly
const idbManager = new IDBManager();

const sessionId = await idbManager.createSimulatorSession({
  deviceName: 'iPhone 12',
  platformVersion: '15.0'
});

await idbManager.tap(sessionId, 100, 200);

🏗️ プロジェクト構成

mcp-server-simulator-ios-idb/
├── src/                      # Source code
│   ├── adapters/             # Adapter components
│   ├── idb/                  # IDB manager implementation
│   ├── mcp/                  # MCP server implementation
│   ├── orchestrator/         # Command orchestrator
│   ├── parser/              # Natural language parser
│   └── index.ts             # Main entry point
├── scripts/                 # Installation scripts
├── package.json            # Project configuration
└── tsconfig.json          # TypeScript configuration

🎯 サポートされているコマンド

NLParser は、以下の自然言語コマンドをサポートしています。

🎮 シミュレーター管理

コマンド	説明	例
セッションを作成	新しいシミュレーターセッションを作成します	"create session", "create simulator iPhone 12"
セッションを終了	現在のセッションを終了します	"terminate session", "close simulator"
シミュレーターを一覧表示	利用可能なシミュレーターを一覧表示します	"list simulators", "show simulators"
起動中のシミュレーターを一覧表示	実行中のシミュレーターを一覧表示します	"list booted simulators", "show running simulators"
シミュレーターを起動	UDID を指定してシミュレーターを起動します	"boot simulator 5A321B8F-4D85-4267-9F79-2F5C91D142C2"
シミュレーターをシャットダウン	シミュレーターをシャットダウンします	"shutdown simulator 5A321B8F-4D85-4267-9F79-2F5C91D142C2"
シミュレーターにフォーカス	シミュレーターのウィンドウを前面に表示します	"focus simulator", "bring simulator to front"
シミュレーターセッションを一覧表示	アクティブなシミュレーターセッションを一覧表示します	"list simulator sessions", "show active sessions"

📱 アプリ管理

コマンド	説明	例
アプリをインストール	シミュレーターにアプリをインストールします	"install app /path/to/app.ipa"
アプリを起動	シミュレーターでアプリを起動します	"launch app com.example.app"
アプリを終了	実行中のアプリを終了します	"terminate app com.example.app"
アプリをアンインストール	アプリをアンインストールします	"uninstall app com.example.app"
アプリを一覧表示	インストール済みのアプリケーションを一覧表示します	"list apps", "show installed apps"
アプリのインストール状況を確認	アプリがインストールされているか確認します	"is app com.example.app installed"

🖱️ UI 操作

コマンド	説明	例
タップ	指定した座標をタップします	"tap at 100, 200"
スワイプ	スワイプ操作を実行します	"swipe from 100, 200 to 300, 400"
ボタンを押す	デバイスのボタンを押します	"press button HOME", "press button SIRI"
テキストを入力	テキストを入力します	"input text Hello World"
キーを押す	コードを指定してキーを押します	"press key 4"
キーシーケンスを押す	キーのシーケンスを押します	"press key sequence 4 5 6"

♿ アクセシビリティ

コマンド	説明	例
要素を説明	すべてのアクセシビリティ要素を一覧表示します（未実装）	"describe all elements", "show accessibility elements"
座標上の要素を説明	指定した座標にある要素を説明します（未実装）	"describe point 100, 200", "what's at 150, 300"

📸 キャプチャとログ

コマンド	説明	例
スクリーンショットを撮る	スクリーンショットを撮影します	"take screenshot", "capture screen"
動画を録画する	画面の動作を録画します（未実装）	"record video /path/output.mp4"
録画を停止する	動画の録画を停止します（未実装）	"stop recording", "stop video recording"
ログを取得する	システムまたはアプリのログを取得します	"get logs", "get logs for com.example.app"

🐛 デバッグ

コマンド	説明	例
デバッグを開始する	デバッグセッションを開始します（未実装）	"debug app com.example.app", "start debug com.example.app"
デバッグを停止する	デバッグセッションを停止します（未実装）	"stop debug", "terminate debug session"
デバッグ状態	デバッグセッションの状態を取得します	"debug status", "show debug info"

💥 クラッシュログ

コマンド	説明	例
クラッシュログを一覧表示する	利用可能なクラッシュログを一覧表示します	"list crash logs", "show crash logs"
クラッシュログを表示する	クラッシュログの内容を表示します	"show crash log crash_2023-01-01"
クラッシュログを削除する	アプリのクラッシュログを削除します。明示的に指示された場合は、すべてのログを削除します	"delete crash logs for com.example.app", "delete all crash logs"

🔧 その他のコマンド

コマンド	説明	例
dylib をインストールする	ダイナミックライブラリをインストールします	"install dylib /path/to/library.dylib"
URL を開く	シミュレーターで URL を開きます	"open url https://example.com"
キーチェーンを消去する	シミュレーターのキーチェーンを消去します	"clear keychain"
位置情報を設定する	シミュレーターの位置情報を設定します	"set location 37.7749, -122.4194"
メディアを追加する	カメラロールにメディアを追加します	"add media /path/to/image.jpg"
権限を許可する	アプリの権限を許可します	"approve permissions com.example.app photos camera"
連絡先を更新する	連絡先データベースを更新します	"update contacts /path/to/contacts.sqlite"

このインターフェースは idb CLI ツールで利用できるすべてのコマンドに対応しており、iOS シミュレーターの自動化に必要な包括的な操作を提供します。

🔍 アーキテクチャ

サーバーは、次の 3 つの主要コンポーネントで構成されています。

1. IDBManager：idb を通じて iOS シミュレーターと直接やり取りする低レベルのコンポーネントです。
2. NLParser：自然言語の指示を解釈し、構造化されたコマンドに変換するコンポーネントです。
3. MCPOrchestrator：パーサーと IDBManager 間のやり取りを調整する中心的なコンポーネントです。

これらのコンポーネントは、アダプターを通じて接続されています。

• ParserToOrchestrator：パーサーの結果をオーケストレーターのコマンドに変換します。
• OrchestratorToIDB：オーケストレーターのコマンドを IDBManager の呼び出しに変換します。

完全な実行フロー（MCP stdio → オーケストレーター → パーサー／レジストリ → アダプター → IDBManager → idb ／ xcrun simctl）、コンポーネントの契約、セッションモデル（activeSessionId と sessionId → UDID）、および新しいコマンドを追加するためのチェックリストについては、ARCHITECTURE.md に記載されています。

🔌 MCP との連携

このサーバーを Model Context Protocol で使用するには、次の手順に従います。

1. MCP の設定にサーバーを追加します。

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

2. LLM アプリケーションでサーバーに接続します。

const result = await useMcpTool({
  serverName: "ios-simulator",
  toolName: "process-instruction",
  arguments: {
    instruction: "create simulator session"
  }
});

🙏 謝辞

このプロジェクトは、基盤となる iOS シミュレーター制御機能を提供する facebook/idb なしには実現できませんでした。強力で信頼性の高いツールを作成し、保守してくださっている Facebook／Meta チームおよび idb プロジェクトのすべてのコントリビューターに、心より感謝申し上げます。

📄 ライセンス

このツールは Apache-2.0 の条件のもと、オープンソースとして利用できます。