Rimcp Hybrid

🚀 RiMCP_hybrid

• このプロジェクトは、RimWorldのソースコードとXML定義に対する検索とナビゲーションツールを提供します。主な目的は、字句検索、意味検索、グラフ構造ナビゲーションを組み合わせて、AIアシスタントが呼び出せるサービスを構築することです。このプロジェクトは、コマンドラインツールとして使用することも、MCPサーバーとしてClaude DesktopやVS Code Copilotなどのアシスタントに統合することもできます。現在のソースコードには、インデックス構築、混合検索戦略、階層間グラフ関係、および完全なソースコードの位置特定と返却の機能が含まれています。

✨ 主な機能

🔧 索引構築パイプライン

• インデックス作成は、C#ソースコードファイルとXML定義ファイル（Defs）という2種類の元データから始まります。インデックスの目的は、リポジトリ全体をそのまま保存するのではなく、検索可能で理解可能な最小単位を抽出することです。これらの単位は、十分なコンテキストを保持しながら、正確なマッチングと意味ベクトルの生成に適したサイズである必要があります。最初のステップは、ファイルシステムをスキャンし、各ファイルを読み取り、分類し、ファイルパス、エンコーディング、タイムスタンプなどの基本メタデータを記録することです。要素には、クラス、関数、変数定義、およびXML定義が含まれます。
• ファイルを読み取った後、長いテキストをいくつかのブロックに分割する必要があります。C#コードの場合、通常は構文記号に基づいて分割されます。分割は、クラス、メソッド、プロパティ、またはコメントブロックに基づいて行われ、各フラグメントのソースファイル内の開始と終了オフセットが記録されます。XML定義の場合、通常は定義ノード全体の文字列表現が1つのブロックとして保持されます。分割時には、各ブロックのタイトル（たとえば、シンボル名または定義名）、要約フラグメント、および検索用の本文テキストが生成されます。分割戦略は、リコール品質に影響を与えます。ブロックが大きすぎるとコンテキストが損なわれ、小さすぎると関連情報が失われる可能性があります。
• テキストブロックが生成された後、インデックス作成プロセスは、各ブロックを2つの異なるストレージ層に並行して送信します。1つは、従来の字句検索用の転置インデックス（ここではLuceneを使用）で、もう1つは意味検索用のベクトルインデックスです。転置インデックスに書き込む際には、ブロックのタイトル、タイプ（C#またはXML）、パス、ソースオフセット、ラベルなどの構造化フィールドが一緒に保存されます。これらのフィールドは、フィルタリングをサポートするとともに、結果をソースファイルに戻すことができます。ベクトル部分では、まずテキストブロックをベクトル表現に変換する必要があります。これは通常、外部の埋め込みサービスによって行われます。このプロジェクトでは、埋め込み生成にバッチパラメーターの構成がサポートされており、異なるビデオメモリまたはCPU条件下でバッチサイズを調整できます。ベクトルが生成された後、これらのベクトルはベクトルインデックスに書き込まれ、対応するブロックIDとマッピングされます。C#のHugging Faceサポートが不十分なため、専用のPythonサーバーをバックグラウンドで127.0.0.1:5000で実行して埋め込みサービスを提供しています。これにより、各クエリ時のコールドスタート時間を節約できます。ベクトル演算には、.NETのSIMD加速機能を使用しており、System.Numerics.Tensorsライブラリによりベクトルの内積演算が高速化され、最新のCPUではハードウェアの並列計算能力を最大限に活用できます。
• インデックスのもう1つの重要な部分は、グラフ関係の構築です。静的解析器は、ソースコードとXMLを解析する際に、意味のある参照関係（たとえば、継承、メソッド呼び出し、フィールド参照、XMLからC#へのバインディングなど）を探します。関係が見つかるたびに、それをグラフの有向辺としてグラフストレージに書き込みます。グラフのノードと辺の属性はTSVに保存され、追加で2つの（行と列）圧縮疎行列表現を使用して保存されます。これにより、O(1)時間で書き込み、下向き関係の読み取り、上向き関係の読み取りが可能になります。また、完全な辺情報テキストではなくバイナリビットを使用して保存することで、元のBツリーデータベースの6.2GBのサイズを400MBに圧縮しました。これらの辺は、テキストの類似度の不足を補い、階層間クエリ（たとえば、「このC#コンポーネントを使用しているDefはどれか」）を効率的に回答することができます。

