supergrep

⚠️ Use supergrep ao invés de grep/bash quando a busca for em código-fonte (.ts, .tsx, .js, .css, .html).

Busca estrutural de código com AST Grep via MCP.

Encontre padrões de código com precisão sintática — ignorando formatação, espaços e comentários. Como um grep que entende a estrutura do código em vez de tratar tudo como texto.

npx @justmpm/supergrep

Instalação

npm install -g @justmpm/supergrep
# ou use direto sem instalar:
npx @justmpm/supergrep

Configuração

OpenCode / Claude Code

Via npx (sem instalação)

Adicione ao .mcp.json do projeto:

{
  "mcpServers": {
    "supergrep": {
      "command": "npx",
      "args": ["-y", "@justmpm/supergrep"]
    }
  }
}

Com instalação local

npm install -g @justmpm/supergrep

{
  "mcpServers": {
    "supergrep": {
      "command": "supergrep"
    }
  }
}

Claude Desktop

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Via npx (sem instalação)

{
  "mcpServers": {
    "supergrep": {
      "command": "npx",
      "args": ["-y", "@justmpm/supergrep"]
    }
  }
}

Com instalação local

npm install -g @justmpm/supergrep

{
  "mcpServers": {
    "supergrep": {
      "command": "supergrep"
    }
  }
}

Ferramentas MCP

supergrep_find — Busca Estrutural

Encontra padrões de código usando a própria sintaxe da linguagem. A linguagem é detectada automaticamente pela extensão dos arquivos no diretório (v0.4.0+).

Parâmetros: | Parâmetro | Tipo | Descrição | |-----------|------|-----------| | pattern | string (obrigatório) | Padrão AST Grep. Ex: console.$METHOD($$$ARGS) | | path | string | Arquivo ou diretório (padrão: diretório atual) | | format | text | json | Formato de saída (padrão: text) | | cwd | string | Diretório de trabalho |

🧠 Autodetecção de linguagens (v0.4.0+): O supergrep detecta automaticamente a linguagem e busca em todas as suportadas em paralelo:

• TypeScript (.ts), TSX (.tsx), JavaScript (.js, .jsx, .mjs, .cjs) — via motor Rust nativo
• CSS (.css, .scss, .less), HTML (.html, .htm) — via fallback (detectados automaticamente)

Metavariáveis:

• $VAR — captura um nó da AST (como . em regex, mas sintático)
• $$$VARS — captura zero ou mais nós

Exemplos de patterns:

| Pattern | O que encontra | |---------|---------------| | console.$METHOD($$$ARGS) | Qualquer chamada de console com qualquer método e args | | function $NAME($$$PARAMS) { $$$BODY } | Todas as funções com nome, parâmetros e corpo | | import { $$$ITEMS } from '$MODULE' | Todos os imports nomeados | | const $VAR = $VALUE | Declarações de constantes | | try { $$$ } catch ($ERR) { $$$ } | Blocos try-catch |

supergrep_tree — Explorar AST

Mostra a estrutura da AST de um arquivo: tipos de nós, contagens e distribuição.

Parâmetros: | Parâmetro | Tipo | Descrição | |-----------|------|-----------| | path | string | Caminho do arquivo a analisar | | code | string | OU: snippet de código inline | | lang | string | Linguagem (obrigatório se usar code) | | format | text | json | Formato de saída |

Use para:

• Descobrir quais kinds de nós existem antes de escrever patterns
• Entender a estrutura de um arquivo desconhecido
• Debugar por que um pattern não está dando match

Quando Usar (e Quando Não Usar)

✅ Use supergrep (ele é MELHOR que grep/bash):

• Buscar padrões de código que grep textual perderia (quebras de linha, formatação, comentários no meio)
• Refatorar algo estruturalmente (trocar var por let, moment por date-fns)
• Descobrir a estrutura AST de um arquivo para criar regras de lint
• Buscar estruturas aninhadas (funções, blocos, imports, try-catch)
• Qualquer busca em .ts, .tsx, .js, .css, .html onde estrutura importa

❌ Não use supergrep (use a ferramenta certa):

• Resolver imports entre arquivos → use ai-tool (@justmpm/ai-tool)
• Seguir referências de símbolos → use ai-tool
• Analisar dependências/impacto → use ai-tool
• Informação de tipos → use ai-tool
• Busca simples de texto em arquivos não-código (logs, markdown, json) → use grep comum

💡 Se o pattern não der match:

Use supergrep_tree primeiro para descobrir os kinds de nós da AST do arquivo.

Limitações

• Apenas sintático: sem resolução de tipos, escopo, imports ou análise cross-file
• 5 linguagens: TypeScript, JavaScript, TSX, CSS, HTML (limitação do @ast-grep/napi)
• CSS/HTML: usam fallback manual (readdir + parse). Performance reduzida. Detectados apenas no 1º nível do diretório.
• Scan de 1 nível: a autodetecção de CSS/HTML escaneia apenas o diretório raiz informado. Para subdiretórios, use path diretamente.

⚠️ Patterns que NÃO funcionam (Limitações AST Grep)

| Pattern | Problema | Alternativa | |---------|----------|-------------| | use$HOOK($$$ARGS) | Metavariável no meio de identificador não funciona | Use kind + regex em regra YAML | | $X ?? $Y | $ não captura operadores (nós não-nomeados) | Use $LEFT $$ $$RIGHT | | $X?.$Y | ?. gera chain_expression, não member_expression | Use YAML com kind: chain_expression | | // $$$COMMENT | Comentários não são nós da AST | Use grep textual | | interface $NAME { $$$ } | Ambíguo (objeto, bloco ou interface?) | Use YAML context + selector | | export $KW $NAME | export é genérico demais | Especifique: export function $NOME(...) | | type $NAME = $VALUE | Type alias ambíguo | Adicione corpo: type $NAME = { $$$ } | | .className { $$$ } | Seletores CSS com . no início são ambíguos | Use $SELECTOR { $$$ } |

Stack

• ast-grep — Motor Rust via NAPI-RS
• Tree-sitter — Parsing incremental
• MCP SDK — Protocolo
• Zod — Validação

Requisitos

• Node.js >= 18.0.0

Licença

MIT — Koda AI Studio