واجهة API وخادم MCP
كل ما يفعله الموقع، من فحص صفحة وقراءة تقريرها إلى تشغيل أداة واحدة، متاح من كودك بواجهة REST بسيطة، ومن مساعد ذكي عبر خادم MCP.
- العنوان
https://arablyzer.com/api/v1- المواصفة
- OpenAPI 3.1، تُولَّد من تعريفات المسارات نفسها
- الحصة
- كل فحص يخصم من حصة حسابك نفسها: لا حصة ثانية للـ API
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"
1const base = 'https://arablyzer.com/api/v1'2const headers = {3 Authorization: `Bearer ${process.env.ARABLYZER_API_KEY}`,4 'Content-Type': 'application/json',5}67const started = await fetch(`${base}/scans`, {8 method: 'POST',9 headers,10 body: JSON.stringify({ url: 'https://example.com/' }),11}).then((r) => r.json())1213let scan = started.data14while (scan.state === 'queued' || scan.state === 'running') {15 await new Promise((resolve) => setTimeout(resolve, 3000))16 const next = await fetch(`${base}/scans/${scan.id}`, { headers })17 scan = (await next.json()).data18}1920const answer = await fetch(`${base}/scans/${scan.id}/report`, { headers })21const { data: report } = await answer.json()22console.log(report.score.overall, report.summary.bySeverity)
- POST
/scansينتظر - GET
/scans/<scan id>ينتظر - GET
/scans/<scan id>/reportينتظر
اضغط «شغّل المثال» لترى الطلبات الثلاثة وأجوبتها بالترتيب.
الجواب دائماً { "data": … }، والخطأ { "error": { "code", "message" } }. التقرير هو التقرير نفسه الذي يعرضه الموقع ويطبعه سطر الأوامر، بمخطط JSON الموثّق في المواصفة.
أربعة مداخل، ومفتاح واحد
كلها تستعمل الواجهة نفسها بمفتاحك، فيسري عليها كل حد وكل قيد. اختر مدخلك لترى طريقه وإعداده.
- التقرير JSONالمخطط نفسه الذي يعرضه الموقع
- ملخص في المحادثةالدرجة وأسوأ المشكلات أولاً
- ملخص المهمة وملف SARIFتظهر المشكلات في Code scanning
- الدرجة على أيقونة الإضافةوأسوأ مشكلات الصفحة
REST بسيطة، وجواب بشكل واحد
افحص صفحة، واقرأ تقريرها، وشغّل أداة واحدة، واقرأ مكتبة القواعد. التقرير هو التقرير نفسه الذي يعرضه الموقع.
- أنشئ مفتاحاً من صفحة حسابك. يبدأ بـ
arb_ويظهر سرّه مرة واحدة. - أرسله في ترويسة
Authorizationمن كل طلب. - ابدأ فحصاً، واسأل عن حالته إلى أن ينتهي، ثم اقرأ تقريره. الفحص يستغرق نحو نصف دقيقة.
- المفتاح وحده يفتح الـ API. كوكي تسجيل الدخول لا يفتحه.
- مفتاح غير صالح أو ملغى أو ناقص يأخذ الجواب نفسه:
401وترويسةWWW-Authenticate: Bearer. - لا تضع المفتاح في كود يعمل في المتصفح. الـ API للخوادم ولأدوات سطر الأوامر.
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
خادم MCP للمساعدات الذكية
يتيح لمساعد ذكي، مثل Claude، أن يفحص صفحة ويقرأ تقريرها ويشرح قاعدة، من داخل المحادثة.
- أنشئ مفتاحاً من صفحة حسابك.
- أضف الخادم إلى إعداد مساعدك: نقطة النهاية
/mcpعلى الموقع نفسه، والمفتاح في ترويسةAuthorization. - اطلب من المساعد أن يفحص صفحة: يستعمل
scan_pageوينتظر انتهاءها، ثم يردّ بالدرجة وعدد المشكلات وأسوأها أولاً.
scan_pageيفحص صفحة وينتظر انتهاءها ويردّ بالدرجة وعدد المشكلات وأسوأها أولاً.get_reportملخص فحص بدأ سابقاً.run_toolيشغّل أداة واحدة على صفحة.list_toolsيعدّد الأدوات ويصفّيها بكلمة.
- ومكتبة القواعد موارد:
arablyzer://rulesفهرس، وarablyzer://rules/ar/<id>وarablyzer://rules/en/<id>شرح قاعدة بلغتها. - نقطة النهاية
/mcpبلا جلسات: كل طلب مستقل، وتردّ بـ JSON.
1{2 "mcpServers": {3 "arablyzer": {4 "type": "http",5 "url": "https://arablyzer.com/mcp",6 "headers": { "Authorization": "Bearer arb_…" }7 }8 }9}
إجراء GitHub لم يُنشر بعد
لا يمكن إضافة الإجراء إلى سير عملك الآن. وإلى أن يُنشر، يستطيع خط التكامل المستمر أن يفحص بواجهة REST نفسها وبمفتاحك. وهذا ما يفعله الإجراء:
- يفحص الصفحات التي تسمّيها في سير العمل، بمفتاحك ومن حصة حسابك.
- ينتظر الفحص، ويكتب في ملخص المهمة الدرجة وأسوأ المشكلات، ويفشل الخطوة عند
fail_on:criticalأوseriousأوnone. - يكتب ملف SARIF لكل صفحة، فتظهر المشكلات في «Code scanning» على GitHub.
fail_on:criticalأوseriousأوnone(الافتراضي). وlang: لغة الملخص ورسائل SARIF،arأوen.- لعدة صفحات استعمل
urls(حتى عشر). كل صفحة تخصم فحصاً واحداً من حصة حسابك، والصفحة نفسها خلال عشر دقائق لا تخصم شيئاً. - يُكتب ملف SARIF لكل صفحة في المجلد
sarif_dir، ويُرفع بـgithub/codeql-action/upload-sarif. كل قاعدة فيه تشير إلى صفحتها في الموقع. - مفتاحك سرٌّ من أسرار المستودع، والإجراء لا يطبعه في السجل.
إضافة Chrome لم تُنشر بعد
لا يمكن تثبيت الإضافة الآن. وإلى أن تُنشر، افحص أي صفحة من الموقع نفسه بلصق عنوانها. وهذا ما تفعله الإضافة:
- تفحص الصفحة المفتوحة حين تضغط «افحص هذه الصفحة».
- تعرض درجة الصفحة وأسوأ مشكلاتها، وتظهر الدرجة على أيقونة الإضافة.
- تستعمل الـ 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_، ولا نحتفظ إلا ببصمته، فإن ضاع أنشئ غيره. احفظه متغير بيئة لا في الكود، وألغِه متى شئت.
الأرقام من إعداد الخدمة، وهي هنا كما تأتي ما لم يغيّرها صاحبها. صفحة حسابك تقرأ أرقامك أنت.