mcp-migrate servidor MCP: qué revisar antes de la revisión 2026-07-28

mcp-migrate servidor MCP: qué rompe la revisión 2026-07-28, cómo leer la nota con cautela y cómo adoptar la herramienta en CI con un baseline.
mcp-migrate serveur MCP : vérifier avant la révision 2026-07-28

Tu servidor MCP funciona detrás de un gateway y un cliente acaba de anunciar que habla la revisión 2026-07-28 del protocolo. ¿Subes de versión ya o esperas? Para decidir hay que saber qué se rompe sin avisar. El proyecto mcp-migrate sirve para eso: una herramienta de línea de comandos que lee el código de un servidor MCP y enumera lo que cambia esa revisión. Esta es mi lectura de mcp-migrate servidor MCP desde la óptica de quien lo opera: qué detecta la herramienta y qué se le escapa.

Datos comprobados el 10 de noviembre de 2026 en el repositorio clonado: licencia Apache 2.0, versión 0.21.1 fechada el 30 de octubre de 2026 en el CHANGELOG, último commit del 10 de noviembre de 2026. No he instalado ni ejecutado la herramienta: las salidas que verás más abajo son los ejemplos del README, no pruebas mías. No cito el número de estrellas porque no pude leerlo con fiabilidad.

Como este blog trata de Dynatrace, una aclaración: mcp-migrate analiza código y no depende de ninguna oferta de Dynatrace, ni SaaS ni Managed.

mcp-migrate servidor MCP: la decisión previa a actualizar

La página de cambios de la revisión 2026-07-28, leída el mismo día, anuncia rupturas de naturaleza muy distinta. Unas hacen fallar a un cliente al instante. Otras degradan la caché o la legibilidad sin ningún error. La herramienta no sustituye a la especificación, pero te ahorra recorrerla a mano archivo por archivo.

Mi pregunta de operador es sencilla: ¿mi servidor falla o simplemente rinde peor? La respuesta fija el orden de los trabajos, no la nota final.

Tres familias de roturas, ordenadas por riesgo de guardia

Lo que se rompe de verdad

El README clasifica 10 de las 21 reglas como «breaking». Las más claras para un servidor HTTP: desaparece la cabecera Mcp-Session-Id (R001), se elimina el handshake initialize (R009) y se retiran ping (R011) y logging/setLevel (R012). A ello se suman resources/subscribe, sustituido por subscriptions/listen (R013), y el código de error de «recurso no encontrado», que pasa de -32002 a -32602 (R017). La página de la especificación confirma cada punto.

Un caso merece atención: el estado en memoria. La regla R002 señala, por ejemplo, un diccionario global indexado por conexión. Detrás de un balanceador, o tras un reinicio, ese estado desaparece. La especificación pide «handles» generados por el servidor y devueltos como argumentos de la herramienta.

Lo que se degrada sin error

Tres reglas «deprecated» (HTTP+SSE, Roots/Sampling/Logging, registro dinámico de clientes) y ocho «advisory» forman la zona gris. Por ejemplo, los resultados de tools/list deben incluir ttlMs y cacheScope (R016). Sin ellos no falla nada, pero los clientes ya no pueden cachear esas listas. El orden de las herramientas (R004) juega en el mismo terreno.

Lo que afecta a la observabilidad

La regla R008 comprueba que el contexto de traza (traceparent, tracestate, baggage) se lea desde _meta. Es el punto que interesa a un SRE: si el servidor ignora esas claves, la traza de OpenTelemetry se corta en su puerta. Sigue siendo «advisory», así que es fácil olvidarla.

Cómo leer la nota sin equivocarse

El README insiste en tres límites de la nota. Primero, cada regla tiene un tope: un único Mcp-Session-Id y catorce dan la misma puntuación, 75, es decir, la nota C. La nota cuenta tipos de problema, no volumen de trabajo. Para dimensionar la migración, el README remite a --json, que lista cada ocurrencia.

Segundo, solo Python recibe nota. TypeScript se analiza con las 21 reglas pero sin letra, y JavaScript con solo 7 reglas, según el README. Tercero, el código de salida 2 significa «código ilegible», no «código limpio».

Ejemplo de salida de mcp-migrate check tomado del README: tabla de hallazgos clasificados como breaking, deprecated y advisory, y nota F con 27 sobre 100
Source : github.com

Tampoco es un veredicto independiente. La «tabla» del proyecto (21 servidores públicos) la elaboró el propio proyecto, no los mantenedores de esos servidores; el README lo dice. Las supresiones en línea no cuentan en la nota, algo que la herramienta recuerda en cada ejecución.

Paso 1: lanzar la comprobación sobre el servidor

Según el README, bastan dos comandos para empezar:

uvx mcp-migrate check .
uvx mcp-migrate check . --json

Para reducir el ruido al principio, --rule R001 limita las reglas que se ejecutan y --severity breaking muestra solo las rupturas sin cambiar la nota ni el código de salida. Las carpetas de tests se ignoran por defecto; --include-tests las añade.

