Testar e Depurar
Lição reescrita a 3 de novembro de 2026 com base nas páginas Connect and test your plugin e Troubleshooting da documentação de Plugins da OpenAI. O antigo “development playground” e os seus comandos pertenciam ao SDK inexistente da primeira versão deste curso. Fontes: Connect and test · Troubleshooting.
Testar por camadas
A OpenAI recomenda testar cada capacidade antes de implementar o plugin completo instalado: primeiro o servidor MCP autónomo ligado ao ChatGPT e, em seguida, o plugin empacotado com as suas competências. Mantenha os seus prompts de avaliação e os respetivos resultados ao longo do desenvolvimento para poder comparar o comportamento entre versões.
O servidor MCP
Preparar o endpoint
Antes de testar no ChatGPT, verifique se o servidor está acessível via HTTPS público — ou através de um Secure MCP Tunnel —, se suporta streamable HTTP (normalmente em /mcp), se os nomes das ferramentas, descrições, esquemas e anotações estão presentes e se a descoberta de autenticação funciona para ferramentas que exigem uma conta. Um túnel de desenvolvimento serve para testes, mas não para submissão.
Inspecionar
O MCP Inspector chama as suas ferramentas diretamente, sem um modelo:
npx @modelcontextprotocol/inspector@latest
Submeta cada ferramenta a testes rigorosos: inputs representativos, casos limite, credenciais em falta e resultados vazios. Verifique a validação do esquema, erros de autenticação, anotações, comportamento de confirmação e a legibilidade da saída pelo modelo.
Avaliar a seleção de ferramentas
Assim que o servidor estiver ligado como um plugin pessoal (Lição 4), instale-o, abra uma nova conversa, escreva @ e selecione-o. Crie um conjunto de avaliação contendo:
- Pedidos diretos que devem acionar uma ferramenta específica;
- Pedidos indiretos que expressam o mesmo objetivo de forma diferente;
- Pedidos de acompanhamento que reutilizam identificadores obtidos anteriormente;
- Operações de escrita que exigem autorização ou confirmação;
- Pedidos fora do âmbito que não devem acionar nenhuma ferramenta.
Para cada um, registe a ferramenta selecionada, os seus argumentos, o resultado, eventuais erros e o comportamento de confirmação. Repita todo o conjunto sempre que alterar um nome, descrição, esquema ou anotação. Se o servidor devolver um componente de interface, teste tanto o componente em si como o resultado legível pelo modelo.
Visualizar trocas brutas
Para ler os pedidos e respostas completos, o API Playground aceita um servidor MCP: vá a Tools → Add → MCP Server, introduza o endereço HTTPS, ligue-se e execute os seus prompts de teste.
Atualizar metadados
Após qualquer alteração num nome, descrição, esquema, anotação, método de autenticação ou recurso de interface: reimplemente ou reinicie o servidor, abra a ligação em chatgpt.com/plugins, selecione Refresh, verifique se os metadados anunciados foram alterados e repita os testes relevantes numa nova conversa. Esta atualização aplica-se a servidores ligados diretamente; para um plugin publicado, as atualizações de ferramentas estão sujeitas a revisão contínua (Lição 11).
Antes de empacotar, verifique se a lista de ferramentas corresponde às capacidades anunciadas, se os resultados estruturados cumprem os esquemas de saída, se as falhas de autenticação devolvem erros úteis, se os prompts certos acionam as ferramentas certas enquanto os errados não acionam nenhuma e se a interface é renderizada sem erros na consola, restaurando corretamente o seu estado.
O plugin completo
Assim que o servidor estiver pronto — ou imediatamente para um plugin constituído apenas por competências —, empacote o plugin (Lição 10), adicione-o a um mercado local, instale-o a partir do diretório de plugins e repita os pedidos do seu inventário de casos de uso: diretos, indiretos, de acompanhamento, negativos e casos limite intencionalmente excluídos. Verifique se o plugin segue as instruções das competências, utiliza os recursos corretos, conclui cada passo e produz um resultado útil; se as competências chamam as ferramentas corretas; e se a autenticação funciona após a instalação.
Diagnosticar por camada
Quando algo corre mal, comece por isolar a camada com defeito: servidor, componente ou cliente ChatGPT.
| Sintoma | Pista |
|---|---|
| Nenhuma ferramenta listada | O servidor está em execução? O endereço termina em /mcp? |
| Dados estruturados, mas sem componente | A ferramenta inclui _meta.ui.resourceUri a apontar para um recurso registado do tipo text/html;profile=mcp-app que carrega sem erros de CSP? |
| Erros de esquema | Os seus modelos Python ou TypeScript correspondem ao outputSchema anunciado? |
| Componente lento | As chamadas de ferramenta excedem algumas centenas de milissegundos? Faça profiling e utilize cache. |
| Falha no carregamento do componente | Consola do navegador: violação de CSP, pacote incompleto? |
| Estado perdido (arrastar e largar, edição) | Chame window.openai.setWidgetState após cada atualização e restaure a partir de window.openai.widgetState na montagem. |
| Layout quebrado em telemóvel | Leia window.openai.displayMode e window.openai.maxHeight; evite alturas fixas e ações de hover. |
| Ferramenta nunca selecionada | Reescreva a descrição como “Use quando…”, reveja os prompts iniciais. |
| Ferramenta errada selecionada | Esclareça as ferramentas vizinhas, especifique casos excluídos, divida ferramentas demasiado abrangentes. |
| Erros 401 | Inclua WWW-Authenticate na resposta; verifique o emissor e a audiência. |
invalid_client numa ligação existente | O cliente OAuth registado ainda existe? Restaure-o em vez de criar um novo. |
| O túnel ngrok expirou | Reinicie-o, verifique se o servidor local está em execução; em produção, utilize alojamento estável com sondas de saúde. |
| Streaming quebrado atrás de um proxy | O balanceador de carga ou CDN deve permitir a passagem do streaming HTTP sem buffering. |
Se o problema persistir, recolha os registos do servidor, a consola do componente, uma transcrição das chamadas de ferramenta e capturas de ecrã. Anote o prompt utilizado e envie tudo para o seu contacto na OpenAI.
Pontos-chave
- Teste por camadas: servidor isolado (Inspector, depois ChatGPT) e, em seguida, o plugin completo
- Crie um conjunto de avaliação: pedidos diretos, indiretos, de acompanhamento, de escrita e fora do âmbito
- O API Playground mostra as trocas MCP brutas
- Refresh após cada alteração de metadados e, em seguida, inicie uma nova conversa
- Em caso de problemas, isole primeiro a camada: servidor, componente ou cliente