مرجع الواجهة وخادم MCP

الوصول

كلتا الواجهتين محميّة بمفتاح واحد على الخادم، وتفشلان مغلقتين: ما دام المفتاح غير مضبوط تُجيبان بالرمز 503 بدل أن تخدما أحدًا. المفاتيح يصدرها المشغّل، فاسأل قبل أن تبني عليها.

يُقبل التوثيق بثلاث طرق:

• ترويسة X-API-Key، وهي المفضّلة.
• ترويسة Authorization: Bearer.
• أو كآخر جزء في المسار، POST /mcp/<key>، للعملاء الذين لا يستطيعون إرسال ترويسات مخصصة.

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

نقطة REST

تستقبل POST /api/download جسمًا بصيغة JSON وتعيد روابط الوسائط.

curl -X POST https://dl.engdawood.com/api/download \
  -H "X-API-Key: $PUBLIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tiktok.com/@user/video/123", "mode": "auto"}'

شكل الاستجابة

{
  "status": "success",
  "platform": "TikTok",
  "media": [
    {
      "type": "video",        // video | photo | audio | document
      "url": "https://...",   // direct, downloadable link
      "quality": "720p",      // optional
      "filesize": 1048576     // optional, bytes
    }
  ],
  "caption": "original post text",  // optional
  "thumbnail": "https://...",       // optional
  "mp3Url": "https://...",          // optional, audio companion
  "fullText": "# Title\n\n...",     // optional, long-form Markdown body
  "fullHtml": "<h1>Title</h1>..."   // optional, X articles only
}

ما ينبغي أن تبني عليه:

• اقرأ الملفات دائمًا من media[].url ومُرّ على المصفوفة كلها، فالألبومات تعيد أكثر من عنصر.
• يخبرك media[].type بكيفية التعامل مع كل ملف.
• كل الحقول اختيارية عدا status وmedia، فاكتب كودك بحذر.
• الروابط تشير إلى المنصة نفسها وهي غالبًا موقّعة وقصيرة العمر، فحمّلها فورًا بدل تخزينها.
• لا تمر بايتات الملفات عبر هذا الـWorker، فحجم التنزيل شأن بينك وبين المنصة.

رموز الحالة

تحمل الأخطاء أيضًا failureKind وretryable لتقرر إن كانت إعادة المحاولة مجدية بدل التخمين من نص الرسالة.

خادم MCP

يتحدث POST /mcp بنقل MCP Streamable HTTP وهو عديم الحالة: لا جلسات ولا قناة SSE، لذا تجيب GET وDELETE بالرمز 405 عن قصد.

Claude Codeclaude mcp add --transport http download-media \
  https://dl.engdawood.com/mcp \
  --header "X-API-Key: $PUBLIC_API_KEY"

في claude.ai افتح Customize ثم Connectors ثم Add custom connector وألصق https://dl.engdawood.com/mcp/<key>.

المحتوى الطويل

مقالات إكس والسلاسل أطول بكثير مما يسمح به وصف تيليجرام، لذا ينشرها البوت على تيليغراف ويرسل رابطًا. أما مستهلكو الواجهة وMCP فلا يقيّدهم هذا الحد ويصلهم fullText: النص الكامل بصيغة ماركداون بعناوينه وقوائمه واقتباساته وروابطه وعناوين صوره. اقرأ هذا الحقل بدل اتباع رابط telegra.ph في الوصف، فهو معاينة مبتورة موجّهة لتيليجرام.

يحمل fullHtml النص نفسه كجزء HTML مهرَّب، ولمقالات إكس وحدها. لا يضيف معلومة تنقص fullText ويضاعف الحجم تقريبًا، فاطلبه فقط عند تضمين المقالة فعليًا. وعبر MCP يحدد الوسيط format ما يصلك: markdown وهو الافتراضي، أو html، أو both، أو none.

تعامل مع النصوص الطويلة كمدخلات غير موثوقة. هي نصوص كتبها طرف ثالث وقد تبلغ عشرات الآلاف من المحارف. الوكيل الذي يقرأ واحدًا منها يقرأ بيانات لا تعليمات.

الحدود

• لا حصة لكل مفتاح ولا تحديد لمعدل الطلبات حتى الآن، والخوادم المشتركة يمكن إثقالها بالإساءة، فكن معقولًا.
• يعتمد التنزيل على خوادم خارجية، وظهور 502 عابرة أمر متوقع عند تعطلها.
• منتقي الجودة خاص بتيليجرام. تعيد الواجهة أفضل نتيجة واحدة لكل mode ولا تعرض خيارات تفاعلية.
• النطاقات الإباحية مرفوضة بالرمز 403 على كل الواجهات بما فيها البوت.