Imperative API

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

Published: May 18, 2026, Last updated: June 2, 2026

الشارح الويب الإضافات حالة Chrome النيّة بالشراء
GitHub فترة تجريبية للمطوّرين فترة تجريبية للمطوّرين العرض النيّة في إجراء تجربة

يمكنك استخدام WebMCP Imperative API لتحديد أنواع عديدة من الأدوات باستخدام JavaScript العادي. يمكن لأدواتك تنفيذ وظائف مختلفة، مثل إدخال البيانات في النماذج والتنقّل في الموقع الإلكتروني وإدارة الحالة.

قبل استخدام واجهة برمجة التطبيقات هذه، اطّلِع على حالات الاستخدام النموذجية.

توفير سياق النموذج

استخدِم واجهة 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 Page Agent للحصول على مثال حول كيفية استرداد الأدوات من إطار 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 من مصادر متعددة التي تستخدم كلاً من سياسات الأذونات وعملية التحكّم الصريح في المصدر.

سياسة الأذونات

يتم إيقاف تسجيل الأدوات تلقائيًا في إطارات iframe من مصادر متعددة. يجب أن تفوّض الصفحة إمكانية الوصول باستخدام "سياسة الأذونات" `tools`: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']
});

التفاعل ومشاركة الملاحظات

تتم مناقشة WebMCP حاليًا وقد تتغيّر في المستقبل. إذا جرّبت واجهة برمجة التطبيقات هذه وكانت لديك ملاحظات، يُسعدنا تلقّيها.