axiom-xcode-mcp-tools

Xcode MCP ツールのワークフロー

基本原則：Xcode MCP を使うと、IDE にプログラムからアクセスできます。個別にツールを呼び出すのではなく、ワークフローのループを活用してください。

ウィンドウの指定（基盤として重要）

ほとんどのツールでは tabIdentifier が必要です。必ず最初に XcodeListWindows を呼び出してください。

1. XcodeListWindows → list of (tabIdentifier, workspacePath) pairs
2. Match workspacePath to your project
3. Use that tabIdentifier for all subsequent tool calls

セッション中はマッピングをキャッシュしてください。再取得が必要なのは次の場合のみです。

• ツール呼び出しが無効なタブ識別子で失敗した
• Xcode のウィンドウを開いた、または閉じた
• プロジェクトを切り替えた

XcodeListWindows の結果が空の場合：Xcode でプロジェクトが開かれていません。ユーザーにプロジェクトを開くよう依頼してください。

ワークフロー：BuildFix ループ

プロジェクトがコンパイルできるまで、ビルド、診断、修正を繰り返します。

1. BuildProject(tabIdentifier)
2. Check buildResult — if success, done
3. GetBuildLog(tabIdentifier) → parse errors
4. XcodeListNavigatorIssues(tabIdentifier) → canonical diagnostics
5. XcodeUpdate(file, fix) for each diagnostic
6. Go to step 1 (max 5 iterations)
7. If same error persists after 3 attempts → fall back to axiom-xcode-debugging

ビルドログの解析より XcodeListNavigatorIssues を使う理由：Issue Navigator では、重複が除かれた構造化診断を確認できます。ビルドログには、ノイズを含むコンパイラーの生の出力が記録されています。

axiom-xcode-debugging に切り替えるタイミング：エラーがコードレベルの問題ではなく、ゾンビプロセス、古い Derived Data、シミュレーターの問題など、環境に起因する場合です。MCP ツールはコードを操作しますが、環境の問題には CLI による診断が必要です。

ワークフロー：TestFix ループ

失敗したテストをすばやく繰り返し実行します。

1. GetTestList(tabIdentifier) → discover available tests
2. RunSomeTests(tabIdentifier, [specific failing tests]) for fast iteration
3. Parse failures → identify code to fix
4. XcodeUpdate(file, fix) to patch code
5. Go to step 2 (max 5 iterations per test)
6. RunAllTests(tabIdentifier) as final verification

最初に RunSomeTests を使う理由：単一のテストは数秒で実行できますが、すべてのテストを実行すると数分かかります。失敗したテストを繰り返し実行して修正し、成功したらテストスイート全体を一度実行して確認してください。

テスト結果の解析：応答の testResult フィールドを確認してください。失敗したテストには、ファイルパスと行番号を含む失敗メッセージが記載されます。

ワークフロー：PreviewVerify

SwiftUI プレビューをレンダリングし、UI の変更を視覚的に確認します。

1. RenderPreview(tabIdentifier, sourceFilePath, previewDefinitionIndexInFile: 0) → image artifact
2. Review the rendered image for correctness
3. If making changes: XcodeUpdate → RenderPreview again
4. Compare before/after for regressions

使用例：レイアウトの変更を検証する、ダークモードでの表示を確認する、Liquid Glass の効果が正しくレンダリングされることを確認する。

ワークフロー：IssueTriage

Xcode の Issue Navigator を標準の診断情報源として使用します。

1. XcodeListNavigatorIssues(tabIdentifier) → all current issues
2. For specific files: XcodeRefreshCodeIssuesInFile(tabIdentifier, file)
3. Prioritize: errors > warnings > notes
4. Fix errors first, rebuild, re-check

エラーの grep 検索よりこれを使う理由：Issue Navigator では、型チェックエラー、インポートの不足、制約の問題など、Xcode のコンパラーフロントエンドでのみ検出できるものも含め、リアルタイムの診断情報を確認できます。

ワークフロー：DocumentationSearch

MCP 経由で Apple のドキュメントコーパスを検索します。

1. DocumentationSearch(query) → documentation results
2. Cross-reference with axiom-apple-docs for bundled Xcode guides

注：DocumentationSearch は、Apple のオンラインドキュメントと WWDC のトランスクリプトを検索します。Xcode に同梱されている LLM 向けガイド 20 件を検索するには、代わりに axiom-apple-docs を使用してください。

MCP によるファイル操作

読み取りと書き込み

