API imperativa

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

Fecha de publicación: 18 de mayo de 2026. Última actualización: 28 de mayo 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 imperativa de WebMCP 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 según su origen.

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

Ejecuta la 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 una ejecución de 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 cambia 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 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 de 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 seguros.

document.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.