# ربط مساعدي الذكاء الاصطناعي (MCP)

<span data-t="appName">DM Champ</span> توفر **خادم MCP** رسميًا — وهو نقطة نهاية لبروتوكول سياق النموذج (Model Context Protocol) تسمح لمساعدي الذكاء الاصطناعي مثل **Claude Code** و **Claude Desktop** و **ChatGPT** و **Cursor** وتطبيقاتك الخاصة بالتحكم في حساب <span data-t="appName">DM Champ</span> الخاص بك مباشرةً. اطلب بلغة بسيطة ("اعرض حملاتي المباشرة"، "أضف هذا العميل المحتمل"، "ما هي تكلفة الذكاء الاصطناعي عليّ هذا الأسبوع؟") وسيقوم المساعد باستدعاء واجهة برمجة تطبيقات <span data-t="appName">DM Champ</span> نيابةً عنك.

إنها نفس واجهة برمجة التطبيقات v1 الموثقة في [قسم واجهة برمجة التطبيقات](../api/getting-started.md)، ويتم المصادقة عليها باستخدام مفتاح واجهة برمجة التطبيقات الخاص بك. يقوم خادم MCP بإنشاء أداة واحدة لكل عملية في مواصفات واجهة برمجة التطبيقات المنشورة لدينا، لذا فهي تغطي معظم واجهة برمجة التطبيقات v1، ولكن ليس كلها: جهات الاتصال، والرسائل، والحملات، ووكلاء الذكاء الاصطناعي، وقاعدة المعرفة، والمواعيد، والتحليلات، والعلامات، والقوائم، والحسابات الفرعية. البث، والأتمتة، والصفقات ليست متاحة كأدوات MCP بعد — استخدم REST API مباشرة لهذه الأغراض. ضمن ما تكشف عنه، لا توجد أذونات لكل أداة ولا يوجد افتراضي للقراءة فقط، لذا فإن مفتاح واجهة برمجة التطبيقات هو التحكم الكامل في الوصول.

