rpg-encoder

rpg-encoder

AI エージェントにコードベースのための頭脳を。

AI コーディングエージェントは、ツール呼び出しの大半を grep、cat、find、ファイル読み取りでコードベースを手探りするために無駄にしています。rpg-encoder はそれを解決します。Tree-sitter を使ってコードのセマンティックグラフを構築します。単に何が何を呼び出すかだけでなく、各関数が何をするかまで捉え、MCP を通じて 1 回のツール呼び出しでリポジトリ全体を理解できるようにします。

クイックスタート

claude mcp add rpg -- npx -y -p rpg-encoder rpg-mcp-server

コマンド 1 つだけです。Claude Code、Cursor、opencode、Windsurf、その他 MCP 互換のあらゆるエージェントで動作します。Rust ツールチェーンも、クローンも、ビルドも不要 — npx がお使いのプラットフォーム向けのビルド済みバイナリをダウンロードします。

あとは任意のリポジトリを開いて、エージェントにこう伝えてください。

「このリポジトリの RPG をビルドしてリフトして」

エージェントがすべてを処理します。エンティティをインデックス化し（数秒）、各関数を読み取って意図レベルの特徴を追加し（数分）、それらをセマンティック階層に整理し、チームのために .rpg/graph.json をコミットします。

エンティティが約 100 件以上あるリポジトリでは、lifting_status がエージェントに対して、リフティングのループをサブエージェントやより安価なモデルに委任するよう指示します。特徴抽出はパターンマッチングであり、新しい推論ではありません。実行環境にサブエージェントの仕組みがない場合は、API キーを設定してターミナルから rpg-encoder lift --provider anthropic|openai を実行してください。CLI はエージェントを介さずに外部 LLM を直接操作します。CLI の完了後、セッションで reload_rpg を呼び出して更新されたグラフを読み込んでください。CLI は特徴のないエンティティをリフトします。古いエンティティの再リフト（特徴は存在するがコード変更後に古くなったもの）は、CLI ではなくセッション内の MCP フローで処理されます。

リフトが完了したら、次のことを試してみてください。

• 「認証を処理しているのはどこ？」 — どこにも「auth」と名付けられていなくてもコードを見つけます
• 「データベース接続に依存しているものをすべて表示して」
• 「API エンドポイントにレート制限を追加する変更を計画して」

grep、cat、find の前に RPG を使う

サーバーの指示は、コード構造や動作に関するあらゆる質問に対して、まず RPG ツールに手を伸ばすようエージェントに伝えます。この反射が重要です — grep、cat、およびその場しのぎのファイル読み取りはトークンを浪費し、RPG がすでに把握している意味的な関係を見落とします。

grep、cat、またはファイル読み取りにフォールバックするのは、クエリが構造ではなくリテラルなテキスト（文字列検索、コメント、TODO、ログメッセージ）に関するものである場合だけにしてください。

仕組み

1. Parse — Tree-sitter が 15 言語からエンティティ（関数、クラス、メソッド）と依存関係のエッジ（インポート、呼び出し、継承）を抽出します。
2. Lift — LLM（あなたのエージェント、または Haiku のような安価な API）が各エンティティを読み、動詞-目的語の特徴を書き出します: 「JWT トークンを検証する」、「設定をディスクにシリアライズする」。
3. Organize — 特徴が 3 レベルのセマンティック階層（エリア → カテゴリ → サブカテゴリ）にクラスタリングされます。これはファイルツリーではなく、コードが何をするかから生まれます。
4. Understand — semantic_snapshot がグラフ全体を約 25K トークンに圧縮します。あなたの LLM はそれを一度読むだけでリポジトリを把握します。

セマンティックスナップショット

ファイルを grep して回る代わりに、LLM は semantic_snapshot を一度呼び出すだけで以下を受け取ります:

