توثيق API - MD-2-PDF v2.0

نظرة عامة

MD-2-PDF هي أداة سحابية لتحويل نصوص Markdown إلى ملفات PDF احترافية مع دعم كامل للغة العربية (RTL)، المعادلات الرياضية (LaTeX)، تلوين الأكواد، ومخططات PlantUML.

معلومات سريعة

المميزات

المصادقة

معظم نقاط النهاية تعمل بدون مصادقة. لتسجيل السجلات واستخدام التاريخ:

GET /api/health GET

فحص صحة الخادم — يتأكد إنو الخدمة شغالة.

مثال الطلب

curl https://md-2-pdf-5vz.pages.dev/api/health

الاستجابة

{
  "status": "ok",
  "service": "md-2-pdf",
  "version": "2.0.0",
  "platform": "cloudflare-pages",
  "timestamp": "2026-05-20T00:00:00.000Z"
}

POST /api/convert POST

تحويل نص Markdown إلى ملف PDF. يعيد الملف بصيغة base64 داخل JSON.

المعاملات

مثال الطلب

curl -X POST https://md-2-pdf-5vz.pages.dev/api/convert \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# مرحباً بالعالم\n\nهذا **نص** تجريبي.\n\nمعادلة: $E = mc^2$\n\n```javascript\nconsole.log(\"Hello\");\n```",
    "options": {
      "title": "مستندي",
      "pageSize": "A4"
    }
  }'

الاستجابة (نجاح)

{
  "success": true,
  "pdf": "JVBERi0xLjQK...",
  "metadata": {
    "title": "مستندي",
    "createdAt": "2026-05-20T00:00:00.000Z"
  }
}

الاستجابة (خطأ - تجاوز الحد)

{
  "success": false,
  "error": "تم تجاوز حد التحويل اليومي...",
  "fallback": true,
  "html": "<html>...",
  "metadata": { ... }
}

POST /api/convert/base64 POST

مثل /api/convert لكن يعيد الـ base64 بحقل اسمه pdfBase64 بدل pdf.

الاستجابة

{
  "success": true,
  "pdfBase64": "JVBERi0xLjQK...",
  "metadata": { ... }
}

POST /api/parse POST

تحليل Markdown واستخراج البيانات الوصفية + معاينة HTML. لا ينشئ PDF.

المعاملات

مثال الطلب

curl -X POST https://md-2-pdf-5vz.pages.dev/api/parse \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "---\ntitle: مستندي\nauthor: أحمد\n---\n\n# مرحباً\n\n**نص عريض** مع `كود`"
  }'

الاستجابة

{
  "success": true,
  "html": "<!DOCTYPE html><html lang=\"ar\" dir=\"rtl\">...",
  "metadata": {
    "title": "مستندي",
    "author": "أحمد",
    "createdAt": "2026-05-20T00:00:00.000Z"
  }
}

POST /api/auth/register POST

تسجيل حساب جديد لحفظ السجلات.

المعاملات

POST /api/auth/login POST

تسجيل الدخول والحصول على JWT token.

المعاملات

POST /api/auth/guest POST

إنشاء جلسة ضيف بدون تسجيل — يكفي لإرسال معرف الجلسة لاحقاً.

GET /api/history GET

جلب سجلات المستندات المحفوظة. يتطلب مصادقة (JWT أو Guest Session).

المعاملات (Query String)

مثال الطلب

curl https://md-2-pdf-5vz.pages.dev/api/history?limit=10 \
  -H "Authorization: Bearer <token>"

🌍 تعدد اللغات

الموقع يدعم لغتين: العربية (افتراضي) وEnglish.

الميزات حسب اللغة

• تبديل كامل لكل النصوص (عناوين، أزرار، مساعدات)
• تبديل اتجاه الصفحة (RTL ↔ LTR) تلقائياً
• تبديل اتجاه محرر النص
• تبديل أزرار الاتجاه (RTL/LTR) لتتطابق اللغة

👤 الحسابات والسجلات

أنشئ حساباً لحفظ سجلات تحويلاتك أو تابع كضيف.

أنواع المستخدمين

كيفية الاستخدام

1. اضغط 🔑 تسجيل الدخول أعلى الصفحة
2. أنشئ حساباً أو سجل دخول
3. حوّل أي ملف Markdown إلى PDF
4. ستجد سجلاتك في صفحة 📋 السجلات

🦾 OpenClaw Skill

MD-2-PDF متاح كـ AgentSkill لأي ذكاء اصطناعي يدعم OpenClaw (Claude, Gemini, Codex, Cursor، وأكثر).

المميزات الموثقة بالـ Skill

خيارات التحويل

طرق الاستخدام

https://md-2-pdf-5vz.pages.dev/mcp

POST https://md-2-pdf-5vz.pages.dev/api/convert
Content-Type: application/json

{
  "markdown": "# مرحبا\n**نص عربي**",
  "options": { "direction": "rtl", "theme": "blue" }
}

🤖 خادم MCP (عن بُعد على Cloudflare)

الخادم يوفّر 5 أدوات للذكاء الاصطناعي لتحويل Markdown والتحكم بسجل التحويلات:

⚙️ إعداد MCP (Remote — URL واحد)

كل عميل MCP يحتاج فقط إضافة الرابط https://md-2-pdf-5vz.pages.dev/mcp — لا تثبيت، لا استنساخ، لا بناء.

{
  "mcpServers": {
    "md-2-pdf": {
      "url": "https://md-2-pdf-5vz.pages.dev/mcp"
    }
  }
}

claude mcp add --transport http md-2-pdf https://md-2-pdf-5vz.pages.dev/mcp

{
  "mcpServers": {
    "md-2-pdf": {
      "url": "https://md-2-pdf-5vz.pages.dev/mcp"
    }
  }
}

{
  "mcp": {
    "md-2-pdf": {
      "type": "http",
      "url": "https://md-2-pdf-5vz.pages.dev/mcp"
    }
  }
}

{
  "mcp": {
    "md-2-pdf": {
      "type": "http",
      "url": "https://md-2-pdf-5vz.pages.dev/mcp"
    }
  }
}

[mcp_servers.md-2-pdf]
type = "http"
url = "https://md-2-pdf-5vz.pages.dev/mcp"

{
  "mcpServers": {
    "md-2-pdf": {
      "url": "https://md-2-pdf-5vz.pages.dev/mcp"
    }
  }
}

{
  "md-2-pdf": {
    "transport": "streamable-http",
    "url": "https://md-2-pdf-5vz.pages.dev/mcp"
  }
}

🧪 اختبار MCP

كل طلب MCP هو عبارة عن JSON-RPC 2.0 عبر POST. جرّب مباشرةً بـ curl:

1) سرد الأدوات المتاحة

curl -X POST https://md-2-pdf-5vz.pages.dev/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

2) تحويل Markdown إلى PDF

curl -X POST https://md-2-pdf-5vz.pages.dev/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"convert-markdown-to-pdf","arguments":{"markdown":"# مرحباً\\nهذا **اختبار** من MCP","direction":"rtl"}}}'

3) فحص نص FYI

curl https://md-2-pdf-5vz.pages.dev/mcp

سيعيد JSON تعريفي يصف الخدمة (مفيد للتأكد أن الخادم حيّ).