Xojo IDE Control

xojo-mcp

AI アシスタントから Xojo IDE を直接操作できるようにする MCP（Model Context Protocol）サーバーです。stdin/stdout JSON-RPC で通信し、実行中の Xojo IDE プロセスに Unix ドメインソケット経由で IDE コマンドを転送します。

名前について。 このクレートは以前、xmcp として公開されていました。X（旧 Twitter）の無関係な xmcp フレームワークとの混同を避けるため、xojo-mcp に改名されました。インストールされる バイナリ名は引き続き xmcp なので、既存の設定はそのまま機能します。

macOS のみ対応。 xojo-mcp は Unix ドメインソケット（/tmp/XojoIDE、または /tmp/$XOJO_IPCPATH — 接続先の IDE の選択を参照）経由で Xojo IDE と通信します。Windows はサポートされておらず、対応を追加する予定もありません。その理由は、Windows に IDE の IPC メカニズムがないからではありません。Xojo の IPCSocket はフレームワークの抽象化であり、Windows ではパス文字列からポートを導出する localhost TCP ソケットです。Xojo アプリケーション自体である元の XMCP は、フレームワークからこのトランスポートをそのまま利用できますが、この移植版はワイヤープロトコルを直接扱うため、Windows に対応するには文書化されていないパスからポートへの導出方法をリバースエンジニアリングする必要があります。Linux は非対応と決まっているのではなく、未テストです。macOS と同様に Unix ソケットを使用しますが、デバッグツールとシステムログツールは macOS 専用の情報源を読み取ります。

クレジット

これは、もともと Xojo で書かれた Øjvind Søgaard Andersen による XMCP の Rust 移植版です。元のプロジェクトは MIT License の下でライセンスされています。

クイックスタート

1. インストール

オプション A：ビルド済みバイナリ（Apple Silicon）

各リリースには aarch64-apple-darwin の tarball が含まれています。これは Developer ID 証明書で署名され、Apple による公証を受けており、分離された minisign 署名が付属しています。Releases から最新のものをダウンロードして検証し、バイナリを PATH に配置してください。

minisign -Vm xmcp-*-aarch64-apple-darwin.tar.gz \
    -P RWR7Jy43Mphvu+jrP2FynfYpR7WdP0PvQaSFKfXub7q9Sh7fjtyAX9GU
tar xzf xmcp-*-aarch64-apple-darwin.tar.gz
install -m 755 xmcp-*/xmcp ~/.cargo/bin/xmcp

.minisig は検証する価値があり、隣にある .sha256 ではできない検証を行えます。チェックサムファイルを検証対象のファイルと一緒にホストしても、ダウンロードが破損していないことしか証明できません。一方のアセットを差し替えられる人は、もう一方も差し替えられるからです。署名はリリースサーバーに一度も触れない鍵で作成されており、上記のコマンドで使う鍵は、このリポジトリに minisign.pub として保存されています。

minisign は MacPorts で利用できます（port install minisign）。検証に成功すると、信頼できるコメントが表示され、そこにはバージョンと署名日が記載されます。必要な方のために、.sha256 も引き続き公開しています。

shasum -a 256 -c xmcp-*-aarch64-apple-darwin.tar.gz.sha256

バイナリは Developer ID 証明書で署名され、Apple による公証も受けているため、Gatekeeper によってそのまま実行できます。必要であれば、次のコマンドで確認できます。

codesign -dvv ~/.cargo/bin/xmcp   # Authority: Developer ID Application …
codesign -vvv -R="notarized" --check-notarization ~/.cargo/bin/xmcp

（spctl はすぐ使いたくなるコマンドですが、この用途には適していません。公証の有無にかかわらず、通常のコマンドラインバイナリに対しては does not seem to be an app と返します。）

公証チケットは実行ファイル単体にはステープルできません。stapler が扱えるのは .app、.dmg、.pkg のみです。そのため、初回の実行時には、チケットを確認するために Apple への接続が必要です。初回実行をオフラインで行う必要がある場合は、代わりに隔離フラグを手動で解除してください。

xattr -d com.apple.quarantine ~/.cargo/bin/xmcp

Intel Mac は対象外です。代わりにソースからビルドしてください。

オプション B：crates.io からインストール

cargo install xojo-mcp