📈 検索リコール部分

• 検索リコールには、4つのツールがあります。粗検索（rough_search）、2方向の依存関係ツリー検索（uses、used_by）、およびコードブロックのリコール（get_item）です。主な考え方は、大規模モデルのコンテキスト内のノイズを減らすために、無駄なソースコードブロックの直接的な返却を最小限に抑えることです。大規模モデルエージェントの典型的な検索パスは、まず問題に対して粗検索を行い、候補要素のリストを取得し、次に大規模モデルが最も興味深い要素名を選択して、コードブロック全体をリコールするか、get_usesまたはget_used_byを使用して依存関係を検索し、要素リストを取得し、最も興味深い要素名を選択してコードブロック全体をリコールすることです。粗検索の5つの結果で直接完全なコードを表示し、その中で有用なコードが1つだけである場合、残りの無駄な情報が大規模モデルのコンテキストを埋めることになり、モデルのパフォーマンスが低下する可能性があります。一方、1つの結果のみを返すと、粗検索で正しい結果が見つからない可能性があります。この場合、大規模モデルは何度も検索を試みるか、誤った情報を採用することになります。そのため、検索を2段階に分割し、大規模モデルの判断能力を十分に活用することで、不要な情報ノイズを減らすことができます。
• 粗検索は2段階に分かれています。まず、Luceneを使用して約8万個の要素すべてに対して曖昧検索を行い、BM25による字面類似度でソートして、最も類似する1000個の要素を選択します。次に、これらの1000個の要素に対して、ベクトル類似度に基づく意味類似度のスコアリングを行い、候補となる5つの要素を選択します。これにより、高速な検索が可能で、正しい答えを見逃す可能性も低くなります。当初は、字面類似度のスコアとベクトル意味類似度のスコアを足し合わせることを考えましたが、両者の利点を生かすことができず、ノイズが情報を圧倒する結果になりました。たとえば、「pawn hunger tick」を検索する場合、最後のステップでベクトルソートのみを使用すると、totalNutritionConsumptionPerdayが3位になりますが、字面の一致度をいくらか重み付けすると、たくさんのxxxxx.Tick()が上位に並び、何も検索できなくなります。
• グラフ検索には特別な設計はありません。3つのグラフデータベースを組み合わせることで十分な速度が得られ、各辺の属性の登録により、種類に応じた結果の事前フィルタリングが容易になり、ノイズを減らすことができます。テスト中に、大規模モデルが突然Verse.Thingの参照関係を検索し、MCPが2万6000件のデータを返してコンテキストがオーバーフローしたことがありました。その後、返却内容のソートを見直し、ソートの安定性を確保し、これを基に簡単なページング機構を実装しました。これにより、実際のリクエスト回数とトークン数を犠牲にして、ある程度の安全性を確保することができました。
• デプロイとパフォーマンスに関しては、このプロジェクトでは、埋め込み生成とベクトルインデックスのバッチサイズを調整するパラメーターを提供しており、異なるビデオメモリとハードウェア構成で速度とリソース使用量のバランスを取ることができます。実際の動作では、Luceneの検索遅延は通常小さく、意味の再ソートとベクトル検索は候補セットとベクトルモデルのサイズに応じて変化します。したがって、リソースが制限された環境では、埋め込みを無効にするか、バッチサイズを小さくすることで安定した動作を保証することができます。
• このシステムを対話または統合のために起動する最も直接的な方法は、MCPサーバーコンポーネントを実行することです。サービスプロセスは、標準入出力またはJSON-RPCプロトコルを介してインターフェースを公開し、外部のAIアシスタントは、検索とナビゲーションリクエストを送信し、構造化された応答を受け取ることができます。また、コマンドラインモードで各ツールコマンドを実行して、インデックス構築、混合検索、またはグラフクエリを行うこともできます。この方法は、オフラインテストやスクリプト化された使用に便利です。

