انتقل إلى المحتوى

واجهة API وخادم MCP

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

العنوان
https://arablyzer.com/api/v1
المواصفة
OpenAPI 3.1، تُولَّد من تعريفات المسارات نفسها
الحصة
كل فحص يخصم من حصة حسابك نفسها: لا حصة ثانية للـ API
ابدأ فحصاً، ثم اقرأ تقريره
الطلب10 أسطر
1curl -sS -X POST https://arablyzer.com/api/v1/scans \2  -H "Authorization: Bearer $ARABLYZER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{"url": "https://example.com/"}'56# the answer: { "data": { "id": "<scan id>", "state": "queued", … } }7curl -sS https://arablyzer.com/api/v1/scans/<scan id> \8  -H "Authorization: Bearer $ARABLYZER_API_KEY"9curl -sS https://arablyzer.com/api/v1/scans/<scan id>/report \10  -H "Authorization: Bearer $ARABLYZER_API_KEY"
  1. POST/scansينتظر
  2. GET/scans/<scan id>ينتظر
  3. GET/scans/<scan id>/reportينتظر
الجوابلم يبدأ

اضغط «شغّل المثال» لترى الطلبات الثلاثة وأجوبتها بالترتيب.

الجواب دائماً { "data": … }، والخطأ { "error": { "code", "message" } }. التقرير هو التقرير نفسه الذي يعرضه الموقع ويطبعه سطر الأوامر، بمخطط JSON الموثّق في المواصفة.

bashAuthorization: Bearerمثال توضيحي: الأجوبة مكتوبة في الصفحة، وأرقامها من تقرير إحدى صفحات اختبارنا. لا يتصل هذا العرض بالخدمة.

أربعة مداخل، ومفتاح واحد

كلها تستعمل الواجهة نفسها بمفتاحك، فيسري عليها كل حد وكل قيد. اختر مدخلك لترى طريقه وإعداده.

الواجهة نفسها، بمفتاحك ومن حصة حسابك
  • التقرير JSONالمخطط نفسه الذي يعرضه الموقع
  • ملخص في المحادثةالدرجة وأسوأ المشكلات أولاً
  • ملخص المهمة وملف SARIFتظهر المشكلات في Code scanning
  • الدرجة على أيقونة الإضافةوأسوأ مشكلات الصفحة

REST بسيطة، وجواب بشكل واحد

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

  1. أنشئ مفتاحاً من صفحة حسابك. يبدأ بـ arb_ ويظهر سرّه مرة واحدة.
  2. أرسله في ترويسة Authorization من كل طلب.
  3. ابدأ فحصاً، واسأل عن حالته إلى أن ينتهي، ثم اقرأ تقريره. الفحص يستغرق نحو نصف دقيقة.
  • المفتاح وحده يفتح الـ API. كوكي تسجيل الدخول لا يفتحه.
  • مفتاح غير صالح أو ملغى أو ناقص يأخذ الجواب نفسه: 401 وترويسة WWW-Authenticate: Bearer.
  • لا تضع المفتاح في كود يعمل في المتصفح. الـ API للخوادم ولأدوات سطر الأوامر.
every request
1Authorization: Bearer arb_…23# every answer4{ "data": … }56# every error7{ "error": { "code": "rate_limited", "message": "…" } }89# with each scan10X-Scans-Limit, X-Scans-Remaining1112# with every answer13RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset
http13 سطراً

خادم MCP للمساعدات الذكية

يتيح لمساعد ذكي، مثل Claude، أن يفحص صفحة ويقرأ تقريرها ويشرح قاعدة، من داخل المحادثة.

  1. أنشئ مفتاحاً من صفحة حسابك.
  2. أضف الخادم إلى إعداد مساعدك: نقطة النهاية /mcp على الموقع نفسه، والمفتاح في ترويسة Authorization.
  3. اطلب من المساعد أن يفحص صفحة: يستعمل scan_page وينتظر انتهاءها، ثم يردّ بالدرجة وعدد المشكلات وأسوأها أولاً.
  • scan_pageيفحص صفحة وينتظر انتهاءها ويردّ بالدرجة وعدد المشكلات وأسوأها أولاً.
  • get_reportملخص فحص بدأ سابقاً.
  • run_toolيشغّل أداة واحدة على صفحة.
  • list_toolsيعدّد الأدوات ويصفّيها بكلمة.
  • ومكتبة القواعد موارد: arablyzer://rules فهرس، وarablyzer://rules/ar/<id> وarablyzer://rules/en/<id> شرح قاعدة بلغتها.
  • نقطة النهاية /mcp بلا جلسات: كل طلب مستقل، وتردّ بـ JSON.
