# دليل مركز المطوّرين — صفحة MCP

> **هذا الدليل مكتوب لك أنت، حتى لو لم تكتب سطر كود في حياتك.**
> الجزء الأول (القسم ١ إلى ٧) بلغة عادية تمامًا. الجزء التقني في آخر الملف،
> ويمكنك تجاهله بالكامل.

---

## ١. ما هي هذه الصفحة ببساطة؟

تخيّل أن منصة مدعوم موظف ذكي. هذه الصفحة هي المكان الذي تعطيه فيه:

| ما تعطيه | يعني ماذا |
|---|---|
| **أدوات** | برامج خارجية يقدر يستخدمها (مثل GitHub أو Google Drive) |
| **مفاتيح** | تصاريح دخول تعطيها لأنظمة أخرى لتتكلّم مع مدعوم |
| **عقل** | مزوّد ذكاء اصطناعي يفكّر ويرد ويكتب |

الصفحة مقسومة إلى **ثلاثة كروت** في أول الصفحة. مرّر الماوس فوق أي كارت
فينقلب ويوريك ما بداخله، واضغط عليه لتدخل.

```
┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│     MCP      │   │     API      │   │      AI      │
│   الأدوات    │   │  المفاتيح    │   │    العقل     │
└──────────────┘   └──────────────┘   └──────────────┘
```

للرجوع لمشهد الكروت: زر **«كل الأقسام»** أعلى الصفحة، أو مفتاح `Esc`.

---

## ٢. اختصارات تريحك

| المفتاح | ماذا يفعل |
|---|---|
| `/` | ينقلك مباشرة لمربع البحث في القسم المفتوح |
| `Ctrl + K` | يتنقّل بين الأقسام بالترتيب |
| `Esc` | يغلق أي نافذة مفتوحة، وإن لم تكن هناك نافذة يرجعك لمشهد الكروت |
| `Ctrl + Enter` | يرسل رسالتك داخل بيئة التطوير |

---

## ٣. قسم AI — الأهم والأكثر استخدامًا

هنا تختار "عقل" المنصة. خمسة تبويبات بالترتيب الطبيعي للاستخدام:

### ٣.١ المزوّدون

المزوّد = الشركة أو الخدمة التي تعطيك الذكاء الاصطناعي.
مثل: OpenAI، Anthropic، Google Gemini، **AgentRouter**، OpenRouter وغيرهم.

**كيف تضيف مزوّدًا (٥ خطوات):**

1. اضغط **«إضافة مزوّد»**.
2. اختر المزوّد من القائمة.
3. الصق **مفتاح الـ API** الخاص بك.
4. اضغط **حفظ**.
5. اضغط **«اختبار»** على الكارت للتأكد أنه يعمل.

> **⚠️ أهم نصيحة في هذا الدليل**
> عند نسخ المفتاح من موقع المزوّد، استخدم **زر النسخ** الموجود عنده.
> لا تنسخ المفتاح من الخانة التي تعرضه بنجوم مثل `sk-fSDF***` — تلك نسخة
> ناقصة عمدًا، وستعطيك خطأ `401 Invalid API Key`.
> النظام سينبّهك تلقائيًا لو حسّ أن المفتاح يبدو ناقصًا.

**ما معنى "البروتوكول"؟**

بعض المزوّدين يتكلمون بأكثر من "لغة". AgentRouter مثلًا يفهم لغتين:
لغة Anthropic ولغة OpenAI. تختار واحدة، والنظام يتصرّف على أساسها.
**لا تقلق** — لو المزوّد يفهم لغة واحدة فقط، لن تظهر لك هذه الخانة أصلًا.

**ما معنى "Base URL"؟**

هو عنوان الخدمة. **اتركه فارغًا** في الحالة العادية وسيملأه النظام لك.

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

```
رابط مخصّص        https://agentrouter.org/v1
نداء التوليد       https://agentrouter.org/v1/chat/completions
قائمة الموديلات    https://agentrouter.org/v1/models
```

لو ظهر تحذير أحمر، اضغط الزر المقترح بجواره وسيصلح الرابط لك.

