استخدم هذه الصفحة عندما تريد أن يعمل Codex مع Apple Search Ads عبر تطبيق SearchAds Manager المحلي بدلًا من نص برمجي مخصص لواجهة API.

1. إعداد تطبيق macOS

1. 1 Codex

   يرسل طلبًا إلى خادم MCP المحلي.

2. 2 SearchAds Manager

   يشغّل الخادم على جهاز Mac لديك ويعالج الطلب.

3. 3 Apple Ads

   يعيد بيانات الحساب أو ينفّذ إجراءً مصرّحًا به على الحملة.

أبقِ SearchAds Manager قيد التشغيل على جهاز Mac لديك. يتصل بـ Apple Ads باستخدام صلاحيات الوصول إلى API التي أعددتها في التطبيق.

1. شغّل SearchAds Manager على macOS.
2. افتح الإعدادات.
3. اضبط بيانات اعتماد Apple Search Ads المعتادة إذا لم تكن قد أُعدّت بعد.
4. افتح الأتمتة، ثم ابحث عن قسم خادم MCP لـ Codex.
5. فعّل الخادم.
6. راجع المنفذ ورمز الوصول أو غيّرهما عند الحاجة.
7. انقر على تطبيق إعدادات الخادم.

على Mac، افتح الإعدادات → الأتمتة وفعّل خادم MCP المحلي. طبّق إعدادات الخادم، ثم انسخ أمر Codex من التطبيق.

إذا لم تكن بيانات الاعتماد قد أُعدّت بعد، فاتبع دليل OAuth من Apple: تطبيق OAuth لواجهة API الخاصة بـ Apple Search Ads.

2. إضافة الخادم إلى Codex

تعرض بطاقة الإعدادات الأمر الدقيق المطلوب تنفيذه. صيغة الأمر هي:

codex mcp add searchads --url "http://127.0.0.1:7717/mcp?token=YOUR_TOKEN"

بعد إضافته:

1. أبقِ تطبيق macOS قيد التشغيل.
2. ابدأ جلسة Codex جديدة في المستودع الذي تريد العمل فيه، أو أعد الاتصال بخوادم MCP إذا كان برنامج العميل لديك يدعم ذلك.
3. استخدم خادم searchads للتقارير وعمليات الكتابة بدلًا من كتابة نصوص برمجية يدويًا للتعامل مع API.

3. سير العمل الموصى به في Codex

1. استدعِ list_apps أولًا عندما تحتاج إلى adam_id.
2. استدعِ list_supported_countries قبل إنشاء الحملات عندما تحتاج إلى رموز بلدان صالحة.
3. استخدم get_campaign_report وget_adgroup_report وget_keyword_report لفحص الأداء قبل إجراء تغييرات.
4. استخدم list_campaigns وlist_adgroups وlist_keywords لفحص الحالة الحالية قبل إجراء تغييرات.
5. استخدم create_campaigns وadd_adgroups وadd_keywords لعمليات الإنشاء.
6. استخدم update_campaigns وupdate_adgroups وupdate_keywords لإجراء تعديلات منضبطة.
7. استخدم delete_campaigns وdelete_adgroups وdelete_keywords فقط لعمليات تنظيف محددة صراحةً تتضمن الحذف.
8. يُفضَّل تنفيذ عمليات الكتابة على دفعات صغيرة ومحددة بوضوح لتسهيل مراجعة حالات الفشل.

4. استكشاف الأخطاء وإصلاحها

1. إذا تعذّر على Codex الاتصال، فتأكد من أن تطبيق macOS مفتوح وأن حالة الخادم هي قيد التشغيل.
2. إذا فشلت استدعاءات الأدوات بسبب أخطاء في الإعدادات، فتحقّق مجددًا من بيانات اعتماد Apple Search Ads في إعدادات التطبيق.
3. إذا أعدت إنشاء رمز الوصول أو غيّرت المنفذ، فأعد تنفيذ codex mcp add ... باستخدام عنوان URL الجديد.

5. مطالبات اختبار أولي ببيانات مؤقتة

إظهار المطالبات الاختيارية للاختبار الأولي

استخدم المطالبات أدناه في جلسة Codex نفسها كي يتذكّر معرّفات الاختبار التي ينشئها.

استخدم بادئة تسمية مؤقتة مثل mcp-smoke-... واحذف كل شيء في النهاية. عادةً ما تكون قيم مقاييس كيانات الاختبار المنشأة حديثًا صفرًا في التقارير؛ ومع ذلك، فهذا يتحقق من سلامة مسار التقارير عبر MCP.

مطالبة الاستكشاف

باستخدام خادم MCP المسمى `searchads` فقط، جهّز بيئة لاختبار أولي لوظائف MCP.

1. ابحث عن تطبيق أملكه ويمكنني استخدامه بأمان في حملة اختبار مؤقتة. أعطِ الأولوية لتطبيق يطابق "Monitor and Manage Search Ads"؛ وإلا فاعرض أول 5 تطبيقات أملكها واختر واحدًا منها.
2. استدعِ `list_supported_countries` واختر `US` إذا كانت مدعومة. وإلا فاختر دولة مدعومة وأخبرني برمز الدولة الذي اخترته.
3. استدعِ `list_campaigns` للحملات التي تبدأ أسماؤها بـ `mcp-smoke-`.
4. أخبرني بقيمة `adam_id` المختارة ورمز الدولة وبادئة اختبار فريدة بالتنسيق `mcp-smoke-YYYYMMDD-HHMMSS`.
5. لا تنشئ أي شيء بعد.