🔜 後続の改善方向

• 粗検索段階のLucene -> embeddingのアプローチは、両者の利点を生かすように見えますが、実際のテストと実験では、Luceneによって除外される正しい選択肢が予想以上に多いことがわかりました。したがって、このプロセスで犠牲にされる精度は、数秒の検索速度の向上と引き換えにする価値がなく、むしろ、大規模言語モデル（LLM）が必要な情報を取得できないため、検索を繰り返し実行することにより、より大きなコストがかかる可能性があります。このような状況では、混合2段階検索のアーキテクチャを廃止し、全量ベクトル検索を直接採用することにしました。リコール速度に関しては、Faissが十分なアルゴリズムの高速化を提供できると信じています。もちろん、LuceneとBM25による再ソートは完全に無駄ではありません。残りの3つのツールでは、入力が正確な要素名である必要があるため、多くの場合、リコールに失敗することがありますが、この高速で効率的な検索と字面類似度のスコアリングを使用することで、より多くのロバスト性を提供し、エージェントのワークフローの流れを改善することができます。この経験は、大規模モデルの強力な理解能力の前では、人為的なエンジニアリング手法が制約になる可能性があり、それぞれの利点を統合することができず、むしろその固有の欠点が大規模モデルの性能を大きく制限することを教えてくれます。エンジニアリング設計では、従来のエンジニアリング手法は、大規模モデルをある欠陥を埋めるための橋渡しとして使用するのではなく、二次的な役割を果たし、補助的な情報を提供することで、大規模モデルの能力を最大限に引き出すことができます。

• また、get_usesとget_used_byツールを集中的にテストした結果、これらのツールはリコールが安定しており、完全ですが、多くのクラスについて、関係の抽出が細かすぎるため、Rimworldのソースコードが非常に複雑であることもあり、上下関係を抽出する際に大量のデータが返されることがあります。この問題は、ThingCompやPawnなどのいくつかの核心的な定義クラスに限定されるものではなく、多くの具体的な機能を実装しているコード要素でも発生します。これは、大規模モデルの判断に多くのノイズをもたらします。そのため、グラフの辺に優先度の重みを付ける重み付けアルゴリズムを設計することにしました。依存関係のクエリ結果を降順にソートすることで、重要なリンクを上位に表示する確率が高くなり、大規模モデルが受け取る情報のノイズを効果的に低減することができます。辺の重みは、辺の種類、ノードの重要度指数（ノードの重要度指数には、古典的なGoogle PageRankアルゴリズムを使用する予定で、計算コストはそれほど大きくないと思われます）、さらには両者の名前の字面類似度に基づく重み付け係数によって決定される可能性があります。ただし、この重み付けアルゴリズムは人為的に直感的に設計されているため、理論上の重要度を反映しているとは限らず、検索効率に悪影響を与える可能性もあります。一方、非人工的な最適解の重み付け方法を探そうとすると、問題自体を定義することすらできず、アルゴリズム的にも手がつけられません。重み付けを勝手に決めることは避けたいので、将来的には多くの実験が必要になるでしょう。😩🤌 Mama Mia.

• その他、いくつかの小さなタスクがあります。たとえば、一部の熱心な方から、ローカルモデルだけでなく、リモートの埋め込みモデルAPIサービスを呼び出せるようにしてほしいという要望がありました。また、初期化時に5000ポートの埋め込みサーバーをワンクリックで起動できるようにする提案もありました。さらに、Stdioの代わりにSSEを使用してデータを転送することで、Stdio方式のいくつかの欠点を回避し、ローカルネットワークでの転送を容易にする提案もあります。これらはすべて非常に良い提案であり、関連する変更はすでに予定されていますので、皆さんにはしばらくお待ちいただければ幸いです（やってます、やってます.jpg）。

• v1.1.0更新：リモート埋め込みAPIの機能が実装されました。現在、--api-keyと--model-nameパラメーターを使用して、OpenAIなどの外部埋め込みサービスに接続することができます。asvc_33氏の貢献に感謝します！

