# موصّل MCP

## نظرة عامة

يشغّل Nibomo خادم MCP (Model Context Protocol) بعيدًا حتى يتمكن عملاء MCP
ووكلاء الذكاء الاصطناعي من قراءة بطاقاتك المستحقة ومراجعتها معك سؤالًا تلو الآخر،
وإنشاء البطاقات والمجموعات أو تعديلها نيابةً عنك.

يمكن للوكلاء الاتصال بطريقتين: عبر خادم MCP هذا (الأفضل لعملاء MCP مثل
Claude أو Cursor)، أو عبر [عنوان اكتشاف واجهة API للوكلاء](/ar/docs/api/) لوكلاء
سطر الأوامر. كلاهما يصل إلى سطح البيانات نفسه لكل مستخدم؛ تغطّي هذه الصفحة خادم MCP.

اتصل به على:

```text
https://mcp.nibomo.com/mcp
```

آلية النقل هي Streamable HTTP، ويكشف الخادم سبع أدوات: أداتان لـ SQL عبر سطح SQL
صغير ومحدود عمدًا، وقائمة بمساحات العمل، ودليل مرجعي، وثلاث أدوات للمراجعة.
وهو سطح البيانات نفسه لكل مستخدم الموجود في
[مرجع API](/ar/docs/api/)؛ وخادم MCP هو الطريقة الملائمة كموصّل
للوصول إليه من العملاء الذين يتحدثون بروتوكول MCP.

## كيفية إضافته في عميلك

تضيف معظم العملاء خادم MCP بعيدًا كموصّل مخصّص:

1. افتح إعدادات الموصّل أو خادم MCP في عميلك.
2. أضف موصّلًا مخصّصًا والصق عنوان الخادم `https://mcp.nibomo.com/mcp`.
3. بالنسبة للعملاء التفاعليين، صرّح بالوصول في المتصفح عند المطالبة. يستخدم الخادم
   OAuth 2.1 مع Dynamic Client Registration، لذا لا يوجد client secret
   تلصقه ولا تطبيق تسجّله أولًا.
4. للاستخدام دون واجهة أو عبر سطر الأوامر، اضبط ترويسة `Authorization: Bearer fca_…` بمفتاح
   API الخاص بالوكيل بدلًا من تدفق المتصفح.

بعد التصريح بالوصول، استدعِ `list_workspaces` مرة واحدة لاختيار مساحة عمل، ثم استخدم
`sql_query` للقراءات و`sql_execute` لكتابات البطاقات والمجموعات. وللمراجعة، استدعِ
`next_review_card`، ثم `reveal_answer`، ثم `submit_review`.

## الأدوات

يكشف الخادم سبع أدوات. وقد فُصلت القراءات عن الكتابات عمدًا حتى لا تخلط أداة
واحدة أبدًا بين العمليات الآمنة والمدمّرة.

- `sql_query` — وصول صارم للقراءة فقط إلى بطاقاتك ومجموعاتك (`SHOW TABLES`
  و`DESCRIBE` و`SHOW COLUMNS` و`SELECT`).
- `sql_execute` — وصول للكتابة إلى بطاقاتك ومجموعاتك (`INSERT` و`UPDATE`
  و`DELETE`) كدفعة ذرّية.
- `list_workspaces` — قائمة صارمة للقراءة فقط بمساحات العمل التي يمكنك الوصول
  إليها، كل منها مع `workspaceId` الخاص بها والاسم وعدد البطاقات النشطة وآخر
  نشاط وما إذا كانت مساحتك الافتراضية المحددة حاليًا. استخدم `workspaceId`
  المُعاد لوسيط `workspaceId` الاختياري في أدوات SQL وأدوات المراجعة.
- `get_guide` — دليل مرجعي صارم للقراءة فقط لموضوع واحد: `sql_dialect`
  أو `card_authoring` أو `bulk_authoring` أو `review_flow`. ولا يقرأ أي بيانات من مساحة العمل.