クレート名は xojo-mcp、インストールされるバイナリ名は xmcp です。

オプション C：ソースからインストール

git clone https://codeberg.org/brechanbech/xojo-mcp.git
cd xojo-mcp
cargo install --path .

xmcp バイナリが ~/.cargo/bin/xmcp にインストールされます。~/.cargo/bin がすでに PATH に含まれていれば（Rust インストーラーによってデフォルトで追加されます）、これで完了です。次のコマンドで確認してください。

xmcp --help

任意： usage-guide.md はコンパイル時にバイナリに埋め込まれるため、MCP リソースは最初から常に利用できます。再ビルドせずにガイドを変更したい場合は、バイナリの隣にコピーを配置してください。xmcp は埋め込みの代替版よりもディスク上のファイルを優先します。

cp usage-guide.md ~/.cargo/bin/

2. Claude Code に追加する

任意のターミナルで次を実行します。

claude mcp add xmcp -- xmcp

または、Claude Code の設定に手動で追加します。MCP 設定ファイル（macOS の場合は ~/.claude/settings.json またはプロジェクトレベルの .claude/settings.json）を開き、次を追加します。

{
  "mcpServers": {
    "xmcp": {
      "command": "xmcp",
      "args": []
    }
  }
}

詳細なログ記録を有効にする場合（stderr に書き込まれ、Claude Code の MCP ログに表示されます）：

{
  "mcpServers": {
    "xmcp": {
      "command": "xmcp",
      "args": ["-v"]
    }
  }
}

3. 使用する

1. Xojo IDE を起動し、プロジェクトを開きます
2. プロジェクトディレクトリで Claude Code のセッションを開始します
3. Claude が 29 個の xmcp ツールと使用ガイドを自動的に検出します

4. Xojo のドキュメントをダウンロードする（推奨）

ドキュメント用ツール（search_docs、lookup_class、list_doc_topics）を使用するには、Xojo ドキュメントのローカルコピーが必要です。docs.xojo.com からダウンロードするスクリプトが用意されています。

scripts/update-xojo-docs.sh

このスクリプトは docs.xojo.com から llms.txt と llms-full.txt をダウンロードし、ドキュメント全体を _sources/ の個別のクラスファイルに分割します。すべてのファイルは ~/Library/Application Support/Xojo/Xojo/<version>/Documentation/ に保存され、xmcp が起動時に自動検出します。ドキュメントの更新を取り込むため、定期的にスクリプトを再実行してください。Xojo は新しいリリースの公開時にこれらのファイルを更新します。

lookup_class は、デフォルトで整形済みの要約を返します。クラスの説明とメンバーの表が含まれ、Sphinx の相互参照マークアップはプレーンテキストに変換されます。元のページが数万文字に及ぶのに対し、返されるのは数千文字です。String だけでも 70,000 文字を超えます。特定のメンバーを取得するには member を、未加工のページを取得するには full: true を指定します。

lookup_class(class_name: "String")                     # description + member tables
lookup_class(class_name: "String", member: "Middle")   # that member's entry alone
lookup_class(class_name: "String", full: true)         # the raw .rst.txt page

代わりにカスタムの場所を使用するには：

scripts/update-xojo-docs.sh /path/to/docs
xmcp --docs-path /path/to/docs

読み取り専用モード

デフォルトでは、xmcp に接続されたアシスタントはプロジェクトを変更できます。コードを書き換えたり、新しい項目を作成したり、保存したり、元に戻したりできます。それこそがこのツールの目的ですが、常にそれを望むとは限りません。アシスタントにプロジェクトを変更または上書きさせずに、コードを読んだり、ビルドしたり、実行したり、分析したり、質問に回答させたり、ドキュメントを参照させたりするだけの場合は、サーバーを読み取り専用モードで起動してください。

読み取り専用モードは、アシスタントに従わせるのではなく、サーバー自体によって強制されます。これは xmcp で最も重要な安全制御です。その仕組みを正確に理解しておく価値があります。

有効にする

最も簡単な方法は、起動コマンドに --read-only フラグを付けることです。Claude Code の場合：

claude mcp add xmcp -- xmcp --read-only

または、Claude Code の設定ファイル（~/.claude/settings.json またはプロジェクトレベルの .claude/settings.json）で指定します。

