Imperative API

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

Published: May 18, 2026, Last updated: July 1, 2026

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

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

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

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

استخدِم واجهة modelContext لتسجيل الأدوات. يتطلّب تسجيل الأداة اسمًا ووصفًا ومخططًا لإدخال البيانات يتضمّن الخصائص ذات الصلة.

استخدِم registertool لإضافة أداة واحدة إلى سياق النموذج.

WebMCPza Maker

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

الحصول على حالة الطلب

await 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();
await 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 سياسة الأذونات:

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

عرض المصدر

تكون الأدوات غير متاحة تلقائيًا للمستندات من مصادر متعددة. يمكنك استخدام مصفوفة exposedTo ضمن registerTool لإدراج مصادر معيّنة مسموح لها بعرض أداة وتنفيذها. لا تتيح هذه المصفوفة سوى المصادر الآمنة.

// https://partner.org

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

دعم Angular

يتوفّر في Angular دعم تجريبي لـ WebMCP. إذا كان تطبيقك مكتوبًا باستخدام Angular، يمكنك تسجيل الأدوات المرتبطة بدورة حقن التبعية في التطبيق وتحويل "نماذج الإشارات" إلى أدوات WebMCP.

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

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