awesome-ios-sim

简体中文 · MCPガイド · DeepSeek Harness · アーキテクチャ

iOS開発者、CIパイプライン、AIエージェントのための「シミュレータ状態をコードとして」管理するツール。

awesome-ios-sim は、iOSシミュレータのセットアップをバージョン管理可能なプロファイルに変換し、キャプチャ、差分比較、計画、レビュー、安全な適用を可能にします。決定論的なCLIとMCP stdioサーバーの両方を提供します。また、DeepSeek Harness用の dsh-plugin バンドルとしてもインストール可能です。

プロジェクトステータス: アルファ版。 状態スキーマは v1alpha1 です。適用前に生成された計画をレビューしてください。特に erase やアプリ削除操作を含む計画には注意が必要です。

なぜこれが必要か

シミュレータの自動化は通常、シェルスクリプト、文書化されていないデフォルト設定、手動セットアップに分散しています。そのため、テスト環境の再現が難しく、AIエージェントに安全でない型付けされていないシェルインターフェースを提供することになります。

このプロジェクトは1つのワークフローを導入します：

profile + current snapshot -> diff -> deterministic plan -> explicit confirmation -> audited apply

• 宣言的: テストやアプリケーションコードの隣にシミュレータプロファイルをコミットします。

• レビュー可能: 変更前に正確な順序付けられた操作計画を検査できます。

• エージェントセーフ: MCPツールはJSON Schemaを使用し、simulator_apply はデフォルトでドライランを実行します。

• 機能認識: 正確、ベストエフォート、未サポートの状態が明示的に報告されます。

• 公開APIのみ: 変更はAppleの xcrun simctl を通じて行われ、プライベートなCoreSimulatorフレームワークは使用しません。

• ローカルファースト: デーモン、クラウドアカウント、テレメトリ、APIキーは不要です。

Related MCP server: Shotter

アーキテクチャ

flowchart LR
    P[State profile] --> E[Pure Swift state engine]
    S[Live or saved snapshot] --> E
    E --> D[Diff]
    E --> PL[Ordered plan]
    PL --> C{Explicit confirm?}
    C -- No --> DR[Dry-run report]
    C -- Yes --> X[Typed simctl driver]
    X --> J[Execution receipts]
    CLI[CLI] --> E
    MCP[MCP stdio server] --> E

状態エンジンはXcodeに依存せず、フィクスチャでテストされています。SimctlDriver のみがホストプロセスの境界に触れます。CLIとMCPサーバーは同じプランナー、バリデーション、適用ゲートを共有します。

必要条件

• macOS 13以降。

• Swift 6。

• ライブインベントリ、スナップショット、適用操作には、iOSシミュレータランタイムを含む完全なXcodeが必要です。

• xcode-select が意図したXcodeインストールに設定されていること。

コマンドラインツールだけでもパッケージをビルドできますが、CoreSimulatorや simctl は提供されません。

インストール

git clone https://github.com/qubyyang/awesome-ios-sim.git
cd awesome-ios-sim
swift build -c release

実行可能ファイルは以下の場所に生成されます：

.build/release/ios-sim-state
.build/release/ios-sim-state-mcp

Homebrew配布と署名済みリリースアーティファクトは、スキーマが安定化した後に計画されています。

クイックスタート

利用可能なシミュレータを一覧表示：

swift run ios-sim-state inventory

1つのシミュレータをキャプチャ：

swift run ios-sim-state snapshot --device <UDID> > simulator.snapshot.json

付属の例からオフラインプランを生成：

swift run ios-sim-state plan \
  --profile Examples/ui-tests.profile.json \
  --snapshot Examples/ui-tests.snapshot.json > simulator.plan.json

変更なしで適用動作をプレビュー（デフォルト）：

swift run ios-sim-state apply --plan simulator.plan.json

レビュー済みの計画を適用し、実行ジャーナルを保持：

swift run ios-sim-state apply \
  --plan simulator.plan.json \
  --confirm \
  --journal simulator.report.json

apply は最初に失敗した操作で停止します。各レシートには実行された引数配列、終了コード、stdout、stderr、タイムスタンプが含まれます。

状態プロファイル

プロファイルは schemas/v1alpha1/simulator-state.schema.json に対して検証されるJSONドキュメントです。安全なデフォルト値を持つフィールドは省略可能です。

{
  "apiVersion": "awesome-ios-sim/v1alpha1",
  "kind": "SimulatorState",
  "metadata": { "name": "ui-tests" },
  "target": {
    "name": "iPhone 17 Pro",
    "runtime": "com.apple.CoreSimulator.SimRuntime.iOS-27-0"
  },
  "spec": {
    "power": "shutdown",
    "applications": [
      {
        "bundleIdentifier": "com.example.app",
        "sourcePath": "/absolute/path/to/Example.app",
        "running": true,
        "launchArguments": ["--uitesting"]
      }
    ],
    "preferences": [
      {
        "domain": "com.example.app",
        "key": "hasSeenOnboarding",
        "value": false
      }
    ],
    "statusBar": { "time": "09:41", "batteryLevel": 100 }
  }
}