{
  "mcpServers": {
    "xmcp": {
      "command": "xmcp",
      "args": ["--read-only"]
    }
  }
}

MCP クライアントでコマンドライン引数より環境変数を使う場合は、変数 XMCP_READ_ONLY=1 でもまったく同じ設定になります。有効とみなされる値は 1、true、yes、on です（大文字と小文字は区別されません）。

{
  "mcpServers": {
    "xmcp": {
      "command": "xmcp",
      "args": [],
      "env": { "XMCP_READ_ONLY": "1" }
    }
  }
}

フラグと環境変数の両方が設定されている場合、どちらか一方で読み取り専用モードが有効になれば十分です。もう一方から無効にすることはできません。

会話中ではなく、起動時に設定する

ここは、初めて使う人が最もよく誤解する点です。チャットで「読み取り専用に徹する」よう伝えても、アシスタントは読み取り専用モードにはなりません。 プロンプトは、モデルが忘れたり、誤解したり、説得されて従わなくなったりする可能性のある依頼にすぎません。モデルが書き込みツールを呼び出した場合は、何の効果もありません。こうした弱点を取り除くために存在するのが、読み取り専用モードです。

読み取り専用モードは、サーバーの起動方法に関する設定です。セッションを開始する前に、MCP クライアントの設定で一度指定します。その後はサーバープロセスが動作している間ずっと、会話に何を入力しても制限が適用されます。あなたもアシスタントも、セッション中にモードを切り替えることはできません。モードを変更するには設定を変更し、サーバーに再接続してください。（変更を反映するにはサーバーの再起動が必要です。すでに実行中のサーバーは、新しいフラグや環境変数を読み込みません。）

実際にブロックされるもの

読み取り専用モードでは、プロジェクトを変更する以下の 10 個のツールが無効になります。

ツール	通常の動作
set_code	メソッド、プロパティ、その他の項目のコードを上書きします
edit_code	項目のコード内の完全一致する部分文字列を置き換えます
set_selected_text	コードエディターで現在選択されているテキストを置き換えます
set_declaration	メソッドまたはプロパティの名前や型を変更します
create_project_item	新しいクラス、モジュール、ウィンドウ、その他の項目を追加します
property_value	App.OptimizationLevel などのフレームワークプロパティを変更します
constant_value	プロジェクト定数の値を変更します
get_item_description	項目の説明を変更します
revert_project	未保存の変更を破棄し、最後に保存した状態に戻します
save_project	プロジェクトの現在のメモリ上の状態をディスクに書き込みます

property_value、constant_value、get_item_description は値の読み取りも行いますが、それぞれ単一のツールであるため、読み取り専用モードでは書き込みとともに読み取りもブロックされます。

ツールのアノテーション

すべてのツールには tools/list 内に MCP の動作に関するヒント（title、readOnlyHint、destructiveHint、idempotentHint、openWorldHint）も付与されており、クライアントは呼び出し前に何を確認するか判断できます。これらは強制力のないヒントであり、プロジェクトではなくマシン全体に対するツールの影響を示すため、読み取り専用モードよりも厳しい内容になっています。build_project、run_project、agentic_run はソースに変更を加えず、読み取り専用モードでも引き続き利用できますが、ビルド出力を書き込んだりアプリを起動したりするため、読み取り専用とは示されません。run_ide_script の DoShellCommand はあらゆるものにアクセスできるため、openWorldHint はこれ以外のすべてで false です。

それ以外はすべて引き続き利用できます。項目の移動や一覧表示、コードの読み取り（get_code）、ビルド（build_project）、実行（run_project）、停止、コンパイルチェック（analyze_project）、説明や定数の確認、デバッグログツール、3 つすべてのドキュメントツールを利用できます。つまり、参照、ビルド、実行、分析はできますが、書き込みはできません。

ビルドと実行は意図的にブロックされていない点に注意してください。ソースは変更せず、動作を確認するだけです。build_project はビルドフォルダーにコンパイル済みアプリを書き込み、run_project はデバッグセッションを開始しますが、どちらもプロジェクト自体には触れないため、読み取り専用でも安全と見なされます。

強制の仕組み

制限は独立した 2 つのレイヤーで適用されるため、クライアントやモデルが誤動作しても維持されます。

