Claude Context-Einführung: Lass KI wirklich dein gesamtes Codebase verstehen

Claude Context ist ein Open-Source-MCP-(Model Context Protocol)-Plugin, das vom Vector-Database-Anbieter Zilliz entwickelt wurde. Seine Kernposition ist sehr klar: KI-Codierungsassistenten mit der semantischen Verständnisfähigkeit für die gesamte Codebase ausstatten.

In einem traditionellen Workflow, wenn du möchtest, dass die KI dir beim Verständnis einer fremden Codebase hilft, musst du Dateien manuell kopieren – also Pfade auswählen, die Projektstruktur beschreiben und die Beziehungen zwischen Modulen erklären. Das wären Aufgaben, die die KI eigentlich selbst erledigen sollte. Claude Context ermöglicht das durch semantische Suche: Die KI kann Funktionen, Klassen und Datentypen direkt in der Codebase abfragen, ohne dass du manuell Kontext injizieren musst.

Dieses Projekt wird auf GitHub gehostet unter zilliztech/claude-context und steht unter der MIT-Lizenz; der gesamte Code ist vollständig Open Source.

---

Schwierigkeit/Dauer/Ertrag

Einsteigerfreundlich | ca. 20 Minuten | Du lernst, wie du mit nur 2 Befehlen jeder Programmierschnittstelle semantisches Verständnis für Millionen Codezeilen gibst – und dabei etwa 40% weniger Token verbrauchst.

---

Zielgruppe

• Entwickler, die täglich KI-Programmierwerkzeuge wie Claude Code, Cursor, Windsurf oder Cline nutzen
• Personen mit grundlegender Kenntnis von RAG (Retrieval-Augmented Generation) und Vektor-Suche, die tiefer einsteigen möchten
• Teams, die Token-Kosten senken und die Antwortgenauigkeit der KI verbessern wollen

---

Zentrale Abhängigkeiten und Umgebung

Systemanforderungen

• Node.js >= 20.0.0 und < 24.0.0
• Betriebssystem: macOS, Windows oder Linux

Service-Abhängigkeiten

• Zilliz Cloud (kostenlose Kontingente reichen für den persönlichen Gebrauch völlig aus): stellt den Vector-Database-Backend bereit
• OpenAI API Key: zum Erzeugen von Vektoren (embeddings) für das Embedding-Modell (du kannst später auch andere Embedding-Anbieter verwenden, die embeddings unterstützen)

---

Vollständiger Projekt-Ordnerbaum

Claude Context ist ein reines npm-Paket. Du musst keine lokale Codebase klonen oder bauen. Nach der Installation verwaltet es seine eigene Speicherstruktur:

~/.claude/
└── plugins/
    └── claude-context/          # MCP-Plugin-Verzeichnis
        └── [Index-Datendatei]   # Inkrementelles Merkle-Tree-Snapshot

Wenn du das Core-Paket direkt in deine Anwendung integrierst, sieht die Struktur so aus:

your-project/
├── node_modules/
│   └── @zilliz/claude-context-core/
├── .env                        # Ablage der API Keys
└── your-codebase/              # Zu indizierender Code

---

Schritt-für-Schritt

Schritt 1: Zilliz Cloud registrieren und Vector-Database-Zugangsdaten erhalten

Claude Contexts Vector-Storage basiert auf Zilliz Cloud (oder selbstgehostetem Milvus). Dafür musst du in dieser Phase ein kostenloses Konto erstellen.

Öffne zilliz.com/cloud und registriere dich mit deiner E-Mail-Adresse oder einem GitHub-Konto. Erstelle nach dem Login in der Konsole einen neuen Serverless Cluster:

1. Klicke Create Cluster
2. Wähle den Serverless-Typ (das kostenlose Kontingent reicht vollkommen aus)
3. Wähle die nächstgelegene Region (AWS us-west-2 oder auch Singapur sind üblich)
4. Benenne deinen Cluster, z. B. claude-context

Sobald der Cluster erstellt ist, öffne die Detailseite des Clusters und finde Connection Info. Kopiere die folgenden beiden Werte für später:

• Public Endpoint: sieht z. B. so aus wie https://xxx.api.gcp-us-west1.zillizcloud.com
• API Key: sieht z. B. so aus wie xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Schritt 2: OpenAI API Key holen

Claude Context nutzt ein Embedding-Modell, um Code-Snippets in Vektoren umzuwandeln. Du musst einen OpenAI API Key bereitstellen, um das Standardmodell text-embedding-3-small zu nutzen.

Öffne platform.openai.com/api-keys, klicke auf Create new secret key und kopiere den generierten Wert (Format sk-xxxxxxxx...).

Schritt 3: Claude Context MCP in Claude Code installieren

