Découvrir Claude Context : faire en sorte que l’IA comprenne réellement l’ensemble de votre base de code

Claude Context est un plugin open source MCP (Model Context Protocol) développé par l’éditeur de bases de données vectorielles Zilliz. Son positionnement est très clair : injecter à l’assistant de codage par IA la capacité de compréhension sémantique de toute votre base de code.

Dans les workflows traditionnels, lorsque vous voulez que l’IA vous aide à comprendre une base de code inconnue, vous devez manuellement copier les chemins des fichiers, décrire la structure du projet et expliquer les relations entre les modules — des tâches qui devraient en réalité être faites par l’IA elle‑même. Grâce à la recherche sémantique, Claude Context permet à l’IA d’interroger directement les fonctions, classes et structures de données dans votre base de code, sans dépendre d’une injection manuelle de contexte.

Ce projet est hébergé sur GitHub : zilliztech/claude-context. Il est distribué sous licence MIT et le code est entièrement open source.

---

Difficulté / durée / bénéfices

Niveau débutant | ~20 minutes | Vous saurez comment donner à n’importe quel outil de codage une compréhension sémantique de millions de lignes de code avec seulement 2 commandes, tout en réduisant d’environ 40 % la consommation de tokens.

---

Public cible

• Les développeurs qui utilisent au quotidien des outils de programmation par IA comme Claude Code, Cursor, Windsurf ou Cline
• Ceux qui ont déjà des notions sur le RAG (Retrieval-Augmented Generation) et la recherche vectorielle, et qui souhaitent passer à la pratique approfondie
• Les équipes qui veulent réduire les coûts en tokens et améliorer la précision des réponses de l’IA

---

Dépendances clés et environnement

Configuration système requise

• Node.js >= 20.0.0 et < 24.0.0
• Systèmes d’exploitation : macOS, Windows et Linux (tous compatibles)

Dépendances de service

• Zilliz Cloud (l’allocation gratuite suffit largement pour un usage personnel) : fournit le backend de la base de données vectorielle
• OpenAI API Key : nécessaire pour générer les vecteurs avec le modèle d’embedding (vous pouvez aussi le remplacer par un autre fournisseur d’embedding compatible)

---

Arborescence complète du projet

Claude Context est un paquet npm pur : il ne vous faut ni cloner ni compiler de code local. Après l’installation, il gère sa propre structure de stockage :

~/.claude/
└── plugins/
    └── claude-context/          # Dossier du plugin MCP
        └── [fichier de données d’index]        # Instantané incrémental d’arbre Merkle

Si vous utilisez le paquet Core pour l’intégrer directement dans votre application, la structure est la suivante :

your-project/
├── node_modules/
│   └── @zilliz/claude-context-core/
├── .env                        # Contient la clé API
└── your-codebase/              # Code à indexer

---

Étapes pas à pas

Étape 1 : enregistrer Zilliz Cloud et obtenir les identifiants de la base vectorielle

Le stockage vectoriel de Claude Context s’appuie sur Zilliz Cloud (ou sur Milvus auto‑hébergé). Cette étape implique la création d’un compte gratuit.

Ouvrez zilliz.com/cloud et inscrivez‑vous avec votre e‑mail ou via votre compte GitHub. Une fois connecté, créez un nouveau Serverless Cluster depuis la console :

1. Cliquez sur Create Cluster
2. Choisissez le type Serverless (l’allocation gratuite est entièrement suffisante)
3. Sélectionnez la région la plus proche (AWS us-west-2 ou Singapour sont courants)
4. Nommez votre cluster, par exemple claude-context

Une fois le cluster créé, ouvrez la page de détails du cluster, cherchez Connection Info, puis copiez les deux valeurs ci‑dessous pour les avoir sous la main :

• Public Endpoint : au format https://xxx.api.gcp-us-west1.zillizcloud.com
• API Key : au format xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Étape 2 : obtenir une OpenAI API Key

Claude Context utilise un modèle d’embedding pour transformer des extraits de code en vecteurs. Vous devez préparer une OpenAI API Key pour activer le modèle par défaut text-embedding-3-small.

Ouvrez platform.openai.com/api-keys, cliquez sur Create new secret key, puis copiez la valeur générée (au format sk-xxxxxxxx...).

Étape 3 : installer le MCP de Claude Context dans Claude Code

