コードベース全体をAIコンテキストにするOSS「claude-context」の仕組み

Claude Codeや CursorなどのAIコーディングツールを使っていると、「コードベースが大きくなるほど、AIが適切なコードを見つけられなくなる」という壁にぶつかることがあります。巨大なリポジトリの全ファイルをAIのコンテキストに詰め込もうとすると、トークン制限に引っかかったり、コストが膨大になったりします。かといって、一部のファイルだけを渡しても、AIは全体像を把握できません。

この問題に対するアプローチとして、セマンティック検索を使った「コードベース全体の仮想コンテキスト化」が注目されています。その実装の一つが、ベクトルデータベース専門企業Zillizが開発するOSS「claude-context」です。

本記事では、claude-contextの仕組み・アーキテクチャ・類似ツールとの違い・採用判断のポイントを、ドキュメントベースで解説します。実際にインストール・実行することなく、設計と思想を理解することを目的としています。

なお、本記事で参照しているリポジトリのメタ情報は2026年4月24日時点のものです（スター数: 9,121 / 最終コミット: 2026-04-24）。

執筆者

秋霜堂株式会社 代表 石川瑞起

中学生でプログラミングを独学で習得し、HP制作やアプリ開発の事業を開始。 大学入学後に事業を売却し、トヨクモ株式会社へ入社。 3年間にわたり1製品の開発責任者を務めたのち秋霜堂株式会社を設立し、多数の企業をサポートしている。

claude-contextとは何か——AIエージェントが「コードを読める」ようにするMCP

claude-context は、AIコーディングツール向けにコードベース全体をセマンティック検索可能にするMCP（Model Context Protocol）プラグインです。開発元はZilliz——オープンソースのベクトルデータベース「Milvus」を手がける企業です。

GitHubでのリポジトリ情報:

• スター数: 9,121
• ライセンス: MIT
• 主要言語: TypeScript
• 最終更新: 2026-04-24（現役アクティブ）

大規模コードベースのコンテキスト問題とは

AIコーディングツールにとって、コンテキスト（AIに渡す情報）は作業品質の決め手です。しかし大規模リポジトリでは、全ファイルをコンテキストに入れることがトークン制限・コスト・処理速度の観点から現実的ではありません。

claude-contextが解決しようとするのは、まさにこの「何を渡すか」の問題です。ベクトルデータベースにコードを事前インデックス化しておき、AIエージェントが「必要なときに必要なコードだけを引き出す」仕組みを提供します。

Augment Code社のMCPレジストリベンチマークによれば、同等の検索品質条件下でトークン使用量を約40%削減できるとされています（出典: Augment Code MCP Registry）。

claude-contextが提供する4つのMCPツール

claude-contextは、AIコーディングツールに以下のMCPツールを追加します:

Claude CodeなどのAIエージェントは、コードに関する質問があれば自動的に search_code ツールを呼び出して関連コードを取得します。開発者は特別なプロンプトを書く必要がなく、自然言語で「ユーザー認証を処理する関数を探して」と指示するだけで動作します。

技術アーキテクチャの詳細——ハイブリッド検索・AST・Merkleツリー

claude-contextの内部は、3つの技術的な柱で構成されています。

ハイブリッド検索（BM25 + 密度ベクトル検索）

単純なキーワード検索だけでは、変数名が異なる関連コードを見つけられません。claude-contextはBM25（全文検索）と密度ベクトル検索を組み合わせたハイブリッド検索を採用しています。

• BM25: キーワードの出現頻度に基づく従来型全文検索
• 密度ベクトル検索: コードの意味的な類似度に基づく検索

この組み合わせにより、「ユーザー認証を処理する」といった抽象的なクエリでも、関連する実装コードを正確に引き出せます。ハイブリッドモードは環境変数 HYBRID_MODE=true（デフォルト）で有効になります。

ASTベースの知的なコード分割（tree-sitter）

コードをベクトルDBに格納する際、単純に行数で区切ると関数の途中で切れてしまい、意味が失われます。claude-contextはtree-sitterパーサーを使ったAST（抽象構文木）ベースの分割を採用しています。

• 関数・クラス・メソッドなど論理的な単位でコードを分割
• 環境変数 SPLITTER_TYPE=ast（デフォルト）で有効
• フォールバックとして LangChain の文字数ベース分割も利用可能

対応言語はTypeScript / JavaScript / Python / Java / C++ / C# / Go / Rust / PHP / Ruby / Swift / Kotlin / Scala / Markdown など14言語以上です。

Merkleツリーによる増分インデックス

コードを変更するたびに全ファイルを再インデックスすると、大規模リポジトリでは時間とコストがかかりすぎます。claude-contextはMerkleツリーを使った増分インデックスを実装しており、変更されたファイルのみを差分更新します。

これにより、日常的な開発サイクル（コード変更→再インデックス→検索）のコストを最小化しています。

対応する埋め込みモデルとベクトルDB

