Imperative API

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

פורסם: 18 במאי 2026, עדכון אחרון: 18 ביוני 2026

סרטון הסבר פיתוח אתרים תוספים הסטטוס של Chrome הרציונל
GitHub גרסת מקור לניסיון גרסת מקור לניסיון תצוגה הבעת עניין בהשתתפות בניסוי

אפשר להשתמש ב-WebMCP Imperative API כדי להגדיר סוגים רבים של כלים באמצעות JavaScript רגיל. הכלים יכולים לבצע פונקציות שונות, כמו הזנת טופס, ניווט באתר וניהול מצב.

לפני שמשתמשים ב-API הזה, כדאי לקרוא על תרחישי שימוש לדוגמה.

מתן הקשר למודל

משתמשים בממשק modelContext כדי לרשום כלים. כדי לרשום כלי, צריך לציין שם, תיאור וסכימת קלט עם מאפיינים רלוונטיים.

משתמשים ב-registertool כדי להוסיף כלי יחיד להקשר של המודל.

WebMCPza Maker

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

קבלת סטטוס ההזמנה

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

אפשר להסיר כלי באמצעות 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();
document.modelContext.registerTool(addTodoTool, { signal: controller.signal });

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

לכל הכלים

משתמשים ב-document.modelContext.getTools() כדי לאחזר את הכלים הזמינים. השיטה האסינכרונית הזו מחזירה רשימה של כלים בסדר אלפביתי שהמסמך שמבצע את הקריאה מורשה לגשת אליהם.

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

כברירת מחדל, הפונקציה getTools() מחזירה רק כלים מאותו מקור שנרשמו על ידי המסמך שקורא לפונקציה או על ידי מסמכים אחרים מאותו מקור בעץ המסגרות. כדי לאחזר כלים חוצי-מקורות, צריך לציין במפורש את המקורות שלהם באפשרות fromOrigins. המערך הזה תומך רק במקורות מאובטחים.

כלים ממסמכים ממקורות שונים נכללים רק אם:

  1. מקור האירוח מופיע באפשרות fromOrigins.
  2. הכלי נחשף באופן מפורש למקור.
// 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']
});

בהדגמה של סוכן דפים ב-WebMCP אפשר לראות דוגמה לאופן שבו מאחזרים כלים מ-iframe ומפעילים אותם בממשק צ'אט מבוסס-אינטרנט.

הפעלת הכלי

כדי להפעיל ידנית כלי שזוהה ב-getTools(), קוראים ל-document.modelContext.executeTool() עם ארגומנטים של קלט כמחרוזת JSON תקינה. השיטה האסינכרונית הזו מחזירה את התוצאה של הפעלת הכלי, או null כשמופעלת ניווט.

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

// 'Added to-do: Buy milk'

אפשר לבטל הפעלה של כלי בהמתנה באמצעות AbortSignal, כשמעבירים אותו כפרמטר אופציונלי.

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

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

אירועים

המסגרות יכולות להאזין לאירוע toolchange ב-document.modelContext כדי לקבל הודעה כשרשימת הכלים הזמינים משתנה.

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

מסגרות iframe חוצות-מקורות

‫WebMCP תומך במסגרות iframe ממקורות שונים שמשתמשות גם במדיניות הרשאות וגם בסינון מפורש של מקורות.

מדיניות ההרשאות

כברירת מחדל, רישום כלי מושבת ב-iframes חוצי-מקורות. דף צריך להעביר גישה באמצעות tools מדיניות ההרשאות:

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

חשיפה למקור

כברירת מחדל, כלים לא זמינים למסמכים ממקורות שונים. אפשר להשתמש במערך exposedTo בתוך registerTool כדי לציין רשימה של מקורות ספציפיים שמורשים להציג כלי ולהפעיל אותו. המערך הזה תומך רק במקורות מאובטחים.

// https://partner.org

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

תמיכה ב-Angular

ל-Angular יש תמיכה ניסיונית ב-WebMCP. אם האפליקציה שלכם כבר כתובה ב-Angular, אתם יכולים לרשום כלים שקשורים למחזור החיים של הזרקת התלות של האפליקציה ולהפוך את טפסי האותות שלכם לכלים של WebMCP.

איך משתתפים ומשתפים משוב

הפיתוח של WebMCP נמצא בעיצומו, ויכול להיות שהוא ישתנה בעתיד. אם תנסו את ה-API הזה ונשמח לקבל מכם משוב.