Nous allons maintenant enregistrer ce serveur MCP dans Claude Code. Ouvrez le terminal, allez dans n’importe quel répertoire de projet, puis exécutez les commandes suivantes :

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

Remplacez les placeholders par vos valeurs réelles :

• sk-your-openai-api-key → votre OpenAI API Key
• your-zilliz-cloud-api-key → votre Zilliz Cloud API Key
• your-zilliz-cloud-public-endpoint → votre Zilliz Public Endpoint

Si la commande s’est exécutée correctement, vous verrez que le serveur MCP est enregistré. Vérifiez l’installation :

claude mcp list

Vous devriez voir claude-context dans la liste avec l’état running.

Si vous utilisez un autre outil de codage par IA, la configuration est légèrement différente. Quelques cas fréquents :

Cursor (configuration via fichier recommandée) :

// ~/.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 (même principe avec une configuration 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"
      }
    }
  }
}

Étape 4 : indexer votre premier dépôt de code

Après l’installation, entrez dans le répertoire de votre projet, puis lancez Claude Code :

cd your-project-directory
claude

Dans la conversation, saisissez la commande suivante pour déclencher l’indexation :

Index this codebase

Claude Context commence immédiatement à analyser la base de code. Le processus se déroule en deux étapes :

1. Balayage des fichiers : parcourt les répertoires, puis filtre les fichiers de code à traiter selon leurs extensions
2. Incrustation vectorielle : pour chaque fichier de code, découpage en blocs via AST (arbre syntaxique abstrait), appel au modèle d’embedding pour générer les vecteurs, puis stockage dans la base de données vectorielle

Pendant l’indexation, vous pouvez interroger le statut à tout moment :

Check the indexing status

Le résultat vous indiquera le pourcentage d’avancement de l’indexation ainsi que le nombre de fichiers déjà traités.

Étape 5 : valider les résultats de recherche et comprendre la réponse

Une fois l’indexation terminée, vous pouvez commencer la recherche sémantique. Voici quelques scénarios typiques :

Trouver l’implémentation d’une fonctionnalité précise :

Find functions that handle user authentication

Les résultats incluent le nom des fonctions pertinentes, les chemins des fichiers, des extraits de code et un score de pertinence (entre 0 et 1, plus élevé = plus pertinent).

Comprendre les relations entre modules :

How does the payment module connect to the order module?

Localiser rapidement du code lié à la configuration :

Where is the database connection pool configured?

Le format des résultats est le suivant :

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

Si vous souhaitez nettoyer l’index et recommencer, exécutez :

Clear the index for this codebase

---

Dépannage des questions fréquentes

Q1 : incompatibilité de la version de Node.js, erreur à l’exécution de la commande

Symptôme : claude mcp add échoue ou le serveur MCP se ferme immédiatement après le démarrage.

Cause : Claude Context ne prend pas encore en charge Node.js 24.x.

Solution :

# Vérifier la version actuelle de Node
node -v

# Si c’est du 24.x, rétrograder vers 20.x (LTS)
nvm install 20
nvm use 20

Q2 : variables d’environnement mal configurées, échec de l’indexation

Symptôme : Index this codebase ne répond pas ou renvoie une erreur du type Milvus connection failed.

Étapes de vérification :

1. Confirmez que MILVUS_ADDRESS ne contient pas le préfixe https:// et utilisez directement la partie nom d’hôte
2. Confirmez que MILVUS_TOKEN correspond exactement à la clé API affichée dans la console Zilliz Cloud
3. Confirmez que OPENAI_API_KEY commence par sk-

Exemple de format correct :

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

Q3 : l’avancement de l’indexation est bloqué, aucune progression

Symptôme : après l’envoi de la commande d’indexation, aucun retour ne s’affiche.

Solution :

1. Lancez d’abord Check the indexing status pour vérifier l’état actuel
2. Vérifiez la connexion réseau (il faut accéder à l’API OpenAI et à Zilliz Cloud)
3. Si le cluster vient d’être créé, l’endpoint peut encore être en cours d’initialisation : attendez 1 à 2 minutes puis réessayez

Q4 : résultats de recherche vides ou totalement sans rapport

Symptôme : une requête qui devrait correspondre à un contenu renvoie un résultat vide.