Paso 2: revisar el diff del fix antes de escribir

El comando fix trabaja en simulación por defecto. Muestra el diff y solo escribe con --write. Cada cambio lleva la etiqueta «safe» o «review». En el ejemplo del README, tres cambios son seguros (código de error, extensions={}, orden de herramientas) y tres necesitan a una persona.

Ejemplo de salida de mcp-migrate fix en simulación tomado del README: diff de errors.py y server.py con las etiquetas R017 safe y R001 review, seis cambios de los que tres son seguros
Source : github.com

Lo importante es la línea TODO(mcp-migrate) que la herramienta deja en el código: comenta la lectura de la cabecera de sesión, pero no puede adivinar cómo llamarás a tu futuro handle. Es el reparto correcto. Solo existen 19 fixers para 21 reglas; R010 (server/discover) y R015 (resultType) no tienen.

Paso 3: adoptarlo sin bloquear a todo el equipo

Un servidor existente rara vez parte de cero hallazgos. El README propone un archivo de referencia: --write-baseline guarda los hallazgos conocidos y --baseline hace fallar el build solo por los nuevos. La nota no cambia: la deuda sigue a la vista.

Para un falso positivo basta un comentario mcp-migrate: ignore[R001] con su motivo. Cuidado con R005, R015 y R016: el README aclara que suprimir una línea neutraliza la regla para todo el archivo.

Fragmento del README: configuración de pre-commit y paso de GitHub Action de mcp-migrate con fail-on deprecated y versión fijada
Source : github.com

En integración continua, el README ofrece un hook de pre-commit y una GitHub Action, con salida SARIF para la pestaña de seguridad. Recomienda fijar la versión: si no, una regla nueva puede poner en rojo un build aunque el código no se haya movido.

Observar el servidor durante la migración

Un análisis estático no ve el comportamiento real. Esto es lo que yo añadiría, como sugerencia y no como función de la herramienta:

  • comparar la tasa de errores por método MCP antes y después del despliegue;
  • seguir qué parte de las peticiones tools/list sigue llegando pese a la caché, una vez añadido ttlMs;
  • comprobar que una llamada del cliente aparece en la misma traza que la llamada a la herramienta en el servidor (R008).

Para medir por herramienta, mira las métricas de herramientas MCP; para la propagación de trazas, la observación de agentes MCP con OpenTelemetry.

Límites y cuestiones abiertas

  • Proyecto joven y muy activo: 21 reglas, versión 0.x; el formato del JSON puede cambiar antes de la 1.0, avisa el README.
  • Detección por patrones, no por ejecución: el README reconoce clases de falsos positivos abiertos.
  • La nota para TypeScript sigue pendiente; JavaScript solo se cubre en parte.
  • No he lanzado la herramienta contra un servidor real: sin verificar.
  • Un análisis de código no sustituye a las pruebas de integración con un cliente real ni a una auditoría de seguridad; consulta la auditoría de servidores MCP en la empresa.

Buenas prácticas

  • Ejecuta primero check --json y cuenta las ocurrencias antes de prometer una fecha.
  • Atiende antes los «breaking» y después la caché y la traza.
  • Revisa cada diff «review»: un TODO es una decisión, no un descuido.
  • Fija la versión de la herramienta en CI y cámbiala a propósito.
  • Mantén una prueba de extremo a extremo con un cliente reciente; para construir o endurecer el servidor, mira cómo asegurar un servidor MCP.

Preguntas frecuentes

¿mcp-migrate modifica mi código sin avisar?

No. fix simula por defecto; para escribir hay que pasar --write. Según el README, se rechaza un archivo que dejaría de ser válido tras la corrección.

¿Una nota A significa que mi servidor es conforme?

No, solo que ninguna de las 21 reglas encontró un patrón. Las reglas leen el código, no el comportamiento, y TypeScript no tiene nota.

¿Es fiable el proyecto para decidir en producción?

Como ayuda de triaje, sí: licencia Apache 2.0 y repositorio activo. Como único control, no: está en versión 0.x y no lo he puesto a prueba yo mismo.

Conclusión

Antes de subir de versión, usa mcp-migrate en tu servidor MCP para ordenar los trabajos: lo que se rompe, lo que se degrada y lo que corta la traza. Después valida con un cliente real y con tus métricas. Enlaces útiles: la página de cambios de la especificación y el repositorio del proyecto citado arriba.

span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC. Dynatrace es una marca de Dynatrace LLC. La información procede del repositorio del proyecto y de la especificación pública, revisados el 10 de noviembre de 2026, y puede cambiar; compruébala en tu entorno.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
traceroot observabilité agents IA : licence, démarrage et limites

traceroot observabilidad agentes IA: licencia, arranque y límites

Next Post
Gatus page de statut : alertes en YAML pour développeurs

Gatus página de estado: alertas YAML para desarrolladores

Related Posts