操作	ツール	備考
ファイルの内容を読み取る	XcodeRead	Xcode のプロジェクトビューを参照します（生成されたファイル、解決済みのパッケージを含む）
新しいファイルを作成する	XcodeWrite	ファイルを作成し、プロジェクト構造に自動で追加します
既存のファイルを編集する	XcodeUpdate	str_replace 形式のパッチを適用します。ファイル全体を書き換えるより安全です
ファイルを検索する	XcodeGlob	プロジェクト内でパターンに一致するファイルを検索します
ファイルの内容を検索する	XcodeGrep	行番号付きで内容を検索します
ディレクトリを一覧表示する	XcodeLS	ディレクトリの一覧を表示します
ディレクトリを作成する	XcodeMakeDir	ディレクトリを作成します

破壊的な操作（確認が必要）

操作	ツール	リスク
ファイル／ディレクトリを削除する	XcodeRM	デフォルトではゴミ箱に移動します（deleteFiles: true）。ユーザーに確認してください
ファイルを移動／名前変更する	XcodeMV	インポートや参照が壊れる可能性があります

XcodeRM または XcodeMV を呼び出す前に、破壊的な操作について必ずユーザーに確認してください。

MCP ファイルツールと標準ツールの使い分け

状況	MCP を使用	標準ツール（Read/Write/Grep）を使用
Xcode のプロジェクトビュー内のファイル	はい。生成／解決済みのファイルを含みます	生成されたファイルを見落とす可能性があります
プロジェクト外のファイル	いいえ	はい。標準ツールはどこでも使えます
ビルドコンテキストが必要（編集後の診断）	はい。1 つのワークフローで編集と再ビルドを行えます	ビルドとの連携はありません
簡単なファイルの読み取り／編集	どちらでも可能です	やや高速です（MCP のオーバーヘッドがありません）

コードスニペット

Swift コードの実行

ExecuteSnippet(tabIdentifier, codeSnippet: "print(MyModel.self)", sourceFilePath: "Sources/MyModel.swift")

特定の Swift ファイルのコンテキストでコードを実行します。そのファイルの fileprivate 宣言にアクセスできます。汎用 REPL ではありません。language パラメーターはありません（Swift のみ）。

注意点とアンチパターン

タブ識別子の陳腐化

次の場合、タブ識別子は無効になります。

• Xcode ウィンドウを閉じて再度開いたとき
• プロジェクトを閉じて再度開いたとき
• Xcode を再起動したとき

解決方法：XcodeListWindows を再度呼び出して、新しい識別子を取得します。

XcodeWrite と XcodeUpdate

• XcodeWrite — 新しいファイルを作成します。ファイルが存在する場合は失敗します（一部のクライアントの場合）。
• XcodeUpdate — oldString／newString の置換によって、既存のファイルにパッチを適用します。呼び出しごとに置換は 1 回です（すべての出現箇所を置換するには replaceAll: true を使用します）。

よくある間違い：既存のファイルの編集に XcodeWrite を使うと、ファイルの内容全体が上書きされます。編集には XcodeUpdate を使用します。

スキーマ準拠

Xcode の mcpbridge には、既知の MCP 仕様違反があります。ツールで outputSchema が宣言されている場合、content は設定されますが、structuredContent は省略されます。これにより、厳格な MCP クライアント（Cursor、一部の Zed 構成）が動作しなくなります。

回避策：厳格なクライアント向けのプロキシとして XcodeMCPWrapper を使用します。

ファイル変更後のビルド

XcodeUpdate の後、新しい診断結果を表示するためにプロジェクトのビルドが必要になる場合があります。再ビルドせずに編集が正しいと決めつけないでください。

正当化を避ける

考え	実際のところ
「xcodebuild を使えばいい」	MCP では、CLI では得られない IDE の状態、ナビゲーターの診断結果、プレビューを取得できます
「Xcode ファイルは Read ツールで問題なく読める」	XcodeRead は、生成ファイルや解決済みパッケージを含む Xcode のプロジェクトビューを確認できます
「プロジェクトは 1 つしかないからタブ識別子は不要」	tabIdentifier がないと多くのツールは失敗しても通知しません。必ず最初に XcodeListWindows を呼び出してください
「毎回すべてのテストを実行する」	反復作業には RunSomeTests、検証には RunAllTests を使うと、サイクルごとに数分節約できます
「ビルドログを解析してエラーを探す」	XcodeListNavigatorIssues は、構造化され、重複が除去された診断結果を提供します
「ファイルの更新に XcodeWrite を使う」	編集には XcodeUpdate を使用します。XcodeWrite は作成／上書きを行います。ツールを誤るとデータが失われます。
「ツール呼び出しは 1 回で十分」	ワークフロー（BuildFix、TestFix）はループを使用します。単発の呼び出しでは反復のパターンを見落とします。

リソース

スキル：axiom-xcode-mcp-setup、axiom-xcode-mcp-ref、axiom-xcode-debugging