مرجع أدوات MCP

الأدوات التي يوفّرها خادم MCP: 12 أداة قراءة للتجارة والتحليلات (تحمل جميعها readOnlyHint: true) وحزمة منشئ المتجر — 21 أداة لقراءة واجهة المتجر وتعديلها ومعاينتها. كتابات منشئ المتجر تقع على مسودات؛ فلا يصل شيء مما تفعله أداة إلى المتسوقين دون أن ينشره إنسان، عدا الاستثناء الوحيد الموثّق أدناه builder_create_menu.

تعلن كل أداة عن مخطط JSON Schema يستطيع عميلك التحقق منه، وكل المخططات مغلقة (additionalProperties: false) — فالوسائط غير المعروفة تُرفض بالخطأ invalid_arguments بدل تجاهلها.

نظرة سريعة

الأداة	الصلاحية المطلوبة	ما تجيب عنه
`get_shop_info`	`STORE_SETTINGS` · `READ`	اسم المتجر وعملته ولغته وحالته
`get_store_metrics`	`ANALYTICS` · `READ`	الإيراد والطلبات ومتوسط قيمة الطلب والمرتجعات والتحويل لفترة
`get_today_snapshot`	`ANALYTICS` · `READ`	مبيعات اليوم وعدد الزوار الحاليين
`get_top_products`	`ANALYTICS` · `READ`	الأكثر مبيعًا بالإيراد أو بعدد القطع
`get_top_customers`	`CUSTOMERS` · `READ`	العملاء الأعلى إنفاقًا
`get_low_stock_products`	`PRODUCTS` · `READ`	ما أوشك على النفاد
`search_products`	`PRODUCTS` · `READ`	البحث عن منتج بالاسم أو SKU أو المورّد أو النوع
`get_product`	`PRODUCTS` · `READ`	تفاصيل منتج واحد كاملة
`list_categories`	`CATEGORIES` · `READ`	التصنيفات وعدد منتجات كل منها
`get_review_summary`	`REVIEWS` · `READ`	متوسط التقييم وتوزيعه وما ينتظر المراجعة
`list_recent_orders`	`ORDERS` · `READ`	طلبات فترة معينة
`get_order`	`ORDERS` · `READ`	طلب واحد برقمه، مع بنوده

صلاحية REVIEWS بمفتاح API فقط

لا يمنح أي نطاق في OAuth صلاحية REVIEWS، لذا تُرجع get_review_summary الخطأ permission_denied على اتصال OAuth. وكل أداة أخرى أعلاه متاحة بالطريقتين.

أدوات منشئ المتجر

تتطلب كل أداة من أدوات منشئ المتجر صلاحية THEME — بإجراء READ لأدوات القراءة والمعاينة، إضافة إلى WRITE لكتابات الترحيل إلى المسودة.

الأداة	النوع	ما تفعله
`builder_list_pages`	قراءة	صفحات واجهة المتجر: الأسماء والروابط والأنواع وحالة الظهور
`builder_get_page`	قراءة	شجرة مكونات صفحة واحدة كاملة مع إعدادات SEO والتخطيط — بعد معالجتها لتطابق ما يراه التجار فعلًا
`builder_list_drafts`	قراءة	المسودات المفتوحة وهل تحمل كل منها تغييرات غير منشورة
`builder_create_draft`	كتابة	مسودة جديدة مسمّاة لترحيل العمل عليها
`builder_update_page`	كتابة	استبدال شجرة مكونات صفحة على مسودة (يُتحقق منها وفق الكتالوج؛ ونقطة استعادة أولًا)
`builder_create_page` / `builder_delete_page`	كتابة	الصفحات المخصصة، على مسودة
`builder_get_theme` / `builder_update_theme`	قراءة / كتابة	مجموعات إعدادات الثيم وشريط التنقل والتذييل العامّان — التحديثات تقع على مسودة
`builder_get_theme_schema`	قراءة	كل مجموعات إعدادات themeV2 وحقولها مع القيمة الافتراضية لكل حقل — اقرأها قبل كتابة مجموعة لم يضبطها المتجر من قبل، إذ لا تُظهر `builder_get_theme` إلا ما يملكه المتجر فعلًا
`builder_upload_asset`	كتابة	رفع صورة لاستخدامها في الأقسام
`builder_create_menu`	كتابة	إنشاء قائمة تنقّل جديدة — شجرة الروابط التي يعرضها شريط التنقل أو التذييل أو قالب Custom Liquid. تكتب مباشرةً لا على مسودة (انظر أدناه)
`builder_get_components`	قراءة	كتالوج المكونات: الأنواع والأوصاف والوسوم وقواعد التداخل — قابل للترشيح
`builder_get_component`	قراءة	العقد الكامل لمكون واحد: الخصائص الافتراضية وكل إعداد قابل للتحرير
`builder_get_component_examples`	قراءة	أشجار أمثلة مجرّبة + قواعد تأليف الأشجار + دليل محاكاة التصاميم
`builder_list_liquid_components`	قراءة	تعريفات Custom Liquid الخاصة بالمتجر
`builder_get_liquid_examples`	قراءة	تعريفات Liquid مرجعية + قواعد التأليف
`builder_upsert_liquid_component`	كتابة	إنشاء أو استبدال تعريف Custom Liquid، على مسودة
`builder_preview_page`	قراءة	لقطة شاشة لصفحة (مباشرة أو مسودة) بمقاس سطح المكتب أو الجهاز اللوحي أو الجوال — تُعاد كصورة
`builder_capture_reference`	قراءة	التقاط تصميم مرجعي من رابط: لقطات شاشة + قياسات الخطوط والألوان ونطاقات الأقسام
`builder_compare_preview`	قراءة	مقارنة عرض مسودة بمرجع ملتقط: درجة تفاوت + صورة فروق بصرية

