Model Context Protocol (MCP) server for ast-grep - structural code search and transformation
This MCP server implements 21 tools for AST-based code search, transformation, and refactoring. Strengths: all tools have clear verb-noun names starting with action verbs (search, file_search, replace, etc.); descriptions are well-written (averaging 150-200 chars, within the 10-1024 char ideal range); input schemas are properly defined with JSON Schema typing, enums for constrained inputs, and descriptions for all parameters. Weaknesses: output schemas are not documented in the visible source (no indication of response structure); error handling lacks recovery guidance and actionable error messages; some tools (refactor, analyze_refactoring, extract_function) have vague parameter descriptions ('Additional parameters specific to the refactoring type' is too generic); tool composition could be tighter (analyze_refactoring and validate_refactoring both validate but differ in purpose, creating potential confusion); file-based tools (file_search, file_replace, rule_search, rule_replace) lack pagination cursor initialization guidance in descriptions. The server demonstrates solid fundamentals but misses the high-confidence patterns expected of production-grade tools.
Analyze a code fragment for refactoring potential, particularly extract function opportunities. Returns structured suggestions for safe extraction.
Create and save a new ast-grep rule for reuse. Stores the rule in the configured rules directory. Rules can be referenced by ID in other operations.
Delete a saved rule by its ID from the rules directory.
Explore and learn AST pattern syntax interactively. Takes code and language, returns pattern suggestions and examples.
Extract a code fragment into a new function. Automatically determines parameters and return values. Modifies code to call the new function.
Replace AST patterns in multiple files using glob patterns. Use summary_only=true for bulk refactoring (returns counts instead of full diffs). Supports dry_run for preview. Essential for large-scale codebase modifications.
Output schemas not documented. Tool responses are returned as JSON via rmcp Content::json() but response structure/field types are not defined in tool schemas or descriptions. LLMs cannot predict output fields for chaining or field extraction. This violates pattern:tool (Document the output schema) and pattern:paginated-result (pagination metadata unclear).
Vague parameter descriptions in refactoring tools. The 'refactor' tool documents params as 'Additional parameters specific to the refactoring type', too generic to guide LLM selection. The 'target' param lacks clarity (is it a variable name, line range, or AST node selector?). The 'params' object is untyped and undocumented (what keys does it accept?). This violates pattern:tool-description (Every input parameter needs a description explaining what it controls).
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 58 | <=2025-11-25 | v2 |
| 2026-03-09 | F | 46 | - | v1 |
Search files for AST patterns using glob patterns. Use path_pattern like '**/*.js' or 'src/**/*.{ts,tsx}'. Supports pagination with cursor for large codebases. Returns matches grouped by file with context lines.
Generate the Abstract Syntax Tree (AST) for code in a given language. Useful for understanding code structure and developing accurate patterns. Returns the complete AST in a readable format.
Get detailed information about a specific refactoring operation, including parameters and constraints.
Retrieve the full configuration of a saved rule by its ID.
Get all supported programming languages for AST pattern matching. Returns 20+ languages including javascript, typescript, python, rust, java, go, cpp, csharp, etc. Use these exact language names in other tools.
List all available refactoring operations and their descriptions.
List all saved ast-grep rules in the configured rules directory. Shows rule IDs and metadata.
Perform general refactoring operations on code. Supports multiple refactoring patterns like rename, inline, extract, etc.
Replace AST patterns in code strings. Use $VAR in both pattern and replacement to preserve captured nodes. Example: pattern 'console.log($MSG)', replacement 'console.warn($MSG)'. Returns the modified code with changes applied.
Replace code using ast-grep YAML rule configurations with fix patterns. Rules support complex patterns with conditions, constraints, and relational matching. Use for advanced replacements and refactoring.
Search using ast-grep YAML rule configurations. Rules support complex patterns with conditions, constraints, and relational matching. More powerful than simple patterns - use for advanced searches requiring logical conditions or multiple pattern combinations.
Search for AST patterns in code strings. Use $VAR to capture single nodes, $$$ for multiple nodes (lists). Example patterns: 'console.log($MSG)', 'function $NAME($PARAMS) { $$$ }'. Returns matches with precise line/column positions and captured variables.
Validate an AST pattern syntax without executing a search. Checks if the pattern is well-formed and compatible with the specified language.
Validate a refactoring operation before applying it. Checks for safety issues, scope conflicts, and correctness.
Validate ast-grep YAML rule configurations against test code. Checks syntax validity and tests the rule against provided code to ensure it matches as expected.
No error recovery guidance. Error handling in tool_router.rs (lines 57 - 73) returns ErrorData with messages but lacks actionable recovery steps. E.g., when 'search' receives path_pattern incorrectly, it suggests 'use file_search', but when 'file_search' fails to find files, no alternative is offered. Violates pattern:recovery-guide (Error responses must tell the LLM what to do next).
Pagination cursor structure underdocumented. file_search, file_replace, rule_search, rule_replace accept cursor objects with last_file_path and is_complete, but descriptions do not explain how to initialize the cursor for a first request (null? empty object?), or how to iterate (is is_complete=true final?). Forces LLM guessing. Violates pattern:paginated-result (pagination parameters and return a total count or next_cursor).
Semantic overlap between analyze_refactoring and validate_refactoring. Both accept code/language/refactoring_type/target/params and both describe validation logic, but analyze_refactoring claims to return 'suggestions for safe extraction' while validate_refactoring 'checks for safety issues'. Unclear when to use which. Violates pattern:tool (Each tool should do exactly one thing).
No confirmation or dry-run for destructive tools. file_replace and rule_replace have dry_run=true by default (safe), but delete_rule lacks any safety mechanism. A single delete_rule call with the wrong rule_id is irreversible. Violates pattern:confirmation-request (Irreversible operations should support a dry-run or confirmation step).
Missing response field chaining documentation. If a tool returns matches, the response structure (line numbers, matched text, captured variables) is not documented, so LLMs cannot extract fields for downstream steps (e.g., passing matched line numbers to extract_function). Violates pattern:tool-chain (Ensure tool A's output contains the IDs and references tool B needs).
Tool result limits not consistently enforced. file_search and rule_search default max_results=20, but max_file_size accepts unbounded values up to 1GB (1073741824 bytes). A 1GB file can cause performance issues. Violates mxe:enforce-result-limits (cap results at a reasonable limit and state the limit in the description).