Versionar herramientas y esquemas
Haga evolucionar su servidor sin romper los clientes.
Versionar herramientas y esquemas es una lección gratuita de MCP Academy en CoddyKit. Esta es la lección 4 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de MCP Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de MCP Academy incluye 4 lecciones en total.
Los clientes dependen de sus estructuras
Una vez conectados, otros sistemas dependen de los nombres de sus herramientas y de las estructuras de sus argumentos. Cambiarlos sin cuidado rompe todos los clientes a la vez.
Los cambios aditivos son seguros
Añadir un parámetro opcional con un valor predeterminado mantiene el funcionamiento de los llamadores antiguos. Simplemente ignoran el campo nuevo que no envían.
def search(q: str, limit: int = 10) -> list:
...Los cambios incompatibles perjudican
Renombrar una herramienta, eliminar un argumento o convertirlo en obligatorio es un cambio incompatible. Los clientes existentes pasan a enviar llamadas que ya no encajan.
Añada primero y marque como obsoleto después
Para evolucionar un campo, añada el nuevo y conserve el antiguo. Marque el antiguo como obsoleto en su descripción para indicar a los llamadores que deben migrar.
Incluya la versión en el nombre de la herramienta
Si se trata de un cambio realmente incompatible, publique una herramienta v2 junto a v1. Ambas funcionarán durante un tiempo, para que los clientes migren a su propio ritmo.
@mcp.tool(name="search_v2")
def search_v2(query: str) -> list:
...El servidor informa de su versión
Su servidor anuncia un nombre y una versión durante el protocolo de enlace. Increméntela para que los clientes puedan ver a qué versión se han conectado.
mcp = FastMCP("my-server")
# version surfaces in server infoSiga el versionado semántico
Utilice semver: incremente el parche para correcciones, la versión menor para funciones aditivas y la versión mayor cuando realice un cambio incompatible. El número cuenta una historia.
Amplíe las salidas, no las reduzca
Añadir un campo a un resultado suele ser seguro; eliminarlo es incompatible. Considere el esquema de salida como un contrato que los clientes analizan.
Mantenga un registro de cambios
Registre cada cambio de herramienta y de esquema en un registro de cambios. Los usuarios que actualicen necesitan saber qué cambió, qué es nuevo y qué desapareció.
Asigne una fecha límite a las obsolescencias
Anuncie cuándo se eliminará una herramienta antigua. Una fecha clara de retirada impulsa la migración sin dejar a nadie desamparado de forma repentina.
Pruebe con clientes antiguos
Antes de publicar, ejecute sus pruebas como lo haría un cliente antiguo. Así detectará cambios incompatibles accidentales que el comprobador de tipos no puede ver.
Comprobación rápida
¿Qué cambio en una herramienta existente es seguro para los clientes actuales?
Repaso: evolucionar de forma segura
Prefiera los cambios aditivos, marque como obsoletos los elementos antes de eliminarlos, publique v2 para los cambios realmente incompatibles, siga semver y mantenga un registro de cambios. ¡Puede publicar con confianza! 🚀
Aprende Python con un tutor de IA — gratis
Escribe y ejecuta código real en tu navegador, obtén ayuda instantánea de un tutor de IA disponible 24/7 y continúa donde lo dejaste en la web o en la aplicación.
- Cursos
- 30
- Lecciones
- 120
Preguntas frecuentes
¿La lección «Versionar herramientas y esquemas» es gratis?
Sí — el texto completo de «Versionar herramientas y esquemas» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de MCP Academy, actualiza a CoddyKit PRO. El curso de MCP Academy incluye 4 lecciones en total.
¿Qué aprenderé en «Versionar herramientas y esquemas»?
Haga evolucionar su servidor sin romper los clientes. Practicas MCP Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.
¿Necesito experiencia previa para empezar MCP Academy?
No se requiere experiencia previa. MCP Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 4 de 4.
¿Cuánto tiempo toma la lección «Versionar herramientas y esquemas»?
La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.
¿Puedo escribir y ejecutar código en esta lección de MCP Academy?
Sí. Cada lección de MCP Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.
Todas las lecciones de este curso
- Arquitectura de servidor por capas
- Configuración y secretos mediante el entorno
- Herramientas idempotentes y conscientes de sus efectos secundarios
- Versionar herramientas y esquemas