ast-grep MCP

Un servidor MCP experimental que utiliza la CLI de ast-grep para búsqueda estructural de código, linting y reescritura.

GitHub
470
Prueba este MCPPatrocinado

Documentación

Servidor MCP de ast-grep

Un servidor experimental de Model Context Protocol (MCP) que proporciona a los asistentes de IA potentes capacidades de búsqueda estructural de código utilizando ast-grep.

Resumen

Este servidor MCP permite a los asistentes de IA (como Cursor, Claude Desktop, etc.) buscar y analizar bases de código utilizando coincidencia de patrones basada en Árbol de Sintaxis Abstracta (AST) en lugar de búsqueda simple basada en texto. Al aprovechar las capacidades de búsqueda estructural de ast-grep, la IA puede:

  • Encontrar patrones de código basados en la estructura sintáctica, no solo en la coincidencia de texto
  • Buscar construcciones de programación específicas (funciones, clases, importaciones, etc.)
  • Escribir y probar reglas de búsqueda complejas usando configuración YAML
  • Depurar y visualizar estructuras AST para un mejor desarrollo de patrones

Requisitos previos

  1. Instalar ast-grep: Siga la guía de instalación de ast-grep

    # macOS
brew install ast-grep
nix-shell -p ast-grep
cargo install ast-grep --locked

  2. Instalar uv: Gestor de paquetes de Python

    curl -LsSf https://astral.sh/uv/install.sh | sh

  3. Cliente compatible con MCP: Como Cursor, Claude Desktop u otros clientes MCP

Instalación

  1. Clone este repositorio:

    git clone https://github.com/ast-grep/ast-grep-mcp.git
cd ast-grep-mcp

  2. Instale las dependencias:

    uv sync

  3. Verifique la instalación de ast-grep:

    ast-grep --version

Ejecución con uvx

Puede ejecutar el servidor directamente desde GitHub usando uvx:

uvx --from git+https://github.com/ast-grep/ast-grep-mcp ast-grep-server

Esto es útil para probar rápidamente el servidor sin clonar el repositorio.

Configuración

Para Cursor

Agregue a su configuración de MCP (generalmente en .cursor-mcp/settings.json):

{
  "mcpServers": {
    "ast-grep": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ast-grep-mcp", "run", "main.py"],
      "env": {}
    }
  }
}

Para Claude Desktop

Agregue a su configuración MCP de Claude Desktop:

{
  "mcpServers": {
    "ast-grep": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ast-grep-mcp", "run", "main.py"],
      "env": {}
    }
  }
}

Configuración personalizada de ast-grep

El servidor MCP admite el uso de un archivo sgconfig.yaml personalizado para configurar el comportamiento de ast-grep. Consulte la documentación de configuración de ast-grep para obtener detalles sobre el formato del archivo de configuración.

Puede proporcionar el archivo de configuración de dos maneras (en orden de precedencia):

  1. Argumento de línea de comandos: --config /path/to/sgconfig.yaml
  2. Variable de entorno: AST_GREP_CONFIG=/path/to/sgconfig.yaml

Comando personalizado de ast-grep

Si ast-grep no está en PATH, o debe lanzarse mediante otro comando, configure AST_GREP_PATH. El valor puede ser una ruta de ejecutable o un prefijo de comando:

{
  "mcpServers": {
    "ast-grep": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ast-grep-mcp", "run", "main.py"],
      "env": {
        "AST_GREP_PATH": "uv run ast-grep"
      }
    }
  }
}

Otros ejemplos:

  • AST_GREP_PATH="/custom/path/to/ast-grep"
  • AST_GREP_PATH="npx ast-grep"
  • AST_GREP_PATH='"/path containing spaces/ast-grep"'

Si no se configura, el comando por defecto es ast-grep.

Uso

Este repositorio incluye documentación completa de reglas de ast-grep en ast-grep.mdc. La documentación cubre todos los aspectos para escribir reglas efectivas de ast-grep, desde patrones simples hasta búsquedas complejas de múltiples condiciones.