mcpServers
1{2  "mcpServers": {3    "arablyzer": {4      "type": "http",5      "url": "https://arablyzer.com/mcp",6      "headers": { "Authorization": "Bearer arb_…" }7    }8  }9}
json9 أسطر

إجراء GitHub لم يُنشر بعد

لا يمكن إضافة الإجراء إلى سير عملك الآن. وإلى أن يُنشر، يستطيع خط التكامل المستمر أن يفحص بواجهة REST نفسها وبمفتاحك. وهذا ما يفعله الإجراء:

  1. يفحص الصفحات التي تسمّيها في سير العمل، بمفتاحك ومن حصة حسابك.
  2. ينتظر الفحص، ويكتب في ملخص المهمة الدرجة وأسوأ المشكلات، ويفشل الخطوة عند fail_on: critical أو serious أو none.
  3. يكتب ملف SARIF لكل صفحة، فتظهر المشكلات في «Code scanning» على GitHub.
  • fail_on: critical أو serious أو none (الافتراضي). وlang: لغة الملخص ورسائل SARIF، ar أو en.
  • لعدة صفحات استعمل urls (حتى عشر). كل صفحة تخصم فحصاً واحداً من حصة حسابك، والصفحة نفسها خلال عشر دقائق لا تخصم شيئاً.
  • يُكتب ملف SARIF لكل صفحة في المجلد sarif_dir، ويُرفع بـ github/codeql-action/upload-sarif. كل قاعدة فيه تشير إلى صفحتها في الموقع.
  • مفتاحك سرٌّ من أسرار المستودع، والإجراء لا يطبعه في السجل.

إضافة Chrome لم تُنشر بعد

لا يمكن تثبيت الإضافة الآن. وإلى أن تُنشر، افحص أي صفحة من الموقع نفسه بلصق عنوانها. وهذا ما تفعله الإضافة:

  1. تفحص الصفحة المفتوحة حين تضغط «افحص هذه الصفحة».
  2. تعرض درجة الصفحة وأسوأ مشكلاتها، وتظهر الدرجة على أيقونة الإضافة.
  3. تستعمل الـ API بمفتاحك الذي تضعه في إعداداتها، وبلا مفتاح تفتح لك صفحة الفحص في الموقع.
  • أذونات قليلة: activeTab وstorage، وإذن الاتصال بخدمة Arablyzer وحدها. ولا خلفية تعمل ولا سكربت يُحقن في الصفحات.
  • لا تحليلات ولا شيفرة من الخارج. المُرسَل إلى الخدمة عنوان الصفحة التي تفحصها، لا غير.

المسارات

كلها تحت /api/v1. القوائم تقبل limit (حتى 100) وcursor، وتردّ meta.nextCursor حين يوجد المزيد.

المواصفة تُولَّد من تعريفات المسارات نفسها، وفيها مخطط التقرير كاملاً، فاستعملها لتوليد عميل بلغتك أو لاستيراد الـ API في أداتك.

الطريقةالمسارما يفعله
POST/api/v1/scansيبدأ فحصاً لصفحة (url، وengines اختيارياً). إن فحص حسابك الصفحة نفسها قبل أقل من عشر دقائق عاد ذلك الفحص بـ reused: true ودون خصم من الحصة.
GET/api/v1/scansفحوص حسابك، الأحدث أولاً.
GET/api/v1/scans/{id}حالة فحص: queued أو running أو complete أو partial أو failed.
GET/api/v1/scans/{id}/reportتقرير الفحص. يردّ 409 ما دام لم ينتهِ.
GET/api/v1/toolsالأدوات: ما يشغَّل منها على صفحة وما يعمل في المتصفح.
POST/api/v1/tools/{slug}/runsيشغّل أداة واحدة على صفحة، بقواعدها وحدها. اقرأ نتيجته كأي فحص.
GET/api/v1/rulesمكتبة القواعد.
GET/api/v1/rules/{ruleId}قاعدة بشرحها بالعربية والإنجليزية: لماذا تهم وكيف تُصلح وكيف نكشفها.
GET/api/v1/openapi.jsonمواصفة OpenAPI 3.1. لا تحتاج مفتاحاً.