> **⚠️ نقطة تربك الجميع أول مرة: لكل بروتوكول رابط مختلف**
>
> بعض المزوّدين (مثل AgentRouter) يدعمون بروتوكولين، وكل واحد يضيف مسارًا
> مختلفًا بعد الرابط الأساسي:
>
> | البروتوكول | الرابط الأساسي | لأنه يضيف بنفسه |
> |---|---|---|
> | **Anthropic** | `https://x.org` — **بدون** `/v1` | `/v1/messages` |
> | **OpenAI** | `https://x.org/v1` — **مع** `/v1` | `/chat/completions` |
>
> لذلك ستجد **حقل رابط مستقل لكل بروتوكول**. لو حطيت `/v1` في خانة Anthropic
> سينتج `/v1/v1/messages` والنظام سينبّهك فورًا. والمعاينة تحتها تعرض لك
> الروابط النهائية لكل البروتوكولات — اقرأها قبل الحفظ وستتجنّب المشكلة كلها.
>
> ولماذا يهمّك بروتوكول لا تستخدمه؟ لأن **اكتشاف الموديلات قد يستخدم بروتوكولًا
> مختلفًا عن المحادثة**. المعاينة توضّح دور كل بروتوكول بشارة بجانبه.

**لو فشل شيء، لن تُترك في الظلام.** سيظهر مربع تشخيص أحمر على الكارت يبقى
ظاهرًا (لا يختفي مثل التنبيهات السريعة) ويحتوي على:

- سبب الفشل بالضبط
- **الرابط الذي جُرّب فعلًا** — أهم معلومة للتشخيص
- البروتوكول المستخدم
- تلميح عن أشهر أسباب هذا الخطأ تحديدًا

### ٣.٢ الموديلات

الموديل = "درجة الذكاء" التي تختارها من عند المزوّد.

**من أين تأتي القائمة؟** ليست مكتوبة في النظام. اضغط **«مزامنة الموديلات»**
على كارت أي مزوّد، والنظام يسأل المزوّد نفسه: "ما الذي تتيحه لهذا المفتاح؟"
لذلك القائمة دائمًا صحيحة ومحدّثة، وتختلف من مفتاح لآخر.

**بجانب كل موديل ستجد شارات تشرح لك لماذا تختاره:**

| الشارة | معناها |
|---|---|
| **محادثة** | يرد على الأسئلة العادية |
| **تفكير** | يحلّل المشاكل المعقّدة قبل الإجابة |
| **برمجة** | يكتب كودًا |
| **أدوات** | يقدر يستخدم أدوات خارجية |
| **وكيل** | ينفّذ مهامًا متعددة الخطوات وحده |
| **رؤية** | يحلّل الصور والتصاميم |
| **سياق طويل** | يستوعب مستندات ضخمة |

الموديل الذي يدعم **برمجة** أو **تفكير** أو **وكيل** يظهر بجانبه زر
**«افتح بيئة التطوير»** بدل «ابدأ محادثة».

> **لم يظهر أي موديل؟** لا مشكلة. بعض الخدمات لا تعرض قائمة موديلات أصلًا.
> استخدم زر **«+ إضافة موديل يدويًا»** واكتب اسم الموديل كما هو عند المزوّد.

**تعديل الشارات:** لو رأيت شارة خاطئة، اضغط **«القدرات»** وصحّحها.
تعديلك يُحفظ كـ «معدّل يدويًا» ولن تمسحه أي مزامنة لاحقة أبدًا.

### ٣.٣ التوجيه والاحتياطي

هنا تقول للنظام: **"استخدم الموديل المناسب لكل مهمة، لا الأغلى لكل شيء."**

```
محادثة بسيطة  →  موديل رخيص
تفكير وتحليل  →  موديل قوي
برمجة         →  موديل برمجة
```

**والاحتياطي؟** لو الموديل الأساسي وقع أو رفض الطلب، ينتقل النظام تلقائيًا
للتالي دون أن يتوقّف شيء:

```
الأساسي  →  فشل  →  احتياطي ١  →  فشل  →  احتياطي ٢
```

كل خطوة في السلسلة صف واحد. الترتيب `0` = الأساسي، `1` = أول احتياطي، وهكذا.

زر **«معاينة المسار»** يوريك الترتيب الفعلي الذي سينفّذه النظام —
**دون أن يرسل أي طلب حقيقي أو يكلّفك مليمًا**.

