ast-grep-mcp

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
   

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": {}
    }
  }
}

Usage

This repository includes comprehensive ast-grep rule documentation in ast-grep.mdc. The documentation covers all aspects of writing effective ast-grep rules, from simple patterns to complex multi-condition searches.

You can add it to your cursor rule or Claude.md, and attach it when you need AI agent to create ast-grep rule for you.

The prompt will ask LLM to use MCP to create, verify and improve the rule it creates.

Features

The server provides four main tools for code analysis:

🔍 dump_syntax_tree

Visualize the Abstract Syntax Tree structure of code snippets. Essential for understanding how to write effective search patterns.

Use cases:

• Debug why a pattern isn't matching
• Understand the AST structure of target code
• Learn ast-grep pattern syntax

🧪 test_match_code_rule

Test ast-grep YAML rules against code snippets before applying them to larger codebases.

Use cases:

• Validate rules work as expected
• Iterate on rule development
• Debug complex matching logic

🎯 find_code

Search codebases using simple ast-grep patterns for straightforward structural matches.

Use cases:

• Find function calls with specific patterns
• Locate variable declarations
• Search for simple code constructs

🚀 find_code_by_rule

Advanced codebase search using complex YAML rules that can express sophisticated matching criteria.

Use cases:

• Find nested code structures
• Search with relational constraints (inside, has, precedes, follows)
• Complex multi-condition searches

Usage Examples

Basic Pattern Search

Use Query:

Find all console.log statements

AI will generate rules like:

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

Complex Rule Example

User Query:

Find async functions that use await

AI will generate rules like:

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

Supported Languages

ast-grep supports many programming languages including:

• JavaScript/TypeScript
• Python
• Rust
• Go
• Java
• C/C++
• C#
• And many more...

Troubleshooting

Common Issues

1. "Command not found" errors: Ensure ast-grep is installed and in your PATH
2. No matches found: Try adding stopBy: end to relational rules
3. Pattern not matching: Use dump_syntax_tree to understand the AST structure
4. Permission errors: Ensure the server has read access to target directories

Contributing

This is an experimental project. Issues and pull requests are welcome!

Related Projects

• ast-grep - The core structural search tool
• Model Context Protocol - The protocol this server implements
• FastMCP - The Python MCP framework used