命令式 API

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

發布日期：2026 年 5 月 18 日

說明 網頁 擴充功能 Chrome 狀態 意圖
GitHub 開發人員試用 開發人員試用 開發人員試用 開發人員試用 查看 實驗意圖

您可以使用 WebMCP Imperative API，透過標準 JavaScript 定義多種工具。工具可以執行各種函式，例如表單輸入、網站導覽和狀態管理。

使用這項 API 前，請先瞭解用途範例。

提供模型背景資訊

使用 modelContext 介面註冊工具。註冊工具時，必須提供名稱、說明和輸入結構定義，並包含相關屬性，

使用 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: ({ layer, action }) => {
    toggleLayer(layer, action);
    return `Performed ${action || 'toggle'} on layer: ${layer}`;
  },
});

取得訂單狀態

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

您可以傳遞 AbortSignal 做為選用參數，移除工具。

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

探索工具

如要查看可用的工具，請使用 navigator.modelContext.getTools()。這個非同步方法會根據呼叫文件的來源，傳回呼叫文件有權存取的工具清單。

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

執行工具

如要手動執行 getTools() 中探索到的工具，請呼叫 navigator.modelContext.executeTool()，並將輸入引數做為有效的 JSON 字串。這個非同步方法會傳回工具執行結果，或在觸發導覽時傳回空值。

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

// 'Added to-do: Buy milk'

當做選用參數傳遞時，您可以使用 AbortSignal 取消待處理的工具執行作業。

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

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

事件

影格可以監聽 navigator.modelContext 上的 toolchange 事件，以便在可用工具清單變更時收到通知。

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

跨來源 iframe

WebMCP 支援使用權限政策和明確來源閘道機制的不同來源 iframe。

權限政策

在跨來源 iframe 中，工具註冊功能預設為停用。網頁必須使用tools 權限政策委派存取權：

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

來源曝光

根據預設，工具無法用於跨原始來源文件。您可以在 registerTool 中使用 exposedTo 陣列，列出允許檢視及執行工具的特定來源。這個陣列只支援使用 HTTPS 通訊協定的來源。

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

參與討論及分享意見

WebMCP 目前仍在討論階段，日後可能會有變動。歡迎試用這項 API 並提供意見。