API imperativa

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

Publicado: 18 de mayo de 2026, última actualización: 1 de junio de 2026

Explicativa Web Extensiones Estado de Chrome Intención
GitHub Prueba para desarrolladores Prueba para desarrolladores Ver Intención de experimentar

Puedes usar la API de WebMCP Imperative para definir muchos tipos de herramientas con JavaScript estándar. Tus herramientas pueden ejecutar diferentes funciones, como la entrada de formularios, la navegación por el sitio y la administración de estados.

Antes de usar esta API, lee sobre los casos de uso de ejemplo.

Proporciona contexto del modelo

Usa la interfaz modelContext para registrar herramientas. El registro de herramientas requiere un nombre, una descripción y un esquema de entrada con propiedades relevantes.

Usa registertool para agregar una sola herramienta al contexto del modelo.

WebMCPza Maker

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}`;
  },
});

Obtén el estado del 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.
  },
});

Puedes quitar una herramienta con AbortSignal cuando se pasa como un 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();

Descubre herramientas

Para ver las herramientas disponibles, usa document.modelContext.getTools(). Este método asíncrono devuelve una lista de herramientas a las que el documento que realiza la llamada tiene autorización para acceder.

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, ...},
// }

De forma predeterminada, getTools() solo devuelve herramientas del mismo origen registradas por el documento de llamada o por otros documentos del mismo origen en el árbol de marcos. Para recuperar herramientas de origen cruzado, debes enumerar de forma explícita sus orígenes en la opción fromOrigins. Este array solo admite orígenes seguros.

Las herramientas de documentos de origen cruzado solo se incluyen si se cumplen las siguientes condiciones:

  1. El origen del hosting aparece en la opción fromOrigins.
  2. La herramienta se expuso explícitamente a tu origen.
// https://example.com

// Get same-origin tools only
const sameOriginTools = await document.modelContext.getTools();

// Get same-origin tools plus tools from specific cross-origin documents
const allTools = await document.modelContext.getTools({
  fromOrigins: ['https://partner.org']
});

Ejecutar herramienta

Para ejecutar manualmente una herramienta descubierta en getTools(), llama a document.modelContext.executeTool() con argumentos de entrada como una cadena JSON válida. Este método asíncrono devuelve el resultado de la ejecución de la herramienta o un valor nulo cuando se activa una navegación.

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

// 'Added to-do: Buy milk'

Puedes cancelar la ejecución de una herramienta pendiente con AbortSignal, cuando se pasa como un parámetro opcional.

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

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

Eventos

Los marcos pueden escuchar el evento toolchange en document.modelContext para recibir una notificación cuando cambie la lista de herramientas disponibles.

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

Iframes de origen cruzado

WebMCP admite iframes de origen cruzado que usan políticas de permisos y restricciones de origen explícitas.

Política de permisos

El registro de herramientas está inhabilitado de forma predeterminada en los iframes de origen cruzado. Una página debe delegar el acceso con la tools Política de permisos:

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

Exposición del origen

Las herramientas no están disponibles para los documentos de origen cruzado de forma predeterminada. Puedes usar el array exposedTo dentro de registerTool para enumerar los orígenes específicos que pueden ver y ejecutar una herramienta. Este array solo admite orígenes seguros.

// https://partner.org

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

Interactúa y comparte comentarios

WebMCP se encuentra en debate activo y está sujeto a cambios en el futuro. Si pruebas esta API y tienes comentarios, nos encantaría recibirlos.