refactor-mcp

Refatore código usando busca e substituição baseada em regex.

GitHub
7

Documentação

refactor-mcp

Um servidor Model Context Protocol (MCP) que fornece ferramentas poderosas de refatoração para Agentes de Codificação. Ele pode ser executado em dois modos:

  • Modo Servidor MCP (padrão): Integra-se com clientes compatíveis com MCP, como Claude Code
  • Modo CLI: Uso direto via linha de comando para tarefas de refatoração autônomas

Recursos

Este servidor MCP implementa duas ferramentas principais para auxiliar na refatoração de código:

🔧 code_refactor

Realiza operações de busca e substituição baseadas em regex em arquivos, com recursos avançados de filtragem.

Parâmetros:

  • search_pattern (string) - Padrão de expressão regular para busca
  • replace_pattern (string) - Padrão de substituição (suporta grupos de captura como $1, $2)
  • context_pattern (string, opcional) - Substituir apenas correspondências dentro deste contexto
  • file_pattern (string, opcional) - Padrão glob para limitar arquivos (ex.: *.js, src/**/*.ts)

Exemplo:

// Replace foo() calls with bar() calls
code_refactor("foo\\((.+)\\)", "bar($1)")

// Before: let k = foo(1,2,3);
// After:  let k = bar(1,2,3);

Refatoração com consciência de contexto:

// Only replace "legacy_sdk" within import statements
code_refactor("legacy_sdk", "brand_new_sdk", "import")

🔍 code_search

Busca padrões de regex e retorna localizações de arquivos com números de linha precisos.

Parâmetros:

  • search_pattern (string) - Padrão de expressão regular para busca
  • context_pattern (string, opcional) - Filtrar correspondências pelo contexto ao redor
  • file_pattern (string, opcional) - Padrão glob para limitar o escopo da busca

Exemplo:

code_search("foo\\(.+\\)")

// Result:
// ./src/utils.js (line: 15)
// ./src/helpers.ts (lines: 23-27)

Instalação

Início Rápido

Modo Servidor MCP (para Claude Code e outros clientes MCP):

# Install globally for MCP integration
npm install -g @myuon/refactor-mcp

# Or use with npx (recommended for MCP clients)
npx @myuon/refactor-mcp@latest

Modo CLI (para uso direto via linha de comando):

# Search for patterns
npx @myuon/refactor-mcp@latest cli search -p "function.*\(" -f "src/**/*.js"

# Refactor with preview
npx @myuon/refactor-mcp@latest cli refactor -s "const (\w+)" -r "let \$1" --dry-run

Para Desenvolvimento

# Clone and install dependencies
git clone https://github.com/myuon/refactor-mcp.git
cd refactor-mcp
npm install

Uso

Modo CLI

Você pode usar as ferramentas de refatoração diretamente da linha de comando adicionando cli após o comando principal:

# Search for patterns
refactor-mcp cli search -p "function (.*) \{" -f "src/**/*.ts"

# Search with matched content display
refactor-mcp cli search -p "function (.*) \{" -f "src/**/*.ts" --print

# Refactor with dry-run (preview changes)
refactor-mcp cli refactor -s "const (\w+) = " -r "let \$1 = " --dry-run

# Refactor with matched content display
refactor-mcp cli refactor -s "const (\w+) = " -r "let \$1 = " --print --dry-run

# Refactor with file pattern
refactor-mcp cli refactor -s "old_function" -r "new_function" -f "src/**/*.js"

# Context-aware refactoring
refactor-mcp cli refactor -s "legacy_sdk" -r "new_sdk" -c "import" -f "src/**/*.ts"

Comandos CLI:

  • search - Buscar padrões de código
    • -p, --pattern <pattern> - Padrão de expressão regular para busca
    • -c, --context <context> - Padrão de contexto opcional para filtrar correspondências
    • -f, --files <files> - Padrão glob de arquivos opcional para limitar o escopo da busca
    • --print - Imprimir conteúdo correspondente na saída padrão
    • --matched - Mostrar apenas o texto correspondente com grupos de captura
  • refactor - Refatorar código com substituição por regex
    • -s, --search <search> - Padrão de expressão regular para busca
    • -r, --replace <replace> - Padrão de substituição (suporta $1, $2, etc.)
    • -c, --context <context> - Padrão de contexto opcional para filtrar correspondências
    • -f, --files <files> - Padrão glob de arquivos opcional para limitar o escopo da busca
    • --dry-run - Visualizar alterações sem modificar arquivos
    • --print - Imprimir conteúdo correspondente e substituições na saída padrão

Notas Importantes:

  • Ao usar grupos de captura em padrões de substituição na linha de comando, escape o cifrão: \$1, \$2, etc.
  • Exemplo: refactor-mcp cli refactor -s "const (\w+) = " -r "let \$1 = " --dry-run
  • Isso evita que o shell interprete $1 como uma variável de shell

Modo Servidor MCP (Padrão)

Por padrão, refactor-mcp é executado como um servidor MCP via transporte stdio:

# Run as MCP server (default mode)
refactor-mcp

# Or explicitly with npx
npx @myuon/refactor-mcp@latest

Desenvolvimento

npm run dev          # Run server in development mode
npm run dev:cli      # Run CLI in development mode with arguments
npm run cli          # Run CLI directly (for testing)
npm run build        # Build for production
npm start            # Run built server (MCP mode)

Qualidade de Código

npm run check        # Run all quality checks
npm run lint         # Run ESLint
npm run format       # Format code with Prettier
npm test             # Run tests

Integração MCP

Este servidor usa o Model Context Protocol para se comunicar com clientes compatíveis. Ele é executado via transporte stdio e pode ser integrado em qualquer ambiente compatível com MCP.

Integração com Claude Code

Para usuários do Claude Code, você pode adicionar facilmente este servidor MCP com:

claude mcp add refactor npx @myuon/refactor-mcp@latest

Configuração Manual

Adicione à configuração do seu cliente MCP:

{
  "mcpServers": {
    "refactor-mcp": {
      "command": "npx",
      "args": ["@myuon/refactor-mcp@latest"]
    }
  }
}

Configuração Alternativa (Instalação Local)

{
  "mcpServers": {
    "refactor-mcp": {
      "command": "refactor-mcp"
    }
  }
}

Arquitetura

  • Framework: Model Context Protocol SDK para TypeScript
  • Runtime: Node.js com módulos ES
  • Validação: Esquemas Zod para validação de entrada com segurança de tipos
  • Operações de Arquivo: Módulo fs nativo com correspondência de padrões glob
  • Testes: Vitest com cobertura abrangente de testes

Contribuindo

  1. Instale as dependências: npm install
  2. Execute os testes: npm test
  3. Verifique a qualidade do código: npm run check
  4. Compile: npm run build

Licença

MIT