La Realidad de la Migración Legacy
Modernizar un sistema PHP legacy debería ser simple: leer el código antiguo, entender las reglas, reconstruirlas limpiamente en una nueva aplicación Laravel. En realidad, el código legacy no se comporta así. Es no lineal, implícito, lleno de efectos secundarios, y a menudo depende de convenciones que nadie recuerda.
Cuando combinas eso con un agente moderno como Claude Code, aprendes rápidamente una dura verdad: un LLM puede escribir código excelente, pero no puede adivinar tus reglas de negocio. Por eso decidimos construir nuestro propio servidor MCP (Model Context Protocol)—escrito en PHP, ejecutándose junto al código legacy—para dar al agente una ventana real al sistema.
¿Por Qué un Servidor MCP?
Los agentes de codificación CLI han cambiado el flujo de trabajo. Cuando un agente puede leer tu repositorio, escribir archivos, ejecutar tests y modificar código de forma asíncrona, deja de ser un chatbot y se convierte en un colaborador. Pero para colaborar, necesita contexto.
En un proyecto Laravel desde cero, eso es fácil: las carpetas son predecibles, los patrones se repiten, la lógica de negocio vive en servicios o acciones. Pero nuestra aplicación legacy era código espagueti clásico—mezclando HTML, strings SQL, funciones globales, includes procedurales, cálculos inline y llamadas de redirección.
Para migrar esto de forma segura, el agente necesita responder preguntas como: ¿Qué tablas existen y cómo son? ¿Qué calcula realmente esta función? ¿Cuántos lugares modifican esta variable de sesión? Ningún prompt puede adivinar eso de forma fiable desde código estático. Necesitábamos acceso ejecutable—no solo texto.
Un Servidor MCP en PHP Junto al Código Legacy
Usamos la librería mcp/capability, que te permite anotar métodos PHP y exponerlos como herramientas MCP. El servidor se ejecuta dentro del mismo entorno que la aplicación legacy, por lo que puede consultar la BD, incluir archivos PHP antiguos y ejecutar funciones legacy.
Una vez expuestos a través de MCP, Claude Code puede llamar a estas herramientas directamente durante una tarea de migración. El servidor incluye capacidades para consultar datos (solo lectura), describir tablas, extraer lógica PHP, analizar reglas de negocio e incluso invocar funciones PHP legacy dentro de su entorno original.
Ejecutando Funciones Legacy Directamente
Muchos de los detalles complicados—cálculos de envío, ajustes de precio, lógica de descuentos—viven en pequeñas funciones dispersas en includes. Para ayudar a Claude a entender qué hacen realmente estas funciones, expusimos una herramienta que carga el archivo original, incluye librerías de funciones compartidas, configura la sesión y BD legacy, y ejecuta la función.
Esto permite al agente probar el comportamiento antes de reescribir la lógica en Laravel: "Dados estos inputs, ¿qué coste de envío calcula el sistema legacy?" El agente ahora puede confirmar el comportamiento legacy en lugar de alucinar una nueva implementación.
Extrayendo las Reglas de Negocio Reales
El análisis estático también importa. La naturaleza espagueti del proyecto significa que la lógica está oculta dentro de ramas, expresiones inline, sentencias SQL y mutaciones de sesión. Una de nuestras herramientas MCP lee un archivo y extrae patrones como condicionales que involucran precios, validaciones básicas, consultas SQL, redirecciones, variables de sesión y expresiones aritméticas con totales, IVA y descuentos.
Esto da a Claude una vista compacta de "qué está haciendo realmente este archivo", sin ahogarlo en HTML o ruido de marcado. El objetivo no es entender perfectamente el código—solo sacar a la superficie la lógica que el agente debe preservar al reescribirlo.
Cómo Esto Cambia el Proceso de Migración
Construir el servidor MCP nos obligó a repensar cómo migramos código legacy. En lugar de reescribir a ciegas, el agente explora el sistema. En lugar de adivinar reglas, las inspecciona. En lugar de hacer ingeniería inversa a mano, exponemos las respuestas vía herramientas.
En el lado de Laravel, el agente ahora produce implementaciones más limpias y fieles porque está recreando el razonamiento que seguiría un desarrollador: verificar el esquema de la tabla, inspeccionar una función, ejecutarla con datos de prueba, extraer sus cálculos, y luego implementar el Feature, Action o Service equivalente.
Sigue siendo un proyecto de migración, no magia. Pero se siente significativamente menos como arqueología y más como una reescritura estructurada.
Reflexiones Finales
Construir un servidor MCP en PHP no era parte del plan original. Pero una vez vimos cómo funcionan los agentes de codificación—y cuánto contexto necesitan—se volvió obvio. Si quieres que una IA colabore en una reescritura, dale las herramientas que usa un desarrollador real.
Ahora podemos migrar funcionalidades con más confianza, con menos conjeturas, y con una separación más clara entre inspección legacy y código Laravel nuevo. Si estás lidiando con un sistema PHP legacy y planeas una migración moderna, construir una pequeña capa MCP alrededor del código antiguo podría ser uno de los pasos más impactantes que tomes.