### ٣.٤ الاستخدام والتكلفة

كل نداء يُسجَّل تلقائيًا: كم كلّف، كم استغرق، وهل نجح.

- بطاقات علوية بالإجماليات
- تفصيل لكل مزوّد، وداخله جدول لكل موديل على حدة
- قائمة بآخر العمليات لمعرفة ما حدث بالضبط ومتى

اختر الفترة من الأعلى: ٢٤ ساعة / ٧ أيام / ٣٠ يوم / ٩٠ يوم.

### ٣.٥ بيئة التطوير

هنا تتعامل مع الذكاء الاصطناعي **كمساعد تطوير**، لا كصندوق دردشة.

**أوضاع التشغيل** — كل وضع يغيّر طريقة تفكير المساعد:

| الوضع | متى تستخدمه |
|---|---|
| **محادثة** | سؤال عادي |
| **تحليل** | يفكّك المشكلة قبل الحل |
| **كتابة كود** | مهمة برمجية محدّدة |
| **تنفيذ مهمة** | شغل متعدد الخطوات من البداية للنهاية |
| **تصحيح أخطاء** | يبحث عن سبب المشكلة الجذري |
| **مراجعة كود** | يفحص كودًا موجودًا |
| **إعادة هيكلة** | يحسّن التنظيم دون تغيير السلوك |

جلساتك محفوظة، فتقدر ترجع لأي محادثة سابقة من القائمة الجانبية.

**⚠️ حدود واضحة يجب أن تعرفها:**

ألواح **Terminal** و **Changes** ستقول لك صراحةً "غير مفعّلة".
هذا **مقصود وليس عطلًا**: لا يوجد تنفيذ أوامر حقيقي ولا وصول لملفات من
المتصفح، لأن ذلك خطر أمني. المكان جاهز لتفعيلها لاحقًا من الخادم بأمان.

لوح **Logs** يعمل فعليًا ويعرض لك بعد كل رد: المزوّد، الموديل، عدد التوكنات،
الوقت المستغرق، والتكلفة.

---

## ٤. قسم MCP — الأدوات

### الجزء الأول: «العميل»
سوق موصلات جاهزة (GitHub، Supabase، Notion...). اضغط ربط، أدخل بياناتك، تم.
**مستكشف الأدوات** بالأسفل يتيح لك تجربة أي أداة قبل استخدامها فعليًا.

### الجزء الثاني: «الخادم»
- **خوادم مخصّصة**: أضف أي خادم MCP خارجي بنفسك.
  زر **«اختبار الكل»** يفحص جميع الخوادم دفعة واحدة بدل فتح كل كارت.
- **مدعوم كخادم MCP**: العكس — عنوان يتيح لبرامج خارجية (Claude، Cursor)
  الاتصال بأدوات منصتك مباشرة.

---

## ٥. قسم API — المفاتيح والتكاملات

### داخلي: مفاتيح API
مفاتيح تعطيها لأنظمة خارجية لتتكلّم مع مدعوم.

> **مهم جدًا:** الـ Secret يظهر **مرة واحدة فقط** عند الإنشاء. احفظه فورًا.
> لو ضاع منك، استخدم «تجديد السر» — وانتبه أن التجديد يوقف السر القديم فورًا
> وأي نظام يستخدمه سيتوقّف.

فيه أيضًا وضع تحديد متعدد لحذف عدة مفاتيح مرة واحدة، وسجل تدقيق بكل استخدام.

### خارجي: التكاملات
بوت تيليجرام، Webhooks، وما شابه.

> **ملاحظة:** مزوّدو الذكاء الاصطناعي الجدد (مثل AgentRouter) تُدار من قسم
> **AI** لا من هنا. لو ضغطت «تعديل» على واحد منهم، سينقلك النظام تلقائيًا.

---

## ٦. الأمان — بلغة بسيطة

- **مفاتيحك لا تُخزَّن في المتصفح إطلاقًا.** تُرسل مرة واحدة لخادم آمن يشفّرها.
- **لا يمكن قراءة المفتاح مرة أخرى بعد الحفظ** — ولا حتى بواسطتك أنت.
  الصفحة تعرض بصمة فقط: `sk-••••••••8F92`.