1. ブロック対象のツールはツール一覧から除外されます。 アシスタントがサーバーに利用可能なツールを問い合わせると（tools/list）、変更を行う 6 つのツールが除外されます。モデルには表示されないため、存在を知らないツールを呼び出そうとすることはできません。これにより、単に防御するだけでなく、実際にモードが機能します。
2. ブロック対象のツールへの呼び出しは拒否されます。 それでも、古いツール一覧、手動で作成した呼び出し、バグのあるクライアントなどにより、ブロック対象の 6 つのツールのいずれかへのリクエストが届いた場合、サーバーはリクエストが IDE に届く前に拒否し、そのツールが読み取り専用モードで無効になっていることを説明する明確なエラーを返します。

埋め込みの使用ガイドを通じて、ツールセットが縮小されている場合はプロジェクトが意図的に読み取り専用になっていること、制限を回避しようとせず利用可能なツールの範囲内で作業することも、アシスタントに伝えられます。

両方のモードを同時に実行する

モードはサーバーごとに固定されるため、xmcp を別々の名前で 2 回登録し、タスクごとにアシスタントが接続するサーバーを選べます。たとえば、編集セッション用の通常の xmcp と、レビュー専用セッション用の xmcp-ro を分けて登録できます。

claude mcp add xmcp    -- xmcp
claude mcp add xmcp-ro -- xmcp --read-only

接続する IDE の選択

IDE は、一時ディレクトリと XojoIDE という名前を組み合わせたパスのソケットで待ち受けます。IDE の環境で XOJO_IPCPATH が設定されている場合は、その値が使われます。インスタンスごとに固有の名前を設定する方法は、複数の IDE（たとえば、2 つのリリースを並行して）を実行し、それぞれに個別に接続するための、Xojo がサポートする方法です。

env XOJO_IPCPATH=Xojo2026r2_1 "/Applications/Xojo 2026 Release 2.1/Xojo.app/Contents/MacOS/Xojo" &

同じ値を xmcp に指定する必要があります。指定しない場合、デフォルトの XojoIDE ソケットを所有するインスタンスに接続されます。

{
  "mcpServers": {
    "xmcp-2026r2-1": {
      "command": "xmcp",
      "args": [],
      "env": { "XOJO_IPCPATH": "Xojo2026r2_1" }
    }
  }
}

名前に使用できるのは a-z、A-Z、0-9、_ のみです。それ以外の文字を含む値は xmcp に無視され（stderr に警告が出力され）、XojoIDE にフォールバックします。候補となるディレクトリは、IDE 自身が優先する /tmp が最初で、次に /tmp に書き込めない場合に IDE がフォールバックする $TMPDIR です。

一度に実行する IDE が常に 1 つだけであれば、これはすべて無視してください。デフォルトのままで動作します。

要件

• macOS（Xojo IDE の IPC ソケットは macOS 固有です）
• Rust ツールチェーン（rustup — https://rustup.rs）
• ツールを使用する前に、Xojo IDE を起動し、プロジェクトを開いておく必要があります

オプション

xmcp [OPTIONS]

• --read-only — 読み取り専用モード：プロジェクトを変更するすべてのツールを非表示にし、拒否します。XMCP_READ_ONLY=1 でも有効にできます。詳しくは読み取り専用モードを参照してください。
• -v、--verbose — stderr への詳細ログ出力を有効にします
• -d、--docs-path <PATH> — Xojo ドキュメントディレクトリへのパス（省略時は自動検出）
• -V、--version — バージョンを表示します
• -h、--help — ヘルプを表示します

環境変数：XMCP_READ_ONLY（上記参照）と、接続する IDE インスタンスを選択する XOJO_IPCPATH。詳しくは接続する IDE の選択を参照してください。

オリジナルとの違い

これはドロップイン置換です。オリジナルにある 25 個すべてのツールを、同じ名前とパラメーターで提供します（最後に analyze_project と debug_control を移植し、完全な互換性を実現しました）。さらに、新しいツール edit_code を 1 つ追加しており、合計 26 個です。同じ Unix ドメインソケット上で IDE Communicator Protocol v2 を使用し、MCP プロトコルバージョン 2025-11-25 に更新しています。

主な違い：

