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 Permissions Policy:

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

دعم React

تتيح React دعمًا تجريبيًا لـ WebMCP باستخدام حزمة usewebmcp. إذا كان تطبيقك مكتوبًا باستخدام React، يمكنك تسجيل الأدوات باستخدام خطافات مستقلة مرتبطة بدورة حياة عملية التحميل والإلغاء للمكوّن. يوفّر الخطاف useWebMCP أيضًا استنتاجًا للنوع يستند إلى المخطط ويعرض حالة التنفيذ المحلية.

دعم Angular

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

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

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