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 العادي. يمكن لأدواتك تنفيذ وظائف مختلفة، مثل إدخال البيانات في النماذج والتنقّل في الموقع الإلكتروني وإدارة الحالة.

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

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

استخدِم واجهة 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 من مصادر متعددة تستخدم سياسات الأذونات وبوابات المصدر الصريحة.

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

يتم إيقاف تسجيل الأدوات تلقائيًا في إطارات iframe المتعددة المصادر. يجب أن تفوّض الصفحة إذن الوصول باستخدام 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، يمكنك تسجيل أدوات مرتبطة بدورة مراحل النشاط لإدخال الاعتمادية في التطبيق وتحويل "نماذج Signal" إلى أدوات WebMCP.

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

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