astra-mcp

Astra — это локальный сервис кодовой аналитики для ИИ-агентов. Он разбирает файлы репозитория в структурный граф NetworkX и индексируемый локальный индекс фрагментов кода, с обогащением на уровне AST для корректных Python-файлов. Тот же движок доступен через CLI astra и официальный MCP Python SDK.

Архитектура

Знак созвездия представляет связи, которые Astra обнаруживает в кодовой базе. Его конвейер состоит из четырёх этапов: обнаружение файлов без их выполнения, построение структурного графа, индексация фрагментов кода и получение семантических совпадений с расширением графа.

Поверхность MCP предоставляет четыре инструмента: astra_index_repo, astra_semantic_search, astra_get_callers и astra_hybrid_context.

Related MCP server: Axon

Установка

Требуется Python 3.10+. Выберите один из этих путей установки.

Установка напрямую из GitHub

Это самый простой вариант для использования Astra. Он устанавливает команды astra и astra-mcp без размещения копии в текущей папке:

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

Для изолированной установки из командной строки используйте pipx:

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

Клонирование для разработки

Используйте этот вариант, если хотите редактировать Astra или запускать его тесты. Запустите редактируемую установку из корня клонированного репозитория — каталога, содержащего 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]"

Если Get-ChildItem pyproject.toml не может найти файл, вы ещё не в корне репозитория Astra. Папка, которую вы хотите анализировать, может находиться где угодно; она не обязана быть внутри копии Astra.

Быстрый старт

Сначала проиндексируйте проект. Замените пример пути на папку, которую Astra должна анализировать:

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

Команда рекурсивно сканирует вложенные папки на предмет файлов, не импортируя и не выполняя их. Корректные Python-файлы получают объявления и связи вызовов на уровне AST; другие читаемые исходные, конфигурационные, разметочные и документационные файлы получают искомые фрагменты уровня файлов. Бинарные файлы, неподдерживаемые кодировки, файлы размером более 2 МБ, а также сгенерированные или зависимые каталоги, такие как .git, .venv, node_modules и .astra_vectors, пропускаются.

Полную матрицу поддержки см. в docs/supported-file-types.md.

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

Запустите astra index снова после изменения исходного кода. Индексация заменяет предыдущий граф и индекс фрагментов для этого целевого каталога.

CLI

Семантический поиск

Поиск по концепции, поведению, имени символа или тексту docstring:

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

Таблица результатов показывает оценку совпадения, вид объявления, путь к файлу, символ и строки исходного кода. Результаты поиска пусты, когда ни один индексированный фрагмент не разделяет термины с запросом.

Структурные вызывающие

Найти функции, которые вызывают целевую функцию:

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

Запрос callers использует сохранённый AST-граф и сообщает о совпадающих узлах-вызывающих в формате JSON. Текущий тип структурного запроса CLI — callers.

Поведение поиска

Индекс по умолчанию детерминирован и работает офлайн с использованием локального лексического сопоставления. Чтобы включить Sentence Transformers и векторный поиск Chroma, установите это перед индексацией и поиском:

$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

Первый запуск с включёнными эмбеддингами может загрузить модель all-MiniLM-L6-v2. Если доступ к модели или векторному хранилищу недоступен, Astra возвращается к локальной реализации поиска.

Визуализация индекса

После индексации создайте локальный HTML-отчёт для целевой папки:

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

Это записывает .astra_visualization.html в целевую папку. Откройте этот файл в браузере, чтобы просмотреть два представления:

• Структурный граф: интерактивные модули, классы, функции, методы и рёбра определений/вызовов из .astra_graph.json.

• Векторные фрагменты: искомые карточки файлов и символов из .astra_vectors/chunks.json с раскрывающимися предпросмотрами исходного кода.

Вы можете выбрать другой путь вывода:

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

Отчёт использует библиотеку браузера Vis Network из её CDN для структурного холста. Векторное представление и сгенерированные данные остаются локальными; интернет-соединение требуется только для загрузки интерактивной библиотеки графов при открытии отчёта.

Примеры визуализации

Представление структурного графа отображает связанные модули, объявления и связи по всему индексированному проекту:

Представление векторных фрагментов предоставляет искомые карточки с путями к файлам, символами, диапазонами строк и расширяемыми предпросмотрами исходного кода:

MCP

Astra также предоставляет свой движок как официальный MCP-сервер через stdio. Настройте ваш MCP-хост на запуск astra-mcp; сервер должен быть установлен в среде, используемой этим хостом.

Четыре нативных инструмента:

Репозиторий включает .vscode/mcp.json для MCP-клиентов VS Code. Для других хостов зарегистрируйте сервер в конфигурации хоста:

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

Если хост не может найти команды из вашей оболочки, используйте абсолютный путь к исполняемому файлу: .venv\Scripts\astra-mcp.exe на Windows или .venv/bin/astra-mcp на macOS/Linux. Сервер общается через stdio, поэтому не перенаправляйте его stdout.

Разработка

pytest
ruff check .

Astra никогда не импортирует и не выполняет файлы, которые индексирует. Ошибки разбора пропускаются и сообщаются только через итоговые счётчики, что сохраняет индексацию полезной для частично сломанных рабочих деревьев.