تسجيل الدخولالتسجيل مجانًا

موصّل MCP

نظرة عامة

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

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

اتصل به على:

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

آلية النقل هي Streamable HTTP، ويكشف الخادم ثلاث أدوات عبر سطح SQL صغير ومحدود عمدًا. وهو سطح البيانات نفسه لكل مستخدم الموجود في مرجع 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، ثم أرسله كرمز Bearer:

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).

المنظومة بأكملها — التطبيق والخلفية والبنية التحتية — مفتوحة المصدر ويمكن استضافتها ذاتيًا، فيمكنك تشغيل الموصّل نفسه على نشرتك الخاصة.