• バイナリ名は xmcp です
• edit_code — 対象を絞った str_replace 方式の編集 — set_code でアイテム全体を再送信する代わりに、1 回の呼び出しでアイテムのコード内にある完全一致する部分文字列を置換します（読み取り → 置換 → 書き込みをすべてサーバー側で実行）。オリジナルにはこのようなツールがないため、小さな編集でもアイテム全体を書き換えるか、シェルベースでテキストを加工する必要があります。
• シェルや base64 による受け渡しなしでコードを直接書き込み — set_code と edit_code はソースを IPC 経由で直接送信します。IDE スクリプト用の文字列エスケープ（引用符、改行、特殊文字）はすべてサーバー側で処理されます。ブリッジ経由でコードを手動で送る必要はありません。オリジナルでファイル編集時に必要となる、エージェント側で base64 にエンコードし、Mac 側でデコードしてシェル経由で実行するワークフローは、ここにはありません。
• 強制適用される読み取り専用モード — --read-only / XMCP_READ_ONLY を指定すると、サーバー側で変更を行うツールが削除され、拒否されます。オリジナルには組み込みの強制機能がなく、プロンプトで書き込まないよう依頼することしかできません。読み取り専用モードを参照してください。
• Xojo ライセンス不要 — 標準の Rust ツールチェーンでビルドできます
• usage-guide.md にコンパイル時のフォールバックを用意 — オリジナルはバイナリの隣にファイルがないと何も通知せずに失敗しますが、Rust 版はコンパイル時にコピーを埋め込むため、MCP リソースを常に利用できます。ディスク上のファイルが引き続き優先されるため、再ビルドせずに編集できます。
• CLI の解析には、オリジナルの独自の OptionParser ではなく、clap を使用します。フラグは同じです。

ツール

xmcp は、5 つのカテゴリにわたって 29 個のツールを公開します。

IDE ツール（22）： list_project_items, get_current_location, select_project_item, get_code, set_code, edit_code, get_selected_text, set_selected_text, build_project, run_project, stop_project, create_project_item, run_ide_script, get_project_info, revert_project, save_project, get_item_description, constant_value, property_value, set_declaration, analyze_project, debug_control

ドキュメントツール（3）： search_docs, lookup_class, list_doc_topics

デバッグツール（2）： get_debug_log, get_system_log

エージェントモード（1）： agentic_run — Xojo 2026r3 の Agentic Mode が有効なプロジェクトを実行し、 場所を含むコンパイルエラーを返します。IDE ソケットではなく、プロジェクトフォルダー内のファイルを処理するため、 ソケットが利用できない場合でも project_dir を指定してプロジェクトを指定できます。

コスト把握（1）： estimate_request_cost

ライセンス

MIT — 詳細は LICENSE.md を参照してください。

MCP レジストリ

MCP レジストリの所有権検証トークン （crates.io にレンダリングされたこのクレートの README から読み取られます）：

レジストリ所有権トークン：mcp-name: io.github.brechanbech/xojo-mcp

リリース

公開後のバージョンは変更できません。crates.io では削除ではなく yanks が行われ、バージョン番号は再利用されません。そのため、順序が重要です。

1. cargo test と cargo clippy --all-targets がクリーンに完了することを確認します。

2. Cargo.toml の version を更新します。

3. server.json の version を更新します。トップレベルと packages[] の下にある両方のフィールドが対象です。これを強制するものはありません。スクリプトも CI もなく、ファイルを読み取るテストもありません。このため、3.4.1 と 3.5.0 のリリースを経ても 3.4.0 のままになり、レジストリには実際にインストールできるバージョンより 2 つ古いバージョンが表示されていました。

4. コミットしてプッシュし、公開後ではなく公開前に CI が成功するのを待ちます。

5. cargo publish --dry-run を実行します。これは パッケージ化されたコピーから コンパイルするため、配布されないファイルに依存するクレートを検出できます。その後、cargo publish を実行します。

6. MCP レジストリには、crates.io への公開後に公開します。先に公開してはいけません。レジストリは、crates.io にレンダリングされたこのクレートの README から mcp-name を読み取って名前空間を検証し、server.json には、すでに crates.io に存在する必要がある cargo のバージョンが記載されているためです。

   mcp-publisher validate      # checks server.json against the live registry
   mcp-publisher login github  # interactive, for the io.github.brechanbech/* namespace
   mcp-publisher publish