API imperativa

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

Publicado em 18 de maio de 2026, atualizado pela última vez em 28 de maio de 2026

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

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

Antes de usar essa API, leia sobre os casos de uso de exemplo.

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.

Criador de WebMCPza

document.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: async ({ layer, action }) => {
    await toggleLayer(layer, action);
    return `Performed ${action || 'toggle'} on layer: ${layer}`;
  },
});

Verificar o status do pedido

document.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: async ({ 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: async ({ 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();
document.modelContext.registerTool(addTodoTool, { signal: controller.signal });

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

Descobrir ferramentas

Para conferir as ferramentas disponíveis, use document.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.

const [tool] = await document.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 document.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 document.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 transmitida como um parâmetro opcional.

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

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

Eventos

Os frames podem detectar o evento toolchange em document.modelContext para serem notificados quando a lista de ferramentas disponíveis mudar.

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

iframes de origem cruzada

O WebMCP oferece suporte a iframes de origem cruzada que usam políticas de permissão e bloqueio de origem explícito.

Política de permissões

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

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

Exposição de origem

As ferramentas não estão disponíveis para documentos de origem cruzada por padrão. É possível usar a matriz exposedTo em registerTool para listar origens específicas permitidas para visualizar e executar uma ferramenta. Essa matriz só oferece suporte a origens seguras.

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

Interagir e compartilhar feedback

O WebMCP está em discussão ativa e sujeito a mudanças no futuro. Se você testar essa API e tiver feedback, gostaríamos de saber.