astra-mcp

Astra is a local code intelligence service for AI agents. It parses repository files into a structural NetworkX graph and a searchable local code-chunk index, with AST-level enrichment for valid Python files. The same engine is available through the astra CLI and the official MCP Python SDK.

Architecture

The constellation mark represents the relationships Astra discovers across a codebase. Its pipeline has four stages: discover files without executing them, build the structural graph, index code chunks, and retrieve semantic matches with graph expansion.

The MCP surface exposes four tools: astra_index_repo, astra_semantic_search, astra_get_callers, and astra_hybrid_context.

Related MCP server: Axon

Install

Python 3.10+ is required. Choose one of these installation paths.

Install directly from GitHub

This is the simplest option for using Astra. It installs the astra and astra-mcp commands without placing a checkout in your current folder:

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

For an isolated command-line installation, use pipx:

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

Clone for development

Use this option when you want to edit Astra or run its tests. Run the editable install from the cloned repository root, the directory containing 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]"

If Get-ChildItem pyproject.toml cannot find the file, you are not in the Astra repository root yet. The folder you want to analyze can be anywhere; it does not need to be inside the Astra checkout.

Quick start

Index a project first. Replace the example path with the folder you want Astra to analyze:

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

The command recursively scans nested folders for files without importing or executing them. Valid Python files receive AST-level declarations and call relationships; other readable source, configuration, markup, and documentation files receive searchable file-level chunks. Binary files, unsupported encodings, files larger than 2 MB, and generated or dependency directories such as .git, .venv, node_modules, and .astra_vectors are skipped.

For a complete support matrix, see docs/supported-file-types.md.

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

Run astra index again after the source code changes. Indexing replaces the previous graph and chunk index for that target directory.

CLI

Semantic search

Search by a concept, behavior, symbol name, or docstring text:

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

The result table shows the match score, declaration kind, file path, symbol, and source lines. Search results are empty when no indexed chunk shares terms with the query.

Structural callers

Find functions that call a target function:

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

The callers query uses the saved AST graph and reports matching caller nodes as JSON. The current CLI structural query type is callers.

Search behavior

The default index is deterministic and works offline using local lexical matching. To enable Sentence Transformers and Chroma vector retrieval, set this before indexing and searching:

$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

The first embedding-enabled run may download the all-MiniLM-L6-v2 model. If model access or the vector store is unavailable, Astra falls back to the local search implementation.

Visualize an index

After indexing, generate a local HTML report for the target folder:

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

This writes .astra_visualization.html into the target folder. Open that file in a browser to inspect two views:

• Structural graph: interactive modules, classes, functions, methods, and definition/call edges from .astra_graph.json.

• Vector chunks: searchable file and symbol cards from .astra_vectors/chunks.json, with expandable source previews.

You can choose a different output path:

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

The report uses the Vis Network browser library from its CDN for the structural canvas. The vector view and generated data remain local; an internet connection is only needed to load the interactive graph library when opening the report.

Visualization examples

The structural graph view renders connected modules, declarations, and relationships across the indexed project:

The vector chunks view provides searchable cards with file paths, symbols, line ranges, and expandable source previews:

MCP

Astra also exposes its engine as an official MCP server over stdio. Configure your MCP host to run astra-mcp; the server must be installed in the environment used by that host.

The four native tools are:

The repository includes .vscode/mcp.json for VS Code MCP clients. For other hosts, register the server in the host's configuration:

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

If the host cannot find commands from your shell, use the absolute executable path: .venv\Scripts\astra-mcp.exe on Windows or .venv/bin/astra-mcp on macOS/Linux. The server communicates over stdio, so do not redirect its stdout.

Development

pytest
ruff check .

Astra never imports or executes files it indexes. Parsing failures are skipped and reported only through the resulting counts, which keeps indexing useful for partially broken working trees.