Puede agregarlo a su regla de cursor o Claude.md, y adjuntarlo cuando necesite que el agente de IA cree una regla de ast-grep para usted.

El prompt pedirá al LLM que use MCP para crear, verificar y mejorar la regla que crea.

Características

El servidor proporciona cuatro herramientas principales para el análisis de código:

🔍 dump_syntax_tree

Visualice la estructura del Árbol de Sintaxis Abstracta de fragmentos de código. Esencial para entender cómo escribir patrones de búsqueda efectivos.

Casos de uso:

  • Depurar por qué un patrón no coincide
  • Entender la estructura AST del código objetivo
  • Aprender la sintaxis de patrones de ast-grep

🧪 test_match_code_rule

Pruebe reglas YAML de ast-grep contra fragmentos de código antes de aplicarlas a bases de código más grandes.

Casos de uso:

  • Validar que las reglas funcionen como se espera
  • Iterar en el desarrollo de reglas
  • Depurar lógica de coincidencia compleja

🎯 find_code

Busque en bases de código usando patrones simples de ast-grep para coincidencias estructurales directas.

Parámetros:

  • max_results: Limite el número de coincidencias completas devueltas (por defecto: ilimitado)
  • output_format: Elija entre "text" (por defecto, ~75% menos tokens) o "json" (metadatos completos)

Formato de salida de texto:

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

Casos de uso:

  • Encontrar llamadas a funciones con patrones específicos
  • Localizar declaraciones de variables
  • Buscar construcciones de código simples

🚀 find_code_by_rule

Búsqueda avanzada en bases de código usando reglas YAML complejas que pueden expresar criterios de coincidencia sofisticados.

Parámetros:

  • max_results: Limite el número de coincidencias completas devueltas (por defecto: ilimitado)
  • output_format: Elija entre "text" (por defecto, ~75% menos tokens) o "json" (metadatos completos)

Casos de uso:

  • Encontrar estructuras de código anidadas
  • Buscar con restricciones relacionales (dentro, tiene, precede, sigue)
  • Búsquedas complejas de múltiples condiciones

Ejemplos de uso

Búsqueda básica de patrones

Consulta de uso:

Encuentra todas las declaraciones console.log

La IA generará reglas como:

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

Ejemplo de regla compleja

Consulta de usuario:

Encuentra funciones asíncronas que usen await

La IA generará reglas como:

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

Lenguajes compatibles

ast-grep admite muchos lenguajes de programación, incluyendo:

  • JavaScript/TypeScript
  • Python
  • Rust
  • Go
  • Java
  • C/C++
  • C#
  • Y muchos más...

Para una lista completa de lenguajes compatibles integrados, consulte la documentación de soporte de lenguajes de ast-grep.

También puede agregar soporte para lenguajes personalizados a través del archivo de configuración sgconfig.yaml. Consulte la guía de lenguajes personalizados para obtener detalles.

Solución de problemas

Problemas comunes

  1. Errores de "Comando no encontrado": Asegúrese de que ast-grep esté instalado y en su PATH
  2. No se encontraron coincidencias: Intente agregar stopBy: end a las reglas relacionales
  3. El patrón no coincide: Use dump_syntax_tree para entender la estructura AST
  4. Errores de permisos: Asegúrese de que el servidor tenga acceso de lectura a los directorios objetivo

Contribuciones

Este es un proyecto experimental. ¡Las issues y pull requests son bienvenidas!

Proyectos relacionados

  • ast-grep - La herramienta central de búsqueda estructural
  • Model Context Protocol - El protocolo que implementa este servidor
  • MCP Python SDK - El framework MCP de Python utilizado
  • Codemod MCP - Proporciona a los asistentes de IA herramientas como tipos de nodos y AST de tree-sitter, instrucciones de ast-grep (YAML y JS ast-grep), y comandos CLI de Codemod para construir, publicar y ejecutar codemods basados en ast-grep fácilmente.

MseeP.ai Security Assessment Badge