Imperative API

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

Opublikowano: 18 maja 2026 r.

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

Za pomocą imperatywnego interfejsu API WebMCP możesz definiować wiele typów narzędzi za pomocą standardowego JavaScriptu. Twoje narzędzia mogą wykonywać różne funkcje, takie jak wprowadzanie danych w formularzu, nawigacja po witrynie i zarządzanie stanem.

Zanim zaczniesz korzystać z tego interfejsu API, przeczytaj o przykładowych przypadkach użycia.

Podawanie kontekstu modelu

Do rejestrowania narzędzi użyj interfejsu modelContext. Rejestracja narzędzia wymaga podania nazwy, opisu i schematu wejściowego z odpowiednimi właściwościami.

Aby dodać pojedyncze narzędzie do kontekstu modelu, użyj polecenia registertool.

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

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: 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ą AbortSignal, gdy 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();
navigator.modelContext.registerTool(addTodoTool, { signal: controller.signal });

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

Odkrywanie narzędzi

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

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

Uruchamianie narzędzia

Aby ręcznie uruchomić narzędzie wykryte w getTools(), wywołaj navigator.modelContext.executeTool() z argumentami wejściowymi jako prawidłowym ciągiem JSON. Ta asynchroniczna metoda zwraca wynik wykonania narzędzia lub wartość null, gdy zostanie uruchomiona 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ą AbortSignal, gdy jest ono przekazywane 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 zmianie listy dostępnych narzędzi.

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

Elementy iframe z różnych domen

WebMCP obsługuje elementy iframe z różnych domen, 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 różnych domen. Strona musi delegować dostęp za pomocą tools zasady dotyczącej uprawnień:

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

Udostępnianie źródła

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

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 w trakcie aktywnej dyskusji i w przyszłości może ulec zmianie. Jeśli wypróbujesz ten interfejs API i masz jakieś uwagi, chętnie je poznamy.