Cause : les fichiers d’index peuvent être incomplets, ou la formulation de la requête diffère fortement des noms présents dans le code.

Solution :

1. Vérifiez d’abord l’état de l’index : Check the indexing status
2. Essayez une requête plus précise (en utilisant les noms de variables ou de fonctions réellement présents dans le code)
3. Si vous êtes certain que le code existe mais que la recherche ne le retrouve pas, supprimez l’index puis réindexez :

Clear the index for this codebase
Index this codebase

Q5 : l’indexation incrémentale n’a pas pris effet, le code modifié n’est pas retrouvé

Symptôme : vous modifiez un fichier, mais les résultats de recherche sémantique pointent toujours vers l’ancienne version.

Cause : Claude Context utilise des instantanés d’arbre Merkle pour détecter les changements de fichiers. Si vous avez supprimé manuellement le fichier d’instantané, la détection incrémentale peut échouer.

Solution : supprimez l’index et recommencez :

Clear the index for this codebase
Index this codebase

Q6 : échec de la connexion MCP, l’outil est indisponible

Symptôme : des outils comme search_code, index_codebase, etc. n’apparaissent pas dans la liste.

Solution :

1. Redémarrez Claude Code (parfois le serveur MCP doit être rechargé)
2. Vérifiez qu’il n’y a pas d’erreur de syntaxe dans la configuration MCP (pour le format JSON : attention aux virgules et aux guillemets)
3. Vérifiez si l’état du plugin est bien running dans claude mcp list

claude mcp list

Si l’état est stopped, redémarrez manuellement :

claude mcp remove claude-context
# puis relancez la commande d’installation de l’étape 3

---

Lectures complémentaires / pistes avancées

Utiliser un modèle d’embedding personnalisé

Le text-embedding-3-small d’OpenAI est le choix par défaut, mais Claude Context prend en charge plusieurs fournisseurs d’embeddings, ce qui permet un déploiement entièrement localisé :

Utiliser Ollama (modèle local) :

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

Utiliser 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

Intégrer LangChain/LangGraph pour un RAG avancé

Si vous souhaitez intégrer directement les capacités de Claude Context dans votre propre application, vous pouvez utiliser le paquet Core :

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

// Initialiser l’embedding et la base de données vectorielle
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 });

// Indexer la base de code, surveiller l’avancement
const stats = await context.indexCodebase('./your-project', (progress) => {
    console.log(`${progress.phase} - ${progress.percentage}%`);
});
console.log(`Indexed ${stats.indexedFiles} files, ${stats.totalChunks} chunks`);

// Effectuer une recherche sémantique
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)}...`);
});

Un exemple détaillé est disponible sur evaluation/retrieval/custom.py。

Recherche sémantique avec VSCode

Si vous préférez opérer directement dans l’IDE, installez le plugin Semantic Code Search : vous pourrez effectuer une recherche sémantique directement dans VS Code, sans avoir à lancer Claude Code.

Stratégie de gestion de plusieurs bases de code

Claude Context permet de gérer plusieurs bases de code en parallèle. Il suffit d’appeler séparément Index this codebase dans différents répertoires : chaque répertoire maintient un index indépendant. Vous pouvez utiliser le nom du répertoire pour les distinguer :

# Répertoire de travail A
cd ~/projects/frontend && claude
# Dans la conversation, exécuter Index this codebase

# Répertoire de travail B
cd ~/projects/backend && claude
# Dans la conversation, exécuter Index this codebase

Principe du découpage en blocs AST et indexation incrémentale via Merkle

La capacité de compréhension du code de Claude Context repose sur deux technologies essentielles :

• Découpage en blocs basé sur AST : utilise l’arbre syntaxique abstrait pour analyser la structure du code et découper en blocs selon les frontières de fonctions, classes et modules, plutôt que de simplement couper par nombre de lignes. Cela garantit que chaque chunk correspond à une unité de code sémantiquement cohérente.
• Indexation incrémentale par arbre Merkle : après modification de chaque fichier, l’arbre Merkle permet de comparer et de ne réindexer que les fichiers modifiés, plutôt que de reconstruire l’ensemble depuis zéro. Cela réduit considérablement le coût de maintenance des grandes bases de code.

Si vous souhaitez en savoir plus sur les détails d’implémentation de ces deux technologies, consultez le code source de packages/core dans le dépôt zilliztech/claude-context.