# موصّل MCP

## نظرة عامة

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

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

اتصل به على:

```text
https://mcp.flashcards-open-source-app.com/mcp
```

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

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

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

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

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

## الأدوات

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

- `sql_query` — وصول للقراءة فقط إلى بطاقاتك ومجموعاتك (`SHOW TABLES`
  و`DESCRIBE` و`SHOW COLUMNS` و`SELECT`).
- `sql_execute` — وصول للكتابة إلى بطاقاتك ومجموعاتك (`INSERT` و`UPDATE`
  و`DELETE`) كدفعة ذرّية.
- `list_workspaces` — يسرد مساحات العمل التي يمكنك الوصول إليها، كل منها مع
  `workspaceId` الخاص بها والاسم وعدد البطاقات النشطة وآخر نشاط وما إذا كانت
  مساحتك الافتراضية المحددة حاليًا. استخدم `workspaceId` المُعاد لوسيط
  `workspaceId` في `sql_query` و`sql_execute`.

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

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

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

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

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

## المصادقة

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

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

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

- بيانات وصفية للمورد المحمي (Protected-resource metadata):
  `https://mcp.flashcards-open-source-app.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`.
- **النطاق لكل مساحة عمل**: كل عبارة مقيّدة بمساحة العمل المحددة
  لديك، بدون وصول عبر المستأجرين.
- **الحدود**: حتى `100` صف لكل عبارة، وحتى `50` عبارة لكل دفعة،
  وحد للنتائج يبلغ نحو `12k` رمز. وتُطبَّق دفعات التعديل بشكل ذرّي.
- **الفصل بين القراءة والكتابة**: `sql_query` و`list_workspaces` للقراءة فقط
  (`readOnlyHint`) و`sql_execute` ينفّذ عمليات الكتابة (`destructiveHint`).

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

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

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

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