ast-grepを用いた強力な構造コード検索機能を提供する実験的なモデルコンテキストプロトコル(MCP)サーバーです。

概要

このMCPサーバーにより、CursorやClaude DesktopなどのAIアシスタントが、単純なテキストベース検索ではなく、抽象構文木(AST)パターンマッチングを用いてコードベースを検索・分析できます。ast-grepの構造検索機能を活用することで、AIは以下を実現できます:

• テキストマッチングだけでなく構文構造に基づくコードパターンを見つける
• 特定のプログラミング構造(関数、クラス、インポートなど)を検索する
• YAML構成を用いた複雑な検索ルールの作成とテスト
• より良いパターン開発のためのAST構造のデバッグと可視化

前提条件

1. ast-grepのインストール:ast-grepのインストールガイドに従う

2. Install uv: Python package manager

3. MCP互換クライアント:例えばCursor、Claude Desktop、その他のMCPクライアント

設置

1. このリポジトリのクローン:

2. 依存関係のインストール:

3. ast-grepのインストール確認:

[[T0]と走る

GitHubからuvxを使ってサーバーを直接実行できます:

これはリポジトリをクローンせずにサーバーを素早く試すのに役立ちます。

ast-grep MCP Server

An experimental Model Context Protocol (MCP) server that provides AI assistants with powerful structural code search capabilities using ast-grep.

Overview

This MCP server enables AI assistants (like Cursor, Claude Desktop, etc.) to search and analyze codebases using Abstract Syntax Tree (AST) pattern matching rather than simple text-based search. By leveraging ast-grep’s structural search capabilities, AI can:

• Find code patterns based on syntax structure, not just text matching
• Search for specific programming constructs (functions, classes, imports, etc.)
• Write and test complex search rules using YAML configuration
• Debug and visualize AST structures for better pattern development

Prerequisites

1. Install ast-grep: Follow ast-grep installation guide

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

2. Install uv: Python package manager

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

3. MCP-compatible client: Such as Cursor, Claude Desktop, or other MCP clients

Installation

1. Clone this repository:

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

2. Install dependencies:

   uv sync
   

3. Verify ast-grep installation:

   ast-grep --version
   

Running with uvx

You can run the server directly from GitHub using uvx:

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

This is useful for quickly trying out the server without cloning the repository.

Configuration

For Cursor

Add to your MCP settings (usually in .cursor-mcp/settings.json):

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

For Claude Desktop

Add to your Claude Desktop MCP configuration:

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

Custom ast-grep Configuration

The MCP server supports using a custom sgconfig.yaml file to configure ast-grep behavior. See the ast-grep configuration documentation for details on the config file format.

You can provide the config file in two ways (in order of precedence):

1. Command-line argument: --config /path/to/sgconfig.yaml
2. Environment variable: AST_GREP_CONFIG=/path/to/sgconfig.yaml

Custom ast-grep Command

If ast-grep is not in PATH, or must be launched through another command, set AST_GREP_PATH. The value can be an executable path or a command prefix:

{