• v1.1.2更新：実際にはLuceneの方法を放棄していません。逆に、BM25の動作方法を少し変更した実験を行いました。現在、BM25は各要素のコード全文（以前は要素名のみ）で字面類似度をマッチングするようになりました。これは、より合理的で一般的な方法であり、実験の結果、期待通りの効果が得られ、リコールもそれほど遅くありません。このように、Faissの必要性は低下しました。

• v1.2.0更新：グラフ生成に対して、辺の重み生成式を設計しました。現在の式は次の通りです。

    $$(Pr\cdot 10^7)\sqrt{d}\cdot w$$
  

  これは非常にシンプルな式で、Prは対象ノードのPageRankの元のスコアを表し、dは同じ接続がこの要素内で出現する回数を表し、wはノードの属性に固有の重みを表します（この重みは私が独自に設定したもので、たとえば継承は2.0、関数呼び出しは0.7などで、特別な根拠はありません）。$10^7$は、浮動小数点数の誤差を防ぐために使用されています。Prの値は一般的に桁数が小さいためです。

• 1.2.1更新：継続的な実験の中で、グラフ生成には非常に大きな問題があることがわかりました。たとえば、親クラスの関係をすべて引き継いでしまい、大量の結果が返されることがあり、ノイズが多くなります。また、静的メンバーや反射呼び出しのケースを見逃してしまいます（実際には、XMLとC#の接続の大部分はこのような方式で行われていますが、これまではすべて解析漏れしていました）。これには、コードの解析方法を大幅に見直す必要があります。現在は、重複した辺の取得問題を修正し、元の約5000万本の辺を23万本に減らしました。これは、可用性を大幅に向上させる結果となりました。これで、なぜ実際の運用で大規模モデルがget-usesやget-used-byツールをほとんど使用しないのかがわかります。これらのツールは実際には使いにくいのです！

• このプロジェクトはMITライセンスの下で公開されており、私のコードが太陽系内のすべての生物に自由に使用されることを願っています。Edgeworld modderコミュニティの皆さんからの熱心なサポートに心から感謝しています。交流や議論の中で多くを学びました。皆さんのサポートに感謝します。

📦 インストール

インデックス構築コマンド

インデックスを構築または更新し、転置インデックス、ベクトル埋め込み、およびグラフ関係データを生成します。

最小インデックス構築コマンド（プロジェクトルートまたはRimWorldCodeRagディレクトリで実行）

cd src\RimWorldCodeRag
dotnet run -- index --root "..\..\RimWorldData"

埋め込み生成バッチサイズの例（ビデオメモリが制限されたマシンで調整）

cd src\RimWorldCodeRag
dotnet run -- index --root "..\..\RimWorldData" --python-batch 128 --embedding-server "http://127.0.0.1:5000"

永続的な埋め込みサーバーの使用（各バッチのコールドスタートを回避）

cd src\RimWorldCodeRag
dotnet run -- index --root "..\..\RimWorldData" --embedding-server "http://127.0.0.1:5000"

新機能：リモート埋め込みAPIの使用（例：OpenAI）

cd src\RimWorldCodeRag
dotnet run -- index --root "..\..\RimWorldData" --embedding-server "https://api.openai.com/v1/embeddings" --api-key "sk-1234567890abcdefghijklmnopqrstuvwxyz" --model-name "text-embedding-3-small"

強制再構築（増分判断を無視して、すべてのインデックスを再構築）

--forceパラメーターは、より細かい制御をサポートしており、インデックスの特定の部分を再構築することができ、時間を節約できます。

# すべてのインデックスを強制的に再構築（古い--forceと同等）。ここでは、embedding-serverにローカルの埋め込みサービスを使用することを想定しています。
cd src\RimWorldCodeRag
dotnet run -- index --root "..\..\RimWorldData" --force all --embedding-server "http://127.0.0.1:5000" --python-batch 512

# Luceneの字句インデックスのみを強制的に再構築
cd src\RimWorldCodeRag
dotnet run -- index --root "..\..\RimWorldData" --force lucene

