Module 1.3 — Migrating Existing Sites

Create a functional inventory

What it is: Map forms, handlers, services, endpoints, and states before proposing tools.

Why learn: The audit reveals where the rule already exists and where the interface contains logic that needs to be separated.

Before modeling

Write the person’s request, the current state, and the evidence that will prove completion.

Starting error

Starting with a function name or a button produces a tool with no clear human purpose.

Predict before opening the code

What information changes the decision? What effect needs to appear in the interface? Answer before implementing.

form -> submitHandler -> enrollmentService -> POST /api/enrollments

Going deeper: evidence worth keeping

Record the input, previous state, decision made, result, and visible change on the page.

Also include a simulated failure and the observed behavior without WebMCP support.

Key concepts

forms

JS functions

APIs

state

Prioritize user journeys by value and risk

What it is: Not every feature deserves to be migrated first; weigh frequency, value, stability, and reversibility.

Why learn: The right scope delivers learning early without starting with a critical or poorly understood action.

Question	Strong contract	Weak contract
When to use it?	The description names intent and context.	“Does things” or “manages.”
What do you receive?	Only the data you need.	Generic, unlimited object.
What does it return?	Verifiable state and next action.	Text without a protocol.
How does it fail?	Code, reason, and recovery.	Opaque exception.

Do

✓ Use specific verbs.
✓ Delimit inputs.
✓ State the evidence.

Avoid

✗ Mix intentions.
✗ Accept any object.
✗ Hide effects.

prioridade = valor * frequencia * estabilidade / risco

Going deeper: evidence worth keeping

Record the input, previous state, decision made, result, and visible change on the page.

Also include a simulated failure and the observed behavior without WebMCP support.

Key concepts

value

frequency

risk

stability

Extract interface logic

What it is: The same domain function should serve both human clicks and WebMCP execution.

Why learn: Sharing the logic prevents divergence between the visual flow and the agent’s path.

Observe

Capture state, input, and context before the action.

Decide

Validate preconditions and choose the allowed transition.

Run

Apply the shared rule and respect cancellation.

Prove

Update the interface and return a structured result.

Checkpoint

If step 2 fails, the tool doesn't try to “make it work”: it returns an explicit recovery.

async function iniciarInscricao(input, context) {
  return enrollmentService.start(input, context);
}

Going deeper: evidence worth keeping

Record the input, previous state, decision made, result, and visible change on the page.

Also include a simulated failure and the observed behavior without WebMCP support.

Key concepts

common service

Adapter UI

adapter tool

single rule

Create thin wrappers

What it is: The tool translates arguments, calls the existing service, updates the UI, and returns a structured response.

Why learn: Small wrappers are easier to review and don't recreate the application inside the WebMCP registry.

REFERENCE CODE

execute: async (input, { signal }) => {
  const result = await service.start(input, { signal });
  ui.showDraft(result);
  return result;
}

Input

It is small, documented, and verifiable.

Execution

Reuses the application's actual rule.

Output

Lets you verify the effect and continue.

Read the code as a contract

Highlight where input is validated, where the effect happens, where cancellation arrives, and where the UI is updated.

Going deeper: evidence worth keeping

Record the input, previous state, decision made, result, and visible change on the page.

Also include a simulated failure and the observed behavior without WebMCP support.

Key concepts

translation

existing service

Synchronized UI

return

Publish with progressive enhancement

What it is: The human workflow remains functional when WebMCP is unavailable or disabled.

Why learn: An experimental technology is added as an additional capability, with monitoring and rollback.

Simulated failure

Run the scenario with missing state, invalid input, or unavailable capability.

Expected recovery

The response explains what failed, what remains safe, and which action can continue.

Minimum test matrix

✓ reproducible happy path

✓ actionable invalid input

✓ cancellation ends work

✓ fallback preserves the journey

✓ interface reflects the state

✓ backend maintains authorization

if (document.modelContext?.registerTool) {
  registerEnrollmentTools();
}

Going deeper: evidence worth keeping

Record the input, previous state, decision made, result, and visible change on the page.

Also include a simulated failure and the observed behavior without WebMCP support.

Key concepts

feature detect

fallback

rollout

rollback

Deliver the migration dossier

What it is: The dossier connects inventory, catalog, risks, implementation, tests, and publication plan.

Why learn: The migration becomes reviewable by product, development, security, and operations.

Synthesis exercise

1. Explain the problem without using the technology name.
2. Map the state before and after.
3. Implement the smallest functional proof.
4. Trigger a failure and record the recovery.
5. Deliver code, evidence, and one known limitation.

Module challenge

Create an inventory, tools map, risk assessment, migration plan, and first implementation on a real website.

Responsible Integrator criterion

The implementation must work, explain its limits, and preserve the human path when the experimental capability is unavailable.

entrega/
  inventario.md
  catalogo-tools.json
  riscos.md
  prova-funcional/
  plano-rollout.md

Going deeper: evidence worth keeping

Record the input, previous state, decision made, result, and visible change on the page.

Also include a simulated failure and the observed behavior without WebMCP support.

Key concepts

map

risk

functional proof

rollout

📦 Module delivery

Create an inventory, tools map, risk assessment, migration plan, and first implementation on a real website.

Acceptance criterion

The implementation works with WebMCP support and preserves the manual path when the API is unavailable.

Evidence

Include code, the tested scenario, the observed result, and a known limitation.

← Back to the learning path Next module: 1.4 →

Technical sources

Draft and official WebMCP repository
Rendered specification
Official snapshot: 26/08/2026 · commit 41d12f0. The declarative API remains experimental; validate the draft before production.