astra-mcp

Astraは、AIエージェント向けのローカルコードインテリジェンスサービスです。Pythonコードを構造化されたNetworkXグラフと検索可能なローカルコードチャンクインデックスに解析します。同じエンジンは、astra CLIと公式MCP Python SDKの両方から利用できます。

アーキテクチャ

星座マークは、Astraがコードベース全体で発見する関係性を表しています。そのパイプラインには4つの段階があります。Pythonファイルを実行せずに解析し、構造グラフを構築し、コードチャンクをインデックス化し、グラフ展開を伴うセマンティックマッチを取得します。

MCPサーフェスは4つのツールを公開しています: 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

このコマンドは、ネストされたフォルダを再帰的にスキャンしてUTF-8テキストファイルを探しますが、それらをインポートしたり実行したりすることはありません。有効なPythonファイルにはASTレベルの宣言と呼び出し関係が付与され、その他のテキストベースのソース、設定、マークアップ、ドキュメントファイルには検索可能なファイルレベルのチャンクが付与されます。バイナリファイル、2 MBを超えるファイル、および .git、.venv、node_modules、.astra_vectors などの生成物または依存関係ディレクトリはスキップされます。 | ASTおよびテキストパーサー | Pythonの宣言、docstring、シンボル、呼び出しを読み取り、その他のUTF-8テキストファイルをファイルレベルのチャンクとしてインデックス化します。 | コードチャンクと参照 |

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 がターゲットフォルダに書き込まれます。そのファイルをブラウザで開いて、2つのビューを確認します:

• 構造グラフ: .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ホストを設定して astra-mcp を実行してください。サーバーは、そのホストが使用する環境にインストールされている必要があります。

4つのネイティブツールは次のとおりです:

リポジトリには、VS Code MCPクライアント用の .vscode/mcp.json が含まれています。他のホストの場合は、ホストの設定にサーバーを登録します:

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

ホストがシェルからコマンドを見つけられない場合は、絶対実行可能パスを使用してください: Windowsでは .venv\Scripts\astra-mcp.exe、macOS/Linuxでは .venv/bin/astra-mcp。サーバーはstdioを介して通信するため、そのstdoutをリダイレクトしないでください。

開発

pytest
ruff check .

Astraは、インデックス化するファイルをインポートしたり実行したりすることはありません。解析の失敗はスキップされ、結果のカウントを通じてのみ報告されるため、部分的に壊れた作業ツリーでもインデックス化が有用に機能します。