update

Author: HerringtonDarkholme

README.md

@@ -1,25 +1,193 @@
-# ast-grep MCP
+# ast-grep MCP Server
 
-This is an experimental MCP implementation using [ast-grep](https://ast-grep.github.io/) CLI.
+An experimental [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides AI assistants with powerful structural code search capabilities using [ast-grep](https://ast-grep.github.io/).
 
+## Overview
 
-## Prerequisite
+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:
 
-1. Installing `ast-grep` and `uv`
-2. Installing MCP client, preferably Cursor
-3. Clone this repo, install via `uv`
-3. Configure MCP json
+- 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](https://ast-grep.github.io/guide/quick-start.html#installation)
+   ```bash
+   # macOS
+   brew install ast-grep
+   nix-shell -p ast-grep
+   cargo install ast-grep --locked
+   ```
+
+2. **Install uv**: Python package manager
+   ```bash
+   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:
+   ```bash
+   git clone https://github.com/ast-grep/ast-grep-mcp.git
+   cd ast-grep-mcp
+   ```
+
+2. Install dependencies:
+   ```bash
+   uv sync
+   ```
+
+3. Verify ast-grep installation:
+   ```bash
+   ast-grep --version
+   ```
+## Configuration
+
+### For Cursor
+
+Add to your MCP settings (usually in `.cursor-mcp/settings.json`):
 
 ```json
 {
-    "mcpServers": {
-      "server-name": {
-        "command": "uv",
-        "args": ["--directory", "/path/to/repo", "run", "main.py"],
-        "env": {}
-      }
+  "mcpServers": {
+    "ast-grep": {
+      "command": "uv",
+      "args": ["--directory", "/absolute/path/to/ast-grep-mcp", "run", "main.py"],
+      "env": {}
     }
   }
+}
 ```
 
-4. Ask cursor ai to search your codebase!
+### For Claude Desktop
+
+Add to your Claude Desktop MCP configuration:
+
+```json
+{
+  "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](https://github.com/ast-grep/ast-grep-mcp/blob/main/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:
+
+```yaml
+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:
+
+```yaml
+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](https://ast-grep.github.io/) - The core structural search tool
+- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol this server implements
+- [FastMCP](https://github.com/pydantic/fastmcp) - The Python MCP framework used