- **الصفحة نفسها لا تتصل بأي مزوّد.** هي لوحة تحكّم فقط، وكل الاتصالات
  الحقيقية تحدث في خدمة منفصلة على الخادم.
- كل هذه الأقسام متاحة لمديري المنصة فقط.

---

## ٧. حل أشهر المشاكل

| ما تراه | السبب غالبًا | الحل |
|---|---|---|
| `401 Invalid API Key` | المفتاح ناقص، أو من حساب/موقع مختلف | انسخه من زر النسخ عند المزوّد، وتأكّد أنه صادر من نفس الموقع الظاهر في مربع التشخيص |
| `Unexpected token '<'` أو "رجّع HTML" | Base URL يشير للموقع لا للخدمة | أضف `/v1` في آخره، أو اتركه فارغًا تمامًا |
| رابطي ينتهي بـ `/v1` ومع ذلك رجع HTML | اكتشاف الموديلات يستخدم بروتوكولًا آخر برابط مختلف | املأ حقل الرابط الخاص بذلك البروتوكول (المعاينة توضّح أيّهما) |
| الرابط فيه `/v1/v1/` | البروتوكول يضيف مسار الإصدار بنفسه | احذف `/v1` من الرابط الأساسي |
| قال «متصل» ثم فشل كل شيء | كان فحصًا كاذبًا على صفحة ويب — لم يعد ممكنًا الآن | أعد الاختبار؛ صار يرفض أي رد ليس JSON |
| لم تظهر أي موديلات | الخدمة لا تعرض قائمة موديلات | استخدم «+ إضافة موديل يدويًا» |
| «لا يوجد مزوّد فعّال» | لا يوجد مزوّد مفعّل بمفتاح صالح | أضف مزوّدًا وفعّله واختبره |
| «لم يُحدَّد موديل» | لم تُزامن الموديلات بعد | اضغط «مزامنة الموديلات» أو أضف موديلًا يدويًا |
| زر «افتح بيئة التطوير» غير ظاهر | الموديل لا يعلن دعم البرمجة/التفكير | صحّح شاراته من زر «القدرات» |

---
---

# الجزء التقني (للمطوّرين)

> إن لم تكن مطوّرًا، تقدر تتوقّف هنا بأمان.

## المعمارية

```
admin/mcp.html  ──►  assets/js/admin/ai/*  ──►  Supabase (جداول إعدادات)
   (لوحة إدارة)          (عرض فقط)                     ▲
                                                        │
                                     ai-gateway (Edge) ──┘
                                            │
                    ProtocolAdapter (openai | anthropic | gemini | custom_http)
                                            │
                                       أي مزوّد خارجي
```

**قاعدة معمارية صارمة:** صفحة الإدارة لا تنادي أي مزوّد ولا ترى أي مفتاح.
الـ runtime كله في Edge Functions مستقلة، فإدخال مزوّد جديد لا يتطلّب لمس
صفحة الإدارة إطلاقًا.

## إضافة مزوّد جديد — سطر SQL واحد

```sql
INSERT INTO public.ai_provider_catalog
  (id, label, label_ar, kind, protocols, default_endpoints,
   auth_methods, credential_fields, models_discovery, sort_order)
VALUES (
  'myprovider', 'My Provider', 'مزوّدي', 'ai_provider',
  ARRAY['openai'],
  '{"openai":"https://api.myprovider.com/v1"}'::jsonb,
  ARRAY['api_key'],
  '[{"key":"api_key","label":"API Key","label_ar":"مفتاح API","type":"password","required":true}]'::jsonb,
  '{"supported":true,"protocol":"openai","path":"/models"}'::jsonb,
  100
);
```

**صفر تعديل كود. صفر إعادة نشر.** يظهر فورًا في الفورم بحقوله الخاصة،
ويعمل معه الاختبار والمزامنة والتوجيه والاحتياطي وتتبّع التكلفة.

## قاعدة `/v1`

لا يُضاف `/v1` تلقائيًا في أي مكان. البروتوكول هو ما يحدّد المسار:

