Muvon/octocode

Structural code intelligence for AI agents — semantic search, knowledge graphs, and a built-in MCP server in one Rust binary. Give Claude, Cursor, and any MCP client a deep understanding of your codebase.

Octocode – AIエージェント向けの構造的コードインテリジェンス

何であるか – Octocodeは、コードベースをライブでクエリ可能な知識グラフに変換するオープンソースのRustツールです。Claude Desktop、Cursor、Windsurfなどに使われるModel-Center-Protocol（MCP）を内蔵したMCPサーバーを提供しており、AIアシスタントがプロジェクトの構造を人間のように検索・ナビゲーション・推論できるようにします。

なぜ重要か – 一般的なRetrieval-Augmented Generation（RAG）はソースファイルをフラットなテキストチャンクとして扱い、インポート、関数呼び出し、継承、モジュール境界などの関係性を失います。OctocodeはASTベースのシンボルグラフを抽出し、確定的なエッジ（imports、calls、extends、implementsなど）を保持。このグラフに加え、意味検索機能をMCP互換エージェントに提供します。その結果、「認証はどこで処理されていますか？」や「支払いモジュールに依存しているファイルは？」といった、キーワード一致から推測する必要のない、コードに特化した回答が可能になります。

コア機能

機能	得られるもの
意味検索	自然言語クエリで、BM25キーワードマッチングとベクトル埋め込み（Voyage、OpenAI、Jinaなど）のハイブリッド方式により、最も関連性の高いファイルを返します。
ライブASTグラフ	Tree-sitterが現在のソースツリーをノード（ファイル、シンボル）とエッジ（`imports`、`calls`など）に解析。常に最新の状態を維持。別インデックスは不要です。
GraphRAG（オプション）	オプションの永続化グラフにより、LLMが生成した説明と、より広範なアーキテクチャ的関係を確定的グラフの上に追加できます。
LSP統合	`--with-lsp`で起動すると、`goto-definition`、`find-references`、`hover`、`completion`など、言語サーバー（例：rust-analyzer）を使用してリクエストを転送します。
構造検索	ASTパターンマッチングにより、特定のコードパターン（例：すべての`.unwrap()`呼び出し）を検出できます。
マルチ言語対応	16言語が標準でサポート（Rust、Python、TypeScript/JS、Go、PHP、C++、Ruby、Elixir、Java、Swift、Svelte、Lua、CSS、JSON、Bash、Markdown）。
ローカル優先・プライバシー優先	fastembedでローカルで埋め込みを生成可能。クラウドプロバイダーはオプションで、送信するチャンクのみを確認できます。

動作原理（概要）

Tree-sitterが各ソースファイルを解析 → ファイル、関数、クラスなどのノードに変換。
ライブシンボルグラフがこれらのノードから確定的なエッジ（contains、imports、callsなど）で構築。
オプションのインデックス：各ファイル（またはシンボル）に対して埋め込みを計算し保存。オプションのLLMでテキスト説明を追加可能。
MCPサーバーがRPCツール（semantic_search、view_signatures、graphrag、structural_search、LSPヘルパー）を公開。AIエージェントが呼び出します。
ハイブリッドリトリーバル：BM25キーワードスコアとベクトル類似度（RRF融合）を組み合わせて結果をランク付け。

クイックスタート（インストール → インデックス → 検索）

# インストール（curlインストーラ、Homebrew、またはcargo）
curl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh
# または：brew install muvon/tap/octocode
# または：cargo install octocode

# 埋め込みプロバイダーを設定（例：Voyage AIキー）
export VOYAGE_API_KEY="your-key"

# プロジェクトをインデックス化
cd /path/to/your/project
octocode index   # すべてのファイルを処理し、ライブグラフを構築

# 自然言語検索
octocode search "authentication middleware"

AIアシスタントの接続（MCPクライアント）

クライアントのmcpServers設定にサーバーエントリを追加。例：Claude Desktopの場合

{
  "mcpServers": {
    "octocode": {
      "command": "octocode",
      "args": ["mcp", "--path", "/path/to/your/project"]
    }
  }
}

これにより、アシスタントは`semantic_search`や`graphrag`などのツールを呼び出し、具体的な場所やコールグラフを含むコードベースの質問に答えられるようになります。

リトリーバル品質（ベンチマーク）

Octocodeは自らのソースツリー上で実行される再現可能なベンチマーク（127件のコード検索クエリ）を同梱しています。単純なハイブリッド（BM25 0.3 + ベクトル 0.7）で以下の成績を達成：

Hit@5 = 0.732
Hit@10 = 0.835
MRR = 0.572
Recall@10 = 0.807 キーワード重視の重み付けにより、密度のみのリトリーバルに比べてHit@5が**+22%**向上。また、汎用的なコードリランカー（bge-reranker-base）は性能を低下させることが示され、コード特化型リランカーの必要性が確認されました。

どのような人が使うか

開発者：LLM搭載アシスタント（Claude、Cursorなど）がリポジトリの実際のアーキテクチャを理解できるようにしたい人。
チーム：信頼性とプライバシーを保ちつつ、コードナビゲーションが必要な内部AIエージェントを構築したい人。
ツール開発者：ASTパースを再実装せずに、LSPレベルの精度を提供する即戦力のMCPサーバーを探している人。

ライセンスとコミュニティ

ライセンス：Apache 2.0（許容性高く、商用利用に適しています）。
リポジトリ活動：CIバッジ、カバレッジバッジ、crates.ioでのリリース、増加するスター数。
サポート：GitHub Issues、Discussions、連絡先メール（opensource@muvon.io）。

結論：Octocodeは実用的でプロダクションレベルのRustプロジェクトであり、AIエージェントにコードの構造的・グラフベースのビューを提供。すべてをローカルで管理し、完全に自分の制御下に置きながら、正確で文脈に応じた支援を可能にします。