يُتاح كتالوج المكونات أيضًا كـ resources في MCP (taketheme://builder/components وtaketheme://builder/components/{type}) للعملاء الذين يقرؤون الموارد؛ وتقدّم الأدوات البيانات نفسها للعملاء الذين لا يقرؤونها.

توفّر المعاينة

تحتاج أدوات المعاينة الثلاث إلى خدمة المتصفح غير المرئي في بيئة النشر. وحيثما لم تكن مفعّلة تجيب بـ PREVIEW_UNAVAILABLE — ولا تتأثر أي أداة أخرى.

builder_create_menu هي الكتابة المباشرة الوحيدة

القوائم غير محفوظة بنسخ، فلا توجد مسودة تقع عليها. ومع ذلك فإنشاء قائمة آمن: القائمة الجديدة لا تُعرض في أي مكان حتى يشير إليها شيء عبر معرّفها النصي، وإنشاء تلك الإشارة — بتوجيه شريط التنقل إليها عبر builder_update_theme، أو بربطها في تعريف Liquid — هو نفسه تعديل مرحَّل يراجعه إنسان. أما تعديل قائمة قائمة فعلًا فغير متاح عمدًا، لأنه سيغيّر واجهة المتجر المباشرة دون شيء يُراجَع. والمعرّفات النصية فريدة داخل المتجر؛ والمعرّف المستخدَم يُرفض بدل الكتابة فوقه.

الأداة التي لا يحمل مفتاحك صلاحيتها تظل ظاهرة في tools/list، لكن استدعاءها يُرجع خطأ الأداة permission_denied.

الفترات الزمنية

تتشارك الأدوات التي تُبلّغ عن نافذة زمنية الوسائط الثلاثة نفسها. وتُحسب النوافذ النسبية في الخادم بتوقيت UTC — فالمساعدون الأذكياء غير موثوقين في حساب التواريخ، ويُفضَّل استخدام فترة مسمّاة بدل حساب التواريخ بنفسك.

الوسيط	النوع	الوصف
`period`	قائمة محددة	النافذة المطلوب التقرير عنها
`startDate`	نص	`YYYY-MM-DD`. مطلوب فقط حين تكون `period` بقيمة `custom`
`endDate`	نص	`YYYY-MM-DD`. مطلوب فقط حين تكون `period` بقيمة `custom`

القيم المقبولة لـ period: today وyesterday وlast_7_days وlast_30_days وlast_90_days وthis_week وlast_week وthis_month وlast_month وthis_year وcustom.

يبدأ الأسبوع يوم الاثنين. وحدود الأيام بتوقيت UTC، بما يطابق حدود مؤشرات لوحة التحكم — فلا تتعارض إجابات المحادثة مع أرقام اللوحة.

تعيد كل استجابة النافذة المحسوبة في حقل period بصيغة مقروءة ("the last 7 days" أو "2026-06-01 to 2026-06-30") ليذكر المساعد النافذة التي استُخدمت فعلًا.

get_shop_info

المعلومات الأساسية عن المتجر — يستحسن استدعاؤها مرة في بداية الجلسة ليُذكر كل رقم مالي بعملته الصحيحة.

الصلاحية: STORE_SETTINGS · READ · الوسائط: لا شيء

تُرجع

الحقل	الوصف
`storeName`	اسم المتجر
`currency`	العملة التي يبيع بها المتجر
`language`	اللغة الأساسية
`status`	حالة الحساب (`live` أو `readonly` أو `suspended` …)
`openedAt`	تاريخ إنشاء المتجر

get_store_metrics

مؤشرات المبيعات والطلبات الرئيسية لفترة، مع إمكانية مقارنتها بالفترة المكافئة السابقة.

الصلاحية: ANALYTICS · READ

الوسائط

الوسيط	النوع	الافتراضي	الوصف
`period` و`startDate` و`endDate`	—	`last_30_days`	راجع الفترات الزمنية
`compareToPrevious`	منطقي	`false`	إرجاع الفترة المكافئة السابقة ونسبة التغير أيضًا

تُرجع

الحقل	الوصف
`period`	وصف النافذة المحسوبة
`currency`	عملة كل الأرقام المالية
`startDate` / `endDate`	النافذة المحسوبة بصيغة ISO
`metrics`	كائن المؤشرات أدناه
`previousPeriod`	البنية نفسها، ويظهر حين تكون `compareToPrevious` بقيمة `true`
`change`	التغير مقارنة بالفترة السابقة

يحتوي metrics على: total_sales وtotal_orders وaov وunique_customers وtotal_items_sold وcancelled_orders وrefunded_orders وrefund_rate وfulfilled_orders وconversion_rate وrepeated_customer_rate وcod_orders وprepaid_orders.

تُحذف المؤشرات التي تعذّر حسابها وتُذكر أسماؤها في _degraded.unavailableFields — راجع بيانات متاحة جزئيًا.

get_today_snapshot

ما يحدث في المتجر الآن، لا عبر نافذة تاريخية.

الصلاحية: ANALYTICS · READ · الوسائط: لا شيء

تُرجع

الحقل	الوصف
`period`	دائمًا `"today (UTC)"`
`currency`	عملة المتجر
`metrics`	`total_sales` و`total_orders` و`unique_customers` لليوم
`activeVisitors`	الزوار الموجودون حاليًا في المتجر، أو `null` إن تعذّر معرفتهم

get_top_products

المنتجات الأكثر مبيعًا خلال فترة. يرتّب حسب المبيعات — ولمعرفة ما أوشك على النفاد استخدم get_low_stock_products.

الصلاحية: ANALYTICS · READ

الوسائط

الوسيط	النوع	الافتراضي	الوصف
`period` و`startDate` و`endDate`	—	`last_30_days`	راجع الفترات الزمنية
`sortBy`	`revenue` أو `quantity`	`revenue`	الإيراد يجيب عن "ما الأكثر ربحًا"، والكمية تجيب عن "ما الأكثر حركة"
`limit`	عدد صحيح 1–50	`10`	عدد المنتجات في الترتيب

تُرجع: period وrankedBy وcurrency وproducts[] وفيه productId وtitle وrevenue وunitsSold وorders.

get_top_customers

العملاء الأعلى إنفاقًا، مع إجمالي إنفاقهم وعدد طلباتهم.

الصلاحية: CUSTOMERS · READ

الوسائط

الوسيط	النوع	الافتراضي	الوصف
`limit`	عدد صحيح 1–50	`10`	عدد العملاء المطلوب إرجاعهم

تُرجع: customers[] وفيه customerId وname وemail وphone وtotalSpent وordersCount وlastOrderDate.

get_low_stock_products

المنتجات التي بلغت حدًا معينًا من المخزون أو أقل، مرتبة تصاعديًا.

تُستثنى المنتجات التي أُلغي تتبع مخزونها أو المسموح ببيعها بعد النفاد — فعدد مخزونها غير ذي دلالة. وللمنتجات ذات المتغيرات، يُحسب المخزون كمجموع المتغيرات.

الصلاحية: PRODUCTS · READ

الوسائط

الوسيط	النوع	الافتراضي	الوصف
`threshold`	عدد صحيح 0–1000	`5`	إدراج المنتجات التي لديها هذا العدد من القطع أو أقل
`limit`	عدد صحيح 1–100	`20`	عدد المنتجات المطلوب إرجاعها
`includeOutOfStock`	منطقي	`true`	تضمين المنتجات التي نفدت بالفعل

تُرجع: threshold وproducts[] وisEmpty — وقيمة true تعني "لا شيء أوشك على النفاد"، لا "فشل الاستعلام".

search_products

البحث عن المنتجات بالعنوان أو SKU أو المورّد أو نوع المنتج. استخدمها أولًا حين يُشار إلى منتج بالاسم وتحتاج إلى معرّفه.

الصلاحية: PRODUCTS · READ

الوسائط

الوسيط	النوع	الافتراضي	الوصف
`query`	نص 1–200 (مطلوب)	—	جزء من عنوان أو SKU أو مورّد أو نوع منتج
`limit`	عدد صحيح 1–50	`10`	عدد النتائج المطلوب إرجاعها

تُرجع: query وmatchCount وisEmpty وproducts[] وفيه productId وtitle وsku وprice وdiscountPrice وquantity وstatus وvendor.

get_product

تفاصيل منتج واحد كاملة، بالمعرّف أو بـ SKU. مرّر أحدهما على الأقل — وبدونهما تُرجع الأداة found: false مع رسالة توجّهك إلى البحث أولًا.

الصلاحية: PRODUCTS · READ

الوسائط

الوسيط	النوع	الوصف
`productId`	نص	معرّف المنتج كما يعيده `search_products`. وهو المفضل
`sku`	نص	SKU المنتج. وهو فريد داخل المتجر

تُرجع

found، ومعه كائن product عند العثور عليه:

الحقل	الوصف
`productId` و`title` و`sku`	التعريف
`price` و`discountPrice`	التسعير
`status` و`vendor` و`productType`	التصنيف
`categories`	أسماء التصنيفات
`stock`	`total` و`tracked` و`oversellAllowed` و`lastRestockedAt`
`variants`	`title` و`sku` و`price` و`quantity` لكل متغير
`rating` و`reviewCount`	ملخص تقييمات المنتج

تصنيفات المنتجات وعدد المنتجات في كل تصنيف.

الصلاحية: CATEGORIES · READ

الوسائط

الوسيط	النوع	الافتراضي	الوصف
`limit`	عدد صحيح 1–200	`50`	عدد التصنيفات المطلوب إرجاعها

تُرجع: categories[] وفيه categoryId وname وproductCount وsubcategoryCount، إضافة إلى isEmpty.

get_review_summary

صورة التقييمات على مستوى المتجر.

الصلاحية: REVIEWS · READ · الوسائط: لا شيء

تُرجع

الحقل	الوصف
`totalReviews`	إجمالي عدد التقييمات
`averageRating`	متوسط التقييم بمنزلتين عشريتين، أو `null`
`ratingBreakdown`	عدد التقييمات لكل عدد نجوم
`byStatus`	العدد لكل حالة مراجعة
`pendingModeration`	التقييمات التي تنتظر الاعتماد

list_recent_orders

طلبات فترة معينة، الأحدث أولًا. تُرجع طلبات مفردة — وللإيراد الإجمالي استخدم get_store_metrics.

تُستثنى الطلبات المحذوفة والمسودّات. وتُقرأ البيانات من سجلات الطلبات الأساسية، فالطلب الذي أُنشئ قبل ثوانٍ يظهر فورًا.

الصلاحية: ORDERS · READ

الوسائط

الوسيط	النوع	الافتراضي	الوصف
`period` و`startDate` و`endDate`	—	`last_7_days`	راجع الفترات الزمنية
`status`	قائمة محددة	الكل	إحدى القيم `pending` أو `confirmed` أو `processing` أو `shipped` أو `delivered` أو `cancelled` أو `returned`
`limit`	عدد صحيح 1–100	`20`	عدد الطلبات المطلوب إرجاعها

تُرجع: period وtotalMatching (كل الطلبات المطابقة للمرشّح) وreturned (عددها في هذه الاستجابة) وorders[] وفيه orderId وorderNumber وstatus وtotal وcurrency وpaymentMethod وitemCount وplacedAt وtags.

get_order

طلب واحد بتفاصيله، برقم الطلب.

يُقبل الرقم مع علامة # أو بدونها، كما يصلح رقم الشحنة أيضًا.

الصلاحية: ORDERS · READ

الوسائط

الوسيط	النوع	الوصف
`orderNumber`	نص 1–64 (مطلوب)	رقم الطلب كما يظهر في لوحة التحكم، أو رقم الشحنة

تُرجع

found، ومعه كائن order عند العثور عليه:

الحقل	الوصف
`orderId` و`orderNumber` و`status` و`placedAt`	التعريف والحالة
`itemCount` و`note` و`tags`	سياق الطلب
`payment`	`total` و`subtotal` و`shipping` و`discount` و`currency` و`method` و`status`
`items[]`	`name` و`quantity` و`unitPrice` و`variant`

الرقم الذي لا يطابق أي طلب يُرجع found: false بدل خطأ — تحقق من الرقم وأعد المحاولة.

بيانات المشتري

تُغفل أدوات الطلبات عمدًا بيانات التواصل مع العميل والعناوين وعناوين IP ودرجات المخاطرة. استخدم الـ REST API حين يحتاج تكاملك إليها فعلًا.

نظرة سريعة​

أدوات منشئ المتجر​

الفترات الزمنية​

get_shop_info​

get_store_metrics​

get_today_snapshot​

get_top_products​

get_top_customers​

get_low_stock_products​

search_products​

get_product​

list_categories​

get_review_summary​

list_recent_orders​

get_order​

نظرة سريعة

أدوات منشئ المتجر

الفترات الزمنية

get_shop_info

get_store_metrics

get_today_snapshot

get_top_products

get_top_customers

get_low_stock_products

search_products

get_product

list_categories

get_review_summary

list_recent_orders

get_order