ast-grep-mcp

ast-grep-mcp

Servidor MCP que expõe ast-grep (sg) como duas ferramentas para busca estrutural de código.

Pré-requisitos

Instale o sg (CLI do ast-grep):

# via npm
npm i -g @ast-grep/cli

# via cargo
cargo install ast-grep

Verifique: sg --version

Instalação e execução

# from this directory
npm install
node src/index.js        # starts MCP server on stdio
# or via npx after publish:
# npx ast-grep-mcp

Ferramentas

ast_search

Busca estrutural de código usando um padrão do ast-grep.

parâmetro	tipo	obrigatório	descrição
lang	string	sim	Idioma: js, ts, py, go, rust, java, …
pattern	string	sim	Padrão do ast-grep (ex.: console.log($MSG))
dir	string	não	Diretório para busca (padrão: .)

Retorna: array JSON de { file, line, match, snippet }

Exemplo de prompt:

Use ast_search com lang=ts, pattern=console.log($MSG), dir=./src

ast_search_preset

Executa um preset nomeado de code-smell.

parâmetro	tipo	obrigatório	descrição
name	enum	sim	Um dos 5 presets abaixo
dir	string	não	Diretório para busca (padrão: .)

Presets disponíveis:

nome	o que encontra
async-no-catch	expressões await — verifique se há try/catch ausente
hooks-missing-deps	useEffect(..., []) — deps vazias podem ocultar dependências ausentes
route-no-auth	Express app.METHOD(path, handler) — rotas que podem não ter middleware de autenticação
sql-no-param	Strings SQL com template-literal — risco potencial de injeção
promise-no-return	corpos new Promise(...) — verifique se todos os caminhos resolvem/rejeitam

Configuração do Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ast-grep": {
      "command": "node",
      "args": ["/absolute/path/to/ast-grep-mcp/src/index.js"]
    }
  }
}

Cursor mcp.json

.cursor/mcp.json na raiz do seu projeto:

{
  "mcpServers": {
    "ast-grep": {
      "command": "node",
      "args": ["/absolute/path/to/ast-grep-mcp/src/index.js"]
    }
  }
}

Ou se você publicar no npm:

{
  "mcpServers": {
    "ast-grep": {
      "command": "npx",
      "args": ["ast-grep-mcp"]
    }
  }
}

Referência rápida de padrões

$VAR          – single node (any)
$$$NODES      – multiple nodes (spread)
`template $X` – template literal containing X
foo($A, $B)   – function call with two args

Consulte a sintaxe de padrões do ast-grep para a documentação completa.