> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudgen.net/llms.txt
> Use this file to discover all available pages before exploring further.

# خادم MCP

> اربط مساعد ذكاء اصطناعي بـ Nudgen عبر OAuth، وابحث عن عملاء محتملين على الخريطة، ووافق على إطلاق الحملات في متصفحك

## نظرة عامة

يستضيف Nudgen خادم MCP عند نقطة النهاية `/mcp` في نطاق تطبيقك. يستخدم الخادم بروتوكول MCP بالإصدار `2026-07-28` عبر Streamable HTTP ويتطلب OAuth 2.1. اربط عميلاً يدعم وسيلة النقل هذه. سجّل الدخول إلى Nudgen في متصفحك، واختر مساحة عمل، ثم وافق على الصلاحيات التي يطلبها العميل. يظل اتصالك مرتبطًا بمساحة العمل تلك حتى إذا بدّلت لاحقًا إلى مساحة عمل أخرى في لوحة التحكم.

## سبب أهمية ذلك

يمكن لمساعدك قراءة جهات الاتصال والحملات، والعثور على الأنشطة التجارية القريبة، وإعداد مسودة محتوى، وتجهيز حملة للإطلاق من دون التعامل مع جلسة لوحة التحكم أو رمز وصول شخصي. وتراجع كل عملية إرسال فعلية أو جدولة في متصفحك قبل تنفيذها.

## ربط عميلك

نقطة نهاية الإنتاج هي:

```text theme={null}
https://app.nudgen.net/mcp
```

أضفها بوصفها **خادم MCP بعيدًا عبر HTTP** في عميل يدعم OAuth. يكتشف العميل خادم التفويض الخاص بـ Nudgen من نقطة النهاية ويفتح مسار تسجيل الدخول والموافقة في المتصفح. اختر مساحة العمل التي تريد أن يصل إليها العميل، ووافق فقط على النطاقات التي يحتاج إليها.

مستندات الاكتشاف:

| المستند | عنوان URL |
| - | - |
| بيانات المورد المحمي الوصفية | `https://app.nudgen.net/.well-known/oauth-protected-resource/mcp` |
| خادم التفويض | `https://app.nudgen.net/mcp-oauth` |
| بطاقة الخادم | `https://app.nudgen.net/.well-known/mcp/server-card.json` |

يستخدم خادم التفويض رمز التفويض مع PKCE S256 وربط الموارد وتدوير رمز التحديث. كما يقبل مستندات بيانات معرّف العميل الوصفية والتسجيل الديناميكي للعملاء.

بالنسبة إلى Codex CLI، استخدم:

```bash theme={null}
codex mcp add nudgen --url "https://app.nudgen.net/mcp" --oauth-resource "https://app.nudgen.net/mcp"
codex mcp login nudgen --scopes campaigns:read,campaigns:write,campaigns:send
```

إذا كان هناك عميل باسم `nudgen` مهيأ بالفعل، فحدّث هذا الإدخال باستخدام عنوان URL ‏`/mcp`.

| النطاق | ما يتيحه |
| - | - |
| `campaigns:read` | فحص مساحة العمل وجهات الاتصال والحملات وإعدادات العلامة التجارية، والبحث عن عملاء محتملين على الخريطة. |
| `campaigns:write` | إنشاء جهات اتصال ومسودات حملات، وتحديث إعدادات العلامة التجارية، وإنشاء مسودات بالذكاء الاصطناعي، واستيراد عملاء محتملين من الخريطة. |
| `campaigns:send` | طلب إطلاق حملة وإكماله. لا يرسل هذا النطاق بريدًا إلكترونيًا بمفرده. |

إذا كنت تحتاج فقط إلى فحص البيانات، فاطلب `campaigns:read`. أضف `campaigns:write` عندما ينبغي للعميل تغيير جهات الاتصال أو المسودات أو إعدادات العلامة التجارية أو العملاء المحتملين المستوردين. ولا تضف `campaigns:send` إلا عندما يحتاج العميل إلى طلب الموافقة على الإطلاق.

<Note>
  تصادق رموز الوصول الشخصية على [واجهة برمجة تطبيقات المطور](/ar/agents/api)، لكنها لا تصادق على `/mcp`. يجب على عميل MCP إكمال تسجيل الدخول عبر OAuth.
</Note>

## الأدوات المتاحة

| المهمة | الأدوات | النطاق |
| - | - | - |
| فحص مساحة عملك | `get_current_user`، `list_contacts`، `list_campaigns`، `get_campaign`، `get_campaign_stats`، `get_brand_settings` | `campaigns:read` |
| العثور على أنشطة تجارية قريبة | `search_map_leads` | `campaigns:read` |
| الإنشاء والتعديل | `create_contact`، `create_campaign`، `update_brand_settings`، `generate_email_draft`، `import_map_leads` | `campaigns:write` |
| طلب إطلاق وإكماله | `prepare_campaign_launch`، `launch_campaign` | `campaigns:send` |

يحفظ `create_campaign` **مسودة حملة لمرة واحدة**. ولا يمكنه الإرسال أو الجدولة مباشرةً. يتيح لك `get_campaign` التحقق من الموضوع والمحتوى والرابط والجمهور والمرسل قبل الإطلاق.

يعرض الخادم أيضًا موارد للقراءة فقط ضمن `campaigns:read`:

| المورد | المحتويات |
| - | - |
| `nudgen://api-catalog` | أسماء الأدوات المستضافة وأوصافها. |
| `nudgen://team/brand` | إعدادات العلامة التجارية لمساحة العمل المتصلة. |
| `nudgen://campaigns/{id}/summary` | إحصاءات التسليم لحملة واحدة. استبدل `{id}` بمعرّف الحملة. |

### البحث عن عملاء محتملين على الخريطة واستيرادهم

1. اطلب من المساعد استدعاء `search_map_leads` مع موقع وكلمات مفتاحية للنشاط التجاري، مثل مدينة و`marketing agency`.
2. المرشحات الاختيارية هي `radiusKm` (من 1 إلى 100)، و`lat` و`lng`، و`emailOnly` للاحتفاظ بالأنشطة التجارية التي تنشر عنوان بريد إلكتروني.
3. عندما تتضمن النتيجة `nextPageToken`، مرّرها بوصفها `pageToken` لتحميل صفحة أخرى.
4. اطلب من المساعد استدعاء `import_map_leads` باستخدام الموقع والكلمات المفتاحية نفسيهما، بالإضافة إلى كائنات العملاء المحتملين المراد حفظها. يقبل كل استدعاء ما يصل إلى 200 عميل محتمل.

تكتب عملية الاستيراد جهات اتصال في مساحة العمل المتصلة. ويتم تخطي العملاء المحتملين الذين ليس لديهم بريد إلكتروني. وإذا كان العميل المحتمل موجودًا بالفعل، فسيتم تحديثه.

### الموافقة على إطلاق حملة

1. اطلب من المساعد فحص المسودة باستخدام `get_campaign`.
2. اطلب منه استدعاء `prepare_campaign_launch` باستخدام معرّف الحملة ووقت الإرسال الفوري أو المجدول الذي تريده بالضبط. يعيد هذا عنوان URL للموافقة يُستخدم مرة واحدة؛ ولا يُرسل أي بريد إلكتروني بعد.
3. افتح عنوان URL، وراجع مساحة العمل وتقدير عدد المستلمين والمحتوى والمرسل والتوقيت، ثم انقر على **الموافقة على الإطلاق**.
4. عُد إلى العميل ليتمكن من استدعاء `launch_campaign` باستخدام معرّف الحملة والتوقيت نفسيهما و`approvalId`.

تنتهي صلاحية الموافقة بعد **10 دقائق** ويمكن استخدامها مرة واحدة. إذا تغيرت الحملة أو المرسل، فاطلب موافقة جديدة. يتحقق Nudgen مجددًا عند الإطلاق من جاهزية المرسل والمستلمين المؤهلين والاشتراك والحصة وتوفر قائمة الانتظار. ولا يبدأ التسليم إلا بعد أن يعالج عامل الحملة عملية الإطلاق.

<Warning>
  قد تؤدي الموافقة على `launch_campaign` وإكماله إلى إرسال بريد إلكتروني حقيقي. استخدم مسار الإرسال التجريبي في لوحة التحكم للتحقق من معاينة البريد الوارد قبل الموافقة على جمهور حقيقي.
</Warning>

## إدارة الوصول

افتح **الإعدادات** ← **مفاتيح API** ← **تطبيقات MCP المتصلة** للاطلاع على مساحة العمل والنطاقات الخاصة بكل عميل متصل. ألغِ اتصالاً من هناك إذا لم يعد ينبغي أن يتمتع بإمكانية الوصول. يؤدي الإلغاء إلى تعطيل رموزه وموافقات الإطلاق المعلقة. ويمكنك إعادة الاتصال عبر OAuth لاحقًا.

تستمر منح OAuth لمدة لا تتجاوز 90 يومًا. كما أن فقدان الوصول إلى مساحة عمل يمنع العميل من استخدام الاتصال الخاص بتلك المساحة.

## حل المشكلات

| العَرَض | ما يجب فعله |
| - | - |
| لا يبدأ تسجيل الدخول | تأكد من أن العميل يدعم MCP البعيد عبر Streamable HTTP مع OAuth ويستخدم `https://app.nudgen.net/mcp`. |
| تحتاج أداة إلى صلاحية إضافية | أعد الاتصال ووافق على النطاق المطلوب لمساحة العمل تلك. |
| يطلب منك البحث في جهات الاتصال تضييق النتائج | يطابق البحث الأسماء وعناوين البريد الإلكتروني ويفحص ما يصل إلى 5,000 جهة اتصال بعد تطبيق مرشحات الوسوم والحالة. ضيّق المرشحات. |
| يتخطى استيراد العملاء المحتملين نشاطًا تجاريًا | لا تُحفظ إلا بيانات العملاء المحتملين الذين لديهم بريد إلكتروني. ابحث مجددًا مع تعيين `emailOnly` على `true`، أو اختر عملاء محتملين يتضمنون بريدًا إلكترونيًا بالفعل. |
| انتهت صلاحية موافقة الإطلاق أو تغيرت الحملة | اطلب موافقة جديدة وراجع الحملة والمرسل الحاليين. |
| تم حظر إطلاق | تحقق من حالة مسودة الحملة وجاهزية المرسل وجهات الاتصال المؤهلة وحصة الباقة و[نطاق الإرسال](/ar/settings/sending-domains). |

للنصوص البرمجية التي تستخدم رموز Bearer ونقاط نهاية REST المباشرة، راجع [واجهة برمجة تطبيقات المطور](/ar/agents/api).