للمطورين

مرجع المطورين في لانغريت

ابنِ معلّمك أو البوت أو السكربت الخاص بك على ذاكرة المتعلّم: خادم MCP قياسي وOAuth 2.1 ورموز شخصية وREST API.

نظرة عامة

طريقتان للوصول، وذاكرة واحدة. كل استدعاء يقرأ أو يكتب سجل المتعلّم نفسه الذي يستخدمه تطبيق لانغريت، فتبقى المراجعات وسلسلة الأيام والمستويات متزامنة.

خادم MCPhttps://langrit.com/mcp

REST APIhttps://langrit.com/api/v1

البدء السريع

اربط عميل MCP

terminal

claude mcp add --transport http langrit https://langrit.com/mcp

JSON-RPC

curl https://langrit.com/mcp \
  -H "Authorization: Bearer lgr_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"whats_due","arguments":{"limit":5}}}'

استدعِ REST API برمز شخصي

REST

curl https://langrit.com/api/v1/due?limit=5 \
  -H "Authorization: Bearer lgr_…"

المصادقة

أرسل رمز Bearer مع كل طلب. استخدم OAuth 2.1 عندما يتصل المستخدمون من تطبيقك، أو رمزًا شخصيًا لسكربتاتك الخاصة.

OAuth 2.1

يجد العملاء خادم التفويض عبر الاكتشاف، بدءًا من الترويسة WWW-Authenticate في استجابة 401 على /mcp. يدعم التسجيل الديناميكي للعملاء ومستندات بيانات معرّف العميل (client ID metadata documents)، لذا لا يحتاج معظم العملاء إلى أي إعداد.

401

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://langrit.com/.well-known/oauth-protected-resource/mcp"

OAuth 2.1

GET https://langrit.com/.well-known/oauth-protected-resource/mcp
GET https://langrit.com/.well-known/oauth-authorization-server

authorize  https://langrit.com/oauth/authorize
token      https://langrit.com/oauth/token
register   https://langrit.com/oauth/register
revoke     https://langrit.com/oauth/revoke

رمز التفويض (authorization code) مع PKCE (S256) فقط. تحمل إعادة التوجيه code وstate وiss.
رموز الوصول صالحة لساعة واحدة. رموز التحديث صالحة 60 يومًا وتتجدد مع كل استخدام، ويتوقف رمز التحديث القديم عن العمل.
عناوين إعادة التوجيه (Redirect URIs): https، أو http على localhost (أي منفذ)، أو مخطط خاص بالتطبيق.

الصلاحيات (Scopes)

`read`	الملف الشخصي، والمراجعات المستحقة، والأنماط، والتصدير
`write`	إضافةً إلى حفظ الأخطاء وتقييم المراجعات (يشمل read)

الرموز الشخصية

أنشئ حتى خمسة رموز في الإعدادات، الوصول عبر API. يُعرض الرمز مرة واحدة فقط، ويمكن إلغاؤه في أي وقت.

خادم MCP

Streamable HTTP، بلا حالة، واستجابات JSON. أرسل كل رسالة JSON-RPC بطلب POST، ويعيد GET الرمز 405 لعدم وجود تدفق من الخادم.

الأدوات

الأداة	الصلاحية	المدخلات	ما تعيده
`learner_profile`	`read`	{}	اللغات والمستوى والخطة وعدد المستحق
`whats_due`	`read`	limit?	البطاقات المستحقة مع النوع والسؤال والخيارات
`my_patterns`	`read`	window? 7d \| 30d \| 90d	الأنماط مع أعدادها وأمثلتها
`remember_mistake`	`write`	wrong, correct, rule?, context? \| items[≤20]	البطاقات المنشأة أو المدمجة، والنمط، والتلميح
`grade_review`	`write`	card_id, answer, mode, elapsed_ms?	صحة الإجابة، والإجابة المتوقعة، والمراجعة التالية، والسلّم

الأوامر الجاهزة والموارد

الأوامر الجاهزة today وquiz وmy-mistakes وwrite تفتح جلسة دراسة بلغات المتعلّم. والمورد langrit://me يعيد الملف الشخصي بصيغة JSON.

أنواع الأسئلة

النوع recognition يأتي مع الخيارات والإجابة المتوقعة، أما typed وtranslate فلا يكشفان الإجابة أبدًا قبل التقييم.

REST API

الذاكرة نفسها عبر HTTPS. المدخلات والمخرجات بصيغة JSON.

نقطة النهاية	ما تفعله
GET /api/v1/me	ملفك وخطتك وعدد المراجعات المستحقة
POST /api/v1/mistakes	حفظ خطأ واحد أو حتى 20 خطأ (write)
GET /api/v1/due	المراجعات المستحقة مع نوع السؤال
POST /api/v1/reviews	تقييم إجابة (write)
GET /api/v1/patterns	أنماط الأخطاء خلال 7 أو 30 أو 90 يومًا
GET /api/v1/export	البطاقات والأخطاء والمراجعات بصيغة JSON أو CSV أو Anki

مثال

mistakes

POST /api/v1/mistakes
Idempotency-Key: 6f1c…

{ "wrong": "de huis", "correct": "het huis", "rule": "huis is a het-word" }

201 -> { "created": 1, "merged": 0,
         "cards": [{ "id": 812, "pattern": "article_de_het", "pattern_label": "de vs het",
                     "merged": false, "l1_hint": "…" }] }

reviews

POST /api/v1/reviews
{ "card_id": 812, "answer": "het huis", "mode": "typed" }

200 -> { "correct": true, "expected": "het huis", "explanation_l1": null,
         "next_due_at": "2026-11-08T09:00:00Z", "interval_days": 4,
         "ladder": { "before": 1, "after": 2 }, "streak": 12 }

الأخطاء

الأخطاء بصيغة JSON تحتوي على error وmessage وhint. الحقل hint مكتوب ليتصرف بناءً عليه النموذج، فمرّره كما هو.

الحالة	المعنى
401	رمز مفقود أو غير صالح أو منتهي الصلاحية
402	لا توجد خطة نشطة أو تجربة سارية (الملف الشخصي والتصدير يعملان)
403	الرمز لا يملك الصلاحية المطلوبة
404	بطاقة أو مسار غير معروف
422	لم يجتز محتوى الطلب التحقق
429	بلغت حد معدل الطلبات أو ميزانية التقييم اليومية بالذكاء الاصطناعي

402

402 -> { "error": "subscription_required",
         "message": "The Langrit subscription for this account is not active.",
         "url": "https://langrit.com/pricing?ref=api",
         "hint": "Tell the learner their Langrit trial or subscription has ended and give them the url." }

الحدود

60 طلبًا في الدقيقة لكل رمز على REST API، و120 على MCP. طلبات POST تقبل الترويسة Idempotency-Key، والطلب المكرر خلال 24 ساعة يعيد الاستجابة الأولى.

تصدير البيانات

يعيد GET /api/v1/export كل شيء بصيغة JSON. أضف format=csv مع table=cards أو mistakes أو reviews، أو format=anki لملف استيراد Anki. يعمل حتى بعد انتهاء الخطة.