ast-grep MCP

Um servidor MCP experimental que utiliza a CLI do ast-grep para busca estrutural de código, linting e reescrita.

GitHub
470
Experimente este MCPPatrocinado

Documentação

Servidor MCP ast-grep

Um servidor experimental de Model Context Protocol (MCP) que fornece a assistentes de IA poderosas capacidades de busca estrutural de código usando ast-grep.

Visão Geral

Este servidor MCP permite que assistentes de IA (como Cursor, Claude Desktop, etc.) busquem e analisem bases de código usando correspondência de padrões por Árvore Sintática Abstrata (AST) em vez de busca simples baseada em texto. Ao aproveitar as capacidades de busca estrutural do ast-grep, a IA pode:

  • Encontrar padrões de código com base na estrutura sintática, não apenas na correspondência de texto
  • Buscar construções de programação específicas (funções, classes, imports, etc.)
  • Escrever e testar regras de busca complexas usando configuração YAML
  • Depurar e visualizar estruturas AST para melhor desenvolvimento de padrões

Pré-requisitos

  1. Instalar ast-grep: Siga o guia de instalação do ast-grep

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

  2. Instalar uv: Gerenciador de pacotes Python

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

  3. Cliente compatível com MCP: Como Cursor, Claude Desktop ou outros clientes MCP

Instalação

  1. Clone este repositório:

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

  2. Instale as dependências:

    uv sync

  3. Verifique a instalação do ast-grep:

    ast-grep --version

Executando com uvx

Você pode executar o servidor diretamente do GitHub usando uvx:

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

Isso é útil para testar rapidamente o servidor sem clonar o repositório.

Configuração

Para Cursor

Adicione às suas configurações MCP (geralmente em .cursor-mcp/settings.json):

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

Para Claude Desktop

Adicione à sua configuração MCP do Claude Desktop:

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

Configuração personalizada do ast-grep

O servidor MCP suporta o uso de um arquivo sgconfig.yaml personalizado para configurar o comportamento do ast-grep. Consulte a documentação de configuração do ast-grep para detalhes sobre o formato do arquivo de configuração.

Você pode fornecer o arquivo de configuração de duas maneiras (em ordem de precedência):

  1. Argumento de linha de comando: --config /path/to/sgconfig.yaml
  2. Variável de ambiente: AST_GREP_CONFIG=/path/to/sgconfig.yaml

Comando personalizado do ast-grep

Se ast-grep não estiver em PATH, ou precisar ser iniciado por outro comando, defina AST_GREP_PATH. O valor pode ser um caminho de executável ou um prefixo 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"
      }
    }
  }
}

Outros exemplos:

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

Se não definido, o comando padrão é ast-grep.

Uso

Este repositório inclui documentação abrangente de regras ast-grep em ast-grep.mdc. A documentação cobre todos os aspectos da escrita de regras ast-grep eficazes, desde padrões simples até buscas complexas com múltiplas condições.

Você pode adicioná-la à sua regra do cursor ou ao Claude.md, e anexá-la quando precisar que o agente de IA crie regras ast-grep para você.

O prompt solicitará que o LLM use MCP para criar, verificar e melhorar a regra que ele criar.

Recursos

O servidor fornece quatro ferramentas principais para análise de código:

🔍 dump_syntax_tree

Visualize a estrutura da Árvore Sintática Abstrata de trechos de código. Essencial para entender como escrever padrões de busca eficazes.

Casos de uso:

  • Depurar por que um padrão não está correspondendo
  • Entender a estrutura AST do código alvo
  • Aprender a sintaxe de padrões do ast-grep

🧪 test_match_code_rule

Teste regras YAML do ast-grep contra trechos de código antes de aplicá-las a bases de código maiores.

Casos de uso:

  • Validar se as regras funcionam como esperado
  • Iterar no desenvolvimento de regras
  • Depurar lógica de correspondência complexa

🎯 find_code

Busque em bases de código usando padrões simples do ast-grep para correspondências estruturais diretas.

Parâmetros:

  • max_results: Limite o número de correspondências completas retornadas (padrão: ilimitado)
  • output_format: Escolha entre "text" (padrão, ~75% menos tokens) ou "json" (metadados completos)

Formato de Saída 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 chamadas de função com padrões específicos
  • Localizar declarações de variáveis
  • Buscar construções de código simples

🚀 find_code_by_rule

Busca avançada em bases de código usando regras YAML complexas que podem expressar critérios de correspondência sofisticados.

Parâmetros:

  • max_results: Limite o número de correspondências completas retornadas (padrão: ilimitado)
  • output_format: Escolha entre "text" (padrão, ~75% menos tokens) ou "json" (metadados completos)

Casos de uso:

  • Encontrar estruturas de código aninhadas
  • Buscar com restrições relacionais (dentro, tem, precede, segue)
  • Buscas complexas com múltiplas condições

Exemplos de Uso

Busca Básica por Padrão

Use Consulta:

Encontre todas as declarações console.log

A IA gerará regras como:

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

Exemplo de Regra Complexa

Consulta do Usuário:

Encontre funções assíncronas que usam await

A IA gerará regras como:

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

Linguagens Suportadas

O ast-grep suporta muitas linguagens de programação, incluindo:

  • JavaScript/TypeScript
  • Python
  • Rust
  • Go
  • Java
  • C/C++
  • C#
  • E muitas outras...

Para uma lista completa de linguagens suportadas nativamente, consulte a documentação de suporte a linguagens do ast-grep.

Você também pode adicionar suporte para linguagens personalizadas através do arquivo de configuração sgconfig.yaml. Consulte o guia de linguagens personalizadas para detalhes.

Solução de Problemas

Problemas Comuns

  1. Erros de "comando não encontrado": Certifique-se de que o ast-grep está instalado e no seu PATH
  2. Nenhuma correspondência encontrada: Tente adicionar stopBy: end às regras relacionais
  3. Padrão não correspondendo: Use dump_syntax_tree para entender a estrutura AST
  4. Erros de permissão: Certifique-se de que o servidor tem acesso de leitura aos diretórios alvo

Contribuindo

Este é um projeto experimental. Issues e pull requests são bem-vindos!

Projetos Relacionados

  • ast-grep - A ferramenta central de busca estrutural
  • Model Context Protocol - O protocolo que este servidor implementa
  • MCP Python SDK - O framework Python MCP usado
  • Codemod MCP - Fornece a assistentes de IA ferramentas como AST tree-sitter e tipos de nós, instruções ast-grep (YAML e JS ast-grep), e comandos CLI do Codemod para facilmente construir, publicar e executar codemods baseados em ast-grep.

MseeP.ai Security Assessment Badge