webmcp-gen: Gere Definições de Ferramentas WebMCP do Chrome a partir do TypeScript

O Chrome 149 lançou o WebMCP — uma API nativa do navegador que permite que páginas da web exponham ferramentas estruturadas para agentes de IA via navigator.modelContext. O ecossistema está se formando rapidamente: webmcp-core rastreia sites ao vivo para gerar automaticamente definições de ferramentas, e @webmcp-registry/kit fornece um SDK em tempo de execução com defineTool() baseado em Zod.

O que está faltando é geração de código em tempo de construção a partir do seu TypeScript existente. Se você já possui interfaces tipadas para sua API, não deveria ter que reescrevê-las como esquemas Zod ou esperar que um rastreador as descubra.

webmcp-gen preenche essa lacuna. Escreva sua API como interfaces TypeScript, execute um comando, obtenha definições de ferramentas WebMCP compatíveis com a especificação + stubs de manipuladores com as melhores práticas de segurança incorporadas.

Onde se encaixa

Elas são complementares — diferentes camadas para diferentes fluxos de trabalho.

Exemplo rápido

// api.ts

/** Pesquisar produtos por palavra-chave. */
interface SearchProducts {
  query: string;
  category?: "eletrônicos" | "roupas" | "casa";
  limit?: number;
}

npx webmcp-gen --api api.ts

Saída: uma definição .webmcp.json + um stub .handler.ts com navigator.modelContext.registerTool() conectado e pronto para implementar.

O que faz

• Analisa interfaces TypeScript e aliases de tipo via ts-morph
• Mapeia tipos TS para JSON Schema (strings, números, enums, arrays, objetos aninhados, opcionais)
• Extrai descrições de comentários JSDoc
• Valida a saída contra a especificação WebMCP
• Gera stubs de manipuladores com a orientação de segurança do Google incorporada:
  • requestUserInteraction() lembretes para ferramentas que mutam
  • Alertas de sanitização de entrada para entradas de string livres
  • readOnlyHint anotações para ferramentas apenas de consulta

Segurança por padrão

O WebMCP permite que agentes de IA executem ferramentas que afetam aplicações web ao vivo. O Google aconselha o uso de ganchos de intervenção humana e proteção contra injeção de prompt indireta. O webmcp-gen incorpora isso em cada stub de manipulador gerado — ferramentas que mutam recebem lembretes de requestUserInteraction(), entradas livres recebem alertas de sanitização. Padrões seguros, não pensamentos posteriores.

Instalação

npm install -g webmcp-gen

Inclui 4 modelos iniciais (CRUD, pesquisa, manipulador de formulários, transformador de dados) para te ajudar a começar:

webmcp-gen --template crud-api
webmcp-gen --api crud-api.ts

Licença MIT. Contribuições são bem-vindas.

v1.2.0 — lançamento com segurança reforçada

A versão atual do npm (v1.2.0) passou por uma auditoria de segurança de 4 agentes cobrindo varredura de diferenças linha por linha, rastreamento entre arquivos, análise de comportamento removido e revisão de segurança dedicada. 10 descobertas foram corrigidas antes do anúncio público, incluindo endurecimento contra injeções no código gerado, proteção contra travessia de caminho e compatibilidade com o Chrome 150 (a API de teste de origem mudou de navigator.modelContext para document.modelContext). Registro de alterações completo no README.

GitHub: oliuntangled/webmcp-gen
npm: webmcp-gen

Não afiliado ou endossado pelo Google ou pelo W3C. Construído com assistência de IA.