# ベクトル埋め込みインデックスのみを強制的に再構築
cd src\RimWorldCodeRag
dotnet run -- index --root "..\..\RimWorldData" --force embed --embedding-server "http://127.0.0.1:5000" --python-batch 512

# グラフ関係インデックスのみを強制的に再構築
cd src\RimWorldCodeRag
dotnet run -- index --root "..\..\RimWorldData" --force graph

⚠️ 重要提示

--forceは既存のインデックスを強制的に削除/更新し、最初から構築します。フィールドの保存または分割ルールの変更後の完全な再構築に適しています。通常の更新では、--forceを省略して増分構築を開始することができ、より高速で変更されていないデータを保持します。

💡 使用建议

最適なバッチサイズはVRAMに依存します。私のGeforce rtx4060 laptop + 16GB VRAMでは、256～512のバッチサイズが適切です。この値を超えると、一部のデータがCPUに動的に移行され、埋め込み効率が大幅に低下します。皆さんもいくつかの値を試して、最適なバッチサイズを見つけてください。

💡 使用建议

--embedding-serverを使用すると、実行中の埋め込みサーバーに接続でき、各バッチでモデルを再読み込みするコストを回避できます。埋め込みサーバーを事前に起動する必要があります：.\scripts\start-embedding-server.ps1

💻 CLIクエリコマンド

混合検索の例

cd src\RimWorldCodeRag
dotnet run -- rough-search --query "weapon gun" --kind def --lexical-k 2000 --max-results 10
# ここでのlexical-kパラメーターのデフォルト値は1000で、第1段階の字面類似度による粗いフィルタリングで得られる結果を表します。意味類似度の検索はこれらの結果の中から行われます。kの値が大きいほど、期待される結果が得られる可能性が高くなりますが、それに伴って処理時間も長くなります。

あるシンボルの使用を検索する（そのシンボルが参照する他のシンボルを返し、--kindで層を制限する）

dotnet run -- get-uses --symbol "xml:Gun_Revolver" --kind csharp

誰が使用しているかを検索する（そのシンボルに依存しているシンボルのリストを返す）

dotnet run -- get-used-by --symbol "RimWorld.CompProperties_Power" --kind xml

完全なソースコードを取得する（シンボルに基づいて元のファイルの断片を返し、行数を制限することもできる）

dotnet run -- get-item --symbol "RimWorld.Building_Door" --max-lines 200
dotnet run -- get-item --symbol "xml:Door"

一般的なパラメーターの説明

• --kindはcsharp/csまたはxml/defをサポートし、特定の層（C#またはXML）でのみクエリを実行するために使用されます。
• --max-resultsは返される候補の数を制御し、--max-linesはソースコードの返却行数の上限を制御します。

🛠️ MCPサーバーの完全なセットアップガイド

前提条件

• .NET 8.0 SDK（microsoft.com/netからダウンロード）
• Python 3.9+（python.orgからダウンロード）
• RimWorldゲームファイル：RimWorldのインストールディレクトリからDefデータをコピーします：C:\Program Files (x86)\Steam\steamapps\common\RimWorld\Data；C#ソースコードは、ILSpyまたはdnspyを使用してエクスポートし、プロジェクトルート/RimWorldDataに保存します。
• クロスプラットフォーム対応：Windows (PowerShell)、Linux/macOS (シェルスクリプト)

1. プロジェクト構造の設定

# プロジェクトをクローンまたはダウンロード
cd RiMCP_hybrid/

# RimWorldデータを配置する（必須）
# RimWorldのインストールディレクトリからDefデータをコピーします：C:\Program Files (x86)\Steam\steamapps\common\RimWorld\Data
# C#ソースコードは、ILSpyまたはdnspyを使用してエクスポートします。
# これらをRimWorldData/（このREADMEと同じ階層）に配置します。
# もし私がリポジトリにEdgeworldのソースコードを直接アップロードすると、泰南に訴えられるので注意してください。

