Imperative API

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

Opublikowano: 18 maja 2026 r., ostatnia aktualizacja: 2 czerwca 2026 r.

Wyjaśnienie Sieć Rozszerzenia Stan Chrome Intencja
GitHub Wersja próbna dla deweloperów Okres próbny dla deweloperów Wyświetl Zamiar przeprowadzenia eksperymentu

Za pomocą interfejsu WebMCP Imperative API możesz definiować wiele typów narzędzi za pomocą standardowego kodu JavaScript. Narzędzia mogą wykonywać różne funkcje, takie jak wprowadzanie danych do formularza, nawigacja po witrynie i zarządzanie stanem.

Zanim zaczniesz korzystać z tego interfejsu API, zapoznaj się z przykładami zastosowań.

Podawanie kontekstu modelu

Użyj interfejsu modelContext, aby zarejestrować narzędzia. Rejestracja narzędzia wymaga podania nazwy, opisu i schematu wejściowego z odpowiednimi właściwościami.

Użyj registertool, aby dodać pojedyncze narzędzie do kontekstu modelu.

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

Pobieranie stanu zamówienia

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

Narzędzie możesz usunąć za pomocą ikony AbortSignal, jeśli jest ono przekazywane jako parametr opcjonalny.

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

Odkryj narzędzia

Aby zobaczyć dostępne narzędzia, użyj gestu document.modelContext.getTools(). Ta asynchroniczna metoda zwraca listę narzędzi, do których wywołujący dokument ma uprawnienia dostępu.

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

Domyślnie metoda getTools() zwraca tylko narzędzia z tej samej domeny zarejestrowane przez dokument wywołujący lub inne dokumenty z tej samej domeny w drzewie ramek. Aby pobrać narzędzia z innych domen, musisz jawnie wymienić ich domeny w opcji fromOrigins. Ta tablica obsługuje tylko bezpieczne domeny.

Narzędzia z dokumentów z innych źródeł są uwzględniane tylko wtedy, gdy:

  1. Pochodzenie hostingu jest wymienione w opcji fromOrigins.
  2. Narzędzie zostało wyraźnie udostępnione Twojej domenie.
// 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']
});

Przykład pobierania narzędzi z elementu iframe i wykonywania ich w interfejsie czatu w przeglądarce znajdziesz w demonstracji agenta strony WebMCP.

Uruchom narzędzie

Aby ręcznie wykonać narzędzie wykryte w getTools(), wywołaj funkcję document.modelContext.executeTool() z argumentami wejściowymi w postaci prawidłowego ciągu tekstowego JSON. Ta metoda asynchroniczna zwraca wynik wykonania narzędzia lub wartość null, gdy zostanie wywołana nawigacja.

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

// 'Added to-do: Buy milk'

Możesz anulować oczekujące wykonanie narzędzia za pomocą parametru AbortSignal, jeśli zostanie on przekazany jako parametr opcjonalny.

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

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

Wydarzenia

Ramki mogą nasłuchiwać zdarzenia toolchange w document.modelContext, aby otrzymywać powiadomienia o zmianach na liście dostępnych narzędzi.

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

Elementy iframe z różnych domen

WebMCP obsługuje elementy iframe pochodzące z różnych źródeł, które korzystają zarówno z zasad dotyczących uprawnień, jak i z jawnego ograniczania dostępu do źródła.

Zasady dotyczące uprawnień

Rejestracja narzędzia jest domyślnie wyłączona w elementach iframe z innej domeny. Strona musi przekazać dostęp za pomocą tools zasad dotyczących uprawnień:

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

Narażenie źródła

Narzędzia są domyślnie niedostępne dla dokumentów z innych źródeł. Możesz użyć tablicy exposedTo w ramach registerTool, aby wyświetlić listę konkretnych źródeł, które mogą wyświetlać i wykonywać narzędzie. Ta tablica obsługuje tylko bezpieczne źródła.

// https://partner.org

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

Zaangażuj się i prześlij opinię

WebMCP jest obecnie przedmiotem dyskusji i w przyszłości może ulec zmianie. Jeśli wypróbujesz ten interfejs API i chcesz podzielić się opinią, chętnie ją poznamy.