🚀 XcodeMCPWrapper - mcpbridge-wrapper
Xcode 26.3のMCPブリッジをCursorやその他の厳格なMCP仕様準拠のクライアントと互換性を持たせるPythonラッパーです。
🚀 クイックスタート
前提条件
- Xcode 26.3以上がインストールされたmacOS
- Python 3.9以上
- Xcode Tools MCP Serverを有効にする(以下を参照)
⚠️ 重要: Xcodeの設定でXcode Tools MCPを有効にする必要があります。
- Xcode > Settings (⌘,)を開く
- サイドバーでIntelligenceを選択
- Model Context Protocolの下で、Xcode ToolsをONに切り替える
MCPクライアントのログに「Found 0 tools」と表示される場合は、この設定が有効になっていません。
Cursorのクイックセットアップ
Cursorを使用する場合は、インストールは必要ありません。~/.cursor/mcp.jsonに以下を追加するだけです。
ブローカーモード(推奨):
{
"mcpServers": {
"xcode-tools": {
"command": "uvx",
"args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper", "--broker"]
}
}
}
Web UIダッシュボード付き(オプション - http://localhost:8080でリアルタイム監視が追加されます):
{
"mcpServers": {
"xcode-tools": {
"command": "uvx",
"args": [
"--from",
"mcpbridge-wrapper[webui]",
"mcpbridge-wrapper",
"--broker",
"--web-ui",
"--web-ui-config",
"/Users/YOUR_USERNAME/.mcpbridge_wrapper/webui.json"
]
}
}
}
ダイレクトモード(代替案):
{
"mcpServers": {
"xcode-tools": {
"command": "uvx",
"args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"]
}
}
}
アップグレードした後、現在実行中のダッシュボードプロセスのバージョンを確認するには:
PORT=8080
PID=$(lsof -tiTCP:$PORT -sTCP:LISTEN | head -n1)
PY=$(ps -p "$PID" -o command= | awk '{print $1}')
"$PY" -c 'import importlib.metadata as m; print(m.version("mcpbridge-wrapper"))'
必要に応じて、一度だけリフレッシュして起動するには:
uvx --refresh --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080
Cursorを再起動すれば完了です。他のクライアントやインストール方法については、引き続き読んでください。
ブローカーモード
ブローカーモードでは、複数の短期間のMCPクライアントセッションが1つの永続的な上流ブリッジセッションを共有できます。
- このモードが存在する理由: AppleはXcode 26.4のCoding Intelligenceに関する既知の問題を文書化しています。外部開発ツールが通常の使用中に繰り返し「Allow Connection?」ダイアログをトリガーする場合があります (
170721057)。ブローカーモードを使用して1つの長期間の上流セッションを再利用することで、このプロンプトパターンが表示される再接続の混乱を減らすことができます。Appleの公式のXcode 26.4リリースノートを参照してください。
--brokerを使用して自動検出する - デーモンが稼働している場合は接続し、そうでない場合は起動します(推奨)。
- 起動したホストまたはデーモンホストが1つの共有ダッシュボードエンドポイントを所有する場合は、
--web-ui(およびオプションの--web-ui-config)を追加します。
- 複数のエディタで1つの明示的なデーモンオーナーと1つの可視的な監視画面が必要な場合は、専用のホストを使用することをお勧めします。一度
--broker-daemon --web-uiを起動し、クライアントを--brokerに設定し、ブラウザのダッシュボードおよび/または--tuiをそのホストに接続します。
クイック移行の例:
claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker
codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker
完全な起動/停止/ステータスコマンド、CursorのJSONスニペット、トラブルシューティング、およびダイレクトモードへのロールバックについては、ブローカーモードガイドを参照してください。
マルチエージェントガイダンス
複数のMCPクライアントプロセスを同時に実行する場合:
- 専用ホストフロントエンドワークフロー(可視性が重要な場合に推奨): 1つの
--broker-daemon --web-uiプロセスを起動し、すべてのエディタ/クライアントを--brokerに設定し、ブラウザのダッシュボードおよび/またはmcpbridge-wrapper --tuiを同じホストに接続します。
- 統一された単一設定の自動起動: 設定を少なくし、暗黙のホスト所有権を受け入れる場合は、各クライアントを
--broker --web-ui --web-ui-config <shared-path>で設定します。
- ランタイムの期待値: 専用ホストはライフサイクルを制御する最も明確な方法です。統一された自動起動では、最初にブローカーを起動する必要があるクライアントがブローカーホストとダッシュボードを起動し、後続のクライアントはそれを再利用します。
- 所有権ルール: 特定のWeb UIの
host:port(例: 127.0.0.1:8080)には、1つのプロセスのみがバインドできます。
- 接続動作: ブローカーがすでに実行中の場合、
--brokerはそれを再利用し、既存のホストにダッシュボード設定を適用しません。
- フォールバック動作: ダッシュボードのバインドが失敗した場合(ポートがすでに使用中)、ブローカーのMCPトランスポートは続行され、ダッシュボードの起動のみがスキップされます。
- 検証フロー:
mcpbridge-wrapper --broker-status、~/.mcpbridge_wrapper/以下のファイル、および共有ダッシュボード/TUIの状態を使用して、両方のエディタが1つのデーモンに接続されていることを検証します。
ブローカーモードガイド、Web UIセットアップガイド、およびトラブルシューティングを参照してください。
Python環境のセットアップ(開発用)
make install、pytest、またはその他の開発コマンドを実行する予定の場合は、最初に仮想環境を作成してアクティブ化してください。これにより、Homebrew Pythonのexternally-managed-environment (PEP 668)エラーを回避できます。
cd XcodeMCPWrapper
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
make install
クイックチェック:
which python3
which pip
環境がアクティブな間、両方が.venv/bin/...を指す必要があります。
インストール
オプション1: uvxを使用する(推奨 - 最も簡単)
インストールする最も速い方法は、uvxを使用することです(uvのインストールが必要):
uvx --from mcpbridge-wrapper mcpbridge-wrapper
または、直接MCPクライアントの設定に追加します(以下の設定セクションを参照)。
オプション2: MCPレジストリを経由する
MCPクライアントがMCPレジストリをサポートしている場合:
サーバー名: io.github.SoundBlaster/xcode-mcpbridge-wrapper
mcp-publisher install io.github.SoundBlaster/xcode-mcpbridge-wrapper
オプション3: pipを使用する
python3 -m pip install mcpbridge-wrapper
その後、mcpbridge-wrapperまたはxcodemcpwrapperコマンドを使用します。
オプション4: 手動インストール(インストールスクリプトを経由)
git clone https://github.com/SoundBlaster/XcodeMCPWrapper.git
cd XcodeMCPWrapper
./scripts/install.sh
インストールスクリプトは仮想環境を作成し、パッケージをインストールし、~/bin/xcodemcpwrapperにラッパーを配置します。
--web-ui MCP引数を使用する予定の場合は、明示的にWeb UI拡張機能をインストールします:
./scripts/install.sh --webui
~/.bashrcまたは~/.zshrcに以下を追加します:
export PATH="$HOME/bin:$PATH"
その後、再読み込みします:
source ~/.zshrc
. ~/.zshrc
オプション5: ローカル開発(venv)
開発用、またはクローンしたリポジトリから直接実行する場合は:
git clone https://github.com/SoundBlaster/XcodeMCPWrapper.git
cd XcodeMCPWrapper
python3 -m venv .venv
source .venv/bin/activate
make install
エントリーポイントは.venv/bin/mcpbridge-wrapperです。MCPクライアントを設定する際には、完全な絶対パスを使用してください(以下の設定セクションを参照)。
アンインストール
システムからxcodemcpwrapperを削除するには:
./scripts/uninstall.sh
オプション:
--dry-runまたは-n: 削除される内容を表示し、実際には削除しません
--yesまたは-y: 確認プロンプトをスキップします
設定
Cursor
ブローカー設定の例を最初に示します。
uvxをブローカーモードで使用する(推奨):
{
"mcpServers": {
"xcode-tools": {
"command": "uvx",
"args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper", "--broker"]
}
}
}
uvxをブローカーモードでWeb UI付きで使用する(オプション):
{
"mcpServers": {
"xcode-tools": {
"command": "uvx",
"args": [
"--from",
"mcpbridge-wrapper[webui]",
"mcpbridge-wrapper",
"--broker",
"--web-ui",
"--web-ui-config",
"/Users/YOUR_USERNAME/.mcpbridge_wrapper/webui.json"
]
}
}
}
uvxをダイレクトモードで使用する:
{
"mcpServers": {
"xcode-tools": {
"command": "uvx",
"args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"]
}
}
}
uvxをダイレクトモードでWeb UI付きで使用する(オプション):
{
"mcpServers": {
"xcode-tools": {
"command": "uvx",
"args": [
"--from",
"mcpbridge-wrapper[webui]",
"mcpbridge-wrapper",
"--web-ui",
"--web-ui-port",
"8080"
]
}
}
}
手動インストールを使用する(ダイレクトモード):
{
"mcpServers": {
"xcode-tools": {
"command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
"args": []
}
}
}
手動インストールをWeb UI付きで使用する(ダイレクトモード、オプション):
./scripts/install.sh --webui(または同等の.[webui]依存関係)でインストールする必要があります。
{
"mcpServers": {
"xcode-tools": {
"command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
"args": ["--web-ui", "--web-ui-port", "8080"]
}
}
}
ローカル開発を使用する(venv、ダイレクトモード):
{
"mcpServers": {
"xcode-tools": {
"command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper"
}
}
}
ローカル開発をWeb UI付きで使用する(ダイレクトモード、オプション):
{
"mcpServers": {
"xcode-tools": {
"command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper",
"args": ["--web-ui", "--web-ui-port", "8080"]
}
}
}
Claude Code
ブローカー設定の例を最初に示します。
uvxをブローカーモードで使用する(推奨):
claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker
uvxをブローカーモードでWeb UI付きで使用する(オプション):
claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --broker --web-ui --web-ui-config "$HOME/.mcpbridge_wrapper/webui.json"
uvxをダイレクトモードで使用する:
claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper
uvxをダイレクトモードでWeb UI付きで使用する(オプション):
claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080
手動インストールを使用する(ダイレクトモード):
claude mcp add --transport stdio xcode -- ~/bin/xcodemcpwrapper
手動インストールをWeb UI付きで使用する(ダイレクトモード、オプション):
./scripts/install.sh --webui(または同等の.[webui]依存関係)でインストールする必要があります。
claude mcp add --transport stdio xcode -- ~/bin/xcodemcpwrapper --web-ui --web-ui-port 8080
ローカル開発を使用する(venv、ダイレクトモード):
claude mcp add --transport stdio xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper
ローカル開発をWeb UI付きで使用する(ダイレクトモード、オプション):
claude mcp add --transport stdio xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper --web-ui --web-ui-port 8080
Codex CLI
ブローカー設定の例を最初に示します。
uvxをブローカーモードで使用する(推奨):
codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker
uvxをブローカーモードでWeb UI付きで使用する(オプション):
codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --broker --web-ui --web-ui-config "$HOME/.mcpbridge_wrapper/webui.json"
uvxをダイレクトモードで使用する:
codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper
uvxをダイレクトモードでWeb UI付きで使用する(オプション):
codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper --web-ui --web-ui-port 8080
手動インストールを使用する(ダイレクトモード):
codex mcp add xcode -- ~/bin/xcodemcpwrapper
手動インストールをWeb UI付きで使用する(ダイレクトモード、オプション):
./scripts/install.sh --webui(または同等の.[webui]依存関係)でインストールする必要があります。
codex mcp add xcode -- ~/bin/xcodemcpwrapper --web-ui --web-ui-port 8080
ローカル開発を使用する(venv、ダイレクトモード):
codex mcp add xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper
ローカル開発をWeb UI付きで使用する(ダイレクトモード、オプション):
codex mcp add xcode -- /path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper --web-ui --web-ui-port 8080
Zed Agent
uvxを使用する(推奨):
~/.zed/settings.jsonを編集します。
{
"xcode-tools": {
"command": "uvx",
"args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"],
"env": {}
}
}
uvxをWeb UI付きで使用する(オプション):
{
"xcode-tools": {
"command": "uvx",
"args": [
"--from",
"mcpbridge-wrapper[webui]",
"mcpbridge-wrapper",
"--web-ui",
"--web-ui-port",
"8080"
],
"env": {}
}
}
手動インストールを使用する:
{
"xcode-tools": {
"command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
"args": [],
"env": {}
}
}
手動インストールをWeb UI付きで使用する(オプション):
./scripts/install.sh --webui(または同等の.[webui]依存関係)でインストールする必要があります。
{
"xcode-tools": {
"command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
"args": ["--web-ui", "--web-ui-port", "8080"],
"env": {}
}
}
ローカル開発を使用する(venv、ダイレクトモード):
{
"xcode-tools": {
"command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper",
"args": [],
"env": {}
}
}
ローカル開発をWeb UI付きで使用する(ダイレクトモード、オプション):
{
"xcode-tools": {
"command": "/path/to/XcodeMCPWrapper/.venv/bin/mcpbridge-wrapper",
"args": ["--web-ui", "--web-ui-port", "8080"],
"env": {}
}
}
Kimi CLI
uvxを使用する(推奨):
~/.kimi/mcp.jsonを編集します。
{
"xcode-tools": {
"command": "uvx",
"args": ["--from", "mcpbridge-wrapper", "mcpbridge-wrapper"],
"env": {}
}
}
手動インストールを使用する:
{
"xcode-tools": {
"command": "/Users/YOUR_USERNAME/bin/xcodemcpwrapper",
"args": [],
"env": {}
}
}
💻 使用例
設定が完了したら、AIアシスタントにXcodeツールを使用するように依頼します。
"Build my project"
"Run the tests"
"Find all Swift files in the project"
"Show me the build errors"
📚 ドキュメント
Web UIダッシュボード(オプション)
このラッパーには、リアルタイム監視と監査ログ用のオプションのWeb UIダッシュボードが含まれています。
make webui
python -m mcpbridge_wrapper --web-ui --web-ui-port 8080
機能:
- リアルタイムメトリクス: RPS、レイテンシパーセンタイル (p50、p95、p99)、エラー率
- ツール使用分析: 最も頻繁に使用されるツールの視覚的なグラフ
- 監査ログ: すべてのMCPツール呼び出しの永続的なログ(JSON/CSVでエクスポート可)
- リクエストインスペクター: フィルタリング付きのライブログストリーム
ブラウザでhttp://localhost:8080を開いてダッシュボードを表示します。
マルチエージェント設定での重要事項:
- ダッシュボードは、1つのラッパープロセスによってホストされ、Xcodeまたは
mcpbridgeによってホストされません。
- 単一の
host:portには1つのリスナーしか存在できません。同じポートで複数のプロセスが起動すると、ダッシュボードの起動がスキップされ、MCPトラフィックは続行されます。
- 明示的なフェーズ6オペレーターワークフローでは、
--broker-daemon --web-uiで1つの専用ブローカーホストを実行し、ブラウザのダッシュボードおよび/またはmcpbridge-wrapper --tuiから同じホストを監視します。
詳細な設定については、Web UIセットアップガイドを参照してください。
既知の問題
- ブローカーのコールドスタート - Xcodeの承認タイミングの競合(緑色のドット付きで0ツール): ブローカーデーモンが新しい
xcrun mcpbridgeプロセスを起動するとき(初回起動またはデーモンの再起動後)、Xcodeはプロセスごとに「Allow Connection?」ダイアログを表示します。MCPクライアントがXcodeの承認を受ける前にtools/listを送信した場合、空のリストを受け取り、それを永久にキャッシュします。これにより、緑色の接続インジケーターが表示され、エラーメッセージがない状態で0ツールが表示されます。各一意のバイナリパス(直接のラッパーとブローカーデーモン)は別々のダイアログをトリガーします。承認後、パーミッションは持続し、以降のセッションで再承認は必要ありません。回避策: ブローカーモードを有効にした直後にXcodeのダイアログを監視します。「Allow」をクリックした後、クライアントでMCP接続を再読み込みします(設定で無効にしてから再有効にします)。クライアント固有の回復手順と診断コマンドについては、トラブルシューティング: 最初のブローカー接続後に0ツールが表示されるを参照してください。
- BUG-T5 → FU-P13-T7 (P0): 空の内容のツール結果は、厳格なMCPクライアントでは依然として厳格な
structuredContentの期待値に違反する可能性があります。
- BUG-T6 → FU-P13-T8 (P0): 複数のMCPセッションが同じ
--web-ui-port(例えば8080)で起動すると、Web UIポートの衝突が発生し、address already in useが発生する可能性があります。
- BUG-T7 → FU-P13-T9 (P0):
resources/listおよびresources/templates/listのプロービングは、一部のクライアントパスでは非標準のエラー形状を返す可能性があります。
免責事項(Codexアプリ)
mcpbridge-wrapperはXcode MCP応答を正規化しますが、Codexアプリの内部を制御することはできません。Codexアプリのトランスポート/セッションの動作は、Codex CLIおよびこのラッパーとは独立して変更される可能性があります。アプリとCLIが異なる場合は、まずクライアント固有の動作として扱い、正確なバージョン、設定、およびログで検証してください。
その他のドキュメント
- インストールガイド
- ブローカーモードガイド - 設定、移行、ロールバック、および操作
- Cursorのセットアップ
- Claude Codeのセットアップ
- Codex CLIのセットアップ
- トラブルシューティング
- ツールリファレンス
- アーキテクチャ
- コントリビュートガイド - 開発セットアップと品質ゲート
🔧 技術詳細
開発
開発セットアップとコントリビューションガイドについては、CONTRIBUTING.mdを参照してください。
クイック品質ゲートチェック:
make test
make lint
make typecheck
または、すべてのゲートを実行:
make test && make lint && make typecheck
パフォーマンス
- オーバーヘッド: 変換ごとに<0.01ms
- メモリ: <10MBのフットプリント
- カバレッジ: 91.62%のテストカバレッジ
📄 ライセンス
MITライセンス - 詳細については、LICENSEを参照してください。
謝辞
- MCPブリッジ機能を提供しているAppleのXcodeチーム
- MCPプロトコル仕様
- AIによる開発ツールを提供しているCursor、Claude、およびCodexのチーム