• 階層 — 集約された特徴を持つすべての機能エリア
• エンティティ — エリアごとにグループ化された、すべての関数、クラス、メソッドとそのセマンティックな特徴
• 依存関係の骨格 — 修飾名を含む凝縮されたコールグラフ
• ホットスポット — 最も接続が多い上位 10 エンティティ（アーキテクチャのバックボーン）

約 25K トークンで約 1000 エンティティをカバーします。これは 1M コンテキストウィンドウの 2〜3% です — LLM は毎セッション、すでにあなたのリポジトリを把握した状態で開始します。

自己メンテナンスするグラフ

作業ツリーが変更されるたびに — コミット済み、ステージ済み、または未ステージを問わず — MCP サーバーは次のクエリに応答する前に自動的に再同期します。(path, size, mtime) に対するチェンジセットハッシュにより、同じファイルの繰り返し保存は 1 回の同期をトリガーし、アイドル状態のクエリはまったくトリガーしません。リバートも検出されます: 以前ダーティだったファイルが HEAD の状態に戻ると、グラフは復元されます。

Lift の 2 つの方法

auto_lift は安価な外部 LLM を直接呼び出します — あなたのコーディングサブスクリプションが lift 作業に触れることはありません。api_key_env を使って環境変数からキーを解決すれば、ツール呼び出しのトランスクリプトにキーが現れることはありません。

アーキテクチャ

7 つの Rust クレート、1 つの MCP サーバーバイナリ、1 つの CLI バイナリ:

MCP ツール (27)

対応言語

Tree-sitter による 15 言語:

インストール

MCP サーバー (推奨)

# Claude Code
claude mcp add rpg -- npx -y -p rpg-encoder rpg-mcp-server

# Cursor — add to ~/.cursor/mcp.json
{
  "mcpServers": {
    "rpg": {
      "command": "npx",
      "args": ["-y", "-p", "rpg-encoder", "rpg-mcp-server"]
    }
  }
}

サーバーは現在の作業ディレクトリからプロジェクトルートを自動検出します — パス引数は不要です。

npm install -g rpg-encoder

# Build a graph
rpg-encoder build

# Query
rpg-encoder search "parse entities from source code"
rpg-encoder fetch "src/parser.rs:extract_entities"
rpg-encoder explore "src/parser.rs:extract_entities" --direction both --depth 2
rpg-encoder info

# Autonomous lifting via API
rpg-encoder lift --provider anthropic --dry-run  # estimate cost
rpg-encoder lift --provider anthropic           # lift with Haiku (~$0.02/100 entities)

# Incremental update
rpg-encoder update

# Pre-commit hook (auto-updates graph on commit)
rpg-encoder hook install

git clone https://github.com/userFRM/rpg-encoder.git
cd rpg-encoder && cargo build --release

ドキュメント

• RPG の比較 — GitNexus、Serena、Repomix などとの率直な比較
• 論文との忠実性 — 研究論文とのアルゴリズム単位の比較
• ユースケース — RPG で何ができるかの実践的な例
• CHANGELOG — リリース履歴

インスピレーションと参考文献

rpg-encoder は RPG-Encoder 研究論文の理論的枠組みの上に構築されており、コードインテリジェンスの領域全体にわたるツールから着想を得た独自の拡張を加えています:

• RPG-Encoder 論文 (Luo ら、2026 年、Microsoft Research) — セマンティックリフティングモデル、3 レベル階層の構築、インクリメンタル進化アルゴリズム、形式グラフモデル G = (V_H ∪ V_L, E_dep ∪ E_feature)。
• GitNexus — 事前計算されたリレーショナルインテリジェンス、ブラスト半径分析、Claude Code フック。コードグラフツールは不可視であってこそ不可欠になれることを示しました。
• Serena — LSP によるシンボルレベルの精度。バッチ分析よりもリアルタイムのコード認識のほうが重要であることを実証しました。
• TOON — LLM に最適化された出力のための Token-Oriented Object Notation。

これは独立した実装です。すべてのコードは MIT ライセンスの下でのオリジナルの成果物です。Microsoft とは提携しておらず、承認も受けていません。

ライセンス

MIT