Use WebMCP Tool: hook React para registrar ferramentas em agentes do navegador

O que é

use-webmcp-tool é um hook React, mantido pelo GoogleChromeLabs, que registra ferramentas WebMCP no navegador e vincula seu ciclo de vida a um componente React. O WebMCP permite que uma página exponha funções JavaScript como "tools" que agentes de IA (embutidos no browser, em iframes ou extensões) podem descobrir e invocar diretamente - em vez de o agente ter que raspar o DOM, a árvore de acessibilidade ou usar screenshots.

API imperativa vs. hook

A API imperativa original expõe document.modelContext.registerTool(...), que recebe um objeto com name, description, inputSchema e execute, além de um AbortSignal para desregistro. O hook useWebMCP encapsula isso no modelo declarativo do React: a ferramenta é registrada quando o componente monta e desregistrada automaticamente quando desmonta, mantendo o conjunto de ferramentas visíveis ao agente em sincronia com o que está na tela.

Instalação e requisitos

npm install use-webmcp-tool

Requer React 18+ como peer dependency. É distribuído como ESM com tipos TypeScript incluídos e sem dependências em runtime. Como o spec WebMCP ainda é experimental, o hook faz feature detection e degrada para um no-op em ambientes onde a API não existe.

Parâmetros e retorno

O hook aceita um objeto com:

• name (string, obrigatório) - identificador da ferramenta
• description (string, obrigatório) - descrição em linguagem natural para o agente
• inputSchema (JSON Schema, opcional) - descreve os argumentos
• annotations (opcional) - hints como readOnlyHint / untrustedContentHint
• execute (função, obrigatório) - lógica da ferramenta
• enabled (boolean, default true) - registra apenas enquanto true
• formatOutput (opcional) - transforma o resultado antes da normalização MCP
• onError (opcional) - efeito colateral quando execute lança erro

Retorna { supported, registered, error }, onde supported indica se document.modelContext existe no ambiente, registered indica se a ferramenta está ativa e error captura erros de registro (ex.: NotAllowedError por política de permissões).

Normalização de resultados

O retorno de execute é normalizado automaticamente:

• string → bloco de texto MCP
• undefined/null → sucesso sem payload
• Objeto já no formato { content: [...] } → passado sem alteração
• Valor lançado (Error ou não) → resultado com isError: true, após chamar onError
• Error retornado (não lançado) → tratado como throw
• Qualquer outro valor → serializado como JSON em bloco de texto

Testes

O repositório inclui 21 testes (vitest + jsdom + @testing-library/react) cobrindo ciclo de vida de registro/desregistro (incluindo StrictMode e enabled), estabilidade de re-registro (mudanças em execute ou schemas equivalentes não causam churn), e a matriz completa de normalização de resultados e erros.