API imperativa

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

Fecha de publicación: 18 de mayo de 2026

Explicativa Web Extensiones Estado de Chrome Intención
GitHub Versión de prueba para desarrolladores Prueba para desarrolladores Versión de 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

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

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

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: ({ 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();

Descubre herramientas

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

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

Ejecuta la herramienta

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

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

// 'Added to-do: Buy milk'

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

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

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

Eventos

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

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

Iframes de origen cruzado

WebMCP admite iframes de origen cruzado que usan políticas de permisos y puertas de enlace 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 orígenes específicos que pueden ver y ejecutar una herramienta. Este array solo admite orígenes con el protocolo HTTPS.

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

Participa y comparte comentarios

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