Imperatieve API

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

Gepubliceerd: 18 mei 2026

Uitleg Web Uitbreidingen Chrome-status Intentie
GitHub Ontwikkelaarsproef Ontwikkelaarsproef Weergave Voornemen om te experimenteren

Met de WebMCP Imperative API kunt u veel verschillende soorten tools definiëren met standaard JavaScript. Uw tools kunnen diverse functies uitvoeren, zoals formulierinvoer, sitenavigatie en statusbeheer.

Voordat u deze API gebruikt, lees dan eerst meer over voorbeelden van gebruiksscenario's .

Geef context aan het model.

Gebruik de modelContext interface om tools te registreren. Voor toolregistratie zijn een naam, een beschrijving en een invoerschema met relevante eigenschappen vereist.

Gebruik registertool om een ​​enkel hulpmiddel aan de modelcontext toe te voegen.

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

Bestelstatus opvragen 

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

Je kunt een tool verwijderen met AbortSignal , wanneer dit als optionele parameter wordt doorgegeven.

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

Ontdek tools

Om de beschikbare tools te bekijken, gebruikt u navigator.modelContext.getTools() . Deze asynchrone methode retourneert een lijst met tools waartoe het aanroepende document toegang heeft op basis van de herkomst ervan.

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

Uitvoeren tool

Om een ​​tool die is gevonden in getTools() handmatig uit te voeren, roept u navigator.modelContext.executeTool() aan met een geldige JSON-string als invoerargument. Deze asynchrone methode retourneert het resultaat van de tooluitvoering, of null wanneer een navigatie wordt geactiveerd.

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

// 'Added to-do: Buy milk'

Je kunt een lopende tooluitvoering annuleren met AbortSignal , wanneer dit als optionele parameter wordt doorgegeven.

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

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

Evenementen

Frames kunnen luisteren naar de toolchange gebeurtenis op navigator.modelContext om een ​​melding te ontvangen wanneer de lijst met beschikbare tools is gewijzigd.

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

Cross-origin iframes

WebMCP ondersteunt cross-origin iframes die gebruikmaken van zowel toestemmingsbeleid als expliciete oorsprongsfiltering.

Toestemmingsbeleid

Het registreren van tools is standaard uitgeschakeld in cross-origin iframes. Een pagina moet toegang delegeren via het machtigingsbeleid tools .

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

Oorsprong blootstelling

Tools zijn standaard niet beschikbaar voor documenten van verschillende oorsprongen. U kunt de array exposedTo binnen registerTool gebruiken om specifieke oorsprongen op te geven die een tool mogen bekijken en uitvoeren. Deze array ondersteunt alleen beveiligde oorsprongen.

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

Betrek de deelnemers en deel je feedback.

WebMCP is onderwerp van actieve discussie en kan in de toekomst nog veranderen. Als u deze API uitprobeert en feedback heeft, horen we dat graag.