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

نظرة عامة

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

الرابط الأساسي: https://md-2-pdf.pages.dev

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

الإصدار	2.0.0
المنصة	Cloudflare Pages + Workers
تنسيق الطلبات	JSON (`Content-Type: application/json`)
البروتوكول	HTTPS فقط
رمز المصدر	GitHub Repository

المميزات

🔤 دعم RTL

دعم كامل للغة العربية والاتجاه من اليمين لليسار

📐 LaTeX

معادلات رياضية سطرية ( $x^2$ ) وعرضية ($$...$$)

🎨 تلوين الأكواد

Syntax Highlighting لـ JavaScript, Python, CSS, SQL وأكثر

📊 PlantUML

مخططات تسلسلية، فئات، وتدفق مباشرة في المستند

🎭 ثيمات متعددة

5 ثيمات: أزرق، أحمر، أخضر، بنفسجي، ذهبي

📄 صفحة غلاف

صفحة غلاف تلقائية مع عنوان، مؤلف، وتاريخ

⚙️ Frontmatter

YAML Frontmatter لبيانات المستند الوصفية

🤖 MCP

أدوات MCP للتكامل مع Claude, Gemini, Codex وأكثر

المصادقة

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

الطريقة	التفاصيل
`JWT Token`	إرسال عبر `Authorization: Bearer <token>`
`Guest Session`	إرسال عبر `X-Guest-Session: <id>`

GET /api/health GET

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

مثال الطلب

curl https://md-2-pdf.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.

المعاملات

المعامل	النوع	مطلوب	الوصف
`markdown`	string	✅ نعم	نص Markdown للتحويل
`options.title`	string	❌ لا	عنوان المستند (يظهر بصفحة الغلاف)
`options.author`	string	❌ لا	اسم المؤلف
`options.pageSize`	string	❌ لا	A4 \| Letter \| Legal (افتراضي: A4)
`options.orientation`	string	❌ لا	portrait \| landscape
`options.fontSize`	number	❌ لا	حجم الخط بالبكسل (افتراضي: 10)
`options.fontFamily`	string	❌ لا	عائلة الخط
`options.css`	string	❌ لا	CSS مخصص يُحقن في PDF
`options.margin`	object	❌ لا	الهوامش: `{top, right, bottom, left}` (مثال: `"20mm"`)

مثال الطلب

curl -X POST https://md-2-pdf.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": { ... }
}

⚠️ ملاحظة: حقل pdf يحتوي على ملف PDF كامل بصيغة base64. استخدم atob() في JavaScript أو base64 -d في الطرفية لاستخراج الملف.

POST /api/convert/base64 POST

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

الاستجابة

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

POST /api/parse POST

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

المعاملات

المعامل	النوع	مطلوب	الوصف
`markdown`	string	✅ نعم	نص Markdown للتحليل
`options`	object	❌ لا	خيارات التحويل (نفس convert)

مثال الطلب

curl -X POST https://md-2-pdf.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

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

المعاملات

المعامل	النوع	مطلوب	الوصف
`username`	string	✅ نعم	اسم المستخدم
`email`	string	✅ نعم	البريد الإلكتروني
`password`	string	✅ نعم	كلمة المرور

POST /api/auth/login POST

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

المعاملات

المعامل	النوع	مطلوب	الوصف
`email`	string	✅ نعم	البريد الإلكتروني
`password`	string	✅ نعم	كلمة المرور

POST /api/auth/guest POST

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

GET /api/history GET

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

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

المعامل	النوع	الوصف
`limit`	number	عدد النتائج (افتراضي: 50)
`offset`	number	بداية النتائج
`search`	string	بحث في العناوين

مثال الطلب

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

🌍 تعدد اللغات

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

التبديل: استخدم القائمة المنسدلة 🌐 أعلى الصفحة. اللغة المحفوظة في المتصفح.

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

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

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

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

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

النوع	المميزات
مسجل	حفظ دائم في السحابة، الوصول من أي جهاز
ضيف	حفظ محلي في المتصفح فقط

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

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

نصيحة: يمكنك فتح أي مستند سابق من السجلات وتعديله وإعادة تحويله.

🦾 OpenClaw Skill

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

الملف: SKILL.md في المستودع
الوصف: تحويل Markdown إلى PDF مع دعم RTL والعربية

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

