WebMCP en tu sitio|INEMA.CLUB-PRO

Clase 7 · 18 min

Diseñar el catálogo y migrar un sitio existente sin romper a nadie

Un buen catálogo tiene pocas tools, cada una con una intención, nombre con verbo, entrada mínima y un error que el agente entiende. En un sitio que ya existe, la regla sale de la interfaz hacia una función que atiende el clic y la tool. En esta clase revisas un catálogo malo con el validador y planeas la migración de tu sitio.

Empezar la lección
Gavetero de taller oscuro con cajones pequeños y etiquetas en blanco, uno de ellos abierto con conectores ordenados.

En esta lección vas a

  1. 1Una intención por tool, nombre con verbo, entrada mínima
  2. 2El validador del kit: reglas de la spec y reglas del curso
  3. 3Error que el agente entiende: devolver { erro } en vez de lanzar
  4. 4Migrar: inventario, regla compartida, wrapper fino, fallback

Objetivo: diseñar un catálogo pequeño (una intención por tool), revisarlo con el validador e integrarlo a un sitio existente con detección y fallback.

01Migrar sin romper a quien no tiene la API

Haz clic en cada etapa.

Haz clic en cada bloque del diagrama para ver qué hace.

Etapas adaptadas de los módulos de integración de la formación anterior, ahora con la API del 16/10/2026.

02Reglas de un buen catálogo

Las que el validador comprueba y las que solo tú puedes comprobar.

1. Intención

Dos herramientas que responden al mismo pedido obligan al agente a adivinar.

Empieza por el recorrido de la persona, no por la lista de botones.

Buenobuscar_oficinas · reservar_vaga · minhas_reservas

03El validador contra un catálogo malo

validar-catalogo.mjs lee las definiciones sin abrir el navegador ni ejecutar nada. El error reprueba (saída 1); el aviso no.

Terminal · catálogo malo y el del kit
cd ~/projetos/formacao-webmcp-site-v72/kit
node scripts/validar-catalogo.mjs catalogos/ruim.mjs; echo "saída: $?"
node scripts/validar-catalogo.mjs; echo "saída: $?"
Ejemplo del repositorio
ERRO  fazer tudo
      erro: nome fora da regra (1–128: letras, números, _ - .)
      aviso: descrição curta: diga o que faz, o que NÃO faz e quando usar
      aviso: sem inputSchema
      aviso: diga se só lê (readOnlyHint) ou se tem consequência (consequentialHint)
ERRO  buscar
      erro: anotação readOnlyHint não é true/false
      aviso: descrição curta: diga o que faz, o que NÃO faz e quando usar
      aviso: inputSchema aceita campo extra (use additionalProperties: false)
      aviso: campo "q" sem description
ERRO  cancelar_reserva
      erro: nome de ação com efeito sem consequentialHint
ERRO  ver_agenda
      erro: descrição vazia
      erro: anotação desconhecida: readOnly
      aviso: sem inputSchema
      aviso: diga se só lê (readOnlyHint) ou se tem consequência (consequentialHint)
CATÁLOGO: 4 ferramentas · 5 erros · 8 avisos
saída: 1
OK    buscar_oficinas
OK    listar_comentarios
OK    reservar_vaga
OK    minhas_reservas
CATÁLOGO: 4 ferramentas · 0 erros · 0 avisos
saída: 0

Reglas de la spec: nombre, descripción no vacía, nombres únicos. Reglas del curso: schema object cerrado y descrito, anotaciones conocidas y coherentes, nombre de acción con efecto marcado con consequentialHint.

04En un framework: registrar al montar, abortar al desmontar

Modelo para adaptar (no corre en el kit). Angular tiene soporte experimental, según la doc de Chrome del 07/10/2026; el patrón de abajo vale para cualquiera.

Modelo · componente React
useEffect(() => {
  const mc = document.modelContext;
  if (!mc) return;                       // sin la API: la pantalla sigue igual
  const ciclo = new AbortController();
  registrar(mc, catalogo(agenda, ui), ciclo.signal).catch(() => {});
  return () => ciclo.abort();            // se desmontó: las herramientas salen
}, [agenda]);
Modelo · JavaScript sin framework
// entrar en la pantalla
const ciclo = new AbortController();
if (document.modelContext) await registrar(document.modelContext, defsDaTela, ciclo.signal);
// salir de la pantalla (ruta nueva, modal cerrado)
ciclo.abort();

05Práctica

Validador y el plan de tu sitio. Cada ejercicio termina con un listo cuando.

E1 · Ver cómo el validador reprueba

3 min

Ejecuta el bloque del validador.

Listo cuando: node scripts/validar-catalogo.mjs catalogos/ruim.mjs; echo "saída: $?" → CATÁLOGO: 4 ferramentas · 5 erros · 8 avisos y saída: 1; el del kit → 0 erros y saída: 0.

E2 · Arreglar el catálogo malo

15 min

Copia catalogos/ruim.mjs a catalogos/meu.mjs y corrige hasta dejar los errores en cero: nombre sin espacios, descripción útil, anotación booleana y conocida, cancelar_reserva con consequentialHint.

Listo cuando: node scripts/validar-catalogo.mjs catalogos/meu.mjs; echo "saída: $?" → 0 erros y saída: 0.

E3 · Inventario de tu sitio

20 min

Para tu sitio, escribe el inventario (formulario → handler → servicio → endpoint) y elige 3 tools: 2 que solo leen y 1 con efecto, con la pantalla de confirmación.

Listo cuando: Un archivo catalogo-[tu sitio].md con las 3 tools (nombre, descripción, entrada, anotación) y la regla compartida de cada una.

06Prueba de la clase

La explicación aparece después de la respuesta.

Pregunta 1 de 4

El execute lanza Error('sem vaga'). ¿Qué recibe el agente en Chromium 156?

07En tres frases

CatálogoPocas tools, una intención cada una, entrada cerrada y error devuelto como dato.
ValidadorReglas de la spec y del curso, sin navegador: ejecútalo antes de publicar.
MigraciónInventario, regla compartida, wrapper delgado y el sitio igual en el modo Sem.

Para ir más allá

Chrome for Developers: WebMCP (limitaciones y frameworks)Spec: errores de ejecución (tool execution error)Curso 1: diseñar una buena tool en el servidor MCP
Clase anteriorSiguiente clase