ast-grep MCP Server

Dump code's syntax structure or dump a query's pattern structure. This is useful to discover correct syntax kind and syntax tree structure. Call it when debugging a rule. The tool requires three arguments: code, language and format. The first two are self-explanatory. format is the output format of the syntax tree. use format=cst to inspect the code's concrete syntax tree structure, useful to debug target code. use format=pattern to inspect how ast-grep interprets a pattern, useful to debug pattern rule.

Internally calls: ast-grep run --pattern --lang --debug-query=

Test a code against an ast-grep YAML rule. This is useful to test a rule before using it in a project.

Internally calls: ast-grep scan --inline-rules --json --stdin

Find code in a project folder that matches the given ast-grep pattern. Pattern is good for simple and single-AST node result. For more complex usage, please use YAML by find_code_by_rule.

Internally calls: ast-grep run --pattern [--json] <project_folder>

Output formats:

• text (default): Compact text format with file:line-range headers and complete match text Example: 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

• json: Full match objects with metadata including ranges, meta-variables, etc.

The max_results parameter limits the number of complete matches returned (not individual lines). When limited, the header shows "Found X matches (showing first Y of Z)".

Example usage: find_code(pattern="class $NAME", max_results=20) # Returns text format find_code(pattern="class $NAME", output_format="json") # Returns JSON with metadata

Find code using ast-grep's YAML rule in a project folder. YAML rule is more powerful than simple pattern and can perform complex search like find AST inside/having another AST. It is a more advanced search tool than the simple find_code.

Tip: When using relational rules (inside/has), add stopBy: end to ensure complete traversal.

Internally calls: ast-grep scan --inline-rules [--json] <project_folder>

Output formats:

• text (default): Compact text format with file:line-range headers and complete match text Example: Found 2 matches:

  src/models.py:45-52 class UserModel: def init(self): self.id = None self.name = None

  src/views.py:12 class SimpleView: pass

• json: Full match objects with metadata including ranges, meta-variables, etc.

The max_results parameter limits the number of complete matches returned (not individual lines). When limited, the header shows "Found X matches (showing first Y of Z)".

Example usage: find_code_by_rule(yaml="id: x\nlanguage: python\nrule: {pattern: 'class $NAME'}", max_results=20) find_code_by_rule(yaml="...", output_format="json") # For full metadata