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

# خادم MCP

> السماح لوكلاء الذكاء الاصطناعي باستخدام WhatsApp من خلال نقطة نهاية بروتوكول السياق النموذجي التابع لGOWA عند /mcp.

وتقوم GOWA بخدمة [بروتوكول السياق النموذجي](https://modelcontextprotocol.io) نقطة نهاية من نفس العملية التي يقوم بها API REST. أي عميل MCP يدعم نقل **HTTP** يمكن إرسال الرسائل وقراءة المحادثة وإدارة المجموعات من خلالها.

* URL: `http://<host>:3000<APP_BASE_PATH>/mcp` (الافتراضي `http://localhost:3000/mcp`)
* تمكين بشكل افتراضي. تعطيل مع `MCP_ENABLED=false` أو `--mcp-enabled=false`.
* عديم الجنسية: لا يوجد مصافحة جلسة للإبقاء على قيد الحياة بين المكالمات.

> [!NOTE]
>
> الترقية من الإصدار الأقدم؟ الأمر المستقل `./whatsapp mcp` ونقطة النهاية الخاصة به SSE على المنفذ 8080 (`/sse`) قد ذهبت. قم بتشغيل `./whatsapp rest` وتحديد العملاء عند `/mcp`. تم استبدال مجموعة الأدوات الوحيدة القديمة لكل عملية بالأدوات المدمجة أدناه.

## قم بتوصيل عميل

تخضع نقطة النهاية `/mcp` للمصادقة الأساسية نفسها التي تخضع لها REST API. أرسل الترويسة `Authorization`، وأضف `X-Device-Id` إذا كنت تشغّل أكثر من جهاز:

```json theme={null}
{
  "mcpServers": {
    "whatsapp": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Basic YWRtaW46Y2hhbmdlbWU=",
        "X-Device-Id": "my-device"
      }
    }
  }
}
```

القيمة `YWRtaW46Y2hhbmdlbWU=` هي ناتج `base64("admin:changeme")`؛ أنشئ قيمتك باستخدام `echo -n 'user:pass' | base64`. احذف `Authorization` إذا كانت المصادقة الأساسية معطّلة، واحذف `X-Device-Id` إذا كان هناك جهاز واحد فقط.

يعتمد تنسيق التكوين بالضبط على العميل. إذا استطاع العميل تشغيل خوادم stdio فقط، استخدم جسر مثل `mcp-remote`.

## أدوات

يتيح GOWA سبع أدوات. تقبل كل أداة وسيطًا باسم `type` (للإرسال) أو `action` (لجميع الأدوات الأخرى) لتحديد العملية.

| أداة | قيم `type` / `action` |
| - | - |
| `whatsapp_send` | `text`, `image`, `video`, `audio`, `document`, `sticker`, `location`, `contact`, `poll`, `link`, `forward` |
| `whatsapp_schedule` | `list`، `get`، `pause`، `resume`، `cancel` |
| `whatsapp_message` | `react`, `edit`, `revoke`, `delete`, `mark_read`, `mark_played`, `star`, `unstar`, `download_media` |
| `whatsapp_chat` | `list_chats`، `list_contacts`، `get_messages`، `archive` |
| `whatsapp_group` | `create`, `join_with_link`, `leave`, `info`, `participants`, `add_participants`, `remove_participants`, `promote`, `demote`, `invite_link`, `set_name`, `set_topic`, `set_settings`, `join_requests`, `manage_join_requests` |
| `whatsapp_app` | `status`, `login_qr` , `login_code` , `logout` , `reconnect` |
| `whatsapp_newsletter` | `follow`, `unfollow`, `info`, `directory`, `messages`, `message_updates`, `live_updates_subscribe`, `live_updates_unsubscribe`, `live_updates_list` |

ملاحظات بشأن الحججج:

* تتطلب `whatsapp_send` دائمًا `type` و`phone`. تُرسل الوسائط **عبر عنوان URL فقط** (`image_url`، `video_url`، `audio_url`، `file_url`، `sticker_url`)؛ ولا يستطيع MCP رفع ملفات محلية. يتطلب `link` كلًا من `link` و`caption`؛ ويتطلب `forward` الحقل `message_id`.
* تقبل `whatsapp_send` [حقول الجدولة](https://gowa-docs.mintlify.site/ar/examples/scheduled-sends.md) (`scheduled_at`، `timezone`، `recurrence`، `weekdays`، `day_of_month`، `end_at`، `occurrence_limit`). أدِر الجدولة الناتجة باستخدام `whatsapp_schedule` (تتطلب `get` و`pause` و`resume` و`cancel` الحقل `schedule_id`).
* `whatsapp_message` يحتاج إلى `phone` (المحادثة) و`message_id`؛ `edit` يحتاج أيضاً إلى `message`.
* في فرع `main` من GOWA بعد v9.9.0، تقبل `whatsapp_message` مع `action: "edit"` القيمة `media_type: "image"` أو `media_type: "document"` لاستبدال التعليق التوضيحي. طابِق نوع الوسائط الأصلي واحذف `link`. راجع [تعديل تعليق توضيحي](https://gowa-docs.mintlify.site/ar/examples/sending-messages.md#%D8%AA%D8%AD%D8%B1%D9%8A%D8%B1-%D8%B5%D9%88%D8%B1%D8%A9-%D8%A3%D9%88-%D9%88%D8%B5%D9%81-%D9%85%D8%B3%D8%AA%D9%86%D8%AF).
* `whatsapp_chat`: يحتاج `get_messages` إلى `chat_jid`; `archive` needs `chat_jid` and `archived`.
* `whatsapp_app`: يتطلب `login_code` الحقل `phone`.

الأزرار التجريبية، وموقع الطلب، وإرسال العربات متاحة من خلال REST فقط. انظر [الرسائل التفاعلية](https://gowa-docs.mintlify.site/ar/examples/interactive-messages.md). أدوات النشرة الإخبارية تدعم اكتشاف القناة، وعدادات التاريخ، واشتراكات التحديث المباشر المجددة تلقائيا. انظر [newsletters](https://gowa-docs.mintlify.site/ar/examples/newsletters.md).

تطبيق تنزيلات URL للوسائط نفس فحوصات العنوان العام التي ترسل وتتصل مباشرة بدون `HTTP_PROXY` أو `HTTPS_PROXY`. التحميلات من الملفات المحلية تتطلب API REST.

يعرض عميل MCP الخاص بك مخطط الإدخال الكامل لكل أداة. نقطة النهاية HTTP تقبل POST و DLETE. يتم تعطيل تدفق SSE.

## تحديد الجهاز

كل مكالمة تحل جهازها بهذا الترتيب:

1. حجة `device_id` على مكالمة الأداة.
2. ترويسة `X-Device-Id` على اتصال MCP .
3. الجهاز الوحيد المسجل، عندما يكون واحد منه بالضبط.

وإلا فشلت المكالمة مع `device identification required: set the X-Device-Id header or pass device_id`. انظر [Multi-device](https://gowa-docs.mintlify.site/ar/concepts/multidevice.md).

## العملاء البعيدين مع OAuth

العملاء المضيفون مثل موصلات كلود المخصصة لا يمكن إرفاق رأس المصادقة الأساسي. بالنسبة لهم، يمكن لGOWA تشغيل خادم إذن OAuth 2.1 ل `/mcp`. يتم إيقافه بشكل افتراضي.

```env theme={null}
APP_BASIC_AUTH=admin:replace-with-a-strong-password
MCP_ENABLED=true
MCP_OAUTH_ENABLED=true
MCP_OAUTH_ISSUER_URL=https://gowa.example.com
# optional, defaults to issuer + APP_BASE_PATH + /mcp
MCP_OAUTH_RESOURCE_URL=https://gowa.example.com/mcp
```

المتطلبات والسلوك:

* يجب تعيين `APP_BASIC_AUTH`: صفحة التفويض توقع على المستخدمين بنفس هذه الحسابات. فشل الإعداد بدونه.
* يجب أن يكون المصدر والمورد **HTTPS** العملاء الرابط، لا عناوين داخلية مثل `http://gowa:3000`.
* مع تشغيل OAuth ، يقبل `/mcp` الرمز المميز لحامله **أو** المصادقة الأساسية. لا تقبل الرموز المميزة على مسارات REST أو واجهة المستخدم.
* ويقوم العملاء بتسجيل أنفسهم (تسجيل العملاء الديناميكيين 7591 (RFC 7591) وتقتصر هيئات التسجيل على 16 كيلوبايت ويعاد توجيه كل جهاز من أجهزة URI إلى 2 كيلوبايت. وتقتصر التسجيلات على 40 في الساعة و 000 1 من الزبائن المخزونين؛ أما الزبائن غير المستعملين فيجري تقسيمهم بعد 24 ساعة.
* PKCE `S256` إلزامي. تنتهي صلاحية الرموز بعد 5 دقائق، والوصول إلى الرموز بعد ساعة واحدة؛ تحديث الرموز المدوّرة، وإعادة استخدام الرمز القديم يلغي العائلة الرمزية بأكملها. يتم تخزين فقط تجزئة SHA-256 من الرموز المميزة، في `MCP_OAUTH_DB_URI` (`file:storages/oauth.db`).

إعادة توجيه URIs يجب أن تتطابق مع القيم المسجلة بالضبط. يمكن للعملاء الأصليين استخدام نسخ IP التراجع HTTP مع منفذ ديناميكي. تتطلب ردود المكالمات `localhost` منفذا صريحا ومطابقة دقيقة. تتطلب عمليات إعادة توجيه أخرى HTTPS. و OAuth `resource` مرتبط بـ MCP URL; يمكن لطلبات الرموز أن تحذف ذلك، ولكن يجب أن تتطابق القيمة الموردة. وتشمل ردود التفويض الناجحة `iss`.

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

نقاط النهاية، نسبةً إلى عنوان الجهة المُصدِرة: `/oauth/authorize`، `/oauth/token`، `/oauth/register`. تستخدم بيانات الاكتشاف الوصفية عناوين URL المعروفة well-known في جذر النطاق مع إدراج المسار، لذا عند ضبط `APP_BASE_PATH=/gowa` يجب أن يوجّه الوكيل الطلبات إلى:

```text theme={null}
https://gowa.example.com/.well-known/oauth-authorization-server/gowa
https://gowa.example.com/.well-known/oauth-protected-resource/gowa/mcp
```

تحقق من الاكتشاف من الخارج:

```bash theme={null}
curl -i -X POST https://gowa.example.com/mcp          # expect 401 with a Bearer challenge
curl https://gowa.example.com/.well-known/oauth-protected-resource/mcp
curl https://gowa.example.com/.well-known/oauth-authorization-server
```

ثم أضف `https://gowa.example.com/mcp` كموصل مخصص وقم بتسجيل الدخول باستخدام حساب `APP_BASIC_AUTH`.

> [!WARNING]
>
> تأكد من أن الوصول إلى Cloudflare أو تحديات البوت أو وكلاء المصادقة أمام GOWA لا يعترضون المسارات المعروفة جيداً أو `/oauth/*` أو `/mcp`. حد معدل تسجيل الدخول الفاشلة على `/oauth/authorize` في وكيلك.


## Related topics

- [GOWA: واجهة WhatsApp REST API](https://gowa-docs.mintlify.site/ar/index.md)
- [تثبيت](https://gowa-docs.mintlify.site/ar/installation.md)
- [تسجيل الدخول إلى خادم Whatsapp](https://gowa-docs.mintlify.site/ar/api-reference/app/تسجيل-الدخول-إلى-خادم-whatsapp.md)
- [مرجع التكوين](https://gowa-docs.mintlify.site/ar/configuration.md)
- [مرجع API](https://gowa-docs.mintlify.site/ar/api-reference/introduction.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.