Claude Context 入門：AI にあなたのコード全体を本当に理解させる

Claude Context は、ベクトルデータベース事業者 Zilliz が開発したオープンソースの MCP（Model Context Protocol）プラグインです。核となるコンセプトは非常に明確です。AI コーディング支援者に、コードベース全体のセマンティクス理解能力を注入すること。

従来のワークフローでは、AI に初見のコードベースを理解してもらうには、ファイルパスを手動でコピーし、プロジェクト構成を説明し、モジュール間の関係を解説する必要がありました。本来それを AI がやるべき作業です。Claude Context はセマンティック検索技術により、AI がコードベース内の関数・クラス・データ構造を直接問い合わせできるようにします。もはや手動でコンテキストを注入する必要はありません。

このプロジェクトは GitHub で zilliztech/claude-context としてホストされており、MIT ライセンスで、コードは完全にオープンソースです。

---

難易度/所要時間/得られるもの

入門レベル | 約 20 分 | たった 2 つのコマンドで、任意のコーディングツールに「数百万行分のコードのセマンティクス理解力」を持たせられるようになり、さらにトークン消費を約 40% ほど削減できます。

---

対象読者

• 日常的に Claude Code、Cursor、Windsurf、Cline などの AI プログラミングツールを使う開発者
• RAG（検索拡張生成）やベクトル検索について基礎知識があり、実践まで深めたい人
• トークンコストを下げ、AI の回答精度を高めたいチーム

---

コア依存関係と環境

システム要件

• Node.js >= 20.0.0 且つ < 24.0.0
• OS：macOS、Windows、Linux いずれも可

サービス依存

• Zilliz Cloud（無料枠で個人利用は十分）：ベクトルデータベースのバックエンドを提供
• OpenAI API Key：embedding モデルでベクトルを生成するために使用（他の embedding 提供プロバイダに置き換えることも可能）

---

完全なプロジェクト構造ツリー

Claude Context は純粋な npm パッケージで、ローカルのコードをクローンしたりビルドしたりする必要はありません。インストール後は、自身がストレージ構造を管理します。

~/.claude/
└── plugins/
    └── claude-context/          # MCP プラグインディレクトリ
        └── [インデックスデータファイル]        # 増分 Merkle 木スナップショット

Core パッケージをアプリケーションに直接組み込む場合は、構造が次のようになります。

your-project/
├── node_modules/
│   └── @zilliz/claude-context-core/
├── .env                        # API Key を格納
└── your-codebase/              # インデックス対象のコード

---

手順（ステップバイステップ）

ステップ 1：Zilliz Cloud を登録し、ベクトルデータベースの認証情報を取得する

Claude Context のベクトルストレージは、Zilliz Cloud（またはセルフホストの Milvus）に依存します。このステップでは無料アカウントの作成が必要です。

https://zilliz.com/cloud を開き、メールアドレスまたは GitHub アカウントで登録します。ログイン後、コンソールで新しい Serverless Cluster を作成してください。

1. Create Cluster をクリック
2. Serverless タイプを選択（無料枠で十分に足ります）
3. 近いリージョンを選択（AWS us-west-2 やシンガポールがよく使われます）
4. クラスタに名前を付ける（例：claude-context）

クラスタ作成後、クラスタ詳細ページに移動し Connection Info を見つけて、次の 2 つの値を控えてください。

• Public Endpoint：https://xxx.api.gcp-us-west1.zillizcloud.com のような形式
• API Key：xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx のような形式

ステップ 2：OpenAI API Key を取得する

Claude Context は embedding モデルでコード断片をベクトルに変換します。既定の text-embedding-3-small モデルを動かすために、OpenAI API Key を用意する必要があります。

platform.openai.com/api-keys を開き、Create new secret key をクリックして、生成された値をコピーします（形式は sk-xxxxxxxx... です）。

ステップ 3：Claude Code に Claude Context MCP をインストールする

ここから Claude Code にこの MCP サーバーを登録します。ターミナルを開き、任意のプロジェクトディレクトリに移動して、次のコマンドを実行します。

claude mcp add claude-context \
  -e OPENAI_API_KEY=sk-your-openai-api-key \
  -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
  -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint \
  -- npx @zilliz/claude-context-mcp@latest

以下のプレースホルダを、実際の値に置き換えてください。

• sk-your-openai-api-key → あなたの OpenAI API Key
• your-zilliz-cloud-api-key → あなたの Zilliz Cloud API Key
• your-zilliz-cloud-public-endpoint → あなたの Zilliz Public Endpoint

コマンドが成功すると、MCP サーバーが登録されたことが表示されます。インストールを検証します。