- **نقطة النهاية:** `https://mcp.youraiconnector.com/mcp`
- **المصادقة:** مفتاح واجهة برمجة تطبيقات <span data-t="appName">DM Champ</span> الخاص بك (يُرسل كترويسة `X-API-Key`)
- **المتطلبات:** خطة تتضمن الوصول إلى واجهة برمجة التطبيقات. [إنشاء مفتاح واجهة برمجة تطبيقات ←](api-access.md#generating-your-api-key)

> يعمل مفتاح واجهة برمجة التطبيقات الخاص بك على **حسابك الخاص**، بنفس أذونات بقية واجهة برمجة التطبيقات — ويمكنه قراءة حسابات العملاء التي تديرها، إذا كنت مشتركاً في خطة الوكالة (انظر أدناه). تعامل معه ككلمة مرور. يمكنك إلغاؤه في أي وقت من الإعدادات ← عمليات التكامل ← مفتاح واجهة برمجة التطبيقات، مما يقطع وصول المساعد على الفور.

## Claude Code

```bash
claude mcp add --transport http dm-champ https://mcp.youraiconnector.com/mcp \
  --header "X-API-Key: YOUR_API_KEY"
```

ثم قم بتشغيل `/mcp` داخل Claude Code للتأكد من ظهور **dm-champ ✓ متصل**.

بشكل افتراضي، تتم إضافة الخادم في النطاق **المحلي** (أنت فقط، هذا المشروع). استخدم `--scope user` لجعله متاحاً في جميع مشاريعك، أو `--scope project` to commit it to a repo's `.mcp.json` لفريقك:

```json
{
  "mcpServers": {
    "dm-champ": {
      "type": "http",
      "url": "https://mcp.youraiconnector.com/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY" }
    }
  }
}
```

## Claude Desktop

قم بتحرير ملف `claude_desktop_config.json` الخاص بك (الإعدادات ← المطور ← تحرير التكوين) وأضف:

```json
{
  "mcpServers": {
    "dm-champ": {
      "type": "http",
      "url": "https://mcp.youraiconnector.com/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY" }
    }
  }
}
```

أعد تشغيل Claude Desktop. ستظهر أدوات <span data-t="appName">DM Champ</span> في قائمة الأدوات.

## ChatGPT

تتوفر موصلات MCP المخصصة في خطط ChatGPT Business و Enterprise و Pro. يجب على مالك مساحة العمل أو المسؤول تفعيل **وضع المطور / الموصلات المخصصة** في إعدادات مساحة العمل أولاً — فبدون ذلك، لن يظهر خيار إنشاء موصل مطلقًا.

ثم قم بإنشاء الموصل باستخدام:

- **الرابط (URL):** `https://mcp.youraiconnector.com/mcp`
- **المصادقة:** ترويسات مخصصة
- **اسم الترويسة:** `X-API-Key`
- **قيمة الترويسة:** مفتاح واجهة برمجة تطبيقات <span data-t="appName">DM Champ</span> الخاص بك

يجب أن ينتهي عنوان URL بـ `/mcp`. إن لصق `https://mcp.youraiconnector.com` فقط هو الخطأ الأكثر شيوعًا — حيث يتحقق ChatGPT من ذلك العنوان بدقة، ولا يجد شيئًا هناك، ويظهر رسالة **"تعذر إضافة عنوان URL للموصل"**.

## Cursor وعملاء MCP الآخرون

تستخدم معظم المحررات التي تدعم MCP نفس شكل `.mcp.json` الموضح أعلاه (خادم HTTP مع `url` وترويسة `X-API-Key`). أضف خادم `dm-champ` يشير إلى `https://mcp.youraiconnector.com/mcp` والصق مفتاح واجهة برمجة التطبيقات الخاص بك في الترويسة.

## واجهة برمجة تطبيقات Claude (دمجها في تطبيقك الخاص)

يمكنك توصيل خادم MCP برمجياً باستخدام موصل MCP الخاص بواجهة برمجة تطبيقات Claude، بحيث يمكن للوكيل الذي تبنيه استخدام أدوات <span data-t="appName">DM Champ</span> دون الحاجة إلى عميل منفصل:

```json
{
  "model": "claude-opus-4-8",
  "messages": [{ "role": "user", "content": "List my live campaigns" }],
  "mcp_servers": [
    {
      "type": "url",
      "name": "dm-champ",
      "url": "https://mcp.youraiconnector.com/mcp",
      "authorization_token": "YOUR_API_KEY"
    }
  ]
}
```

## ما يمكنك القيام به

ضمن الجزء الذي يعرضه خادم MCP من واجهة برمجة التطبيقات v1، يختار المساعد الأداة المناسبة تلقائيًا:

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

## السؤال عن حسابات عملائك (الوكالات)

اتصال واحد يغطي كل حساب تديره. لا تحتاج إلى إضافة اتصال ثانٍ لكل عميل: في خطة الوكالة، يمكن للمساعد قراءة أي حساب عميل تابع لك، لذا يمكنك السؤال عنهم جميعاً في محادثة واحدة.

فقط اذكر اسم العميل:

- "كم عدد جهات الاتصال لدى Bella's Bistro؟"
- "ما هي تكلفة الذكاء الاصطناعي لكل عميل من عملائي هذا الأسبوع؟"
- "ما هي الحملات المباشرة لـ Northside Dental، وما هي حالة قنواتهم؟"

يغطي هذا قراءة جهات الاتصال، والرسائل، والدردشات، والحملات، والمواعيد، والمهام، والعلامات، والأحداث، والأسئلة الشائعة، ومصادر قاعدة المعرفة، وأرقام الهواتف، والقنوات، وخطافات الويب (webhooks)، والتحليلات. نتحقق من أن الحساب يخصك حقاً قبل تشغيل أي شيء — طلب حساب ليس لك سيؤدي إلى رد "غير موجود". اترك العميل خارجاً وسيقوم المساعد بقراءة حسابك الخاص، تماماً كما كان من قبل.

**تغيير حساب العميل** محدود أكثر. إعداد وكلاء الذكاء الاصطناعي، والوظائف المخصصة، وقوالب WhatsApp، ونقاط الدخول، واتصالات القنوات، وحالة الحملة، وشراء رقم، كلها تعمل لعميل محدد؛ بينما لا تزال معظم إجراءات الكتابة الأخرى تعمل على حسابك الخاص، لذا قم بتنفيذها من مفتاح ذلك العميل نفسه أو من [REST API](../agency/api-for-agencies.md)، الذي يغطي المزيد.

هذه أيضاً هي الإجابة للعميل الذي يدير **عدة شركات تحت تسجيل دخول واحد**. امنح كل شركة حسابها الخاص، ثم ادعُ بريد العميل الإلكتروني كعضو في الفريق في جميع تلك الحسابات: يسجلون الدخول مرة واحدة ويتبادلون بين علاماتهم التجارية باستخدام منتقي الحساب في الشريط الجانبي.

## تزويد مساعدك بوثائق المساعدة

يمنح خادم MCP المساعد حق الوصول إلى **حسابك**؛ ولا يمنحه هذه الوثائق. إذا كنت تريده أيضاً أن يجيب على أسئلة "كيف أقوم بـ..." بشكل صحيح، فقم بتوجيهه إلى `https://docs.dmchamp.com/llms.txt` (فهرس لكل صفحة مساعدة مع رابط لنسخة Markdown الخاصة بكل صفحة) أو `https://docs.dmchamp.com/llms-full.txt` (الوثائق الكاملة في ملف Markdown واحد). كلاهما متاح للعامة، ولا يتطلب مفتاحاً، ويتم إعادة بنائهما مع كل تغيير في الوثائق. راجع [قراءة هذه الوثائق بصيغة Markdown](../api/getting-started.md#reading-these-docs-as-markdown).

## العثور على مفتاح API الخاص بك أو إنشاؤه

يوجد مفتاح API الذي يستخدمه هذا الاتصال في **الإعدادات ← عمليات التكامل ← مفتاح API** — وهو قسم خاص به، منفصل عن Webhooks. راجع [الوصول إلى واجهة برمجة التطبيقات](api-access.md#generating-your-api-key) لمعرفة الخطوات الدقيقة.

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

- **"Unable to add connector URL" (ChatGPT) / "connection refused"** — العنوان يفتقد إلى `/mcp` في النهاية. استخدم `https://mcp.youraiconnector.com/mcp`، وليس `https://mcp.youraiconnector.com`.
- **`Needs authentication` / 401** — مفتاح واجهة برمجة التطبيقات (API key) الخاص بك مفقود أو غير صحيح. أعد إضافة الخادم باستخدام `X-API-Key` صالح.
- **أداة تُرجع `403`** — خطتك أو دور فريقك لا يسمح بهذا الإجراء؛ خادم MCP لا يفرض أي قيود إضافية، فهو نفس فحص الأذونات الخاص بـ API.
- **أداة غير موجودة (Tool not found)** — يتم إنشاء قائمة الأدوات مباشرة من API، لذا فهي تطابق دائمًا الإصدار الحالي؛ أعد الاتصال للتحديث.
- **تحذير أمني أو تحذير شهادة على نطاقك الخاص** — توجيه سجل DNS إلينا ليس كافيًا بحد ذاته: يجب أيضًا التحقق من النطاق الفرعي في لوحة التحكم قبل أن يتمكن من توفير اتصال آمن. يمكن لوكالات العلامات البيضاء (White-label) وضع عنوان MCP على نطاقها الخاص (على سبيل المثال `mcp.youragency.com`) من بطاقة **النطاق المخصص (Custom domain)** تحت **الإعدادات ← العلامة البيضاء (Settings → White Labeling)** — أضف CNAME لدى مسجل النطاق الخاص بك أولاً، ثم أدخل اسم المضيف في كتلة **نطاق MCP (مساعدو الذكاء الاصطناعي) (MCP domain (AI assistants))** وانقر على **تحقق (Verify)**، وهو نفس مسار العمل لنطاقاتك الفرعية الأخرى ذات العلامة التجارية. حتى يتم التحقق منه، استخدم العنوان القياسي المذكور أعلاه — فهو غير يحمل علامة تجارية، لذا من الآمن مشاركته مع العملاء.

---

## الخطوات التالية

- [الوصول إلى واجهة برمجة التطبيقات](api-access.md) — لإنشاء أو تدوير المفتاح الذي يستخدمه هذا الاتصال.
- [Webhooks](webhooks.md) — النظير القائم على الدفع لهذا الاتصال القائم على السحب MCP.