Imperative API

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

Opublikowano: 18 maja 2026 r., ostatnia aktualizacja: 1 lipca 2026 r.

Wyjaśniający Sieć Rozszerzenia Stan Chrome Intencja
GitHub Wersja próbna origin Testowanie origin 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żywaj interfejsu modelContext. Rejestracja narzędzia wymaga podania nazwy, opisu i schematu danych wejściowych z odpowiednimi właściwościami.

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

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

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

Odkrywanie narzędzi

Aby pobrać dostępne narzędzia, użyj document.modelContext.getTools(). Ta asynchroniczna metoda zwraca uporządkowaną alfabetycznie listę narzędzi, do których dostęp ma wywołujący dokument.

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 getTools() zwraca tylko narzędzia z tej samej domeny zarejestrowane przez wywołujący dokument lub inne dokumenty z tej samej domeny w drzewie ramek. Aby pobrać narzędzia współdzielenia, musisz wyraźnie wymienić ich pochodzenie w opcji fromOrigins. Ta tablica obsługuje tylko bezpieczne domeny.

Narzędzia z dokumentów z różnych domen są uwzględniane tylko wtedy, gdy:

  1. domena hostingu jest wymieniona 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 internetowym interfejsie czatu znajdziesz w wersji demonstracyjnej agenta strony WebMCP.

Uruchamianie narzędzia

Aby ręcznie uruchomić narzędzie wykryte w getTools(), wywołaj document.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 wywołana nawigacja.

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

// 'Added to-do: Buy milk'

Oczekiwanie na wykonanie narzędzia możesz anulować za pomocą AbortSignal, gdy jest ono przekazywane 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 zmianie listy dostępnych narzędzi.

document.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 wyraźnego ograniczania dostępu do domeny.

Zasady dotyczące uprawnień

Rejestracja narzędzi jest domyślnie wyłączona w elementach iframe ze współdzieleniem. Strona musi delegować dostęp za pomocą tools zasady dotyczącej uprawnień:

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

Udostępnianie domeny

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

// https://partner.org

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

Obsługa Reacta

React eksperymentalnie obsługuje WebMCP za pomocą pakietu usewebmcp. Jeśli Twoja aplikacja jest już napisana w React, możesz zarejestrować narzędzia za pomocą samodzielnych haków powiązanych z cyklem życia montowania i odmontowywania komponentu. Hak useWebMCP zapewnia też wnioskowanie o typach na podstawie schematu i udostępnia lokalny stan wykonania.

Obsługa Angulara

Angular eksperymentalnie obsługuje 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łów w narzędzia WebMCP.

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.