| البروتوكول | الـ Base | المسار المضاف |
|---|---|---|
| `openai` | يتضمّن `/v1` | `/chat/completions` • `/models` |
| `anthropic` | بدون `/v1` | `/v1/messages` • `/v1/models` |
| `gemini` | `.../v1beta` | `/models/{model}:generateContent` |

مثال AgentRouter — بوابة واحدة ببروتوكولين:

```jsonc
protocols: ["anthropic", "openai"],
default_endpoints: {
  "anthropic": "https://co.agentrouter.org",     // → /v1/messages
  "openai":    "https://co.agentrouter.org/v1"   // → /chat/completions
}
```

أي مسار شاذّ يوضع في `endpoint_paths` بالكتالوج دون لمس أي كود.

## جداول قاعدة البيانات

| الجدول | الدور |
|---|---|
| `ai_provider_catalog` | سجل أنواع المزوّدين (البروتوكولات، الروابط، حقول الاعتماد) |
| `external_integrations` | المزوّدون المُعدّون فعليًا + المفاتيح المشفّرة |
| `external_integration_models` | الموديلات المكتشفة + قدراتها + أسعارها |
| `ai_routing_rules` | سلاسل التوجيه والاحتياطي |
| `ai_agent_modes` | أوضاع التشغيل السبعة (بيانات لا كود) |
| `ai_usage_events` | حدث لكل نداء (توكنات، تكلفة، زمن، أخطاء) |
| `ai_sessions` / `ai_session_messages` | جلسات بيئة التطوير |

## Edge Functions

| الدالة | الدور |
|---|---|
| `ai-gateway` | المكان الوحيد الذي يتكلم مع المزوّدين. أفعاله: `generate` • `list_models` • `add_model` • `test` • `resolve_route` • `capabilities` |
| `ai-session` | جلسات المحادثة والبرمجة. تنادي الـ gateway فقط |
| `manage-external-integration` | حفظ مشفّر (AES-GCM) + تحقّق من الكتالوج + تقنيع المفتاح |

### إضافة بروتوكول جديد

ملف واحد + سطر تسجيل في `supabase/functions/ai-gateway/protocols.ts`:

```ts
const myAdapter: ProtocolAdapter = {
  id: 'myproto', chatUrl, modelsUrl, headers, buildBody, parseResponse, parseModels,
};
const PROTOCOLS = { ..., myproto: myAdapter };
```

`index.ts` و`router.ts` و`usage.ts` والواجهة كلها: **صفر تعديل**.

## ملفات الواجهة

```
assets/js/admin/
  mcp.js                 ← منطق الصفحة + الـ Hub
  mcp-hub.css            ← تصميم الكروت ثلاثية الأبعاد
  ai/
    provider-registry.js     ← قراءة الكتالوج + حلّ البروتوكول/الرابط
    capability-registry.js   ← تعريف القدرات والتصنيفات
    ai-service.js            ← كل نداءات Supabase وEdge Functions
    ai-admin.js              ← الحالة المشتركة + التبويبات + تفويض الأحداث
    ai-styles.css
    ui/
      providers-view.js  models-view.js  routing-view.js
      usage-view.js      dev-environment.js  shared.js
```

## نقاط الامتداد غير المفعّلة

معرَّفة بالاسم في `ai-session`، وترجع `extension_not_enabled`:

`sandbox` • `repository` • `github` • `filesystem` • `terminal` • `code_execution`

تفعيل أي منها يتم في `ai-session` وحدها — الواجهة تعرضه تلقائيًا دون تعديل.

## ملاحظات أمنية

- التشفير AES-GCM بمفتاح مشتق من `INTEGRATIONS_ENC_KEY`، ويحدث في Edge Function حصريًا.
- `ai_usage_events` لا تملك سياسة كتابة عمدًا — الكتابة بـ service_role فقط.
- `ai-gateway` تعمل بـ `verify_jwt: false` لأنها تنفّذ تحققًا مخصّصًا: إما
  مفتاح service_role (نداء داخلي موثوق) أو JWT مستخدم صالح + `is_admin()`.
- رسائل الأخطاء تُقنّع أي سر داخل الروابط (بروتوكول Gemini يضع المفتاح في
  الـ query string).

---

*آخر تحديث: أغسطس ٢٠٢٦*