- `next_review_card` — للقراءة فقط بشكل صارم: يعيد البطاقة التالية للمراجعة، بوجهها
  الأمامي فقط، وبترتيب طابور المراجعة نفسه المستخدم في التطبيقات. ويضيّق `tags`
  أو `deckId` الاختياري طابور المراجعة.
- `reveal_answer` — للقراءة فقط بشكل صارم: يعيد الوجه الخلفي لبطاقة واحدة بعد أن
  يحاول المتعلم الإجابة عن وجهها الأمامي.
- `submit_review` — يسجّل تقييمًا واحدًا من `Again` أو `Hard` أو `Good` أو `Easy`
  ويدفع جدول FSRS الخاص بالبطاقة إلى الأمام.

سطح SQL هو لهجة محدودة عمدًا وليس PostgreSQL كاملًا.
تغطي هذه الوثائق اللهجة المدعومة فقط، وليست مرجع توافق مع PostgreSQL.
يمكن للعبارات أن تتناول فقط موارد `workspace` و`cards` و`decks` و`review_events`،
وكل عبارة مقيّدة بمساحة عملك الخاصة، والقراءات والكتابات محدودة بـ `100` صف
لكل عبارة.

## المراجعات

تتيح أدوات المراجعة للوكيل أن يختبر المتعلم بطاقةً تلو الأخرى وأن يحفظ كل
تقييم في جدول FSRS الخاص بالبطاقة:

1. يعيد `next_review_card` قيمتَي `cardId` و`frontText`، أو `card: null` عندما
   لا يكون هناك ما هو مستحق.
2. بعد أن يجيب المتعلم، يعيد `reveal_answer` قيمة `backText` لتلك البطاقة.
3. يأخذ `submit_review` قيمة `cardId`، و`reviewId` بصيغة UUID يولّده العميل،
   و`rating`، و`reviewedTimeZone` الخاص بالمتعلم بصيغة IANA. يضع الخادم الطابع
   الزمني للمراجعة ويعيد الجدول الجديد للبطاقة.

أعد محاولة الإرسال غير المؤكد باستخدام `reviewId` نفسه؛ فلن يسجّل ذلك مراجعة
ثانية أبدًا. وقد يعيد الإرسال أيضًا أحد الردود التالية:

- `409 REVIEW_EVENT_CONFLICT` — سُجّلت المراجعة بالفعل، وتحمل تفاصيل الخطأ
  الجدول الحالي للبطاقة.
- `409 REVIEW_ID_CARD_MISMATCH` — يعرّف `reviewId` بالفعل مراجعةً لبطاقة
  مختلفة، لذا لم يُخزَّن شيء؛ أرسل مجددًا باستخدام `reviewId` جديد.
- `409 REVIEW_STALE` — وقت المراجعة المخزّن للبطاقة يساوي وقت الخادم الحالي
  أو يأتي بعده؛ راجع بطاقة أخرى.

لا تُسجَّل المراجعات إلا عبر `submit_review`: لا يمكن لـ SQL كتابة
`review_events` أو حالة جدولة FSRS. استدعِ `get_guide` مع الموضوع
`review_flow` للاطلاع على القواعد الكاملة للمراجعة والتقييم.

## عقد البطاقة

تتبع كل بطاقة عقدًا واحدًا، وتعتمد الأدوات عليه:

- `front_text` هو سؤال أو مطالبة مراجعة فقط ولا يحمل الإجابة أبدًا.
- `back_text` يحمل الإجابة، مع مثال محدد اختياريًا.

الوكلاء الذين يولّدون البطاقات عبر `sql_execute` يتبعون هذا العقد، لذا تكون
البطاقات التي ينشئونها قابلة للمراجعة فورًا بالتكرار المتباعد.

## المصادقة

يصل مساران للتصريح بالوصول إلى سطح البيانات نفسه لكل مستخدم.

### OAuth 2.1 (عملاء الموصّل التفاعليون)

ينفّذ الخادم تدفق authorization-code مع PKCE وDynamic Client
Registration. أضف عنوان MCP كموصّل مخصّص وصرّح بالوصول في المتصفح؛
لا يُشارك أي client secret مسبقًا. الاكتشاف قياسي:

- بيانات وصفية للمورد المحمي (Protected-resource metadata):
  `https://mcp.nibomo.com/.well-known/oauth-protected-resource`
- بيانات وصفية لخادم التصريح (Authorization-server metadata):
  `https://auth.flashcards-open-source-app.com/.well-known/oauth-authorization-server`

### مفتاح API (دون واجهة وعبر سطر الأوامر)

احصل على مفتاح API طويل العمر للوكيل يبدأ بـ `fca_` عبر تدفق تسجيل الدخول بـ OTP
بالبريد الموثّق في [مرجع API](/ar/docs/api/)، ثم أرسله كرمز Bearer:

```text
Authorization: Bearer fca_ABCDEFGH_0123456789ABCDEFGHJKMNPQRS
```

هذا هو المفتاح نفسه الذي يقبله سطح REST للوكيل، ولا يحتاج إلى متصفح أو
جولة OAuth.

الوصف القانوني القابل للقراءة آليًا لكلا المسارين هو حمولة الاكتشاف
على `https://api.flashcards-open-source-app.com/v1/` (المنعكسة على `/v1/agent`).

## الأمان والنطاق

أدوات SQL آمنة للموافقة عليها لأن السطح هو لهجة محتواة ومفروضة من
المحلّل اللغوي بدلًا من الوصول العشوائي إلى قاعدة البيانات:

- **قائمة عبارات مغلقة**: يقبل `sql_query` فقط `SHOW TABLES`
  و`DESCRIBE` و`SHOW COLUMNS` و`SELECT`؛ ويقبل `sql_execute` فقط `INSERT`
  و`UPDATE` و`DELETE`. وأي شيء آخر يُرفض أثناء التحليل.
- **موارد محدودة**: لا يمكن للعبارات أن تمسّ سوى `workspace` و`cards` و`decks`
  و`review_events`.
- **النطاق لكل مساحة عمل**: كل عبارة SQL وكل مراجعة مقيّدة بمساحة عمل واحدة
  يمكنك الوصول إليها، إما `workspaceId` الذي تمرّره أو مساحتك الافتراضية
  المحددة، بدون وصول عبر المستأجرين.
- **وسائط صارمة**: ترفض كل أداة أي وسيط غير معروف، لذا يفشل `workspaceId`
  المكتوب بشكل خاطئ بدلًا من التنفيذ على مساحة عملك الافتراضية.
- **الحدود**: حتى `100` صف لكل عبارة، وحتى `50` عبارة لكل دفعة،
  وحد للنتائج يبلغ نحو `12k` رمز. وتُطبَّق دفعات التعديل بشكل ذرّي.
- **الفصل بين القراءة والكتابة**: `sql_query` و`list_workspaces` و`get_guide`
  و`next_review_card` و`reveal_answer` للقراءة فقط بشكل صارم (`readOnlyHint`)
  ولا تصلح البيانات أو تعيد حساب الجدولة أو تغيّر حالة البطاقة.
  `sql_execute` و`submit_review` هما أداتا الكتابة الوحيدتان (`destructiveHint`):
  يكتب `sql_execute` البطاقات والمجموعات، ويسجّل `submit_review` مراجعةً ويدفع
  جدول بطاقتها إلى الأمام.

المنظومة بأكملها — التطبيق والخلفية والبنية التحتية — مفتوحة المصدر ويمكن
[استضافتها ذاتيًا](/ar/docs/self-hosting/)، فيمكنك تشغيل الموصّل نفسه على
نشرتك الخاصة.

---
*[عرض النسخة المنسقة HTML من هذه الصفحة](<https://nibomo.com/ar/docs/mcp-connector/>)*

*يمكن لوكلاء الذكاء الاصطناعي إنشاء حساب للمستخدم في هذه الخدمة بدءًا من `GET https://api.flashcards-open-source-app.com/v1/`. وبعد الإعداد، يمكنهم أيضًا الاتصال عبر MCP على `https://mcp.nibomo.com/mcp`.*

*نصيحة: أضف `.md` إلى أي رابط على https://nibomo.com للحصول على نسخة Markdown نظيفة من الصفحة.*