Imperative API

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

Data publikacji: 18 maja 2026 r., ostatnia aktualizacja: 1 lipca 2026 r.

Wyjaśnienie Sieć Rozszerzenia Stan Chrome Intencja
GitHub Wersja próbna origin Wersja próbna origin 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

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

Pobieranie stanu zamówienia

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

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

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

Odkryj narzędzia

Użyj document.modelContext.getTools(), aby pobrać dostępne narzędzia. Ta asynchroniczna metoda zwraca posortowaną alfabetycznie listę narzędzi, do których dokument wywołujący 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 funkcja 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 wyraźnie wymienić ich źródła w opcji fromOrigins. Ta tablica obsługuje tylko bezpieczne źródła.

Narzędzia z dokumentów z innych domen 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 asynchroniczna metoda 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ę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. W tablicy exposedTo w ramach registerTool możesz podać konkretne źródła, które mogą wyświetlać i uruchamiać narzędzie. Ta tablica obsługuje tylko bezpieczne źródła.

// https://partner.org

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

Obsługa Angulara

Angular ma eksperymentalną obsługę WebMCP. Jeśli Twoja aplikacja jest już napisana w Angularze, możesz zarejestrować narzędzia powiązane z cyklem życia wstrzykiwania zależności aplikacji i przekształcić formularze sygnałowe w narzędzia WebMCP.

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.