# 埋め込みモデルを配置する
# mkdir -p src/RimWorldCodeRag/models/
# モデル（例：e5-base-v2）をダウンロードして、src/RimWorldCodeRag/models/e5-base-v2/に配置します。
# 注意：このプロジェクトはe5-base-v2に対して特別な最適化を行っています（"query: "と"passage: "の接頭辞を追加します）。
# 他のモデルも動作しますが、性能が若干低下する可能性があります。実際には、他のmodderの使用経験からすると、それほど大きな影響はありません。

2. 埋め込み環境の設定（1回限り、構築前に実行）

# Python仮想環境を設定し、モデルをダウンロードする（必須、構築前に実行）
# Windows PowerShell:
.\scripts\setup-embedding-env.ps1

# Linux/macOS:
./scripts/setup-embedding-env.sh

3. プロジェクトの構築

# すべてのコンポーネントを構築する（.gitignoreにより構築出力が除外されているため）
dotnet build

4. インデックスの構築（1回限り、実際のサービス開始前に実行）

# RimWorldデータから検索インデックスを作成する
cd src/RimWorldCodeRag
dotnet run -- index --root "..\..\RimWorldData"

5. サービスの起動

# ターミナル1：埋め込みサーバーを起動する（バックグラウンドで実行し続ける、デフォルトのポートは127.0.0.1:5000）
# Windows PowerShell:
.\scripts\start-embedding-server.ps1

# Linux/macOS:
./scripts/start-embedding-server.sh

# ターミナル2：MCPサーバーを起動する
cd src\RimWorldCodeRag.McpServer
dotnet run

⚙️ MCPサーバーの詳細設定

環境変数の設定

MCPサーバーを起動する前に、これらの変数を設定します。

# 必須：ステップ3で作成したインデックスフォルダのパスを指定する
$env:RIMWORLD_INDEX_ROOT = "c:\path\to\RiMCP_hybrid\index"

# オプション：埋め込みサーバーのURL（デフォルト：http://127.0.0.1:5000）
$env:EMBEDDING_SERVER_URL = "http://127.0.0.1:5000"

代替案：appsettings.jsonの設定

src/RimWorldCodeRag.McpServer/appsettings.jsonを編集します。

{
  "McpServer": {
    "IndexRoot": "c:/path/to/RiMCP_hybrid/index",
    "EmbeddingServerUrl": "http://127.0.0.1:5000"
  }
}

🧪 MCPサーバーのテスト

基本テスト

cd src\RimWorldCodeRag.McpServer
# Windows PowerShell:
.\test-mcp.ps1

# Linux/macOS（利用可能な場合）:
./test-mcp.sh

手動JSON-RPCテスト

# 1つのターミナルでサーバーを起動する
dotnet run

# 別のターミナルでテストする
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}' | dotnet run

🆚 VS Codeの統合

%APPDATA%\Code\User\globalStorage\mcp-servers.jsonを作成または編集します。

{
  "mcpServers": {
    "rimworld-code-rag": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "c:/path/to/RiMCP_hybrid/src/RimWorldCodeRag.McpServer"
      ],
      "env": {
        "RIMWORLD_INDEX_ROOT": "c:/path/to/RiMCP_hybrid/index",
        "EMBEDDING_SERVER_URL": "http://127.0.0.1:5000"
      }
    }
  }
}

🛠️ MCPツールの説明

すべてのツールが実装され、正常に動作します。

1. rough_search - 混合意味検索

自然言語クエリを使用して、RimWorldのコードシンボルとXML定義を検索します。一致する項目名のリストとメタデータを返します。その後、get_itemツールを使用して、関心のある結果の完全なソースコードを取得できます。検索が関連する結果を返さない場合は、クエリを簡素化して基本的なキーワードに焦点を当ててみてください。

2. get_uses - 依存関係分析（下流）

シンボルが何に依存しているかを検索します。呼び出し関係と実装ロジックを表示します。他のコード/シンボルを使用しているものを追跡することで、機能の動作原理を理解するのに非常に役立ちます。その後、get_itemツールを使用して、関心のある依存関係の完全なソースコードを確認できます。

3. get_used_by - 逆依存関係分析（上流）

