Skip to main content
Glama
deenesjakoruzh
nimelkot

astra-mcp

by nimelkot
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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

架构

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

组件

角色

输出

AST 与文本解析器

读取 Python 声明、docstring、符号名与调用；将其余可读文件索引为文件级块。

代码块与引用

结构图

在模块、声明和调用方之间构建有向 NetworkX 关系。

.astra_graph.json

向量索引

在本地存储可搜索的代码块，并可选用 Sentence Transformers 和 Chroma 加速。

.astra_vectors/

双接口

让同样引擎可被终端用户和 MCP 主机使用。

astra 和 astra-mcp

MCP 接口层提供四个工具：astra_index_repo、astra_search、astra_get_callers 和 astra_hybrid_context。

Related MCP server: codebase-mcp

安装

需要 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；服务器必须安装在该主机所在的环境中。

四个原生工具：

组件

状态

astra_index_repo(path)

为本地仓库建立索引。

astra_semantic_search(path, query, limit)

在已有索引的代码块中搜索。

astra_get_callers(path, symbol, limit)

通过结构图查找调用者。

astra_hybrid_context(path, query, limit, expansion)

将语义匹配与图扩元结合。

astra_visualize(path, output)

生成本地 HTML 图报告，返回文件路径与 URL。

仓库提供 .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.

Available Tools

5 tools
astra_get_callersB

Find exact callers of a function or method using the structural graph.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes
limitNo
targetYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the structural-graph mechanism and implies a read-only lookup, but it does not mention prerequisites such as an indexed repository, whether callers are direct or indirect, limits on traversal, or error behavior. This is too little transparency for an unannotated tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with no filler. 'Exact' and 'structural graph' are meaningful qualifiers, and the core purpose is front-loaded. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even though an output schema exists, this unannotated tool has three undocumented parameters and no usage guidance. The description does not explain how to construct path/target values, whether the repo must be indexed first, or how result limits behave. An agent would need to guess important invocation details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It only hints that 'target' refers to a function or method; it does not explain what 'path' means, how 'limit' applies, or the expected format of 'target'. The description fails to close the parameter documentation gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Find') and names the resource ('exact callers of a function or method') plus the mechanism ('structural graph'). The qualifiers 'exact' and 'structural' help differentiate it from semantic-search siblings, so an agent can tell what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'exact callers' implies a precise, structural query rather than a semantic one, giving some context for when to use it. However, the description never explicitly names alternatives like astra_semantic_search or states when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

astra_hybrid_contextC

Combine semantic matches with structural expansion.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes
limitNo
queryYes
expansionNo

TDQS

C2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full behavioral burden. It does not disclose whether the operation reads or writes, whether it is safe to call repeatedly, or any side effects. The phrase 'Combine semantic matches with structural expansion' is too abstract to convey behavioral implications.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single under-specified fragment rather than a properly sized explanation. It is not well-structured and does not front-load any practical information. While brief, the brevity sacrifices clarity, making it inadequate for an agent selecting the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, no annotations, and a two-line description, the tool is critically incomplete. The agent lacks information on what the tool returns, how to construct the path/query, what limit and expansion control, and any usage constraints. This is insufficient for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema describes four parameters (path, query, limit, expansion) with 0% coverage from the description. The description does not explain any parameter's meaning, acceptable values, or how they interact, forcing the agent to guess from names alone. This is a severe gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a general sense of the tool's role ('Combine semantic matches with structural expansion') but does not state a concrete verb+resource outcome or differentiate from siblings like astra_semantic_search and astra_get_callers. It implies a hybrid behavior but is ambiguous about what it actually produces.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus relying on astra_semantic_search alone or astra_get_callers. No exclusions, prerequisites, or context that would help an agent decide between siblings. The description merely states the concept without any conditions for use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

astra_index_repoC

