astra-mcp

Astra ist ein lokaler Code-Intelligence-Dienst für KI-Agenten. Er parst Repository-Dateien in einen strukturellen NetworkX-Graphen und einen durchsuchbaren lokalen Code-Chunk-Index, mit Anreicherung auf AST-Ebene für gültige Python-Dateien. Dieselbe Engine ist über die astra-CLI und das offizielle MCP-Python-SDK verfügbar.

Architektur

Das Sternbild-Markenzeichen repräsentiert die Beziehungen, die Astra in einer Codebasis entdeckt. Seine Pipeline hat vier Phasen: Dateien entdecken, ohne sie auszuführen, den strukturellen Graphen aufbauen, Code-Chunks indizieren und semantische Treffer mit Grapherweiterung abrufen.

Die MCP-Oberfläche stellt vier Tools bereit: astra_index_repo, astra_semantic_search, astra_get_callers und astra_hybrid_context.

Related MCP server: Axon

Installation

Python 3.10+ ist erforderlich. Wählen Sie einen dieser Installationswege.

Direkt von GitHub installieren

Dies ist die einfachste Option für die Nutzung von Astra. Sie installiert die Befehle astra und astra-mcp, ohne einen Checkout in Ihrem aktuellen Ordner zu platzieren:

python -m pip install "git+https://github.com/nimelkot/astra.git"

Für eine isolierte Kommandozeilen-Installation verwenden Sie pipx:

pipx install "git+https://github.com/nimelkot/astra.git"

Für die Entwicklung klonen

Verwenden Sie diese Option, wenn Sie Astra bearbeiten oder seine Tests ausführen möchten. Führen Sie die editierbare Installation aus dem Wurzelverzeichnis des geklonten Repository aus, dem Verzeichnis, das pyproject.toml enthält:

git clone https://github.com/nimelkot/astra.git
cd astra
Get-ChildItem pyproject.toml
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

Wenn Get-ChildItem pyproject.toml die Datei nicht finden kann, befinden Sie sich noch nicht im Wurzelverzeichnis des Astra-Repository. Der Ordner, den Sie analysieren möchten, kann überall liegen; er muss nicht im Astra-Checkout liegen.

Schnellstart

Indizieren Sie zuerst ein Projekt. Ersetzen Sie den Beispielpfad durch den Ordner, den Astra analysieren soll:

astra index C:\Users\YourName\Downloads\my-project

Der Befehl durchsucht rekursiv verschachtelte Ordner nach Dateien, ohne sie zu importieren oder auszuführen. Gültige Python-Dateien erhalten Deklarationen auf AST-Ebene und Aufrufbeziehungen; andere lesbare Quell-, Konfigurations-, Markup- und Dokumentationsdateien erhalten durchsuchbare Datei-Chunks. Binärdateien, nicht unterstützte Kodierungen, Dateien größer als 2 MB sowie generierte oder Abhängigkeitsverzeichnisse wie .git, .venv, node_modules und .astra_vectors werden übersprungen.

Eine vollständige Unterstützungsmatrix finden Sie unter docs/supported-file-types.md.

my-project/
├── .astra_graph.json   # structural modules, declarations, and call relationships
└── .astra_vectors/     # local searchable code chunks

Führen Sie astra index erneut aus, nachdem sich der Quellcode geändert hat. Die Indizierung ersetzt den vorherigen Graphen und den Chunk-Index für dieses Zielverzeichnis.

CLI

Semantische Suche

Suchen Sie nach einem Konzept, Verhalten, Symbolnamen oder Docstring-Text:

astra search "authentication token validation" --path C:\Users\YourName\Downloads\my-project --limit 8

Die Ergebnistabelle zeigt den Übereinstimmungswert, die Deklarationsart, den Dateipfad, das Symbol und die Quellzeilen. Die Suchergebnisse sind leer, wenn kein indizierter Chunk Begriffe mit der Abfrage teilt.

Strukturelle Aufrufer

Finden Sie Funktionen, die eine Zielfunktion aufrufen:

astra query callers calculate_total --path C:\Users\YourName\Downloads\my-project

Die callers-Abfrage verwendet den gespeicherten AST-Graphen und meldet passende Aufruferknoten als JSON. Der aktuelle CLI-Strukturabfragetyp ist callers.

Suchverhalten

Der Standardindex ist deterministisch und funktioniert offline mit lokalem lexikalischem Abgleich. Um Sentence Transformers und Chroma-Vektorabruf zu aktivieren, setzen Sie dies vor dem Indizieren und Suchen:

$env:ASTRA_ENABLE_EMBEDDINGS = "1"
astra index C:\Users\YourName\Downloads\my-project
astra search "rate limiting and retries" --path C:\Users\YourName\Downloads\my-project

Der erste Lauf mit aktivierten Embeddings kann das Modell all-MiniLM-L6-v2 herunterladen. Wenn der Modellzugriff oder der Vektorspeicher nicht verfügbar ist, fällt Astra auf die lokale Suchimplementierung zurück.

Ein Index visualisieren

Nach der Indizierung generieren Sie einen lokalen HTML-Bericht für den Zielordner:

astra visualize C:\Users\YourName\Downloads\my-project

Dies schreibt .astra_visualization.html in den Zielordner. Öffnen Sie diese Datei in einem Browser, um zwei Ansichten zu untersuchen:

• Struktureller Graph: interaktive Module, Klassen, Funktionen, Methoden und Definitions-/Aufrufkanten aus .astra_graph.json.

• Vektor-Chunks: durchsuchbare Datei- und Symbolkarten aus .astra_vectors/chunks.json, mit erweiterbaren Quellvorschauen.

Sie können einen anderen Ausgabepfad wählen:

astra visualize C:\Users\YourName\Downloads\my-project --output C:\Users\YourName\Desktop\astra-report.html

Der Bericht verwendet die Vis-Network-Browserbibliothek von ihrem CDN für die strukturelle Leinwand. Die Vektoransicht und die generierten Daten bleiben lokal; eine Internetverbindung ist nur erforderlich, um die interaktive Graphbibliothek beim Öffnen des Berichts zu laden.

Visualisierungsbeispiele

Die strukturelle Graphansicht rendert verbundene Module, Deklarationen und Beziehungen im gesamten indizierten Projekt:

Die Vektor-Chunk-Ansicht bietet durchsuchbare Karten mit Dateipfaden, Symbolen, Zeilenbereichen und erweiterbaren Quellvorschauen:

MCP

Astra stellt seine Engine auch als offiziellen MCP-Server über stdio bereit. Konfigurieren Sie Ihren MCP-Host so, dass er astra-mcp ausführt; der Server muss in der Umgebung installiert sein, die von diesem Host verwendet wird.

Die vier nativen Tools sind:

Das Repository enthält .vscode/mcp.json für VS-Code-MCP-Clients. Für andere Hosts registrieren Sie den Server in der Konfiguration des Hosts:

[mcp_servers.astra]
command = "astra-mcp"
args = []

Wenn der Host keine Befehle aus Ihrer Shell finden kann, verwenden Sie den absoluten ausführbaren Pfad: .venv\Scripts\astra-mcp.exe unter Windows oder .venv/bin/astra-mcp unter macOS/Linux. Der Server kommuniziert über stdio, daher nicht sein stdout umleiten.

Entwicklung

pytest
ruff check .

Astra importiert oder führt niemals Dateien aus, die es indiziert. Parsing-Fehler werden übersprungen und nur über die resultierenden Zählungen gemeldet, was die Indizierung für teilweise defekte Arbeitsbäume nützlich hält.