انتقل إلى المحتوى الرئيسي

مرجع أدوات MCP

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

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

نظرة سريعة​

الأداةالصلاحية المطلوبةما تجيب عنه
get_shop_infoSTORE_SETTINGS · READاسم المتجر وعملته ولغته وحالته
get_store_metricsANALYTICS · READالإيراد والطلبات ومتوسط قيمة الطلب والمرتجعات والتحويل لفترة
get_today_snapshotANALYTICS · READمبيعات اليوم وعدد الزوار الحاليين
get_top_productsANALYTICS · READالأكثر مبيعًا بالإيراد أو بعدد القطع
get_top_customersCUSTOMERS · READالعملاء الأعلى إنفاقًا
get_low_stock_productsPRODUCTS · READما أوشك على النفاد
search_productsPRODUCTS · READالبحث عن منتج بالاسم أو SKU أو المورّد أو النوع
get_productPRODUCTS · READتفاصيل منتج واحد كاملة
list_categoriesCATEGORIES · READالتصنيفات وعدد منتجات كل منها
get_review_summaryREVIEWS · READمتوسط التقييم وتوزيعه وما ينتظر المراجعة
list_recent_ordersORDERS · READطلبات فترة معينة
get_orderORDERS · READطلب واحد برقمه، مع بنوده

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

تتطلب كل أداة من أدوات منشئ المتجر صلاحية 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_upload_assetكتابةرفع صورة لاستخدامها في الأقسام
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 — ولا تتأثر أي أداة أخرى.

الأداة التي لا يحمل مفتاحك صلاحيتها تظل ظاهرة في 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عملة المتجر
metricstotal_sales وtotal_orders وunique_customers لليوم
activeVisitorsالزوار الموجودون حاليًا في المتجر، أو null إن تعذّر معرفتهم

get_top_products​

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

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

الوسائط

الوسيطالنوعالافتراضيالوصف
period وstartDate وendDate—last_30_daysراجع الفترات الزمنية
sortByrevenue أو quantityrevenueالإيراد يجيب عن "ما الأكثر ربحًا"، والكمية تجيب عن "ما الأكثر حركة"
limitعدد صحيح 1–5010عدد المنتجات في الترتيب

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

get_top_customers​

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

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

الوسائط

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

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

get_low_stock_products​

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

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

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

الوسائط

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

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

search_products​

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

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

الوسائط

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

تُرجع: 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أسماء التصنيفات
stocktotal وtracked وoversellAllowed وlastRestockedAt
variantstitle وsku وprice وquantity لكل متغير
rating وreviewCountملخص تقييمات المنتج

list_categories​

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

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

الوسائط

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

تُرجع: 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–10020عدد الطلبات المطلوب إرجاعها

تُرجع: 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سياق الطلب
paymenttotal وsubtotal وshipping وdiscount وcurrency وmethod وstatus
items[]name وquantity وunitPrice وvariant

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

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

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