Ast Grep

ast-grep MCP サーバー

ast-grep を使用した強力な構造的コード検索機能を AI アシスタントに提供する、実験的な Model Context Protocol (MCP) サーバーです。

概要

この MCP サーバーを使うと、AI アシスタント（Cursor、Claude Desktop など）が、単純なテキストベースの検索ではなく、抽象構文木（AST）のパターンマッチングを使用してコードベースを検索、分析できます。ast-grep の構造的検索機能を活用することで、AI は次のことができます。

• テキストの一致だけでなく、構文構造に基づいてコードパターンを見つける
• 特定のプログラミング構造（関数、クラス、インポートなど）を検索する
• YAML 設定を使用して複雑な検索ルールを作成、テストする
• AST 構造をデバッグ、可視化し、パターンの開発を改善する

前提条件

1. ast-grep をインストールする：ast-grep のインストールガイドに従います

   # macOS
   brew install ast-grep
   nix-shell -p ast-grep
   cargo install ast-grep --locked
   

2. uv をインストールする：Python パッケージマネージャー

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

3. MCP 対応クライアント：Cursor、Claude Desktop、その他の MCP クライアントなど

インストール

1. このリポジトリをクローンします：

   git clone https://github.com/ast-grep/ast-grep-mcp.git
   cd ast-grep-mcp
   

2. 依存関係をインストールします：

   uv sync
   

3. ast-grep のインストールを確認します：

   ast-grep --version
   

uvx で実行する

uvx を使用すると、GitHub からサーバーを直接実行できます。

uvx --from git+https://github.com/ast-grep/ast-grep-mcp ast-grep-server

リポジトリをクローンせずにサーバーをすぐに試す場合に便利です。

設定

Cursor の場合

MCP 設定（通常は .cursor-mcp/settings.json）に追加します。

{
  "mcpServers": {
    "ast-grep": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ast-grep-mcp", "run", "main.py"],
      "env": {}
    }
  }
}

Claude Desktop の場合

Claude Desktop の MCP 設定に追加します。

{
  "mcpServers": {
    "ast-grep": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ast-grep-mcp", "run", "main.py"],
      "env": {}
    }
  }
}

ast-grep のカスタム設定

MCP サーバーは、ast-grep の動作を設定するために、カスタム sgconfig.yaml ファイルを使用できます。 設定ファイルの形式について詳しくは、ast-grep の設定ドキュメントを参照してください。

設定ファイルは、次の 2 つの方法で指定できます（優先順位順）。

1. コマンドライン引数：--config /path/to/sgconfig.yaml
2. 環境変数：AST_GREP_CONFIG=/path/to/sgconfig.yaml

ast-grep コマンドのカスタマイズ

ast-grep が PATH にない場合や、別のコマンド経由で起動する必要がある場合は、 AST_GREP_PATH を設定します。値には、実行可能ファイルのパスまたはコマンドのプレフィックスを指定できます。

{
  "mcpServers": {
    "ast-grep": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ast-grep-mcp", "run", "main.py"],
      "env": {
        "AST_GREP_PATH": "uv run ast-grep"
      }
    }
  }
}

その他の例：

• AST_GREP_PATH="/custom/path/to/ast-grep"
• AST_GREP_PATH="npx ast-grep"
• AST_GREP_PATH='"/path containing spaces/ast-grep"'

未設定の場合、コマンドのデフォルト値は ast-grep です。

使い方

このリポジトリには、ast-grep.mdc に ast-grep ルールの包括的なドキュメントが含まれています。単純なパターンから複雑な複数条件の検索まで、効果的な ast-grep ルールの作成に関するあらゆる内容を説明しています。

これを cursor のルールまたは Claude.md に追加し、AI エージェントに ast-grep ルールを作成してもらうときに添付できます。

このプロンプトを使うと、LLM に MCP を使用してルールを作成、検証、改善するよう依頼できます。

機能

このサーバーは、コード分析のための 4 つの主要なツールを提供します。

🔍 dump_syntax_tree

コードスニペットの抽象構文木構造を可視化します。効果的な検索パターンの作成方法を理解するうえで役立ちます。

使用例：

• パターンが一致しない理由をデバッグする
• 対象コードの AST 構造を理解する
• ast-grep のパターン構文を学ぶ

🧪 test_match_code_rule

コードベース全体に適用する前に、コードスニペットに対して ast-grep の YAML ルールをテストします。

使用例：

• ルールが想定どおりに動作することを検証する
• ルールの開発を繰り返し行う
• 複雑なマッチングロジックをデバッグする

🎯 find_code

シンプルな ast-grep パターンを使用してコードベースを検索し、わかりやすい構造的マッチングを行います。

パラメーター:

• max_results: 返される完全一致の数を制限します（デフォルト: 無制限）
• output_format: "text"（デフォルト、トークン数が約75%削減）または "json"（完全なメタデータ）から選択します

テキスト出力形式:

Found 2 matches:

path/to/file.py:10-15
def example_function():
    # function body
    return result

path/to/file.py:20-22
def another_function():
    pass

ユースケース:

• 特定のパターンを持つ関数呼び出しを検索する
• 変数宣言を特定する
• シンプルなコード構造を検索する

🚀 find_code_by_rule

高度なマッチング条件を表現できる複雑な YAML ルールを使用した、コードベースの高度な検索です。

パラメーター:

• max_results: 返される完全一致の数を制限します（デフォルト: 無制限）
• output_format: "text"（デフォルト、トークン数が約75%削減）または "json"（完全なメタデータ）から選択します

ユースケース:

• ネストされたコード構造を検索する
• 関係制約（inside、has、precedes、follows）を使用して検索する
• 複雑な複数条件の検索

使用例

基本的なパターン検索

クエリを使用します:

すべての console.log ステートメントを検索する

AI は次のようなルールを生成します:

id: find-console-logs
language: javascript
rule:
  pattern: console.log($$$)

複雑なルールの例

ユーザークエリ:

await を使用する非同期関数を検索する

AI は次のようなルールを生成します:

id: async-with-await
language: javascript
rule:
  all:
    - kind: function_declaration
    - has:
        pattern: async
    - has:
        pattern: await $EXPR
        stopBy: end

対応言語

ast-grep は以下を含む多くのプログラミング言語をサポートしています:

• JavaScript/TypeScript
• Python
• Rust
• Go
• Java
• C/C++
• C#
• その他多数...

組み込みでサポートされている言語の完全なリストについては、ast-grep の言語サポートドキュメントをご覧ください。

sgconfig.yaml 設定ファイルを通じて、カスタム言語のサポートを追加することもできます。詳細については、カスタム言語ガイドをご覧ください。

トラブルシューティング

よくある問題

1. 「Command not found」エラー: ast-grep がインストールされ、PATH に含まれていることを確認してください
2. 一致が見つからない: 関係ルールに stopBy: end を追加してみてください
3. パターンが一致しない: dump_syntax_tree を使用して AST 構造を理解してください
4. 権限エラー: サーバーが対象ディレクトリへの読み取りアクセス権を持っていることを確認してください

コントリビューション

これは実験的なプロジェクトです。Issue やプルリクエストを歓迎します！

関連プロジェクト

• ast-grep - コアとなる構造検索ツール
• Model Context Protocol - このサーバーが実装するプロトコル
• MCP Python SDK - 使用されている Python MCP フレームワーク
• Codemod MCP - AI アシスタントに tree-sitter AST やノードタイプ、ast-grep の手順（YAML および JS ast-grep）、Codemod CLI コマンドなどのツールを提供し、ast-grep ベースの codemod を簡単に構築、公開、実行できるようにします。