Versionar ferramentas e esquemas
Evolua seu servidor sem quebrar os clientes.
Versionar ferramentas e esquemas é uma aula grátis de MCP Academy no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de MCP Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de MCP Academy inclui 4 aulas no total.
Os clientes dependem dos seus formatos
Depois que outras pessoas se conectam, elas dependem dos nomes das suas ferramentas e dos formatos dos argumentos. Alterá-los sem cuidado quebra todos os clientes de uma só vez.
Alterações aditivas são seguras
Adicionar um parâmetro opcional com um valor padrão mantém os chamadores antigos funcionando. Eles simplesmente ignoram o novo campo que não enviam.
def search(q: str, limit: int = 10) -> list:
...Mudanças Incompatíveis Causam Problemas
Renomear uma ferramenta, remover um argumento ou tornar algo obrigatório é uma mudança incompatível. Os clientes existentes passam de repente a enviar chamadas que já não são aceitas.
Adicione e Depois Descontinue
Para evoluir um campo, adicione o novo e mantenha o antigo. Marque o antigo como descontinuado na descrição para que os chamadores saibam que precisam migrar.
Inclua a Versão no Nome da Ferramenta
Para uma mudança realmente incompatível, disponibilize uma ferramenta v2 ao lado da v1. Ambas funcionarão por algum tempo, permitindo que os clientes migrem no próprio ritmo.
@mcp.tool(name="search_v2")
def search_v2(query: str) -> list:
...O Servidor Informa a Própria Versão
Seu servidor anuncia um nome e uma versão durante o handshake. Incremente-a para que os clientes saibam a qual versão se conectaram.
mcp = FastMCP("my-server")
# version surfaces in server infoSiga o Versionamento Semântico
Use semver: incremente o patch para correções, a versão minor para recursos aditivos e a versão major quando fizer uma mudança incompatível. O número conta uma história.
Amplie, Não Restrinja, as Saídas
Adicionar um campo a um resultado geralmente é seguro; removê-lo é uma mudança incompatível. Trate o esquema de saída como uma promessa que os clientes interpretam.
Mantenha um Registro de Alterações
Registre todas as mudanças nas ferramentas e nos esquemas em um registro de alterações. Quem atualizar precisa ver o que mudou, o que é novo e o que desapareceu.
Defina uma Data de Encerramento para Descontinuações
Anuncie quando uma ferramenta antiga será removida. Uma data clara de encerramento incentiva a migração sem deixar ninguém desamparado de repente.
Teste com Clientes Antigos
Antes do lançamento, execute seus testes como um cliente antigo faria chamadas para você. Isso detecta mudanças incompatíveis acidentais que o verificador de tipos não consegue perceber.
Verificação Rápida
Qual mudança em uma ferramenta existente é segura para os clientes atuais?
Recapitulação: Evolua com Segurança
Prefira mudanças aditivas, descontinue antes de remover, disponibilize a v2 para mudanças realmente incompatíveis, siga o semver e mantenha um registro de alterações. Você pode lançar com confiança! 🚀
Aprenda Python com um tutor de IA — grátis
Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.
- Cursos
- 30
- Aulas
- 120
Perguntas Frequentes
A aula “Versionar ferramentas e esquemas” é grátis?
Sim — o texto completo de “Versionar ferramentas e esquemas” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de MCP Academy, atualize para CoddyKit PRO. O curso de MCP Academy inclui 4 aulas no total.
O que vou aprender em “Versionar ferramentas e esquemas”?
Evolua seu servidor sem quebrar os clientes. Você pratica MCP Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar MCP Academy?
Nenhuma experiência prévia é necessária. MCP Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.
Quanto tempo leva a aula “Versionar ferramentas e esquemas”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de MCP Academy?
Sim. Cada aula de MCP Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Arquitetura de servidor em camadas
- Configuração e segredos pelo ambiente
- Ferramentas idempotentes e conscientes dos efeitos colaterais
- Versionar ferramentas e esquemas