Index a local Python code directory into Astra's graph and vector store.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the full burden of behavioral disclosure. It only states the action without disclosing whether the operation is destructive, requires permissions, is additive or overwriting, or what the return value or side effects are. This is a significant gap for a mutating tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, direct sentence with zero filler. It is appropriately concise and the primary action is stated immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an indexing operation with no annotations, no output schema, and an undocumented parameter, the description is critically incomplete. It does not explain prerequisites, the effect on an existing index, or the result of the operation. An agent cannot predict what happens on success or failure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides no description for the sole parameter 'path' (0% coverage), and the tool description does not reference it at all. There is no indication of expected format (absolute vs relative, file vs directory), whether it must exist, or what constraints apply. The agent has no way to correctly populate the parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Index') and a specific resource ('local Python code directory'), and it is clearly distinct from the sibling tools which are query/visualization operations. The purpose is unambiguous and immediately understood.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus the alternatives. There is no mention that indexing is a prerequisite for search tools, nor any exclusions or conditions that would help an agent decide to call this instead of astra_semantic_search or astra_visualize.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

astra_visualizeC

Generate a local HTML visualization and return its path and file URL.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes
outputNo

TDQS

C2.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full disclosure burden. It does reveal the key side effect: generating a local HTML file and returning its path/URL. However, it omits whether the file overwrites an existing output, whether it is temporary or persistent, and any resource or environment constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded with the action and clearly states the return value. Every word contributes to understanding, with no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so mentioning the returned path and file URL is useful. However, the required 'path' parameter is unexplained, the optional 'output' parameter is undefined, and there is no context about what should be visualized. A simple tool with two parameters still needs at least minimal input semantics to be invoked correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain the meaning of the required 'path' parameter or the optional 'output' parameter. The phrase 'return its path and file URL' refers to the result, not the input parameters, leaving the agent without enough information to construct a valid invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action and result: 'Generate a local HTML visualization and return its path and file URL.' It is clear about what the tool does. However, it does not differentiate from sibling tools by naming them or contrasting the visualization use case with indexing/searching.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided about when to use this tool versus alternatives such as astra_index_repo or astra_semantic_search. There is no explicit condition, prerequisite, or exclusions. The intended context is only vaguely implied by the tool name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.1.0
    • First observedastra_get_callers
    • First observedastra_hybrid_context
    • First observedastra_index_repo
    • First observedastra_semantic_search
    • First observedastra_visualize
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

B3.2/5.0

Scored across 5 tools

Disambiguation5/5

Each tool has a distinct purpose: indexing a repo, semantic search, exact callers, hybrid context, and visualization. No two tools overlap in functionality; agents can easily select the right one.

Naming Consistency5/5

All tools follow a consistent 'astra_' prefix with verb_noun naming: index_repo, semantic_search, get_callers, hybrid_context, visualize. The pattern is uniform and predictable.

Tool Count5/5

Five tools is an ideal scope for a code indexing and querying server. Each tool serves a core workflow without unnecessary bloat or missing essential operations.

Completeness4/5

The set covers the main lifecycle: indexing, searching, structural queries, combined retrieval, and visualization. Minor gaps exist (e.g., no delete index or update) but they are not critical for the primary use case.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • codebase-mcp

    theunreal
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to semantically search and navigate code repositories using natural language, with support for multiple repos, incremental indexing, and no local install needed.
    -

  • codebase-rag

    Ar-maan05
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables LLM agents to efficiently understand and navigate a codebase by providing semantic search over symbols and a reference graph, replacing expensive grep/glob calls with structured tools like definition lookup, caller/callee queries, and change-impact analysis.
    18 PyPI
    3
    MIT

  • mcp-intelligence-context

    LeoChimal09
    F
    license
    A
    quality
    C
    maintenance
    Provides codebase indexing and retrieval tools that give AI agents token-efficient, query-relevant context packages (symbols, imports, and dependencies) instead of scanning entire repositories.
    6
    -