Imperative API

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

Published: May 18, 2026

วิดีโออธิบาย เว็บ ส่วนขยาย สถานะ 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: async ({ layer, action }) => {
    await 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: async ({ 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: 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();

ค้นพบเครื่องมือ

หากต้องการดูเครื่องมือที่พร้อมใช้งาน ให้ใช้ 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 ที่ถูกต้อง เมธอดแบบไม่พร้อมกันนี้จะแสดงผลลัพธ์ของการเรียกใช้เครื่องมือ หรือแสดงค่า Null เมื่อมีการทริกเกอร์การไปยังส่วนต่างๆ

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

กิจกรรม

เฟรมสามารถรับฟังเหตุการณ์ toolchange ใน navigator.modelContext เพื่อรับการแจ้งเตือนเมื่อรายการเครื่องมือที่พร้อมใช้งานมีการเปลี่ยนแปลง

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

iframe แบบข้ามต้นทาง

WebMCP รองรับ iframe แบบข้ามต้นทางที่ใช้นโยบายสิทธิ์และการควบคุมการเข้าถึงต้นทางอย่างชัดเจน

นโยบายสิทธิ์

การลงทะเบียนเครื่องมือจะปิดใช้โดยค่าเริ่มต้นใน iframe แบบข้ามต้นทาง หน้าเว็บต้อง มอบสิทธิ์เข้าถึงโดยใช้tools นโยบายสิทธิ์:

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

การเปิดเผยต้นทาง

เครื่องมือจะไม่พร้อมใช้งานสำหรับเอกสารแบบข้ามต้นทางโดยค่าเริ่มต้น คุณสามารถใช้อาร์เรย์ exposedTo ภายใน registerTool เพื่อแสดงรายการต้นทางที่เฉพาะเจาะจงซึ่งได้รับอนุญาตให้ดูและเรียกใช้เครื่องมือ อาร์เรย์นี้รองรับเฉพาะต้นทางที่ปลอดภัย

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

มีส่วนร่วมและแชร์ความคิดเห็น

WebMCP อยู่ระหว่างการพูดคุยอย่างจริงจังและอาจมีการเปลี่ยนแปลงในอนาคต หากคุณลองใช้ API นี้และมีความคิดเห็น โปรดแจ้งให้เราทราบ