API دستوری

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

منتشر شده: ۱۸ مه ۲۰۲۶

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

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

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

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

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

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

سازنده WebMCPza 

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 معتبر فراخوانی کنید. این متد ناهمزمان نتیجه اجرای ابزار را برمی‌گرداند، یا در صورت فعال شدن ناوبری، 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.
});

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

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

سیاست مجوزها

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

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

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

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

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

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

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