Jetzt registrieren wir diesen MCP-Server in Claude Code. Öffne das Terminal, wechsle in ein beliebiges Projektverzeichnis und führe die folgenden Befehle aus:

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

Ersetze die folgenden Platzhalter durch deine echten Werte:

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

Wenn die Ausführung erfolgreich war, siehst du, dass der MCP-Server registriert wurde. Überprüfe die Installation:

claude mcp list

Du solltest claude-context in der Liste sehen und den Status running.

Wenn du ein anderes KI-Coding-Tool verwendest, unterscheidet sich die Konfiguration leicht. Einige gängige Szenarien:

Cursor (empfohlen: Konfiguration über Datei):

// ~/.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 (ebenfalls JSON-Konfiguration):

// ~/.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"
      }
    }
  }
}

Schritt 4: Indiziere deine erste Codebase

Nach der Installation gehst du in das Verzeichnis deines Projekts und startest Claude Code:

cd your-project-directory
claude

Gib in der Unterhaltung den folgenden Befehl ein, um die Indizierung zu starten:

Index this codebase

Claude Context beginnt sofort mit der Analyse der Codebase. Der Prozess läuft in zwei Phasen ab:

1. Datei-Scan: Durchläuft das Verzeichnis und filtert anhand der Dateiendungen aus, welche Code-Dateien verarbeitet werden müssen
2. Vektor-Embeddings: Für jede Code-Datei wird mit AST (Abstract Syntax Tree) in Abschnitte (Chunks) zerlegt; anschließend wird das Embedding-Modell aufgerufen, um Vektoren zu erzeugen und in der Vector-Database zu speichern

Während der Indizierung kannst du jederzeit nach dem Fortschritt fragen:

Check the indexing status

Das Ergebnis teilt dir den aktuellen Fortschritt in Prozent sowie die Anzahl der bereits abgeschlossenen Dateien mit.

Schritt 5: Suchergebnisse prüfen und Rückgaben verstehen

Nach Abschluss der Indizierung kannst du mit der semantischen Suche beginnen. Hier sind ein paar typische Abfragen:

Implementierung einer bestimmten Funktion finden:

Find functions that handle user authentication

Die Ergebnisse enthalten verwandte Funktionsnamen, Dateipfade, Code-Snippets und einen Relevanz-Score (zwischen 0 und 1; je höher, desto passender).

Beziehungen zwischen Modulen verstehen:

How does the payment module connect to the order module?

Konfigurationen schnell lokalisieren:

Where is the database connection pool configured?

Das Rückgabeformat ist wie folgt:

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

Wenn du die Indizierung bereinigen und von vorn beginnen möchtest, führe aus:

Clear the index for this codebase

---

Häufige Probleme beheben

Q1: Node.js-Version inkompatibel, Befehl schlägt fehl

Symptom: claude mcp add wirft einen Fehler oder der MCP-Server beendet sich direkt nach dem Start.

Ursache: Claude Context unterstützt derzeit kein Node.js 24.x.

Lösung:

# Aktuelle Node-Version prüfen
node -v

# Wenn es 24.x ist: auf 20.x (LTS) downgraden
nvm install 20
nvm use 20

Q2: Fehler bei der Umgebungsvariablen-Konfiguration, Indizierung schlägt fehl

Symptom: Index this codebase reagiert nicht oder liefert den Fehler Milvus connection failed.

Prüfschritte:

1. Stelle sicher, dass MILVUS_ADDRESS ohne https://-Präfix gesetzt ist und direkt nur den Hostteil nutzt
2. Prüfe, dass MILVUS_TOKEN exakt mit dem API Key übereinstimmt, der in der Zilliz Cloud-Konsole angezeigt wird
3. Stelle sicher, dass OPENAI_API_KEY mit sk- beginnt

Beispiel für korrektes Format:

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

Q3: Indizierungsfortschritt hängt fest, ohne Fortschritt

Symptom: Nach dem Starten des Indizierungsbefehls erfolgt dauerhaft keine Reaktion.

Lösung:

1. Zuerst Check the indexing status ausführen, um den aktuellen Status zu prüfen
2. Netzwerkverbindung überprüfen (es muss möglich sein, auf die OpenAI API und Zilliz Cloud zuzugreifen)
3. Wenn der Cluster gerade erst erstellt wurde, könnte der Endpoint noch initialisiert werden. Warte 1–2 Minuten und versuche es dann erneut

Q4: Suchergebnisse leer oder völlig unpassend

Symptom: Abfrage, die eigentlich Treffer liefern sollte, gibt keine Ergebnisse zurück.

Ursache: Die Indizierungsdateien könnten unvollständig sein oder die Formulierung der Abfrage weicht deutlich von den Benennungen im Code ab.

