API دستوری

الکساندرا کلپر
Alexandra Klepper
GitHub Bluesky
فرانسوا بوفور
François Beaufort
GitHub

منتشر شده: ۱۸ مه ۲۰۲۶، آخرین به‌روزرسانی: ۲ ژوئن ۲۰۲۶

توضیح دهنده وب افزونه‌ها وضعیت کروم قصد
گیت‌هاب نسخه آزمایشی توسعه‌دهنده نسخه آزمایشی توسعه‌دهنده مشاهده قصد آزمایش

شما می‌توانید از WebMCP Imperative API برای تعریف انواع مختلفی از ابزارها با جاوا اسکریپت استاندارد استفاده کنید. ابزارهای شما می‌توانند عملکردهای مختلفی مانند ورودی فرم، پیمایش سایت و مدیریت وضعیت را اجرا کنند.

قبل از استفاده از این API، موارد استفاده از آن را مطالعه کنید.

زمینه مدل را فراهم کنید

از رابط modelContext برای ثبت ابزارها استفاده کنید. ثبت ابزار نیاز به نام، توضیحات و طرح ورودی با ویژگی‌های مربوطه دارد.

registertool برای اضافه کردن یک ابزار واحد به متن مدل استفاده کنید.

سازنده WebMCPza 

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']
});

برای مثالی از نحوه بازیابی ابزارها از یک iframe و اجرای آنها در یک رابط چت مبتنی بر وب، به نسخه آزمایشی WebMCP Page Agent مراجعه کنید.

ابزار اجرا

برای اجرای دستی ابزاری که در 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.
});

آیفریم‌های چندمنبعی

WebMCP از iframe های بین مبدایی که هم از سیاست‌های مجوز و هم از دروازه‌های مبدا صریح استفاده می‌کنند، پشتیبانی می‌کند.

سیاست مجوزها

ثبت ابزار به طور پیش‌فرض در iframe های cross-origin غیرفعال است. یک صفحه باید با استفاده از سیاست مجوزهای tools ، دسترسی را واگذار کند:

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

قرار گرفتن در معرض منشاء

ابزارها به طور پیش‌فرض برای اسناد cross-origin در دسترس نیستند. می‌توانید از آرایه exposedTo درون registerTool برای فهرست کردن originهای خاصی که مجاز به مشاهده و اجرای یک ابزار هستند، استفاده کنید. این آرایه فقط originهای امن را پشتیبانی می‌کند.

// https://partner.org

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

مشارکت کنید و بازخورد خود را به اشتراک بگذارید

WebMCP در حال حاضر در دست بررسی است و ممکن است در آینده تغییر کند. اگر این API را امتحان کردید و بازخوردی داشتید، خوشحال می‌شویم آن را بشنویم.