シンボルを使用しているものを検索します。逆依存関係と呼び出し関係を表示します。シンボルを呼び出しまたは参照しているものを追跡することで、影響範囲と使用パターンを理解するのに非常に役立ちます。その後、get_itemツールを使用して、関心のある呼び出し元の完全なソースコードを確認できます。

4. get_item - 正確なソースコード検索

特定のシンボルの完全なソースコードとメタデータを検索します。rough_search、get_uses、またはget_used_byの結果から関心のあるシンボルを見つけた後、このツールを使用します。完全なクラス定義、メソッド実装、またはXML定義と詳細なメタデータを返します。

🚧 MCPサーバーのトラブルシューティング

"Index not found"エラー

• インデックス構築手順を実行したことを確認してください：dotnet run -- index --root "..\..\RimWorldData"
• RIMWORLD_INDEX_ROOT環境変数がindex/フォルダを指していることを確認してください。

"Embedding server connection failed"エラー

• まず埋め込みサーバーを起動してください：
  • Windows PowerShell: .\scripts\start-embedding-server.ps1
  • Linux/macOS: ./scripts/start-embedding-server.sh
• "Model loaded successfully"メッセージが表示されるまで待ってください。
• ポート5000で実行されていることを確認してください。

構築失敗

• .NET 8.0 SDKがインストールされていることを確認してください。
• プロジェクトルートからdotnet buildを実行してください。

検索結果が得られない

• RimWorldDataフォルダにゲームファイルが含まれていることを確認してください。
• より単純な検索クエリを試してみてください（例："pawn hunger system"ではなく"pawn"）。

📊 パフォーマンスに関する説明

• コールドスタート：約2～5秒（インデックスの読み込み）
• ホットクエリ：0.5～1秒
• メモリ使用量：ベクトルインデックスで約300MB
• 推奨GPU：埋め込みサーバーに使用すると大幅な高速化が期待できます。

🔄 更新に関する説明

RimWorldが更新された場合：

1. 新しいゲームファイルを使用してRimWorldData/フォルダを更新します。
2. インデックスを再構築します：dotnet run -- index --root "..\..\RimWorldData" --force

📚 関連ドキュメント

• 実装の詳細：docs/ディレクトリ
• MCPプロトコル：https://modelcontextprotocol.io/

💡 ワークフローでの使用に関する推奨手順

初回使用時

まず、完全にインデックスを構築し（--forceを使用しないか、クリーンな状態を確認する場合は--forceを使用します）、その後、いくつかの典型的なクエリを実行して結果を確認します。

コードまたは解析ルールが更新された後

少量のファイルが変更された場合は、増分インデックスを使用します。分割または保存フィールドが変更された場合は、--forceを使用して完全に再構築します。

MCPサービスをAIアシスタントに渡す前

ローカルでCLIを使用して一般的なクエリを検証し、get-itemが正しいソースコード断片を返すことを確認し、グラフクエリ（get-uses/get-used-by）の結果が合理的であることを確認します。

クロスプラットフォーム対応

• Windows: PowerShellスクリプト（.ps1）を使用します。
• Linux/macOS: シェルスクリプト（.sh）を使用します。
• 両方のプラットフォームで同じ機能とパラメーターがサポートされています。

日常的なメンテナンス

インデックスの構築または増分更新をCIプロセスに組み込み、重要なブランチが変更された後に検証スクリプトを実行します。

🚑 トラブルシューティングのクイックリファレンス

• シンボルが見つからない場合：シンボルの形式を確認してください。XMLの場合はxml:DefName、C#の場合はNamespace.ClassNameを使用します。必要に応じてインデックスを再構築し、検証してください。
• 埋め込み生成が失敗するか、OOM（メモリ不足）エラーが発生する場合：--python-batchを小さくするか、GPUがない環境では小さいモデルを使用するか、転置インデックスのみを使用してください。
• MCPが応答しない場合：起動ディレクトリとコマンドが正しいことを確認し、dotnet runがコマンドラインでサーバーを単独で起動できることを確認し、コンソールログを確認してエラーを特定してください。
• リモートAPIエラーが発生する場合：--api-keyを使用する場合は、--embedding-server（APIのURL）と--model-nameも同時に指定していることを確認してください。