مطالبة إنشاء حملة

باستخدام خادم MCP المسمى `searchads` فقط، أنشئ حملة اختبار مؤقتة ومتوقفة مؤقتًا باسم `<PREFIX>-campaign` للتطبيق والدولة اللذين تم اختيارهما سابقًا.

استخدم:
- قيمة `adam_id` المختارة
- رمز دولة واحدًا
- `daily_budget_amount` بقيمة 5
- `currency` بقيمة `USD`

بعد الإنشاء، استدعِ `list_campaigns` باستخدام بادئة الاختبار وأرجع قيمة `campaign_id` الجديدة.

مطالبة تقرير الحملة وتحديثها

باستخدام خادم MCP المسمى `searchads` فقط:

1. استدعِ `get_campaign_report` للحملة `<CAMPAIGN_ID>` مع `days: 0`.
2. حدّث تلك الحملة باستخدام `update_campaigns` لتصبح الميزانية اليومية 6 USD والحالة `ENABLED`.
3. استدعِ `list_campaigns` مرة أخرى باستخدام بادئة الاختبار.
4. لخّص حالة الحملة قبل التحديث وبعده.

مطالبة إضافة مجموعات إعلانية

باستخدام خادم MCP المسمى `searchads` فقط، أضف مجموعتين إعلانيتين متوقفتين مؤقتًا إلى `<CAMPAIGN_ID>`:

1. `<PREFIX>-ag-1`
2. `<PREFIX>-ag-2`

استخدم:
- `default_bid_amount` بقيمة 1
- `currency` بقيمة `USD`
- `automated_keywords_opt_in` بقيمة false

بعد الإنشاء، استدعِ `list_adgroups` للحملة وأرجع قيمتي `ad_group_id`.

مطالبة تقرير المجموعة الإعلانية وتحديثها

باستخدام خادم MCP المسمى `searchads` فقط:

1. استدعِ `get_adgroup_report` للحملة `<CAMPAIGN_ID>` مع `days: 0`.
2. حدّث `<PREFIX>-ag-1` باستخدام `update_adgroups` لتصبح الحالة `ENABLED` وقيمة `default_bid_amount` هي 1.2 USD وقيمة `cpa_goal_amount` هي 4 USD.
3. استدعِ `list_adgroups` مرة أخرى للحملة `<CAMPAIGN_ID>`.
4. لخّص المجموعة الإعلانية المحدّثة وأرجع قيمة `ad_group_id` الخاصة بها.

مطالبة إضافة كلمات مفتاحية

باستخدام خادم MCP المسمى `searchads` فقط، أضف كلمات مفتاحية إلى `<AD_GROUP_ID>` ضمن `<CAMPAIGN_ID>` باستخدام `keyword_set` واحد.

استخدم:
- `default_bid_amount` بقيمة 0.8
- `default_currency` بقيمة `USD`

أضف الكلمات المفتاحية التالية:
1. `<PREFIX> exact` مع `match_type` بقيمة `EXACT` و`status` بقيمة `ACTIVE`
2. `<PREFIX> broad` مع `match_type` بقيمة `BROAD` و`status` بقيمة `ACTIVE`

بعد الإنشاء، استدعِ `list_keywords` للحملة `<CAMPAIGN_ID>` والمجموعة `<AD_GROUP_ID>` وأرجع قيم `keyword_id` التي تم إنشاؤها.

مطالبة تقرير الكلمات المفتاحية وتحديثها

باستخدام خادم MCP المسمى `searchads` فقط:

1. استدعِ `get_keyword_report` للحملة `<CAMPAIGN_ID>` و`ad_group_ids: [<AD_GROUP_ID>]` مع `days: 0`.
2. حدّث الكلمة المفتاحية من نوع EXACT باستخدام `update_keywords` ليصبح عرض سعرها 0.9 USD وحالتها `PAUSED`.
3. استدعِ `list_keywords` مرة أخرى للحملة `<CAMPAIGN_ID>` والمجموعة `<AD_GROUP_ID>`.
4. لخّص الكلمة المفتاحية المحدّثة وأرجع الصفّين الحاليين للكلمات المفتاحية.

مطالبة التنظيف

باستخدام خادم MCP المسمى `searchads` فقط، احذف بيانات الاختبار الأولي لوظائف MCP.

1. احذف جميع الكلمات المفتاحية الخاصة بالاختبار في `<AD_GROUP_ID>` باستخدام `delete_keywords`.
2. استدعِ `list_keywords` للحملة `<CAMPAIGN_ID>` والمجموعة `<AD_GROUP_ID>` للتأكد من حذف الكلمات المفتاحية.
3. احذف مجموعتي الإعلانات الخاصتين بالاختبار باستخدام `delete_adgroups`.
4. استدعِ `list_adgroups` للحملة `<CAMPAIGN_ID>` للتأكد من حذف مجموعتي الإعلانات.
5. احذف حملة الاختبار باستخدام `delete_campaigns`.
6. استدعِ `list_campaigns` باستخدام بادئة الاختبار للتأكد من حذف الحملة.
7. لخّص نتائج التنظيف.