API imperativa

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

Data di pubblicazione: 18 maggio 2026

Divulgatore Web Estensioni Stato di Chrome Intenzione
GitHub Prova per sviluppatori Prova per sviluppatori Visualizza Intenzione di sperimentare

Puoi utilizzare l'API imperativa WebMCP per definire molti tipi di strumenti con JavaScript standard. I tuoi strumenti possono eseguire diverse funzioni, come l'input del modulo, la navigazione del sito e la gestione dello stato.

Prima di utilizzare questa API, leggi gli esempi di casi d'uso.

Fornire il contesto del modello

Utilizza l'interfaccia modelContext per registrare gli strumenti. La registrazione dello strumento richiede un nome, una descrizione e uno schema di input con proprietà pertinenti,

Utilizza registertool per aggiungere un singolo strumento al contesto del modello.

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

Visualizzare lo stato dell'ordine

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: async ({ timeframe }) => {
    // Add your API or database logic here to fetch and return the order data as a string.
  },
});

Puoi rimuovere uno strumento con AbortSignal, se passato come parametro facoltativo.

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

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

Scoprire gli strumenti

Per visualizzare gli strumenti disponibili, utilizza navigator.modelContext.getTools(). Questo metodo asincrono restituisce un elenco di strumenti a cui il documento chiamante è autorizzato ad accedere in base alla sua origine.

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

Eseguire lo strumento

Per eseguire manualmente uno strumento rilevato in getTools(), chiama navigator.modelContext.executeTool() con gli argomenti di input come stringa JSON valida. Questo metodo asincrono restituisce il risultato dell'esecuzione dello strumento o null quando viene attivata una navigazione.

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

// 'Added to-do: Buy milk'

Puoi annullare l'esecuzione di uno strumento in attesa con AbortSignal, se passato come parametro facoltativo.

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

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

Eventi

I frame possono ascoltare l'evento toolchange su navigator.modelContext per ricevere una notifica quando l'elenco degli strumenti disponibili è cambiato.

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

Iframe multiorigine

WebMCP supporta gli iframe multiorigine che utilizzano sia le policy relative alle autorizzazioni sia il gating esplicito dell'origine.

Policy relativa alle autorizzazioni

Per impostazione predefinita, la registrazione degli strumenti è disattivata negli iframe multiorigine. Una pagina deve delegare l'accesso utilizzando la tools policy relativa alle autorizzazioni:

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

Esposizione dell'origine

Per impostazione predefinita, gli strumenti non sono disponibili per i documenti multiorigine. Puoi utilizzare l'array exposedTo all'interno di registerTool per elencare le origini specifiche autorizzate a visualizzare ed eseguire uno strumento. Questo array supporta solo le origini con il protocollo HTTPS.

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

Partecipare e condividere feedback

WebMCP è in fase di discussione attiva e sarà soggetto a modifiche in futuro. Se provi questa API e hai feedback, saremo felici di riceverli.