Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Testar e Depurar

Aula 9 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Testar por camadas
  2. O servidor MCP
  3. O plugin completo
  4. Diagnosticar por camada
  5. Pontos-chave

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.

SintomaPista
Nenhuma ferramenta listadaO servidor está em execução? O endereço termina em /mcp?
Dados estruturados, mas sem componenteA 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 esquemaOs seus modelos Python ou TypeScript correspondem ao outputSchema anunciado?
Componente lentoAs chamadas de ferramenta excedem algumas centenas de milissegundos? Faça profiling e utilize cache.
Falha no carregamento do componenteConsola 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óvelLeia window.openai.displayMode e window.openai.maxHeight; evite alturas fixas e ações de hover.
Ferramenta nunca selecionadaReescreva a descrição como “Use quando…”, reveja os prompts iniciais.
Ferramenta errada selecionadaEsclareça as ferramentas vizinhas, especifique casos excluídos, divida ferramentas demasiado abrangentes.
Erros 401Inclua WWW-Authenticate na resposta; verifique o emissor e a audiência.
invalid_client numa ligação existenteO cliente OAuth registado ainda existe? Restaure-o em vez de criar um novo.
O túnel ngrok expirouReinicie-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 proxyO 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