Imperative API

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

Data publikacji: 18 maja 2026 r.

Wyjaśnienie Sieć Rozszerzenia Stan Chrome Intencja
GitHub Wersja próbna dla deweloperów Okres próbny dla deweloperów 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 JavaScriptu. 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

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

Pobieranie stanu zamówienia

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

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

Odkryj narzędzia

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

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

Uruchom narzędzie

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

const result = await navigator.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, gdy jest on przekazywany jako parametr opcjonalny.

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

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

Wydarzenia

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

navigator.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ędzi jest domyślnie wyłączona w elementach iframe z innego źródła. Strona musi delegować 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 domen. Możesz użyć tablicy exposedTo w ramach registerTool, aby podać konkretne źródła, które mogą wyświetlać i uruchamiać narzędzie. Ta tablica obsługuje tylko źródła z protokołem HTTPS.

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

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.