claude mcp list

claude-context がリストにあり、状態が running になっているはずです。

別の AI コーディングツールを使っている場合は、設定方法が少し異なります。代表的なパターンをいくつか紹介します。

Cursor（推奨：設定ファイル方式）：

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/claude-context-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

Windsurf（同様に JSON 設定）：

// ~/.windsurf/mcp_settings.json
{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/claude-context-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

ステップ 4：最初のコードベースをインデックスする

インストールが完了したら、プロジェクトディレクトリに移動して Claude Code を起動します。

cd your-project-directory
claude

対話で次のコマンドを入力して、インデックスを開始します。

Index this codebase

Claude Context はすぐにコードベースの分析を始めます。全体の処理は 2 つの段階に分かれます。

1. ファイルスキャン：ディレクトリを走査し、拡張子で処理対象のコードファイルを絞り込みます
2. ベクトル埋め込み：各コードファイルを AST（抽象構文木）ベースでチャンク化し、embedding モデルを呼び出してベクトルを生成し、ベクトルデータベースに保存します

インデックス処理中でも、いつでも進捗を質問できます。

Check the indexing status

返答には、現在のインデックス進捗の割合（百分率）と、完了済みのファイル数が表示されます。

ステップ 5：検索結果を検証し、返ってきた内容を理解する

インデックスが完了したら、セマンティック検索を開始できます。代表的な問い合わせ例をいくつか示します。

特定機能の実装を探す：

Find functions that handle user authentication

返ってくる結果には、関連する関数名、ファイルパス、コード断片、相関スコア（0〜1 の間。数値が高いほど関連性が高い）が含まれます。

モジュール間の関係を理解する：

How does the payment module connect to the order module?

設定に関係するコードを素早く特定する：

Where is the database connection pool configured?

返答のフォーマットは次のとおりです。

File: src/database/connection.ts:45-78
Score: 0.94
Content:
  const pool = new Pool({
    max: 20,
    idleTimeoutMillis: 30000,
    connectionTimeoutMillis: 2000,
  });

インデックスをクリーンにして最初からやり直したい場合は、次を実行します。

Clear the index for this codebase

---

よくある問題の切り分け

Q1: Node.js のバージョンが非対応で、コマンド実行時にエラーが出る

症状：claude mcp add がエラーになる、または MCP サーバー起動直後にすぐ終了する。

原因：Claude Context は現在 Node.js 24.x に対応していません。

解決：

# 現在の Node のバージョンを確認
node -v

# もし 24.x なら 20.x（LTS）にダウングレード
nvm install 20
nvm use 20

Q2: 環境変数の設定ミスで、インデックスに失敗する

症状：Index this codebase が反応しない、または Milvus connection failed のようなエラーが返る。

確認手順：

1. MILVUS_ADDRESS に https:// のプレフィックスが含まれていないことを確認し、ホスト名部分をそのまま使う
2. MILVUS_TOKEN が Zilliz Cloud のコンソールに表示されている API Key と完全に一致していることを確認する
3. OPENAI_API_KEY が sk- で始まっていることを確認する

正しいフォーマット例：

-e MILVUS_ADDRESS=in-xx-xxxxxxxx.api.gcp-us-west1.zillizcloud.com
-e MILVUS_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-e OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Q3: インデックスの進捗が止まっていて進まない

症状：インデックスコマンドを出したあと、ずっと応答がない。

解決：

1. まず Check the indexing status を実行して現在の状態を確認する
2. ネットワーク接続を確認（OpenAI API と Zilliz Cloud へのアクセスが必要）
3. クラスタ作成直後だとエンドポイントがまだ初期化中の可能性があるため、1〜2 分待ってから再試行する

Q4: 検索結果が空、またはまったく関連がない

症状：本来一致するはずの内容を問い合わせても、空の結果が返る。

原因：インデックスファイルが不完全か、あるいは問い合わせ文の表現がコード内の命名と大きく異なっている可能性があります。

解決：

1. まずインデックス状態を確認：Check the indexing status
2. より具体的な問い合わせを試す（コード内で実際に使われている変数名や関数名を使う）
3. コードが存在するのに検索できない場合は、インデックスをクリアして再インデックスする：

Clear the index for this codebase
Index this codebase

Q5: 増分インデックスが反映されず、変更したコードが検索に出てこない

症状：あるファイルを変更したのに、セマンティック検索の結果が旧バージョンのままである。

原因：Claude Context は Merkle 木のスナップショットを使ってファイルの変更を検出します。スナップショットファイルを手動で削除してしまうと、増分検出が無効になる可能性があります。

解決：インデックスをクリアして最初からやり直せばOKです。

Clear the index for this codebase
Index this codebase

Q6: MCP 接続に失敗し、ツールが使えない

症状：ツール一覧に search_code、index_codebase などのツールが表示されない。

解決：

1. Claude Code を再起動する（ときに MCP サーバーの再読み込みが必要です）
2. MCP の設定に構文エラーがないことを確認する（JSON の場合はカンマや引用符に注意）
3. claude mcp list において、そのプラグインの状態が running になっているか確認する

claude mcp list

状態が stopped の場合は、手動で再起動します。

claude mcp remove claude-context
# その後、第 3 ステップのインストールコマンドをもう一度実行

---

追加の読み物 / 進化（アドバンス）方向

カスタム Embedding モデルを使う

OpenAI の text-embedding-3-small は既定の選択ですが、Claude Context は複数の embedding 提供プロバイダに対応しており、完全にローカル化したデプロイも実現できます。

Ollama（ローカルモデル）を使う：

claude mcp add claude-context \
  -e EMBEDDING_PROVIDER=ollama \
  -e OLLAMA_BASE_URL=http://localhost:11434 \
  -e OLLAMA_MODEL=nomic-embed-text \
  -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
  -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint \
  -- npx @zilliz/claude-context-mcp@latest

VoyageAI を使う：

claude mcp add claude-context \
  -e EMBEDDING_PROVIDER=voyageai \
  -e VOYAGEAI_API_KEY=your-voyageai-key \
  -e VOYAGEAI_MODEL=voyage-code-3 \
  -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
  -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint \
  -- npx @zilliz/claude-context-mcp@latest

LangChain/LangGraph を使って高度な RAG を実装する

自分のアプリ内に Claude Context の能力を直接統合したい場合は、Core パッケージを使えます。

import { Context, MilvusVectorDatabase, OpenAIEmbedding } from '@zilliz/claude-context-core';

// embedding とベクトルデータベースを初期化
const embedding = new OpenAIEmbedding({
    apiKey: process.env.OPENAI_API_KEY || 'your-openai-api-key',
    model: 'text-embedding-3-small'
});

const vectorDatabase = new MilvusVectorDatabase({
    address: process.env.MILVUS_ADDRESS || 'your-zilliz-cloud-public-endpoint',
    token: process.env.MILVUS_TOKEN || 'your-zilliz-cloud-api-key'
});

const context = new Context({ embedding, vectorDatabase });

// コードベースをインデックスし、進捗を監視
const stats = await context.indexCodebase('./your-project', (progress) => {
    console.log(`${progress.phase} - ${progress.percentage}%`);
});
console.log(`Indexed ${stats.indexedFiles} files, ${stats.totalChunks} chunks`);

// セマンティック検索を実行
const results = await context.semanticSearch('./your-project', 'vector database operations', 5);
results.forEach(result => {
    console.log(`File: ${result.relativePath}:${result.startLine}-${result.endLine}`);
    console.log(`Score: ${(result.score * 100).toFixed(2)}%`);
    console.log(`Content: ${result.content.substring(0, 100)}...`);
});

詳細な例は evaluation/retrieval/custom.py を参照してください。

VSCode で可視化して検索する

IDE 上で操作する方が慣れているなら、Semantic Code Search プラグインをインストールして、VS Code 内で直接セマンティック検索を行えます。Claude Code を起動する必要はありません。

複数コードベースの管理戦略

Claude Context は、複数のコードベースを同時に管理できます。別々のディレクトリでそれぞれ Index this codebase を呼び出すだけで、各ディレクトリは独立したインデックスを維持します。ディレクトリ名を使って区別できます。

# 作業ディレクトリ A
cd ~/projects/frontend && claude
# 対話中で Index this codebase を実行

# 作業ディレクトリ B
cd ~/projects/backend && claude
# 対話中で Index this codebase を実行

AST チャンク化の仕組みと Merkle 木による増分インデックス

Claude Context のコード理解能力は、2 つの中核技術に基づいています。

• AST ベースのチャンク化：抽象構文木を使ってコード構造を解析し、行数の単純な分割ではなく、関数・クラス・モジュール境界でチャンク化します。これにより、各 chunk がセマンティック的に完結したコード単位になるよう保証されます。
• Merkle 木による増分インデックス：各ファイルが変更された後、Merkle 木で照合して「変更されたファイルだけ」を再インデックスし、全量の作り直しは行いません。大規模コードベースの保守コストを大幅に下げられます。

これら 2 つの技術の実装の詳細が気になる場合は、zilliztech/claude-context リポジトリ内の packages/core のソースコードを確認してください。