ast-grep을 사용하여 AI 보조자들에게 강력한 구조 코드 검색 기능을 제공하는 실험적인 모델 컨텍스트 프로토콜(MCP) 서버입니다.

개요

이 MCP 서버는 Cursor, Claude Desktop 등과 같은 AI 비서들이 단순한 텍스트 기반 검색 대신 추상 구문 트리(AST) 패턴 매칭을 통해 코드베이스를 검색 및 분석할 수 있게 합니다. ast-grep의 구조적 검색 기능을 활용함으로써 AI는 다음을 할 수 있습니다:

• 단순히 텍스트 매칭이 아닌 문법 구조에 기반한 코드 패턴 찾기
• 특정 프로그래밍 구성(함수, 클래스, 가져오기 등) 검색
• YAML 구성을 사용하여 복잡한 탐색 규칙을 작성하고 테스트합니다
• 더 나은 패턴 개발을 위한 AST 구조의 디버깅 및 시각화

선수 조건

1. ast-grep 설치: ast-grep 설치 가이드를 따르세요

2. uv 설치: Python 패키지 관리자

3. MCP 호환 클라이언트: 예를 들어 커서, 클로드 데스크톱 또는 기타 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:

{