埋め込みモデル（ベクトル変換エンジン）は以下から選択できます:

ベクトルDBはMilvus（オープンソース）またはZilliz Cloud（マネージドサービス）を使用します。

類似ツールとの比較——Serena・Context7との違いと使い分け

claude-contextと同じく「AIコーディング支援」を目的とするツールとして、SerenaとContext7がよく比較されます。

Serena（oraios/serena）との比較

SerenaはLSP（Language Server Protocol）ベースのシンボル解析ツールです。

SerenaはベクトルDBが不要で完全ローカル動作できる点が優位です。一方、「意味的に関連するコードを自然言語で探す」用途ではclaude-contextに一日の長があります。両者は目的が異なるため、組み合わせて使うことも可能です。

Context7（upstash/context7）との比較

Context7は自コードベースではなく、外部ライブラリ・フレームワークのドキュメントをAIに提供するサービスです。

Context7の2026年1月の無料枠削減（6,000→1,000リクエスト/月）は多くの開発者に影響を与えましたが、claude-contextはセルフホスト構成であれば制限なく利用できます。

用途別の選択ガイド

対応するAIコーディングツール——Claude Code以外でも使える

claude-contextはMCP標準プロトコルを通じて統合されるため、Claude Code以外の多数のAIコーディングツールに対応しています。

各ツールでの設定方法は公式ドキュメントを参照してください。

Claude Codeでの設定コマンド

以下のコマンドをターミナルで実行することでMCPとして登録できます（出典: README）:

Cursorでの設定（mcp.json）

~/.cursor/mcp.json に以下を追加します（出典: README）:

前提条件と注意事項——Node.jsバージョン制約・Zilliz Cloud無料枠

claude-contextを使う前に、以下の前提条件と制約を確認してください。

Node.jsバージョン制約

claude-contextはNode.js 20.x または 22.xのみサポートします。Node.js 24.0.0 以上は非対応のため、注意が必要です（公式READMEより）。

利用前に node --version でバージョンを確認し、非対応バージョンを使っている場合はnvm等でバージョンを切り替えてください。

ベクトルDB（Milvus / Zilliz Cloud）の準備

コードのインデックスを格納するベクトルデータベースが必要です:

• Zilliz Cloud: 無料枠あり。cloud.zilliz.com でサインアップして取得
• ローカルMilvus: Docker経由でローカル実行可能。プライバシー重視の場合に有効

埋め込みモデルのAPIキー

埋め込みモデルとして選択したプロバイダーのAPIキーが必要です。デフォルトはOpenAI（OPENAI_API_KEY）です。

ローカル完結を望む場合、Ollamaを選択することでOpenAI APIキー不要の構成も可能です（EMBEDDING_PROVIDER=Ollama）。

npmパッケージ

npmパッケージは @zilliz/claude-context-mcp として公開されています。npx での直接実行が標準の使用方法です。

主要な環境変数一覧

（出典: environment-variables.md）

どんなプロジェクトに向いているか——採用判断のチェックリスト

claude-contextの採用を検討する際、以下の観点で適合性を判断してください。

採用に向いているケース

• コードベースが大規模（目安: 5万行以上）で、AIがコンテキストを把握しにくい
• 複数言語が混在したリポジトリで、ファイル間の関連を自然言語で検索したい
• Claude Code / Cursor / Gemini CLI などのAIコーディングツールを積極的に活用している
• トークンコストを削減したい（約40%のトークン削減効果が期待される）
• Zilliz Cloudの無料枠か、ローカルMilvusで構成を組める

慎重に検討すべきケース

• Node.js 24.0.0以上を使っており、バージョン切り替えが難しい
• ベクトルDBのセットアップやAPIキー管理がプロジェクトポリシーで難しい
• 小規模なリポジトリ（数千行程度）で、通常のファイル読み込みで十分な場合
• 完全にオフライン・インターネット非接続の環境（Ollama + ローカルMilvusで対応可能だが構築コストがある）

メンテナンス状況

採用判断において、OSSのメンテナンス健全性は重要な指標です:

• スター数: 9,121（2026-04-25時点）
• フォーク数: 699
• 最終コミット: 2026-04-24（直近24時間以内、非常にアクティブ）
• ライセンス: MIT（商用利用・改変自由）
• 開発元: Zilliz（Milvusを主力製品とするベクトルDBベンダー）

開発元が自社製品（Milvus）と密接に連携するOSSであるため、継続的なメンテナンスが期待できます。

代替手段との比較で選ぶ基準

claude-contextは、「大規模コードベースをAIエージェントに理解させる」という課題に対してベクトルデータベースとハイブリッド検索で応える、設計思想の明確なOSSです。スター数9,121・MIT・アクティブなメンテナンス状況から、今後のAIコーディングエコシステムの中で存在感を増していく可能性があります。

まずGitHubリポジトリのREADMEと公式ドキュメントで詳細な設定手順を確認した上で、自プロジェクトへの適合性を判断することをお勧めします。