Imperative API

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

Veröffentlicht am 18. Mai 2026

Erklärung Web Erweiterungen Chrome-Status Absicht
GitHub Testversion für Entwickler Entwicklertestzeitraum Testversion für Entwickler Entwicklertestzeitraum Ansicht Absichtserklärung für Tests

Mit der WebMCP Imperative API können Sie viele Arten von Tools mit Standard-JavaScript definieren. Ihre Tools können verschiedene Funktionen ausführen, z. B. Formulareingabe, Websitenavigation und Statusverwaltung.

Lesen Sie sich vor der Verwendung dieser API die Beispielanwendungsfälle durch.

Kontext für das Modell angeben

Verwenden Sie die modelContext-Schnittstelle, um Tools zu registrieren. Für die Toolregistrierung sind ein Name, eine Beschreibung und ein Eingabeschema mit relevanten Attributen erforderlich.

Verwenden Sie registertool, um dem Modellkontext ein einzelnes Tool hinzuzufügen.

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

Bestellstatus abrufen

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

Sie können ein Tool mit AbortSignal entfernen, wenn es als optionaler Parameter übergeben wird.

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

Tools entdecken

Mit navigator.modelContext.getTools() können Sie sich die verfügbaren Tools ansehen. Diese asynchrone Methode gibt eine Liste von Tools zurück, auf die das aufrufende Dokument basierend auf seinem Ursprung zugreifen darf.

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

Tool ausführen

Wenn Sie ein in getTools() gefundenes Tool manuell ausführen möchten, rufen Sie navigator.modelContext.executeTool() mit Eingabeargumenten als gültigen JSON-String auf. Diese asynchrone Methode gibt das Ergebnis der Tool-Ausführung zurück oder „null“, wenn eine Navigation ausgelöst wird.

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

// 'Added to-do: Buy milk'

Sie können eine ausstehende Tool-Ausführung mit AbortSignal abbrechen, wenn dieser Parameter als optionaler Parameter übergeben wird.

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

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

Ereignisse

Frames können auf navigator.modelContext auf das Ereignis toolchange warten, um benachrichtigt zu werden, wenn sich die Liste der verfügbaren Tools geändert hat.

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

Ursprungsübergreifende iFrames

WebMCP unterstützt ursprungsübergreifende iFrames, die sowohl Berechtigungsrichtlinien als auch explizite Ursprungsbeschränkungen verwenden.

Richtlinie für Berechtigungen

Die Tool-Registrierung ist in ursprungsübergreifenden iFrames standardmäßig deaktiviert. Auf einer Seite muss der Zugriff über die tools Berechtigungsrichtlinie delegiert werden:

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

Ursprungsgefährdung

Tools sind für ursprungsübergreifende Dokumente standardmäßig nicht verfügbar. Mit dem exposedTo-Array in registerTool können Sie bestimmte Ursprünge auflisten, die ein Tool ansehen und ausführen dürfen. Dieses Array unterstützt nur Ursprünge mit dem HTTPS-Protokoll.

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

Feedback geben

WebMCP befindet sich in der aktiven Diskussion und kann sich daher in Zukunft ändern. Wenn Sie diese API ausprobieren und Feedback dazu haben, würden wir uns freuen, wenn Sie uns dieses mitteilen.