convez.ai
MCP ServerAutomaçãoAvançado
ThinkDonk

ast-grep MCP Server

ThinkDonk/ast-grep-mcp

Busca e refatore código via padrões AST, não regex

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que integra ast-grep para buscas e substituições de código baseadas em AST (Abstract Syntax Tree) em 26 linguagens. Otimizado para IA com proteção contra path traversal, sandboxing de workspace e modo dry-run seguro para refatorações.

Instalação

$npx convez-ai ThinkDonk/ast-grep-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
v0.1.2
Issues abertas
0
Contribuidores
1

Casos de uso

  • Refatoração de código em larga escala mantendo semântica
  • Busca de padrões de código específicos em múltiplos arquivos
  • Migração de APIs ou mudanças de nomenclatura estruturais

Veredito

Ferramenta de nível production para automação de refatoração. Excelente integração com Claude via MCP, segurança robusta (sandboxing, dry-run), mas requer compreensão de padrões AST. Ideal para equipes que trabalham com grandes codebases.

README

A tradução para o português deste README ainda está na fila.

ast-grep-mcp

CI npm version License: MIT

中文文档

Standalone MCP server wrapping ast-grep for AI-optimized AST code search and replace across 26 languages.

Extracted from oh-my-opencode.

Features

  • AI-optimized tool descriptions: Explicitly warns LLMs that ast-grep is NOT regex
  • Pattern hints on empty results: Detects regex misuse and language-specific mistakes (Python, JS/TS/TSX, Go, Rust, C#)
  • Workspace sandboxing: Prevents path traversal, argument injection, and null byte injection
  • Output truncation: 500 match / 1 MB / 5 min caps with JSON repair on truncated output
  • Safe replace: Dry-run by default, two-pass write (search preview then --update-all)
  • Bun/Node compatibility: Spawn shim handles both runtimes

Installation

npm install
npm run build

Usage

As MCP Server (stdio)

node dist/cli.js

Configure in OpenCode

Add to your opencode.json:

{
  "mcp": {
    "ast-grep": {
      "type": "local",
      "command": ["node", "path/to/ast-grep-mcp/dist/cli.js"],
      "enabled": true
    }
  }
}

No AST_GREP_WORKSPACE needed — it defaults to the current working directory (i.e., whichever project you open in OpenCode).

Environment Variables

VariableDefaultDescription
AST_GREP_WORKSPACEprocess.cwd()Override workspace directory for all path operations
AST_GREP_DISABLED_TOOLS(none)Comma-separated list of tools to disable (e.g. search or replace)

Tools

search

Search code by AST structure. Parameters:

  • pattern (required): AST pattern using $VAR and $$$ wildcards
  • lang (required): Target language
  • paths (optional): Paths to search
  • globs (optional): Include/exclude globs
  • context (optional): Context lines around matches

Empty results automatically trigger pattern-hint diagnostics (regex misuse / language-specific mistakes).

replace

Rewrite code by AST pattern. Dry-run by default. Parameters:

  • pattern (required): AST pattern to match
  • rewrite (required): Replacement pattern
  • lang (required): Target language
  • paths (optional): Paths to search
  • globs (optional): Include/exclude globs
  • dryRun (optional): Preview without applying (default: true)

Supported Languages

bash, c, cpp, csharp, css, elixir, go, haskell, hcl, html, java, javascript, json, kotlin, lua, nix, php, python, ruby, rust, scala, solidity, swift, typescript, tsx, yaml

Architecture

  • MCP protocol: From-scratch JSON-RPC 2.0 implementation (no SDK dependency). Handles initialize, tools/list, tools/call, ping.
  • Two-pass replace: First pass runs search+preview, second pass runs --update-all for actual file writes.
  • Workspace sandbox: All paths resolved via realpath, must stay inside workspace. Three-layer protection: path traversal (../), argument injection (leading -), null byte injection (\0).
  • Output truncation: Matches capped at 500, output at 1 MB, timeout at 5 min. Truncated JSON gets repaired by finding last valid }, boundary.
  • sg binary detection: Three-level probe: @ast-grep/cli npm package → platform-specific package → Homebrew.
  • Bun/Node compat: bun-spawn-shim.ts detects runtime and provides unified ReadableStream interface.

Known Issues

  • No integration tests: Unit tests cover MCP handler and pattern hints, but no end-to-end test with actual sg binary execution.
  • process-output-timeout.ts uses Response API: Requires Node 18+. Node 16 is EOL and not supported.
  • .gitignore pattern overlap: *.d.ts and *.js.map exclusions apply globally including src/, but this is intentional — only dist/ should contain emitted files.

Development

npm install
npm run typecheck   # tsc --noEmit
npm run build       # esbuild bundle to dist/cli.js
npm test            # vitest run
npm run start       # node dist/cli.js

License

MIT

Ver o original no GitHub

Bom para

Relacionados