astra-mcp

Astra es un servicio de inteligencia de código local para agentes de IA. Analiza los archivos del repositorio en un grafo estructural NetworkX y un índice local de fragmentos de código buscable, con enriquecimiento a nivel de AST para archivos Python válidos. El mismo motor está disponible a través de la CLI astra y el SDK oficial de MCP para Python.

Arquitectura

La marca de la constelación representa las relaciones que Astra descubre en una base de código. Su pipeline tiene cuatro etapas: descubrir archivos sin ejecutarlos, construir el grafo estructural, indexar fragmentos de código y recuperar coincidencias semánticas con expansión de grafo.

La superficie MCP expone cuatro herramientas: astra_index_repo, astra_semantic_search, astra_get_callers y astra_hybrid_context.

Related MCP server: Axon

Instalación

Se requiere Python 3.10+. Elige una de estas rutas de instalación.

Instalar directamente desde GitHub

Esta es la opción más sencilla para usar Astra. Instala los comandos astra y astra-mcp sin colocar un checkout en tu carpeta actual:

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

Para una instalación aislada de línea de comandos, usa pipx:

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

Clonar para desarrollo

Usa esta opción cuando quieras editar Astra o ejecutar sus pruebas. Ejecuta la instalación editable desde la raíz del repositorio clonado, el directorio que contiene pyproject.toml:

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]"

Si Get-ChildItem pyproject.toml no puede encontrar el archivo, aún no estás en la raíz del repositorio de Astra. La carpeta que quieres analizar puede estar en cualquier lugar; no necesita estar dentro del checkout de Astra.

Inicio rápido

Indexa un proyecto primero. Reemplaza la ruta de ejemplo con la carpeta que quieres que Astra analice:

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

El comando escanea recursivamente las carpetas anidadas en busca de archivos sin importarlos ni ejecutarlos. Los archivos Python válidos reciben declaraciones a nivel de AST y relaciones de llamadas; otros archivos de código fuente, configuración, marcado y documentación legibles reciben fragmentos a nivel de archivo buscables. Se omiten los archivos binarios, las codificaciones no compatibles, los archivos de más de 2 MB y los directorios generados o de dependencias como .git, .venv, node_modules y .astra_vectors.

Para una matriz de compatibilidad completa, consulta docs/supported-file-types.md.

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

Ejecuta astra index de nuevo después de que cambie el código fuente. La indexación reemplaza el grafo y el índice de fragmentos anteriores para ese directorio de destino.

CLI

Búsqueda semántica

Busca por concepto, comportamiento, nombre de símbolo o texto de docstring:

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

La tabla de resultados muestra la puntuación de coincidencia, el tipo de declaración, la ruta del archivo, el símbolo y las líneas de origen. Los resultados de búsqueda están vacíos cuando ningún fragmento indexado comparte términos con la consulta.

Llamadores estructurales

Encuentra funciones que llaman a una función objetivo:

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

La consulta callers usa el grafo AST guardado y reporta los nodos de llamadores coincidentes como JSON. El tipo de consulta estructural actual de la CLI es callers.

Comportamiento de búsqueda

El índice predeterminado es determinista y funciona sin conexión mediante coincidencia léxica local. Para habilitar la recuperación vectorial de Sentence Transformers y Chroma, establece esto antes de indexar y buscar:

$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

La primera ejecución con embeddings habilitados puede descargar el modelo all-MiniLM-L6-v2. Si el acceso al modelo o el almacén de vectores no está disponible, Astra recurre a la implementación de búsqueda local.

Visualizar un índice

Después de indexar, genera un informe HTML local para la carpeta de destino:

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

Esto escribe .astra_visualization.html en la carpeta de destino. Abre ese archivo en un navegador para inspeccionar dos vistas:

• Grafo estructural: módulos, clases, funciones, métodos y aristas de definición/llamada interactivos desde .astra_graph.json.

• Fragmentos vectoriales: tarjetas de archivos y símbolos buscables desde .astra_vectors/chunks.json, con vistas previas de código expandibles.

Puedes elegir una ruta de salida diferente:

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

El informe usa la librería de navegador Vis Network desde su CDN para el lienzo estructural. La vista vectorial y los datos generados permanecen locales; solo se necesita conexión a internet para cargar la librería de grafo interactivo al abrir el informe.

Ejemplos de visualización

La vista de grafo estructural renderiza módulos, declaraciones y relaciones conectadas en el proyecto indexado:

La vista de fragmentos vectoriales proporciona tarjetas buscables con rutas de archivo, símbolos, rangos de líneas y vistas previas de código expandibles:

MCP

Astra también expone su motor como un servidor MCP oficial sobre stdio. Configura tu host MCP para ejecutar astra-mcp; el servidor debe estar instalado en el entorno utilizado por ese host.

Las cuatro herramientas nativas son:

El repositorio incluye .vscode/mcp.json para clientes MCP de VS Code. Para otros hosts, registra el servidor en la configuración del host:

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

Si el host no puede encontrar los comandos desde tu shell, usa la ruta absoluta del ejecutable: .venv\Scripts\astra-mcp.exe en Windows o .venv/bin/astra-mcp en macOS/Linux. El servidor se comunica a través de stdio, así que no redirijas su stdout.

Desarrollo

pytest
ruff check .

Astra nunca importa ni ejecuta los archivos que indexa. Los fallos de análisis se omiten y se reportan solo a través de los recuentos resultantes, lo que mantiene la indexación útil para árboles de trabajo parcialmente rotos.