Lösung:

1. Zuerst den Index-Status prüfen: Check the indexing status
2. Versuche eine konkretere Abfrage (mit den tatsächlich im Code vorhandenen Variablennamen oder Funktionsnamen)
3. Wenn du sicher bist, dass der Code existiert, aber die Suche ihn nicht findet, lösche den Index und indiziere neu:

Clear the index for this codebase
Index this codebase

Q5: Inkrementelles Indizieren greift nicht, geänderter Code wird nicht gefunden

Symptom: Du hast eine Datei geändert, aber die semantische Suche verweist weiterhin auf die alte Version.

Ursache: Claude Context nutzt Merkle-Tree-Snapshots, um Dateiveränderungen zu erkennen. Wenn du die Snapshot-Dateien manuell gelöscht hast, kann die inkrementelle Erkennung ausfallen.

Lösung: Index bereinigen und von vorn starten:

Clear the index for this codebase
Index this codebase

Q6: MCP-Verbindung fehlgeschlagen, Werkzeug nicht verfügbar

Symptom: In der Werkzeugliste sind search_code, index_codebase und ähnliche Tools nicht sichtbar.

Lösung:

1. Starte Claude Code neu (manchmal muss der MCP-Server neu geladen werden)
2. Stelle sicher, dass deine MCP-Konfiguration keine Syntaxfehler hat (bei JSON auf Kommas und Anführungszeichen achten)
3. Prüfe, ob der Plugin-Status in claude mcp list auf running steht

claude mcp list

Wenn der Status stopped ist, starte manuell neu:

claude mcp remove claude-context
# Danach die Installationsanweisungen aus Schritt 3 erneut ausführen

---

Weiterführende Lektüre / Erweiterte Richtung

Verwendung eines benutzerdefinierten Embedding-Modells

text-embedding-3-small von OpenAI ist die Standardeinstellung, aber Claude Context unterstützt verschiedene Embedding-Anbieter, sodass du eine vollständig lokale Bereitstellung umsetzen kannst:

Mit Ollama (lokales Modell):

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

Mit 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 für erweitertes RAG anbinden

Wenn du die Fähigkeiten von Claude Context direkt in deine eigene Anwendung integrieren möchtest, kannst du das Core-Paket verwenden:

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

// Embedding und Vector Database initialisieren
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 });

// Codebase indizieren und Fortschritt beobachten
const stats = await context.indexCodebase('./your-project', (progress) => {
    console.log(`${progress.phase} - ${progress.percentage}%`);
});
console.log(`Indexed ${stats.indexedFiles} files, ${stats.totalChunks} chunks`);

// Semantische Suche durchführen
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)}...`);
});

Ausführliche Beispiele findest du unter evaluation/retrieval/custom.py。

VSCode: Semantische Suche visualisieren

Wenn du lieber in deiner IDE arbeitest, kannst du das Plugin Semantic Code Search installieren. Damit kannst du in VS Code direkt semantisch suchen, ohne Claude Code starten zu müssen.

Strategie zur Verwaltung mehrerer Codebases

Claude Context kann mehrere Codebases gleichzeitig verwalten. Rufe einfach in unterschiedlichen Verzeichnissen jeweils Index this codebase auf; jedes Verzeichnis verwaltet dann einen eigenen Index. Du kannst den Verzeichnisnamen nutzen, um sie zu unterscheiden:

# Arbeitsverzeichnis A
cd ~/projects/frontend && claude
# In der Unterhaltung Index this codebase ausführen

# Arbeitsverzeichnis B
cd ~/projects/backend && claude
# In der Unterhaltung Index this codebase ausführen

Prinzip der AST-Chunking- und Merkle-Tree-Inkrementalindizierung

Das Codeverständnis von Claude Context basiert auf zwei zentralen Techniken:

• AST-basiertes Chunking: Verwendet Abstract Syntax Trees, um die Code-Struktur zu analysieren. Es wird nach Funktions-, Klassen- und Modulgrenzen gechunk-t und nicht einfach nach Zeilenzahl geschnitten. So wird sichergestellt, dass jedes Chunk eine semantisch vollständige Einheit des Codes ist.
• Merkle-Tree-Inkrementalindizierung: Nach jeder Änderung in einer Datei werden per Merkle-Tree-Vergleich nur die geänderten Dateien erneut indiziert und nicht der gesamte Bestand komplett neu aufgebaut. Dadurch sinken die Wartungskosten für große Codebases drastisch.

Wenn du dich für die Implementierungsdetails dieser beiden Techniken interessierst, sieh dir den Code im Repository zilliztech/claude-context im Verzeichnis packages/core an.