WebMCP on your site|INEMA.CLUB-PRO

Lesson 7 · 18 min

Design the catalog and migrate an existing site without breaking anyone

A good catalog has few tools, each with one intent, a verb-based name, minimal input, and an error the agent understands. On a site that already exists, the rule moves out of the interface into a function that serves both the click and the tool. In this lesson you review a bad catalog with the validator and plan the migration of your site.

Start the lesson
A dark workshop parts cabinet with small drawers and blank labels, one of them open showing neatly organized connectors.

In this lesson you will

  1. 1One intent per tool, verb-based name, minimal input
  2. 2The kit's validator: spec rules and course rules
  3. 3An error the agent understands: return { erro } instead of throwing
  4. 4Migrate: inventory, shared rule, thin wrapper, fallback

Goal: design a small catalog (one intent per tool), review it with the validator, and integrate it into an existing site with detection and fallback.

01Migrate without breaking people who don't have the API

Click each step.

Click each block in the diagram to see what it does.

Steps adapted from the integration modules of the old track, now with the 10/16/2026 API.

02Rules of a good catalog

The ones the validator checks and the ones only you can check.

1. Intent

Two tools that answer the same request force the agent to guess.

Start from the person's journey, not from the list of buttons.

Goodbuscar_oficinas · reservar_vaga · minhas_reservas

03The validator against a bad catalog

validar-catalogo.mjs reads the definitions without opening a browser or running anything. An error fails (exit 1); a warning does not.

Terminal · bad catalog and the kit's catalog
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: $?"
Example from the repository
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

Spec rules: name, non-empty description, unique names. Course rules: closed, described object schema, known and consistent annotations, a name for an action with effects marked with consequentialHint.

04In a framework: register on mount, abort on unmount

Template to adapt (does not run in the kit). Angular has experimental support, according to the Chrome doc from 10/07/2026; the pattern below works for any framework.

Template · React component
useEffect(() => {
  const mc = document.modelContext;
  if (!mc) return;                       // no API: the screen stays the same
  const ciclo = new AbortController();
  registrar(mc, catalogo(agenda, ui), ciclo.signal).catch(() => {});
  return () => ciclo.abort();            // unmounted: the tools leave
}, [agenda]);
Template · JavaScript without a framework
// entrar na tela
const ciclo = new AbortController();
if (document.modelContext) await registrar(document.modelContext, defsDaTela, ciclo.signal);
// sair da tela (rota nova, modal fechado)
ciclo.abort();

05Practice

The validator and your site's plan. Each exercise ends with a done when.

E1 · Watch the validator fail

3 min

Run the validator block.

Done when: node scripts/validar-catalogo.mjs catalogos/ruim.mjs; echo "saída: $?" → CATÁLOGO: 4 ferramentas · 5 erros · 8 avisos and saída: 1; the kit's own catalog → 0 erros and saída: 0.

E2 · Fix the bad catalog

15 min

Copy catalogos/ruim.mjs to catalogos/meu.mjs and fix it until the errors are gone: a name with no spaces, a useful description, a boolean and known annotation, cancelar_reserva with consequentialHint.

Done when: node scripts/validar-catalogo.mjs catalogos/meu.mjs; echo "saída: $?" → 0 erros and saída: 0.

E3 · Inventory of your site

20 min

For your own site, write the inventory (form → handler → service → endpoint) and pick 3 tools: 2 that only read and 1 with a side effect, with the confirmation screen.

Done when: A file catalogo-[your site].md with the 3 tools (name, description, input, annotation) and the shared rule for each one.

06Lesson quiz

The explanation appears after your answer.

Question 1 of 4

The execute throws Error('sem vaga'). What does the agent receive in Chromium 156?

07In three sentences

CatalogFew tools, one intent each, a closed input, and errors returned as data.
ValidatorRules from the spec and the course, no browser: run it before you publish.
MigrationInventory, shared rule, thin wrapper, and the site works the same in the Sem mode.

To go further

Chrome for Developers: WebMCP (limitations and frameworks)Spec: execution errors (tool execution error)Course 1: designing a good tool on the MCP server
Previous lessonNext lesson