astra-mcp

Astra 是一个面向 AI 代理的本地代码智能服务。它将仓库文件解析为结构化的 NetworkX 图和可搜索的本地代码块索引，并为有效的 Python 文件提供 AST 级增强。同样的引擎可以通过 astra CLI 和官方 MCP Python SDK 使用。

架构

星群标记代表 Astra 在代码库中发现的各种关系。其流水线包含四个阶段：在不执行代码的情况下发现文件、构建结构图、索引代码块，以及通过图扩展检索语义匹配。

MCP 接口层提供四个工具：astra_index_repo、astra_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"

如需屏蔽安装覆盖沙installation，请用 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 MB 的文件，以及 .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 还具备通过 stdio 的 MCP 服务器，为做成官方 MCP 服务。请配置你的 MCP 主机来运行 astra-mcp；服务器必须安装在该主机所在的环境中。

四个原生工具：

仓库提供 .vscode/mcp.json 用于 VS Code MCP 客户端。对其他主机，请在 hosts 配置中注册此服务器：

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

如果主机无法在 shell 中找到命令，请使用可执行文件绝对路径：Windows 上为 .venv\Scripts\astra-mcp.exe，macOS/Linux 上为 .venv/en/astra-mcp。服务器通过 stdio 通信，因此不要重定向其 stdout。

开发

pytest
ruff check .

Astra never imports or executes files it indexes. Parsing failures are skipped and reported only through final counts, which keeps indexing usable for partially broken worktrees.