power: "unchanged" は一時的な作業後に元の電源状態を復元します。消去が計画されている場合、起動中のデバイスは最初にシャットダウンされます。ブート操作は依存する作業の前に simctl bootstatus -b を待ちます。

CLI

すべての機械向け出力はJSONです。--compact を使用すると1行出力になります。

AIエージェント向けMCP

MCP実行可能ファイルをビルドし、stdio対応のMCPクライアントにその絶対パスを指定します：

{
  "mcpServers": {
    "awesome-ios-sim": {
      "command": "/absolute/path/awesome-ios-sim/.build/release/ios-sim-state-mcp"
    }
  }
}

サーバーは5つのツールを公開します：

stdioサーバーはMCP 2026-07-28 ステートレスリクエストモデルを実装しており、server/discover、リクエストごとの _meta、キャッシュ可能なツールリスト、resultType、JSON Schema 2020-12 を含みます。また、2025-11-25、2025-06-18、2024-11-05 のツールクライアントで使用されるレガシー初期化ハンドシェイクも受け入れます。ワイヤー例と正確なサポートサブセットについては MCPガイド を参照してください。

DeepSeek Harnessプラグイン

リポジトリをDSHバンドルとしてインストールし、Webプロファイルを起動します：

dsh plugin --profile web add github:qubyyang/awesome-ios-sim
dsh web

Harnessは既存のMCPサーバーをブリッジし、mcp__ios_sim__simulator_inventory や mcp__ios_sim__simulator_plan などの名前空間付きツールを公開します。アダプターは現在 @deepseek-ai/dsh 0.1.0-rc.7 に対してテストされています。再現可能な環境ではタグまたはコミットを固定してください。Harnessはまだ開発者プレビュー段階です。

設定、開発、ツール名、アンインストール手順、ホストプロセスのセキュリティ境界については DeepSeek Harnessガイド を参照してください。

状態カバレッジ

プランナーはベストエフォートデータを決して静かに正確な状態にアップグレードしません。読み戻しがない場合は、機能メタデータ、繰り返しの冪等書き込み、または収束の誤った主張ではなく警告を生成します。

安全性モデル

• シェルは呼び出されません。実行可能ファイルと引数は別々に渡されます。

• diff、plan、デフォルトの apply はシミュレータを変更できません。

• CLIのapplyには --confirm が必要です。MCPのapplyにはブール値 confirm: true が必要です。

• 操作は直列化され、最初の失敗で停止します。

• 起動中のシミュレータは消去前にシャットダウンされます。

• 一時的なブートは要求された、または元の最終電源状態を復元します。

• ツールスキーマは未知のトップレベル引数を許可しません。

• プライベートフレームワークのロード、孤立ディレクトリの削除、ファイルシステムのクリーンアップは行われません。

計画ファイルは実行可能な意図として扱ってください。確認前に、ターゲットUDID、アプリパス、消去操作、設定ドメインへの変更をレビューしてください。

なぜSwiftか

シミュレータの作業はXcodeとCoreSimulatorプロセスのレイテンシに支配されており、言語レベルのCPU時間ではありません。SwiftはネイティブなmacOS配布、強力な Codable モデル、ランタイムを追加せずにiOSツールとの直接的な整合性を提供します。RustはポータブルでCPU負荷の高いインデクサーには強力な選択肢ですが、simctl boot、インストール、消去を実質的に高速化することはありません。パッケージは純粋な状態エンジンとプロセス境界を分離しているため、プロファイリングが必要と判断された場合に後で専門のヘルパーを導入できます。

開発

swift build
swift test
npm ci
npm test
npm run pack:check
swift run ios-sim-state plan \
  --profile Examples/ui-tests.profile.json \
  --snapshot Examples/ui-tests.snapshot.json

CONTRIBUTING.md、SECURITY.md、アーキテクチャノート を参照してください。プライベートなCoreSimulator APIは追加しないでください。

ロードマップ

• プロファイルスキーマを安定化し、タグ付きバイナリを公開。

• Homebrew配布と署名済みユニバーサルアーティファクトを追加。

• 再利用可能なプロファイルレイヤーとプリセットを追加。

• プライベートフレームワークなしで機能認識設定を拡張。

• 同じ状態エンジン上にネイティブSwiftUIコンパニオンアプリを構築。

ライセンス

MIT。 LICENSE を参照。