WebMCP Builder

A mesma busca pode ser feita por uma pessoa, por automação visual ou por uma tool estruturada.

Comparar os três caminhos cria a imagem mental que sustenta o restante do curso.

objetivo humano · passos visuais · capacidade explícita · mesma interface

Web semântica, automação do navegador, API, MCP e WebMCP resolvem problemas diferentes.

A distinção impede que nomes parecidos virem uma única abstração vaga.

entender · operar · chamar · descobrir

A página registra; o navegador observa; o agente escolhe; o JavaScript executa; o resultado volta.

Entender o ciclo completo revela onde cada responsabilidade realmente vive.

registro · descoberta · escolha · execução

Uma tool combina nome, descrição, schema e uma função execute.

Cada campo influencia uma decisão diferente do agente e da aplicação.

name identifica · description orienta · schema restringe · execute realiza

As capacidades úteis mudam entre home, produto, carrinho e área autenticada.

Um catálogo contextual reduz ruído e evita oferecer ações impossíveis.

home busca · produto escolhe · carrinho altera · sessão autoriza

O Builder precisa prever fallback, autorização, cancelamento, evidência e limites.

O projeto fecha o modelo mental com uma entrega que pode ser demonstrada e criticada.

fallback · segurança · evidência · projeto

A interface ModelContext é definida para SecureContext; HTTPS e localhost são a base mínima do laboratório.

O teste correto separa ausência da API, configuração experimental e falha real do código.

HTTPS em produção · localhost no laboratório · flag pode variar · origem importa

Vite oferece servidor local e módulos ES; Node executa a automação do projeto, não a API WebMCP do documento.

A separação permite desenvolver o site em qualquer browser e ativar WebMCP apenas por enhancement progressivo.

Node para tooling · Vite serve a página · API vive no Document · build não decide suporte

Feature detection pergunta pela capacidade real no momento do uso, sem confiar em user-agent ou versão fixa.

Como o draft muda, detectar a superfície disponível é mais durável do que codificar uma lista de navegadores.

teste a propriedade · fallback é funcional · mensagem é honesta · sem sniffing

DevTools, console e um inspector local ajudam a observar registro, troca de catálogo, entrada e resultado.

Sem evidência, é fácil confundir uma tool bem registrada com uma tool realmente segura e utilizável.

console estruturado · toolchange observável · inputs de teste · resultado capturado

Tipos ajudam o editor e um polyfill pode simular a superfície para testes, mas nenhum deles prova suporte nativo do agente no navegador.

Distinguir simulação de implementação impede falsos positivos no relatório de prontidão.

types não executam · polyfill simula · nativo é diferente · registre o modo

A matriz registra navegador, canal, flag, contexto seguro, data e resultado do teste.

Uma API experimental exige rastreabilidade; “funciona aqui” não basta para uma equipe ou para produção.

data do teste · versão e canal · flag documentada · fallback verificado

Os atributos toolname e tooldescription declaram a intenção do formulário sem remover sua semântica HTML.

É o caminho de menor esforço para jornadas que já possuem campos, validação e botão de envio.

form continua HTML · toolname identifica · descrição orienta · progressive enhancement

O name do controle vira a propriedade; toolparamdescription explica ao agente o significado e o formato esperado.

Labels ajudam pessoas, enquanto descrições precisas reduzem preenchimentos plausíveis porém errados.

name é chave · label serve pessoas · descrição serve escolha · exemplos esclarecem

Tipos de input, required, min, max e opções contribuem para o schema sintetizado pelo navegador.

Reutilizar restrições semânticas mantém o formulário manual e a tool alinhados.

required vira requisito · select limita valores · min/max restringem · algoritmo ainda evolui

Sem toolautosubmit, o agente preenche e a página devolve o foco ao usuário para revisão; com o atributo, o envio pode ocorrer automaticamente.

A escolha deve seguir o risco e o efeito da ação, não apenas a conveniência do fluxo.

ausente pede revisão · booleano habilita envio · risco orienta decisão · UI mostra preenchimento

Em envio acionado por agente, agentInvoked permite identificar a origem e respondWith entrega uma Promise com o resultado estruturado.

O agente recebe um protocolo verificável sem depender de raspar a página após o envio.

preventDefault primeiro · teste agentInvoked · Promise como resposta · erro é estruturado

A API declarativa e os eventos toolactivated/toolcanceled são propostas abertas; toolchange é o evento especificado no snapshot atual.

A interface precisa continuar legível quando o agente inicia, o usuário revisa ou a chamada é cancelada.

estado visual explícito · cancelamento limpa UI · draft pode mudar · fallback não depende disso

document.modelContext.registerTool recebe name, title opcional, description, inputSchema, execute e annotations opcionais.

A forma imperativa atende jornadas que não cabem num formulário ou dependem de lógica e estado ricos.

nome único · descrição não vazia · execute obrigatório · registro é Promise

inputSchema usa JSON Schema para declarar propriedades, tipos, enums, descrições e campos obrigatórios.

O schema é parte do raciocínio de escolha e geração de argumentos; validação real ainda deve ocorrer no código.

type object · propriedades focadas · required coerente · valide no execute

O callback execute pode retornar uma Promise; o valor resolvido é entregue ao agente.

Resultados pequenos, tipados por convenção e acompanhados de evidência facilitam verificação e encadeamento.

Promise é aceita · resultado é serializável · UI é atualizada · erros são úteis

O signal de registerTool remove a ferramenta quando abortado; o signal recebido por execute cancela a chamada em andamento.

Esse modelo evita ferramentas obsoletas e trabalho continuando depois que o agente perdeu interesse.

signal de registro remove · signal de execução cancela · fetch aceita signal · cleanup é determinístico

getTools lista ferramentas expostas ao documento e executeTool executa uma RegisteredTool com entrada estruturada.

Essas operações viabilizam agentes in-page e testes controlados sem simular um agente externo.

getTools é assíncrono · origem pode filtrar · execute usa RegisteredTool · cancelamento opcional

Buscar, consultar e verificar disponibilidade formam uma sequência com responsabilidades distintas e sem tool genérica.

Um catálogo enxuto melhora a escolha do agente e cria uma base clara para a fase Integrator.

buscar lista · consultar detalha · disponibilidade verifica · sem sobreposição