توثيق المطورين — مدعوم

جدول api_tokens هو مصدر الهوية الوحيد لكل شيء — سواء تولّد يدويًا من لوحة "مفاتيح API"، أو صدر تلقائيًا عبر تدفق OAuth 2.1 لعميل مثل Claude أو ChatGPT.

كل طلب — سواء بمفتاح API ثابت أو Access Token صادر من OAuth — يصل في النهاية لنفس نقطة الدخول: POST /mcp، بروتوكول JSON-RPC 2.0 واحد يغطي كل الأدوات.

أسرع طريقة للاتصال: ولّد مفتاح API من لوحة المطورين، ثم استدعِ /mcp مباشرة.

curl -X POST https://mad3oom.online/mcp \
  -H "Authorization: Bearer mad3oom_pk_XXXX.mad3oom_sk_YYYY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

# tools/list
curl -X POST https://mad3oom.online/mcp \
  -H "Authorization: Bearer mad3oom_pk_XXXX.mad3oom_sk_YYYY" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# tools/call
curl -X POST https://mad3oom.online/mcp \
  -H "Authorization: Bearer mad3oom_pk_XXXX.mad3oom_sk_YYYY" \
  -d '{
    "jsonrpc":"2.0","id":3,"method":"tools/call",
    "params":{"name":"list_tickets","arguments":{"status":"open","limit":10}}
  }'

جدول api_tokens يخزّن SHA-256 فقط لكل سر — لا يوجد أي استرجاع للسر الأصلي بعد الإنشاء، فقط تجديد كامل.

أنواع بيانات الاعتماد

الاستخدام في هيدر Authorization

// api_key_secret → فيه نقطة فاصلة بين الاثنين
Authorization: Bearer mad3oom_pk_XXXX.mad3oom_sk_YYYY

// bearer → توكن واحد بدون نقطة
Authorization: Bearer mad3oom_bt_ZZZZZZZZ

كل مفتاح له مصفوفة scopes — الأداة اللي محتاجة scope غير موجود عند المفتاح ببساطة مش هتظهر في tools/list، ومحاولة استدعائها في tools/call بترجع خطأ 403 (JSON-RPC code -32003).

الصلاحيات المستهلَكة فعليًا من أدوات MCP

الصلاحيات الافتراضية (لو ماتحددتش صراحة)

نقطة JSON-RPC 2.0 واحدة تخدم كل عملاء MCP الخارجيين (Claude, ChatGPT, Cursor...) عبر Streamable HTTP.

دورة حياة الجلسة

// 1) initialize — يرجع Mcp-Session-Id في الهيدر
→ {"method":"initialize","params":{"protocolVersion":"2025-06-18"}}
← {"result":{"protocolVersion":"2025-06-18","serverInfo":{"name":"mad3oom-mcp","version":"1.1.0"}}}

// 2) tools/list — مفلترة حسب scopes التوكن + الأدوات المعطّلة إداريًا
→ {"method":"tools/list"}
← {"result":{"tools":[{"name":"list_tickets", ...}]}}

// 3) tools/call
→ {"method":"tools/call","params":{"name":"list_tickets","arguments":{"status":"open"}}}
← {"result":{"content":[{"type":"text","text":"[...]"}]}}

18 أداة موزّعة على 5 مجموعات — كل أداة مربوطة بـ scope واحد محدد.

نموذج الصلاحيات (Actor-based)

كل أداة تمر بـ getActor(userId) لتحديد: أدمن رئيسي (بريد ثابت)، أدمن (profiles.role='admin')، أو مستخدم فرعي. الأدمن يرى كل شيء في التذاكر والاشتراكات، العميل العادي يرى نفسه ومستخدميه الفرعيين فقط. الإشعارات استثناء — مقصورة على صاحب المفتاح نفسه حتى لو كان أدمن.

عكس الاتجاه السابق — هنا مدعوم بيتصل بخوادم MCP خارجية (Supabase, GitHub, Notion...) نيابةً عن الأدمن، عبر جدولين منفصلين.

التشفير

كل الأسرار (api_key_encrypted, bearer_token_encrypted, oauth_access_token_encrypted...) مشفّرة بـ AES-GCM حقيقي (IV عشوائي 12 بايت + ciphertext). لا يوجد أي مسار في الكود يعيد فك هذه القيم للواجهة — فقط تُستخدم داخليًا وقت الاستدعاء الفعلي.

أنواع المصادقة المدعومة

لكل نوع oauth2، الدالة ensureFreshAccessToken بتجدّد access_token تلقائيًا لو باقي أقل من 60 ثانية على انتهائه، قبل بناء الهيدر.

هذا المسار تستخدمه Claude/ChatGPT/أي عميل يدعم Dynamic Client Registration + PKCE، عوضًا عن مفتاح API ثابت.

تسجيل كل طلب موثّق في api_token_usage_logs + عدّاد usage_count على api_tokens. كانت فيه 3 فجوات حقيقية في الكود، اتصلحت الثلاثة في نفس الإصدار.

كيف اتصلحت

التسجيل انتقل من بداية الطلب (داخل verifyApiToken) لنهايته، بعد معرفة الـ method واسم الأداة والـ Response النهائي فعليًا — عبر دالة withLogging() بتلف كل مسارات الرد في index.ts.

function withLogging(response) {
  logApiUsage({
    tokenId: auth.token.id,
    endpoint: endpointLabel, // ديناميكي حسب method/الأداة
    statusCode: response.status, // من الـ Response الفعلي
    ip, userAgent,
  });
  return response;
}
// كل return في الملف بقى: return withLogging(httpJson(...))

كل الروابط العامة rewrites (مش redirects) — العميل يرى دومين mad3oom.online فقط طول الوقت، وهو مطلوب لتطابق issuer في RFC 8414/9728.

verify_jwt: false على mcp وoauth-* إجباري — المصادقة عندهم مخصّصة (api_tokens / client credentials)، مش JWT قياسي.