refactor-mcp

Refactorizar código usando búsqueda y reemplazo basado en expresiones regulares.

GitHub
7

Documentación

refactor-mcp

Un servidor de Model Context Protocol (MCP) que proporciona potentes herramientas de refactorización para Agentes de Codificación. Puede ejecutarse en dos modos:

  • Modo Servidor MCP (predeterminado): Se integra con clientes compatibles con MCP como Claude Code
  • Modo CLI: Uso directo desde la línea de comandos para tareas de refactorización independientes

Características

Este servidor MCP implementa dos herramientas principales para ayudar con la refactorización de código:

🔧 code_refactor

Realiza operaciones de búsqueda y reemplazo basadas en expresiones regulares en archivos con capacidades avanzadas de filtrado.

Parámetros:

  • search_pattern (cadena) - Patrón de expresión regular para buscar
  • replace_pattern (cadena) - Patrón de reemplazo (admite grupos de captura como $1, $2)
  • context_pattern (cadena, opcional) - Solo reemplazar coincidencias dentro de este contexto
  • file_pattern (cadena, opcional) - Patrón glob para limitar archivos (por ejemplo, *.js, src/**/*.ts)

Ejemplo:

// 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);

Refactorización consciente del contexto:

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

🔍 code_search

Busca patrones de expresiones regulares y devuelve ubicaciones de archivos con números de línea precisos.

Parámetros:

  • search_pattern (cadena) - Patrón de expresión regular para buscar
  • context_pattern (cadena, opcional) - Filtrar coincidencias por contexto circundante
  • file_pattern (cadena, opcional) - Patrón glob para limitar el alcance de la búsqueda

Ejemplo:

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

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

Instalación

Inicio Rápido

Modo Servidor MCP (para Claude Code y otros 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 directo desde la línea de comandos):

# 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 Desarrollo

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

Uso

Modo CLI

Puede usar las herramientas de refactorización directamente desde la línea de comandos agregando cli después del 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 patrones de código
    • -p, --pattern <pattern> - Patrón de expresión regular para buscar
    • -c, --context <context> - Patrón de contexto opcional para filtrar coincidencias
    • -f, --files <files> - Patrón glob de archivos opcional para limitar el alcance de la búsqueda
    • --print - Imprimir contenido coincidente en la salida estándar
    • --matched - Mostrar solo texto coincidente con grupos de captura
  • refactor - Refactorizar código con reemplazo de expresiones regulares
    • -s, --search <search> - Patrón de expresión regular para buscar
    • -r, --replace <replace> - Patrón de reemplazo (admite $1, $2, etc.)
    • -c, --context <context> - Patrón de contexto opcional para filtrar coincidencias
    • -f, --files <files> - Patrón glob de archivos opcional para limitar el alcance de la búsqueda
    • --dry-run - Vista previa de cambios sin modificar archivos
    • --print - Imprimir contenido coincidente y reemplazos en la salida estándar

Notas Importantes:

  • Al usar grupos de captura en patrones de reemplazo en la línea de comandos, escape el signo de dólar: \$1, \$2, etc.
  • Ejemplo: refactor-mcp cli refactor -s "const (\w+) = " -r "let \$1 = " --dry-run
  • Esto evita que el shell interprete $1 como una variable de shell

Modo Servidor MCP (Predeterminado)

Por defecto, refactor-mcp se ejecuta como un servidor MCP mediante transporte stdio:

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

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

Desarrollo

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)

Calidad 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

Integración MCP

Este servidor utiliza el Model Context Protocol para comunicarse con clientes compatibles. Se ejecuta mediante transporte stdio y puede integrarse en cualquier entorno compatible con MCP.

Integración con Claude Code

Para usuarios de Claude Code, puede agregar fácilmente este servidor MCP con:

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

Configuración Manual

Agregue a la configuración de su cliente MCP:

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

Configuración Alternativa (Instalación Local)

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

Arquitectura

  • Framework: SDK de Model Context Protocol para TypeScript
  • Runtime: Node.js con módulos ES
  • Validación: Esquemas Zod para validación de entrada con seguridad de tipos
  • Operaciones de Archivos: Módulo fs nativo con coincidencia de patrones glob
  • Pruebas: Vitest con cobertura integral de pruebas

Contribuciones

  1. Instalar dependencias: npm install
  2. Ejecutar pruebas: npm test
  3. Verificar calidad de código: npm run check
  4. Compilar: npm run build

Licencia

MIT