لكل خطأ رمز ثابت تبني عليه

لكل خطأ رمز ثابت تبني عليه، ورسالة بالإنجليزية للقراءة. details يحمل ما يلزم، مثل سبب رفض العنوان.

  • invalid_request400الطلب ليس ما يقبله المسار: جسم ليس JSON، أو حقل ناقص أو زائد.
  • invalid_url400العنوان لا يصلح لفحص: غير صالح أو مخطط غير http وhttps أو طويل جداً أو فيه بيانات دخول أو منفذ ممنوع.
HTTP/1.1 400{ "error": {    "code": "invalid_request",    "message": "…"} }
  • unauthorized401مفتاح ناقص أو غير صالح أو ملغى.
HTTP/1.1 401WWW-Authenticate: Bearer{ "error": {    "code": "unauthorized",    "message": "…"} }
  • plan_limit403خطة الحساب لا تسمح بالمزيد (details.limit يسمّي الحد).
HTTP/1.1 403{ "error": {    "code": "plan_limit",    "message": "…", "details": { "limit": "…" }} }
  • not_found404لا فحص ولا أداة ولا قاعدة بهذا المعرّف.
HTTP/1.1 404{ "error": {    "code": "not_found",    "message": "…"} }
  • report_not_ready409لا تقرير لهذا الفحص بعد، أو لن يكون له لأنه فشل (details.state).
HTTP/1.1 409{ "error": {    "code": "report_not_ready",    "message": "…", "details": { "state": "running" }} }
  • blocked_target422عنوان لا يصل إليه الفحص: خاص أو داخلي أو لا يُحَلّ اسمه.
HTTP/1.1 422{ "error": {    "code": "blocked_target",    "message": "…"} }
  • rate_limited429بلغت حداً: حصة الفحوص أو ميزانية الطلبات أو حد الموقع المفحوص. Retry-After يقول متى.
HTTP/1.1 429Retry-After: <seconds>{ "error": {    "code": "rate_limited",    "message": "…"} }
  • accounts_off503الحسابات مطفأة في هذه الخدمة فلا API.
  • unavailable503الخدمة غير متاحة الآن.
HTTP/1.1 503{ "error": {    "code": "accounts_off",    "message": "…"} }

الحدود والتكرار

  • الفحص يخصم من حصة فحوص حسابك نفسها (الدلو الذي يخصم منه الموقع)، ولا حصة ثانية. قد يحدّد صاحب الخدمة للـ API نصيباً أصغر منها. في جواب كل فحص: X-Scans-Limit وX-Scans-Remaining.
  • لكل مفتاح ميزانية طلبات في الدقيقة تشمل القراءة. في كل جواب: RateLimit-Limit وRateLimit-Remaining وRateLimit-Reset. عند بلوغ حد يأتي 429 وRetry-After بالثواني.
  • القراءة (حالة الفحص، التقرير، الأدوات، القواعد) لا تخصم من حصة الفحوص.
  • جواب إنشاء الفحص يحمل deleteToken مرة واحدة: بإرساله في DELETE /api/reports/{id} تُحذف الفحص وتقريره.
  • حين تكون الحسابات مطفأة في الخدمة يردّ كل مسار 503 ورمز accounts_off.

المفتاح من حسابك، وسرّه يظهر مرة واحدة

يبدأ بـ arb_، ولا نحتفظ إلا ببصمته، فإن ضاع أنشئ غيره. احفظه متغير بيئة لا في الكود، وألغِه متى شئت.

  • 2مفتاحان لكل حساب على الأكثر
  • 120طلباً في الدقيقة لكل مفتاح، والقراءة منها
  • reusedالصفحة نفسها خلال عشر دقائق تعود بالفحص نفسه ولا تخصم فحصاً ثانياً

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