API imperativa

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky
François Beaufort
François Beaufort
GitHub

Publicado em: 18 de maio de 2026

Explicação Web Extensões Status do Chrome Intenção
GitHub Teste para desenvolvedores Período de teste para desenvolvedores Teste para desenvolvedores Período de teste para desenvolvedores Ver Intenção de experimentar

É possível usar a API imperativa do WebMCP para definir vários tipos de ferramentas com JavaScript padrão. Suas ferramentas podem executar diferentes funções, como entrada de formulário, navegação no site e gerenciamento de estado.

Antes de usar essa API, leia sobre exemplos de casos de uso.

Fornecer contexto do modelo

Use a interface modelContext para registrar ferramentas. O registro de ferramentas exige um nome, uma descrição e um esquema de entrada com propriedades relevantes.

Use registertool para adicionar uma única ferramenta ao contexto do modelo.

WebMCPza Maker

navigator.modelContext.registerTool({
  name: 'toggle_layer',
  description: 'Control pizza layers (sauce, cheese). Use "add", "remove", or "toggle".',
  inputSchema: {
    type: 'object',
    properties: {
      layer: { type: 'string', enum: ['sauce-layer', 'cheese-layer'] },
      action: { type: 'string', enum: ['add', 'remove', 'toggle'] },
    },
    required: ['layer'],
  },
  execute: ({ layer, action }) => {
    toggleLayer(layer, action);
    return `Performed ${action || 'toggle'} on layer: ${layer}`;
  },
});

Verificar o status do pedido

navigator.modelContext.registerTool({
  name: 'get_order_status',
  description: 'Search orders in a given timeframe. Returns order number, shipping status and location',
  inputSchema: {
    "type": "object",
    "properties": {
      "timeframe": { "type": "string", "oneOf": [
        { "type": "string", "const": "today", "title": "Today" },
        { "type": "string", "const": "yesterday", "title": "Yesterday" },
        { "type": "string", "const": "last_7_days", "title": "Last 7 Days" },
        { "type": "string", "const": "last_30_days", "title": "Last 30 Days" },
        { "type": "string", "const": "last_6_months", "title": "Last 6 Months" }],
      "enum": [ "today", "yesterday", "last_7_days", "last_30_days", "last_6_months" ],
      "description": "Timeframe for the order lookup." }
    },
    "required": [ "timeframe" ]
  },
  execute: ({ timeframe }) => {
    // Add your API or database logic here to fetch and return the order data as a string.
  },
});

É possível remover uma ferramenta com AbortSignal, quando transmitida como um parâmetro opcional.

const addTodoTool = {
  name: "addTodo",
  description: "Add a new item to the to-do list",
  inputSchema: {
    type: "object",
    properties: { text: { type: "string" } },
  },
  execute: ({ text }) => {
    // You should handle the persistence logic here (omitted for demo)
    return `Added to-do: ${text}`;
  },
  annotations: {
    readOnlyHint: false,
    untrustedContentHint: true
  },
};
const controller = new AbortController();
navigator.modelContext.registerTool(addTodoTool, { signal: controller.signal });

// Unregister the tool later...
controller.abort();

Descubra as ferramentas

Para conferir as ferramentas disponíveis, use navigator.modelContext.getTools(). Esse método assíncrono retorna uma lista de ferramentas que o documento de chamada está autorizado a acessar com base na origem dele.

const [tool] = await navigator.modelContext.getTools();
console.log(tool);

// {
//   annotations: { readOnlyHint: false, untrustedContentHint: true },
//   description: "Add a new item to the to-do list",
//   inputSchema: '{"type":"object","properties":{"text":{"type":"string"}}}',
//   name: "addTodo",
//   origin: "https://example.com",
//   window: Window {window: Window, self: Window, ...},
// }

Executar ferramenta

Para executar manualmente uma ferramenta descoberta em getTools(), chame navigator.modelContext.executeTool() com argumentos de entrada como uma string JSON válida. Esse método assíncrono retorna o resultado da execução da ferramenta ou nulo quando uma navegação é acionada.

const result = await navigator.modelContext.executeTool(tool, '{"text": "Buy milk"}');
console.log(result);

// 'Added to-do: Buy milk'

É possível cancelar uma execução de ferramenta pendente com AbortSignal, quando transmitido como um parâmetro opcional.

const controller = new AbortController();
navigator.modelContext.executeTool(tool, '{"text": "Buy milk"}', {
  signal: controller.signal,
});

// Cancel tool execution later...
controller.abort();

Eventos

Os frames podem detectar o evento toolchange em navigator.modelContext para receber uma notificação quando a lista de ferramentas disponíveis mudar.

navigator.modelContext.addEventListener("toolchange", (event) => {
  // Tools have changed.
});

iframes entre origens

O WebMCP é compatível com iframes de origem cruzada que usam políticas de permissão e controle de origem explícito.

Política de permissões

O registro de ferramentas fica desativado por padrão em iframes de origem cruzada. Uma página precisa delegar acesso usando a tools política de permissões:

<iframe src="https://example.com" allow="tools"></iframe>

Exposição de origem

Por padrão, as ferramentas não estão disponíveis para documentos de origem cruzada. É possível usar a matriz exposedTo em registerTool para listar origens específicas que podem ver e executar uma ferramenta. Essa matriz é compatível apenas com origens que usam o protocolo HTTPS.

navigator.modelContext.registerTool({
  name: 'my_shared_tool',
  description: 'Shared across origins',
  // ...
}, {
  exposedTo: ['https://trusted.com', 'https://partner.org']
});

Engajamento e como compartilhar feedback

O WebMCP está em discussão e sujeito a mudanças no futuro. Se você testar essa API e tiver feedback, envie sua opinião.