Imperative API

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

Veröffentlicht am 18. Mai 2026, zuletzt aktualisiert am 1. Juli 2026

Erklärvideo Web Erweiterungen Chrome-Status Absicht
GitHub Ursprungstest Ursprungstest Ansicht Absicht zum Testen

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 vor der Verwendung dieser API die Anwendungsbeispiele.

Modellkontext angeben

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

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

WebMCPza Maker

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

Bestellstatus abrufen

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

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

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

Tools entdecken

Verwenden Sie document.modelContext.getTools(), um verfügbare Tools abzurufen. Diese asynchrone Methode gibt eine alphabetisch sortierte Liste von Tools zurück, auf die das aufrufende Dokument zugreifen darf.

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

Standardmäßig gibt getTools() nur Tools desselben Ursprungs zurück, die vom aufrufenden Dokument oder anderen Dokumenten desselben Ursprungs im Frame-Baum registriert wurden. Wenn Sie ursprungsübergreifende Tools abrufen möchten, müssen Sie ihre Ursprünge explizit in der Option fromOrigins auflisten. Dieses Array unterstützt nur sichere Ursprünge.

Tools aus ursprungsübergreifenden Dokumenten werden nur berücksichtigt, wenn:

  1. Der Hosting-Ursprung ist in der Option fromOrigins aufgeführt.
  2. Das Tool wurde explizit für Ihren Ursprung freigegeben.
// https://example.com

// Get same-origin tools only
const sameOriginTools = await document.modelContext.getTools();

// Get same-origin tools plus tools from specific cross-origin documents
const allTools = await document.modelContext.getTools({
  fromOrigins: ['https://partner.org']
});

In der WebMCP Page Agent-Demo finden Sie ein Beispiel dafür, wie Sie Tools aus einem iFrame abrufen und in einer webbasierten Chat-Oberfläche ausführen.

Tool ausführen

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

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

// 'Added to-do: Buy milk'

Sie können eine ausstehende Toolausführung mit AbortSignal abbrechen, wenn es als optionaler Parameter übergeben wird.

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

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

Ereignisse

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

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

Ursprungsübergreifende iFrames

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

Berechtigungsrichtlinie

Die Toolregistrierung ist in ursprungsübergreifenden iFrames standardmäßig deaktiviert. Eine Seite muss den Zugriff mit der tools Berechtigungsrichtlinie delegieren:

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

Ursprungsfreigabe

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

// https://partner.org

await document.modelContext.registerTool({
  name: 'my_shared_tool',
  description: 'Shared across origins',
  // ...
}, {
  exposedTo: ['https://example.com']
});

React-Unterstützung

React bietet experimentelle Unterstützung für WebMCP mit dem usewebmcp Paket. Wenn Ihre Anwendung bereits mit React geschrieben wurde, können Sie Tools mit eigenständigen Hooks registrieren, die an den Mount- und Unmount-Lebenszyklus Ihrer Komponente gebunden sind. Der Hook useWebMCP bietet auch schemagesteuerte Typinferenz und gibt den lokalen Ausführungsstatus aus.

Angular-Unterstützung

Angular bietet experimentelle Unterstützung für WebMCP. Wenn Ihre Anwendung bereits mit Angular geschrieben wurde, können Sie Tools registrieren, die an den Lebenszyklus der Abhängigkeitsinjektion der Anwendung gebunden sind, und Ihre Signal Forms in WebMCP-Tools umwandeln.

Mitmachen und Feedback geben

WebMCP wird aktiv diskutiert und kann sich in Zukunft ändern. Wenn Sie diese API testen und Feedback haben, freuen wir uns darauf.