الميزة	الوصف
تحويل سريع	Markdown → PDF عبر API أو MCP
RTL وعربي	دعم كامل للاتجاه من اليمين لليسار
LaTeX	معادلات رياضية سطرية وعرضية
تلوين الأكواد	GitHub Dark Dimmed theme
PlantUML	مخططات مباشرة في المستند
ثيمات	5 ثيمات: أزرق، أحمر، أخضر، بنفسجي، ذهبي
MCP Server	5 أدوات للتكامل المباشر

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

الخيار	القيم	الافتراضي
`direction`	`rtl \| ltr \| hybrid`	`rtl`
`theme`	`blue \| red \| green \| purple \| gold`	`blue`
`pageSize`	`A4 \| Letter \| Legal`	`A4`
`orientation`	`portrait \| landscape`	`portrait`
`fontSize`	`8–24`	`10`
`css`	CSS إضافي	—

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

1️⃣ MCP Server (للـ AI Agents)

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

2️⃣ REST API

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

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

3️⃣ الواجهة (Web UI)

زر https://md-2-pdf.pages.dev — اكتب أو ارفع Markdown، عاين، وحمّل PDF.

ملف SKILL.md: متوفر في GitHub Repository

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

نقطة النهاية الوحيدة: https://md-2-pdf.pages.dev/mcp
خادم MCP يعمل مباشرةً على Cloudflare Pages عبر Streamable HTTP — لا حاجة لتثبيت Node.js أو استنساخ المشروع أو بنائه محلياً. أي عميل MCP متوافق يتصل بهذا الرابط فقط.

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

convert-markdown-to-pdf تحويل مباشر

تحويل نص Markdown إلى ملف PDF (Base64). يدعم: frontmatter، تلوين الكود، رياضيات KaTeX، رسوم PlantUML، تخطيطات عربية/RTL.

المعامل	النوع	الوصف
`markdown`	string	نص Markdown (مطلوب)
`pageSize`	enum	A4 \| Letter \| Legal
`orientation`	enum	portrait \| landscape
`direction`	enum	rtl \| ltr \| hybrid
`fontSize`	number	حجم الخط (8–24)
`css`	string	CSS إضافي
`margin`	object	{ top, right, bottom, left }
`filename`	string	اسم الملف المقترح
`saveToHistory`	boolean	حفظ في السجل (يتطلب auth)

parse-markdown تحليل

تحويل Markdown إلى HTML منسّق + استخراج الـ frontmatter. لا يستخدم الشبكة (سريع جداً).

المعامل	النوع	الوصف
`markdown`	string	نص Markdown (مطلوب)
+ نفس خيارات التحويل أعلاه (pageSize, direction, …)

list-documents سجل

عرض المستندات المحوّلة سابقاً للمستخدم أو الجلسة الضيف. يتطلب auth.

المعامل	النوع	الوصف
`limit`	number	عدد النتائج (1–200)
`offset`	number	ترقيم الصفحات
`search`	string	بحث في العناوين

get-document سجل

جلب مستند واحد بالكامل (Markdown + metadata) عبر معرّفه الرقمي.

المعامل	النوع	الوصف
`id`	number	معرّف المستند (مطلوب)

create-guest-session auth

إنشاء جلسة ضيف UUID لحفظ التحويلات بدون تسجيل حساب. استخدم الناتج في _meta.auth.guestSessionId.

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

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

🔑 المصادقة (اختياري): لتشغيل saveToHistory أو list-documents، مرّر أحد هذه في _meta.auth:

{ "token": "<JWT>" } — من POST /api/auth/login
{ "guestSessionId": "<UUID>" } — أنشئه بأداة create-guest-session

C Claude Desktop / Claude Code

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) · %APPDATA%\Claude\claude_desktop_config.json (Windows)

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

أو عبر Claude Code CLI:

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

A Antigravity / Gemini CLI

~/.gemini/settings.json

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

K Kilo Code / Cline / Continue

~/.config/kilo/kilo.jsonc · أو إعدادات الـ IDE

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

O OpenClaw / OpenCode

~/.config/opencode/opencode.jsonc

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

X Codex (OpenAI)

~/.codex/config.toml

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

Q Qwen CLI

~/.qwen/mcp_config.json

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

* أي عميل MCP متوافق

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

✅ لماذا Remote؟

الذكاء الاصطناعي يتصل مباشرة بـ Cloudflare — زمن استجابة عالمي منخفض.
لا حاجة لـ Node.js على جهاز المستخدم.
التحديثات تنطبق فوراً على كل العملاء.
التشفير عبر HTTPS، CORS مفتوح للاستخدام من المتصفح.

🧪 اختبار MCP

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

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

curl -X POST https://md-2-pdf.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.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.pages.dev/mcp

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