Comece listando o que as pessoas esperam conseguir fazer com seu plugin. O nome, a descrição, as habilidades, as ferramentas e a conexão do plugin com um produto existente criam expectativas. A implementação deve atender a essas expectativas, e você deve ter um motivo claro para qualquer exceção.
Esse levantamento ajuda a decidir o que incluir no plugin:
- Adicione uma habilidade quando instruções, exemplos ou recursos incluídos no plugin puderem orientar o modelo ao longo do fluxo de trabalho.
- Adicione um servidor MCP quando o fluxo de trabalho exigir dados em tempo real, autenticação, ferramentas de uso controlado ou código executado na infraestrutura que você opera.
- Adicione uma interface de usuário ao servidor MCP somente quando a interação visual trouxer uma melhoria significativa a alguma etapa do fluxo de trabalho.
Comece pelas expectativas dos usuários
Imagine que uma pessoa instalou seu plugin e ainda não leu a documentação. O que seria razoável ela pedir ao plugin?
Para identificar pedidos prováveis, considere:
- As tarefas que as pessoas já realizam no seu produto ou serviço.
- Entrevistas com usuários, chamados de suporte, termos de busca e pedidos de novos recursos.
- Os termos que as pessoas costumam usar para se referir ao seu produto, aos dados e aos fluxos de trabalho.
- As soluções improvisadas que hoje exigem copiar dados de uma ferramenta para outra.
- O nome do plugin, sua página no catálogo e os prompts iniciais.
Inclua tanto pedidos diretos, que mencionam o plugin pelo nome, quanto pedidos indiretos, que descrevem o objetivo. Por exemplo, um plugin de gestão de projetos pode precisar responder tanto a “Mostre meu quadro de lançamento da Acme” quanto a “O que está impedindo o lançamento?”.
Não limite o levantamento aos fluxos de trabalho que sua API já permite. Primeiro, registre o que as pessoas vão esperar do plugin. Depois, compare essas expectativas com o que você pode oferecer de forma segura e confiável.
Monte um inventário de casos de uso
Para cada caso de uso, registre:
| Campo | Pergunta a responder |
|---|---|
| Objetivo do usuário | O que a pessoa quer fazer? |
| Exemplos de pedidos | Como ela poderia fazer o pedido, direta ou indiretamente? |
| Resultado esperado | Que resultado indicaria que a interação foi bem-sucedida? |
| Contexto necessário | Quais informações são necessárias, a quais contas é preciso ter acesso e de que estado anterior a tarefa depende? |
| Recursos do plugin | Uma habilidade é suficiente ou é necessária uma ferramenta MCP? |
| Limites de segurança | A ação pode expor dados, alterar o estado do sistema, gerar gastos ou afetar outra pessoa? |
| Decisão sobre o suporte | A primeira versão dará suporte a esse caso de uso? Se não, a implementação ficará para depois ou o caso será excluído de propósito? |
Agrupe os pedidos que têm o mesmo objetivo. “Liste minhas tarefas em aberto”, “O que preciso fazer hoje?” e “Mostre as tarefas atrasadas” podem ser pedidos de um único caso de uso de consulta de tarefas, com filtros diferentes, em vez de três funcionalidades independentes.
Verifique a cobertura
Compare cada expectativa com os recursos propostos para o plugin:
- Confirme que, em cada caso de uso contemplado, o plugin consegue executar todas as etapas, do pedido até a entrega de um resultado útil.
- Identifique habilidades, ferramentas, dados e permissões que faltam, além de estados de erro ainda não previstos.
- Procure ferramentas que expõem operações técnicas sem permitir que o usuário alcance um objetivo claro.
- Verifique se as ações de escrita exigem autorização e confirmação adequadas.
- Confira se o plugin consegue explicar o que não pode fazer e sugerir um próximo passo útil.
O plugin não deve dar a impressão de que atende a todo o fluxo de trabalho quando só consegue executar uma pequena parte dele. Se os usuários conseguem criar projetos, mas não conseguem listá-los, consultar seus detalhes ou atualizá-los, implemente as operações que faltam ou apresente o plugin de forma que seu escopo fique claro.
Documente as exclusões intencionais
Você não precisa implementar todos os pedidos imagináveis. Cada exclusão importante deve ter uma boa justificativa, como uma das seguintes:
- A ação traria um risco inaceitável à segurança ou à privacidade.
- O produto ou a API de que o plugin depende não oferece suporte confiável à ação.
- O fluxo de trabalho exige permissões que o plugin não consegue verificar.
- O resultado seria enganoso sem informações às quais o plugin não tem acesso.
- O caso de uso está fora do escopo da primeira versão, e a página do plugin no catálogo deixa isso claro.
Registre essas decisões. Use-as para definir os limites das habilidades, descrever as ferramentas, determinar como o plugin deve recusar pedidos, elaborar casos de teste e redigir o texto da página pública do plugin no catálogo.
Use os casos de uso para decidir o que implementar
Para cada caso de uso contemplado, escolha a implementação mais simples que permita concluí-lo:
- Crie uma habilidade para fornecer instruções e recursos reutilizáveis.
- Crie um servidor MCP para acessar dados em tempo real e executar ações controladas.
- Adicione uma interface de usuário ao servidor MCP quando as pessoas precisarem examinar, comparar, editar ou confirmar informações estruturadas ou navegar por elas.
Use o inventário de casos de uso como plano de testes. Acrescente exemplos representativos de pedidos diretos e indiretos, de casos extremos e de pedidos fora do escopo. Depois de implementar o plugin, verifique se ele se comporta como esperado em cada caso.
Se o plugin precisar acessar dados em tempo real ou executar ações controladas, prossiga para Defina as ferramentas.